Integrate your customers' Veri*Factu invoicing with a REST API.
Contacts, products, series and invoices — the same logic the Kullqi app uses, available over HTTP with an API key. Record chaining and submission to the Spanish Tax Agency apply in exactly the same way, wherever you call it from.
# replace sk_live_... with your own key, generated at 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" }' # response — 201 Created { "id": 42, "type": "CUSTOMER", "legalName": "Comercial Ejemplo SL", "taxId": "B12345674", "archived": false }
Authentication
Every request to /v1/** carries your key in the Authorization header, as a Bearer token. Generate and revoke keys from API keys in your account — only an ADMIN can do this, and the key is shown only once, when it is created (save it then; Kullqi only keeps its hash, never the value).
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Each key has one or more scopes — per-resource permissions, independent of the role of the user who created it. A request to an endpoint without the required scope gets 403 Forbidden.
| Scope | Allows |
|---|---|
| contacts:read | Read and list contacts. |
| contacts:write | Create, update and archive contacts. |
| products:read | Read and list catalogue products. |
| products:write | Create and update products. |
| invoices:read | Read and list invoices, series and their PDFs. |
| invoices:write | Create drafts, issue corrective invoices, delete drafts and issue invoices. |
Invoice lifecycle
Issuing an invoice takes two deliberately separate steps: creating the draft never has any tax effect; issuing it does — it assigns the series number, chains the record and triggers the real submission to the Spanish Tax Agency (Veri*Factu). No endpoint combines both in a single call.
POST /v1/invoices
Creates a draft (status: "DRAFT") with its lines. No number and no tax effect; it can be read and discarded freely. Requires Idempotency-Key — see below.
POST /v1/invoices/{id}/issue
Issues the draft in a series (seriesId). From this point the invoice cannot be changed: number assigned, record chained and submission to the Tax Agency under way.
Mandatory idempotency when creating invoices
POST /v1/invoices requires the Idempotency-Key header — an identifier you generate (for example, one UUID per creation attempt from your system). Repeating the same request with the same key never creates a second draft: it returns the resource that was already created.
Without Idempotency-Key, the request fails with 400 Bad Request before touching anything — it is not optional. A real invoice cannot be undone with a simple DELETE, so a network retry on your side must never be able to duplicate it.
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 } ] }' # first call → 201 Created, id: 17 # repeat EXACTLY the same Idempotency-Key → 200 OK, same id: 17
Corrective invoices (credit notes)
A corrective invoice is created from the issued invoice it corrects, also in two steps: POST /v1/invoices/{id}/rectify creates the draft and it is issued with the same /issue, in a corrective-type series (with number if its numbering is external). Kullqi links the corrected invoice —number, series and date— in the Veri*Factu record automatically.
type:R1–R4for full invoices;R5only for simplified ones (and simplified invoices only withR5).mode:"I"(by differences), the only one available through the API for now. Substitution (correcting the customer's details) is done from the app.lines: the differences, with sign (negative amounts to credit). If omitted, the whole invoice is credited.reason: the reason; it appears on the invoice next to the reference to the original.- Requires
Idempotency-Key, just like creating an invoice. Using the same key for another operation returns409 Conflict. - Across all its corrective invoices, an invoice cannot go negative: trying to credit more than was invoiced returns
422with codeRECTIFICATION_EXCEEDS_ORIGINAL. A corrective invoice cannot itself be corrected: correct the original invoice.
To find the invoice you want to correct by its number, use GET /v1/invoices?q=<number>.
# 1) corrective invoice draft → 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) issue it in the corrective series 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 }'
IRPF withholding tax
If your customer withholds IRPF (Spanish income tax), set the rate on the draft with withholdingRate: a percentage from 0 to 50, with at most 2 decimals (for example 15 or 7). The withholding is calculated on the taxable base of the whole invoice. Without the field, or with 0, the invoice has no withholding.
- The invoice response includes
withholdingRate,withholdingAmount(base × rate / 100, rounded to 2 decimals) andamountDue, the amount payable:totalAmount−withholdingAmount. totalAmountis still base + VAT: it is the amount recorded with the AEAT and in the QR code. For what the customer owes you useamountDue, and for what is still to be collected,amountPending, which already deducts the withholding.- Only on full invoices (
F1) and their corrective invoices (R1–R4). On a simplified invoice (F2),R5orF3, a rate above 0 returns422with codeWITHHOLDING_NOT_ALLOWED_FOR_TYPE. - A corrective invoice inherits the rate of the invoice it corrects; you don't need to send it.
- The rate you save on a contact (
defaultWithholdingRate, in/v1/contacts) is what the app suggests when it is selected; the API does not apply it on its own: sendwithholdingRateon every draft. - Other
422errors:WITHHOLDING_RATE_OUT_OF_RANGE(rate outside 0–50 or with more than 2 decimals) andWITHHOLDING_EXCEEDS_TOTAL(the withholding would leave the amount payable at 0 or less).
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 } ] }' # in the response, among other fields: { "subtotalAmount": 100.00, "taxAmount": 21.00, "totalAmount": 121.00, "withholdingRate": 15.00, "withholdingAmount": 15.00, "amountDue": 106.00 }
Rate limits
Designed for real integrations, not for scraping or replacing normal use of the app.
| Limit | Value |
|---|---|
| Daily quota per account (tenant) | 5,000 requests / calendar day |
| Sustained rate (gateway) | 20 requests / second |
| Maximum burst (gateway) | 40 requests |
Exceeding the daily quota returns 429 Too Many Requests with a { "message": "..." } body; the counter resets at midnight.
Available resources
All routes live under https://api.kullqi.com. The bodies and fields are exactly the same as those used by the Kullqi app itself — nothing simplified or cut down for the public API.
Contacts
| Method | Path | Scope | Description |
|---|---|---|---|
| POST | /v1/contacts | contacts:write | Create a contact (customer or supplier). |
| GET | /v1/contacts | contacts:read | List contacts, with search and pagination. |
| GET | /v1/contacts/{id} | contacts:read | Get a contact. |
| PUT | /v1/contacts/{id} | contacts:write | Update a contact. |
| DELETE | /v1/contacts/{id} | contacts:write | Archive a contact (its history is kept). |
Products
| Method | Path | Scope | Description |
|---|---|---|---|
| POST | /v1/products | products:write | Create a catalogue product or service. |
| GET | /v1/products | products:read | List products, with search and pagination. |
| GET | /v1/products/{id} | products:read | Get a product. |
| PUT | /v1/products/{id} | products:write | Update a product. |
Invoice series
| Method | Path | Scope | Description |
|---|---|---|---|
| GET | /v1/invoice-series | invoices:read | List the available series (needed to issue). |
Read-only in this version of the API: series are created and configured in the app.
Invoices
| Method | Path | Scope | Description |
|---|---|---|---|
| POST | /v1/invoices | invoices:write | Create a draft. Requires Idempotency-Key. |
| POST | /v1/invoices/{id}/issue | invoices:write | Issue the draft — number, record chain and submission to the Tax Agency. |
| POST | /v1/invoices/{id}/rectify | invoices:write | Create a corrective invoice draft for issued invoice {id}. Requires Idempotency-Key. |
| DELETE | /v1/invoices/{id} | invoices:write | Delete a draft (issued invoices are never deleted). |
| GET | /v1/invoices | invoices:read | List invoices, filtered by status, series, dates or contact. |
| GET | /v1/invoices/{id} | invoices:read | Get an invoice, with its hash, QR code and status with the Tax Agency. |
| GET | /v1/invoices/{id}/pdf | invoices:read | Download the PDF with the official verification QR code. |
Not in this version of the API: voiding, recording payments, sending by email and corrections by substitution — for now only from the Kullqi app.
Errors
Standard HTTP status codes. Validation errors specific to /v1 return a simple JSON body: { "message": "..." }.
| Code | Meaning |
|---|---|
400 | Invalid request — for example, Idempotency-Key is missing when creating an invoice. |
401 | Key missing, malformed, revoked or expired. |
403 | The key is valid but lacks the scope required for this route. |
404 | The resource does not exist or does not belong to your account. |
409 | The Idempotency-Key was already used for another operation, or the invoice is not in the required state (for example, deleting one already issued). |
422 | Data that breaks invoicing rules. The body carries a stable code (for example, RECTIFICATION_EXCEEDS_ORIGINAL) in addition to message. |
429 | Daily quota or rate limit exceeded. |
Generate your key and make your first call
It is shown only once, when it is created — copy it then.
Go to API keys