Integra la facturación Veri*Factu de tus clientes con una API REST.
Contactos, productos, series y facturas — la misma lógica que usa la app de Kullqi, disponible por HTTP con clave de API. La cadena de registro y el envío a la AEAT se aplican igual, la llames desde donde la llames.
# sustituye sk_live_... por tu propia clave, generada en 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" }' # respuesta — 201 Created { "id": 42, "type": "CUSTOMER", "legalName": "Comercial Ejemplo SL", "taxId": "B12345674", "archived": false }
Autenticación
Cada petición a /v1/** lleva tu clave en la cabecera Authorization, como token Bearer. Genera y revoca claves desde Claves de API en tu cuenta — solo un ADMIN puede hacerlo, y la clave se muestra una única vez al crearla (guárdala entonces; Kullqi solo conserva su hash, nunca el valor).
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Cada clave lleva uno o varios scopes — permisos por recurso, independientes del rol del usuario que la creó. Una petición a un endpoint sin el scope necesario recibe 403 Forbidden.
| Scope | Permite |
|---|---|
| contacts:read | Leer y listar contactos. |
| contacts:write | Crear, modificar y archivar contactos. |
| products:read | Leer y listar productos del catálogo. |
| products:write | Crear y modificar productos. |
| invoices:read | Leer y listar facturas, series y su PDF. |
| invoices:write | Crear borradores, rectificar, borrar borradores y emitir facturas. |
Ciclo de vida de una factura
Emitir una factura son dos pasos separados a propósito: crear el borrador nunca tiene efecto fiscal; emitirlo sí — asigna número de serie, encadena el registro y dispara el envío real a la AEAT (Veri*Factu). Ningún endpoint combina ambas cosas en una sola llamada.
POST /v1/invoices
Crea un borrador (status: "DRAFT") con sus líneas. Sin número, sin efecto fiscal, se puede leer y descartar libremente. Requiere Idempotency-Key — ver más abajo.
POST /v1/invoices/{id}/issue
Emite el borrador contra una serie (seriesId). A partir de aquí la factura es inalterable: número asignado, registro encadenado y envío a la AEAT en marcha.
Idempotencia obligatoria al crear facturas
POST /v1/invoices exige la cabecera Idempotency-Key — un identificador que generas tú (por ejemplo, un UUID por intento de creación desde tu sistema). Repetir la misma petición con la misma clave nunca crea un segundo borrador: devuelve el mismo recurso ya creado.
Sin Idempotency-Key, la petición falla con 400 Bad Request antes de tocar nada — no es opcional. Una factura de verdad no se puede deshacer con un simple DELETE, así que un reintento de red por tu parte nunca debe poder duplicarla.
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 llamada → 201 Created, id: 17 # repetir EXACTAMENTE la misma Idempotency-Key → 200 OK, mismo id: 17
Rectificativas (abonos)
Una rectificativa se crea desde la factura emitida que corrige, también en dos pasos: POST /v1/invoices/{id}/rectify crea el borrador y se emite con el mismo /issue, en una serie de tipo rectificativa (con number si su numeración es externa). Kullqi enlaza sola la factura rectificada —número, serie y fecha— en el registro Veri*Factu.
type:R1–R4para facturas completas;R5solo para simplificadas (y las simplificadas, solo conR5).mode:"I"(por diferencias), el único disponible por la API de momento. La sustitución (corregir los datos del cliente) se hace desde la app.lines: las diferencias, con signo (importe negativo para abonar). Si no se envían, es un abono total de la factura.reason: el motivo; aparece en la factura junto a la referencia a la original.- Exige
Idempotency-Key, igual que crear una factura. Usar la misma clave para otra operación devuelve409 Conflict. - Entre todas sus rectificativas, una factura no puede quedar en negativo: si se intenta abonar más de lo facturado, la respuesta es
422con el códigoRECTIFICATION_EXCEEDS_ORIGINAL. Una rectificativa no se rectifica: se rectifica la factura original.
Para encontrar por su número la factura que vas a rectificar, usa GET /v1/invoices?q=<número>.
# 1) borrador 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) emitirla en la serie de rectificativas 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ón de IRPF
Si tu cliente te retiene IRPF, indica el tipo en el borrador con withholdingRate: un porcentaje de 0 a 50, con 2 decimales como máximo (por ejemplo 15 o 7). La retención se calcula sobre la base imponible de toda la factura. Sin el campo, o con 0, la factura no lleva retención.
- La respuesta de la factura trae
withholdingRate,withholdingAmount(base × tipo / 100, redondeado a 2 decimales) yamountDue, el total a pagar:totalAmount−withholdingAmount. totalAmountsigue siendo base + IVA: es el importe que se registra en la AEAT y en el QR. Para saber lo que te debe el cliente usaamountDue, y para lo que queda por cobrar,amountPending, que ya descuenta la retención.- Solo en facturas completas (
F1) y en sus rectificativas (R1–R4). En una simplificada (F2),R5oF3, un tipo mayor que 0 devuelve422con el códigoWITHHOLDING_NOT_ALLOWED_FOR_TYPE. - Una rectificativa hereda el tipo de la factura que rectifica; no hace falta enviarlo.
- El tipo que guardes en un contacto (
defaultWithholdingRate, en/v1/contacts) es el que propone la app al elegirlo; la API no lo aplica sola: envíawithholdingRateen cada borrador. - Otros errores
422:WITHHOLDING_RATE_OUT_OF_RANGE(tipo fuera de 0–50 o con más de 2 decimales) yWITHHOLDING_EXCEEDS_TOTAL(la retención dejaría el total a pagar en 0 o menos).
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 } ] }' # en la respuesta, entre otros campos: { "subtotalAmount": 100.00, "taxAmount": 21.00, "totalAmount": 121.00, "withholdingRate": 15.00, "withholdingAmount": 15.00, "amountDue": 106.00 }
Límites de uso
Pensados para integraciones reales, no para scraping ni para sustituir el uso normal de la app.
| Límite | Valor |
|---|---|
| Cuota diaria por cuenta (tenant) | 5.000 peticiones / día natural |
| Ritmo sostenido (gateway) | 20 peticiones / segundo |
| Ráfaga máxima (gateway) | 40 peticiones |
Superar la cuota diaria devuelve 429 Too Many Requests con un cuerpo { "message": "..." }; el contador se reinicia a medianoche.
Recursos disponibles
Todas las rutas cuelgan de https://api.kullqi.com. Los cuerpos y campos son exactamente los mismos que usa la propia app de Kullqi — nada simplificado ni recortado para la API pública.
Contactos
| Método | Ruta | Scope | Descripción |
|---|---|---|---|
| POST | /v1/contacts | contacts:write | Crear un contacto (cliente o proveedor). |
| GET | /v1/contacts | contacts:read | Listar contactos, con búsqueda y paginación. |
| GET | /v1/contacts/{id} | contacts:read | Obtener un contacto. |
| PUT | /v1/contacts/{id} | contacts:write | Actualizar un contacto. |
| DELETE | /v1/contacts/{id} | contacts:write | Archivar un contacto (no se elimina el histórico). |
Productos
| Método | Ruta | Scope | Descripción |
|---|---|---|---|
| POST | /v1/products | products:write | Crear un producto o servicio del catálogo. |
| GET | /v1/products | products:read | Listar productos, con búsqueda y paginación. |
| GET | /v1/products/{id} | products:read | Obtener un producto. |
| PUT | /v1/products/{id} | products:write | Actualizar un producto. |
Series de facturación
| Método | Ruta | Scope | Descripción |
|---|---|---|---|
| GET | /v1/invoice-series | invoices:read | Listar las series disponibles (necesarias para emitir). |
Solo lectura en esta versión de la API: las series se crean y configuran desde la app.
Facturas
| Método | Ruta | Scope | Descripción |
|---|---|---|---|
| POST | /v1/invoices | invoices:write | Crear un borrador. Exige Idempotency-Key. |
| POST | /v1/invoices/{id}/issue | invoices:write | Emitir el borrador — número, cadena de registro y envío a la AEAT. |
| POST | /v1/invoices/{id}/rectify | invoices:write | Crear el borrador de una rectificativa de la factura emitida {id}. Exige Idempotency-Key. |
| DELETE | /v1/invoices/{id} | invoices:write | Borrar un borrador (las facturas emitidas no se borran nunca). |
| GET | /v1/invoices | invoices:read | Listar facturas, con filtros por estado, serie, fechas, contacto. |
| GET | /v1/invoices/{id} | invoices:read | Obtener una factura, con su hash, QR y estado ante la AEAT. |
| GET | /v1/invoices/{id}/pdf | invoices:read | Descargar el PDF con el QR de verificación oficial. |
Fuera de esta versión de la API: anular, registrar cobros, enviar por email y rectificar por sustitución — de momento solo desde la app de Kullqi.
Errores
Códigos HTTP estándar. Los errores de validación propios de /v1 devuelven un cuerpo JSON simple: { "message": "..." }.
| Código | Significado |
|---|---|
400 | Petición inválida — por ejemplo, falta Idempotency-Key en la creación de una factura. |
401 | Clave ausente, mal formada, revocada o expirada. |
403 | La clave es válida pero no tiene el scope necesario para esta ruta. |
404 | El recurso no existe o no pertenece a tu cuenta. |
409 | La Idempotency-Key ya se usó para otra operación, o la factura no está en el estado necesario (por ejemplo, borrar una ya emitida). |
422 | Datos que no cumplen las reglas de facturación. El cuerpo lleva un code estable (por ejemplo, RECTIFICATION_EXCEEDS_ORIGINAL) además del message. |
429 | Cuota diaria o límite de ritmo superado. |
Genera tu clave y haz tu primera llamada
Se muestra una sola vez al crearla — cópiala en ese momento.
Ir a Claves de API