API Verifactu: declara las facturas de tu sistema a través de Kiby

Cada ruta exige un permiso. La clave los recibe al crearla en Ajustes → Claves de API; si le falta el de la ruta, la respuesta es 403 INSUFFICIENT_SCOPE y no se hace nada más.

Son independientes a propósito: invoices:write no abre la pasarela y verifactu:write no deja crear facturas en Kiby. A un sistema que solo declara sus propias facturas no hace falta darle acceso a la numeración de Kiby. Cada operación indica su permiso en su descripción y en la extensión x-kiby-scope.

⚠️ Claves de la pasarela creadas antes de que existiera verifactu:write. Hasta ahora la pasarela se abría con invoices:write. Esas claves reciben verifactu:write automáticamente en la migración que Kiby ejecuta antes de publicar este cambio: no tienes que crear otra. Si aun así una llamada a /v1/verifactu/* te responde 403 INSUFFICIENT_SCOPE, avisa a soporte.

El entorno lo decide el prefijo de la clave, no la URL: kiby_test_ es pruebas y kiby_live_ es producción. Pero «pruebas» significa cosas distintas en cada producto, y confundirlas es caro:

En la pasarela Verifactu, una clave kiby_test_ declara DE VERDAD ante el entorno de pruebas de la AEAT, pero con el NIF de demostración de Kiby, no con el del emisor. Ese NIF lo comparten todos los integradores (ver «En el sandbox de la pasarela, usa una serie propia»), y el QR que devuelve verifica un registro de Kiby: no vale como justificante fiscal de nadie.

En la API de facturación, una clave kiby_test_ NO declara nada a Verifactu. POST /v1/invoices ejecuta el mismo código que en producción —misma validación, mismos totales con la configuración real de la cuenta (serie, IRPF, régimen del cliente), mismo control del orden de fechas contra la serie real— pero:

• la factura no entra en los libros de la cuenta: se guarda aparte, con su propia numeración (un contador de pruebas por serie y año, que no consume números reales);
• no se declara: verifactu.estado es siempre Omitido y la respuesta lleva sandbox: true;
• no se apunta cobro ni se generan vencimientos: con paid: true la factura sale COBRADO, pero sin bloque cobro;
• el cliente se busca en los contactos reales sin tocarlos y después entre los de pruebas; si no está en ninguno, se crea solo entre los de pruebas (con los mismos datos obligatorios que en producción);
• todo se borra solo a los 90 días: la factura, los clientes de pruebas y el registro de idempotencia;
• las consultas con kiby_test_ solo ven las facturas de pruebas, y con kiby_live_ solo las reales;
• exige lo mismo que producción (suscripción al corriente y gema activa) y tiene su propio cupo.

No es trabajo tuyo y no puedes hacerlo por él:

1. Para la API de facturación: activa la gema API de facturación (sin ella, 403 MODULE_NOT_ACTIVE) y tiene al menos una serie de facturas configurada. Si además tiene Verifactu configurado, el alta tiene que estar terminada (si no, 409 TENANT_NOT_READY).
2. Para la pasarela: completa su alta Verifactu en Kiby (credencial y declaración responsable). Sin eso, cualquier petición en producción responde 409 TENANT_NOT_READY.
3. Crea una clave en Ajustes → Claves de API con solo los permisos que necesitas y te la entrega junto con su NIF, que es lo que va en X-Kiby-Tenant.

Las dos cosas exigen que la cuenta esté al corriente de pago (si no, 402).

Tu numeración, tu correlatividad y si el destinatario existe. No somos tu sistema de facturación, y fingir que lo comprobamos sería peor que no hacerlo. La numeración correlativa por serie es una obligación del emisor (RD 1619/2012, art. 6.1.a).

⚠️ Si el emisor además factura dentro de Kiby (a mano o con POST /v1/invoices), los dos canales escriben en la cadena del mismo NIF. Es legal y habitual repartir la facturación en series separadas, pero no reutilicéis en la pasarela un código de serie que use Kiby: cada canal lleva su propio contador y ninguno ve al otro. Ojo con la A, que es la serie que Kiby crea por defecto en toda cuenta nueva.

Se cuentan por cuenta, no por clave: crear más claves no multiplica nada. Cada producto tiene su cupo mensual, y las facturas de pruebas el suyo:

• Al mes cuenta cada petición que sale bien (2xx), consultas incluidas; los errores no gastan cupo. Un lote de la pasarela cuenta una, lleve las facturas que lleve. La pasarela con clave kiby_test_ cuenta en el cupo de la pasarela. Si la cuenta no está al corriente de pago se aplica el tramo Freelance.
• Lo que gastas lo ves en cada respuesta, en X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset (segundos Unix del inicio del mes siguiente, hora de Madrid). Con cupo ilimitado, X-RateLimit-Limit: unlimited y sin las otras dos. Viajan también en las respuestas de error, salvo en las que se cortan antes de mirar el cupo (credencial, permiso o límite por minuto).
• Por minuto cuenta toda petición, salga bien o mal: un bucle con un cuerpo mal formado también lo gasta. Es un único cupo por cuenta para la pasarela y la facturación real; las facturas de pruebas tienen el suyo. Además hay dos topes propios, por debajo del de tu plan: 20 consultas de estado por minuto en la pasarela y 30 consultas de facturas por minuto (GET /v1/invoices, /v1/invoices/{id} y /v1/tenants).
• Si agotas el cupo del mes de la API de facturación, se corta todo (crear y consultar) hasta el mes siguiente o hasta mejorar de plan.
• Si agotas el cupo del mes de la pasarela, no se pueden declarar facturas nuevas, pero consultar, anular y subsanar siguen funcionando: nunca te quedas sin poder corregir una factura que la AEAT ha rechazado.
• Avisamos al titular de la cuenta por correo al llegar al 80, al 90 y al 100 % del cupo.

Con una clave kiby_test_ todos los integradores declaran con el mismo NIF de demostración de Kiby, así que comparten numeración. La AEAT rechaza una factura cuya serie, número y fecha ya consten para ese NIF: si otro integrador probó A / 1 el mismo día que tú, tu registro saldrá rechazado como duplicado aunque tu integración esté bien.

Para que no te pase, usa en el sandbox una serie que solo uses tú —por ejemplo con el nombre de tu empresa: ACME-PRUEBAS— y números que no reutilices. Con la misma serie y número en fechas distintas no hay choque (medido en el entorno de pruebas). En producción esto no aplica: declaras con el NIF del emisor, que es solo suyo. Y en la API de facturación tampoco: allí el número lo pone Kiby.

Todos tienen la misma forma, { "error": { "code", "message", "details"? } }, vengan de donde vengan. Ramifica por code, nunca por el texto de message: los mensajes se reescriben para que sean más claros y no son un contrato. Los códigos sí.

/v1 es estable. Cambios compatibles (pueden llegar sin aviso): campos nuevos en las respuestas, códigos de error nuevos dentro de una familia HTTP ya existente, mensajes reescritos. Diseña tu cliente para tolerarlos: ignora los campos que no conozcas y trata un code desconocido según su familia HTTP.

Cambios incompatibles —quitar o renombrar un campo, cambiar el tipo de uno existente, endurecer una validación— no se hacen sobre /v1: irían a una versión nueva, con las dos conviviendo y un plazo de migración anunciado por correo a los titulares de claves activas.

Authorization: Bearer <clave>. Nunca en la URL: una clave en un parámetro (?api_key=) se rechaza con 401 aunque también venga en la cabecera, porque ya ha quedado en logs y proxies. Rótala.

Cada ruta pide un permiso (ver la tabla de la introducción); si la clave no lo tiene, 403 INSUFFICIENT_SCOPE.

El prefijo de la clave decide el entorno, y es la única cosa que lo decide:

⚠️ Un QR obtenido en el sandbox de la pasarela verifica un registro declarado con el NIF de Kiby, no con el del emisor. Sirve como prueba técnica y no vale como justificante fiscal de nadie. No lo pongas en un PDF que vaya a un cliente real.

En la pasarela la respuesta trae siempre el campo entorno, y en la API de facturación una factura de pruebas trae sandbox: true: un modo de pruebas silencioso es el peor fallo posible de este producto y queremos que se note en cada llamada.