Integra la facturació Veri*Factu dels teus clients amb una API REST.
Contactes, productes, sèries i factures — la mateixa lògica que fa servir l'app de Kullqi, disponible per HTTP amb clau d'API. La cadena de registre i l'enviament a l'AEAT s'apliquen igual, la cridis des d'on la cridis.
# substitueix sk_live_... per la teva clau, generada a app.kullqi.com/api-keys curl -X POST https://api.kullqi.com/v1/contacts \ -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "type": "CUSTOMER", "legalName": "Comercial Ejemplo SL", "taxId": "B12345674", "email": "facturacion@ejemplo.com" }' # resposta — 201 Created { "id": 42, "type": "CUSTOMER", "legalName": "Comercial Ejemplo SL", "taxId": "B12345674", "archived": false }
Autenticació
Cada petició a /v1/** porta la teva clau a la capçalera Authorization, com a token Bearer. Genera i revoca claus des de Claus d'API al teu compte — només un ADMIN ho pot fer, i la clau es mostra una sola vegada en crear-la (desa-la llavors; Kullqi només en conserva el hash, mai el valor).
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Cada clau té un o diversos scopes — permisos per recurs, independents del rol de l'usuari que la va crear. Una petició a un endpoint sense el scope necessari rep 403 Forbidden.
| Scope | Permet |
|---|---|
| contacts:read | Llegir i llistar contactes. |
| contacts:write | Crear, modificar i arxivar contactes. |
| products:read | Llegir i llistar productes del catàleg. |
| products:write | Crear i modificar productes. |
| invoices:read | Llegir i llistar factures, sèries i el seu PDF. |
| invoices:write | Crear esborranys i emetre factures. |
Cicle de vida d'una factura
Emetre una factura són dos passos separats expressament: crear l'esborrany mai no té efecte fiscal; emetre'l sí — assigna el número de sèrie, encadena el registre i dispara l'enviament real a l'AEAT (Veri*Factu). Cap endpoint no combina totes dues coses en una sola crida.
POST /v1/invoices
Crea un esborrany (status: "DRAFT") amb les seves línies. Sense número ni efecte fiscal, es pot llegir i descartar lliurement. Requereix Idempotency-Key — vegeu més avall.
POST /v1/invoices/{id}/issue
Emet l'esborrany en una sèrie (seriesId). A partir d'aquí la factura és inalterable: número assignat, registre encadenat i enviament a l'AEAT en marxa.
Idempotència obligatòria en crear factures
POST /v1/invoices exigeix la capçalera Idempotency-Key — un identificador que generes tu (per exemple, un UUID per cada intent de creació des del teu sistema). Repetir la mateixa petició amb la mateixa clau mai no crea un segon esborrany: retorna el mateix recurs ja creat.
Sense Idempotency-Key, la petició falla amb 400 Bad Request abans de tocar res — no és opcional. Una factura de debò no es pot desfer amb un simple DELETE, així que un reintent de xarxa per part teva mai no l'ha de poder duplicar.
curl -X POST https://api.kullqi.com/v1/invoices \ -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Idempotency-Key: 8f14e45f-ceea-4c9c-8b3d-4a9e5f1c2b90" \ -H "Content-Type: application/json" \ -d '{ "contactId": 42, "invoiceType": "F1", "lines": [ { "description": "Consultoría", "quantity": 1, "unitPrice": 100.00, "taxRate": 21 } ] }' # primera crida → 201 Created, id: 17 # repetir EXACTAMENT la mateixa Idempotency-Key → 200 OK, mateix id: 17
Límits d'ús
Pensats per a integracions reals, no per fer scraping ni per substituir l'ús normal de l'app.
| Límit | Valor |
|---|---|
| Quota diària per compte (tenant) | 5.000 peticions / dia natural |
| Ritme sostingut (gateway) | 20 peticions / segon |
| Ràfega màxima (gateway) | 40 peticions |
Superar la quota diària retorna 429 Too Many Requests amb un cos { "message": "..." }; el comptador es reinicia a mitjanit.
Recursos disponibles
Totes les rutes pengen de https://api.kullqi.com. Els cossos i camps són exactament els mateixos que fa servir la mateixa app de Kullqi — res simplificat ni retallat per a l'API pública.
Contactes
| Mètode | Ruta | Scope | Descripció |
|---|---|---|---|
| POST | /v1/contacts | contacts:write | Crear un contacte (client o proveïdor). |
| GET | /v1/contacts | contacts:read | Llistar contactes, amb cerca i paginació. |
| GET | /v1/contacts/{id} | contacts:read | Obtenir un contacte. |
| PUT | /v1/contacts/{id} | contacts:write | Actualitzar un contacte. |
| DELETE | /v1/contacts/{id} | contacts:write | Arxivar un contacte (no se n'elimina l'historial). |
Productes
| Mètode | Ruta | Scope | Descripció |
|---|---|---|---|
| POST | /v1/products | products:write | Crear un producte o servei del catàleg. |
| GET | /v1/products | products:read | Llistar productes, amb cerca i paginació. |
| GET | /v1/products/{id} | products:read | Obtenir un producte. |
| PUT | /v1/products/{id} | products:write | Actualitzar un producte. |
Sèries de facturació
| Mètode | Ruta | Scope | Descripció |
|---|---|---|---|
| GET | /v1/invoice-series | invoices:read | Llistar les sèries disponibles (necessàries per emetre). |
Només lectura en aquesta versió de l'API: les sèries es creen i es configuren des de l'app.
Factures
| Mètode | Ruta | Scope | Descripció |
|---|---|---|---|
| POST | /v1/invoices | invoices:write | Crear un esborrany. Exigeix Idempotency-Key. |
| POST | /v1/invoices/{id}/issue | invoices:write | Emetre l'esborrany — número, cadena de registre i enviament a l'AEAT. |
| GET | /v1/invoices | invoices:read | Llistar factures, amb filtres per estat, sèrie, dates i contacte. |
| GET | /v1/invoices/{id} | invoices:read | Obtenir una factura, amb el seu hash, QR i estat davant l'AEAT. |
| GET | /v1/invoices/{id}/pdf | invoices:read | Descarregar el PDF amb el QR de verificació oficial. |
Fora d'aquesta versió de l'API: rectificar, anul·lar, registrar cobraments i enviar per correu — de moment només des de l'app de Kullqi.
Errors
Codis HTTP estàndard. Els errors de validació propis de /v1 retornen un cos JSON simple: { "message": "..." }.
| Codi | Significat |
|---|---|
400 | Petició no vàlida — per exemple, falta Idempotency-Key en crear una factura. |
401 | Clau absent, mal formada, revocada o caducada. |
403 | La clau és vàlida però no té el scope necessari per a aquesta ruta. |
404 | El recurs no existeix o no pertany al teu compte. |
429 | Quota diària o límit de ritme superat. |
Genera la teva clau i fes la primera crida
Es mostra una sola vegada en crear-la — copia-la en aquell moment.
Ves a Claus d'API