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, rectificar, esborrar 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
Rectificatives (abonaments)
Una rectificativa es crea des de la factura emesa que corregeix, també en dos passos: POST /v1/invoices/{id}/rectify crea l'esborrany i s'emet amb el mateix /issue, en una sèrie de tipus rectificativa (amb number si la numeració és externa). Kullqi enllaça sola la factura rectificada —número, sèrie i data— al registre Veri*Factu.
type:R1–R4per a factures completes;R5només per a simplificades (i les simplificades, només ambR5).mode:"I"(per diferències), l'única disponible per l'API de moment. La substitució (corregir les dades del client) es fa des de l'app.lines: les diferències, amb signe (import negatiu per abonar). Si no s'envien, és un abonament total de la factura.reason: el motiu; apareix a la factura al costat de la referència a l'original.- Exigeix
Idempotency-Key, igual que crear una factura. Fer servir la mateixa clau per a una altra operació retorna409 Conflict. - Entre totes les seves rectificatives, una factura no pot quedar en negatiu: si s'intenta abonar més del que s'ha facturat, la resposta és
422amb el codiRECTIFICATION_EXCEEDS_ORIGINAL. Una rectificativa no es rectifica: es rectifica la factura original.
Per trobar pel número la factura que rectificaràs, fes servir GET /v1/invoices?q=<número>.
# 1) esborrany de la rectificativa → 201 Created, id: 18 curl -X POST https://api.kullqi.com/v1/invoices/17/rectify -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -H "Idempotency-Key: 3b9d6c1e-5a7f-4e2b-9c8d-1f0a2b3c4d5e" -H "Content-Type: application/json" -d '{ "type": "R1", "mode": "I", "reason": "Devolución del pedido 1042" }' # 2) emetre-la a la sèrie de rectificatives curl -X POST https://api.kullqi.com/v1/invoices/18/issue -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -H "Content-Type: application/json" -d '{ "seriesId": 3 }'
Retenció d'IRPF
Si el teu client et reté IRPF, indica el tipus a l'esborrany amb withholdingRate: un percentatge de 0 a 50, amb 2 decimals com a màxim (per exemple 15 o 7). La retenció es calcula sobre la base imposable de tota la factura. Sense el camp, o amb 0, la factura no porta retenció.
- La resposta de la factura porta
withholdingRate,withholdingAmount(base × tipus / 100, arrodonit a 2 decimals) iamountDue, el total a pagar:totalAmount−withholdingAmount. totalAmountcontinua sent base + IVA: és l'import que es registra a l'AEAT i al QR. Per saber el que et deu el client fes serviramountDue, i per al que queda per cobrar,amountPending, que ja descompta la retenció.- Només en factures completes (
F1) i en les seves rectificatives (R1–R4). En una simplificada (F2),R5oF3, un tipus més gran que 0 retorna422amb el codiWITHHOLDING_NOT_ALLOWED_FOR_TYPE. - Una rectificativa hereta el tipus de la factura que rectifica; no cal enviar-lo.
- El tipus que desis en un contacte (
defaultWithholdingRate, a/v1/contacts) és el que proposa l'app en triar-lo; l'API no l'aplica sola: enviawithholdingRatea cada esborrany. - Altres errors
422:WITHHOLDING_RATE_OUT_OF_RANGE(tipus fora de 0–50 o amb més de 2 decimals) iWITHHOLDING_EXCEEDS_TOTAL(la retenció deixaria el total a pagar en 0 o menys).
curl -X POST https://api.kullqi.com/v1/invoices \ -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Idempotency-Key: 6c2f8a1d-0b4e-4f7a-9e3c-5d8b1a2c3e4f" \ -H "Content-Type: application/json" \ -d '{ "contactId": 42, "invoiceType": "F1", "withholdingRate": 15, "lines": [ { "description": "Consultoría", "quantity": 1, "unitPrice": 100.00, "taxRate": 21 } ] }' # a la resposta, entre altres camps: { "subtotalAmount": 100.00, "taxAmount": 21.00, "totalAmount": 121.00, "withholdingRate": 15.00, "withholdingAmount": 15.00, "amountDue": 106.00 }
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. |
| POST | /v1/invoices/{id}/rectify | invoices:write | Crear l'esborrany d'una rectificativa de la factura emesa {id}. Exigeix Idempotency-Key. |
| DELETE | /v1/invoices/{id} | invoices:write | Esborrar un esborrany (les factures emeses no s'esborren mai). |
| 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: anul·lar, registrar cobraments, enviar per correu i rectificar per substitució — 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. |
409 | La Idempotency-Key ja s'ha fet servir per a una altra operació, o la factura no és en l'estat necessari (per exemple, esborrar-ne una ja emesa). |
422 | Dades que no compleixen les regles de facturació. El cos porta un code estable (per exemple, RECTIFICATION_EXCEEDS_ORIGINAL) a més del message. |
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