Crea archivos XRechnung y ZUGFeRD y haz que se comprueben archivos de factura electrónica desde tu propio software, con un token de acceso personal.
- POST /xrechnung genera un archivo XRechnung 3.0 (sintaxis CII, EN 16931), la versión que cubre la configuración XRechnung 3.0.2, y lo devuelve como application/xml.
- POST /zugferd genera un PDF ZUGFeRD 2.x (perfil EN 16931) con el XML incrustado y sin mención de InkVoice en la página.
- POST /check lee un PDF ZUGFeRD o Factur-X, o un archivo XML XRechnung, CII o UBL, enviado tal cual como cuerpo de la solicitud (application/pdf, application/xml, text/xml, application/octet-stream; los demás tipos reciben 415).
- GET /usage informa de las llamadas contadas en el periodo más reciente (el actual mientras el plan está activo), por ruta. Consultarlo no es una llamada a la API.
- Enviar una factura a su destinatario, ni archivarla por ti.
- Comprobar un archivo al crearlo.
- Crear facturas rectificativas o abonos, varios tipos de IVA en una factura, entregas intracomunitarias (K), exportaciones (G), ni descuentos y recargos a nivel de documento.
- Dar asesoramiento fiscal o jurídico.
El plan de desarrollador
El plan de desarrollador cuesta 19 € al mes e incluye 1000 llamadas a la API por periodo para el espacio de trabajo. InkVoice es un Kleinunternehmer (pequeña empresa) según el § 19 UStG y no cobra IVA, así que el precio es el precio final.
- Una llamada que devolvió un archivo o un veredicto (
acceptoreject) cuenta, aunque no leas la respuesta. Las llamadas rechazadas o fallidas, las comprobaciones connot_checkedy la consulta del uso no cuentan. - Una vez agotadas las llamadas incluidas, las siguientes se rechazan con
api_call_limit_reachedhasta que empieza el siguiente periodo. Las llamadas que se ejecutan a la vez pueden superar el límite. Las llamadas no usadas caducan al final del periodo, y no se cobra nada por llamada. - Cuando el plan se renueva, las llamadas no usadas del periodo anterior siguen disponibles hasta que Stripe haya comunicado a InkVoice el nuevo periodo, como máximo hasta 3 días después de que empiece el nuevo; una llamada en ese tiempo cuenta para ambos periodos.
- No hay prueba gratuita.
El propietario del espacio de trabajo contrata el plan en la configuración del espacio de trabajo y paga a través de Stripe. El plan de desarrollador es independiente del plan del espacio de trabajo (gratuito, Pro o Master): contratar, cambiar, cancelar o terminar uno no afecta al otro. Los planes de pago solo pueden contratarlos clientes cuyo domicilio social, residencia o establecimiento para el que se contrata el plan esté en Alemania.
Tu primera llamada
- 1Contratar el plan de desarrollador
El propietario del espacio de trabajo contrata el plan en la configuración del espacio de trabajo y paga a través de Stripe.
- 2Crear un token de acceso
Crea un token de acceso en «Tokens de acceso» con «Lectura y escritura». El token se muestra una sola vez, al crearlo.
- 3Permitirlo para la API
Un token funciona con la API solo después de que el propietario del espacio de trabajo active «Permitir la API para desarrolladores» para él en «Tokens de acceso». Esta opción no está activada de entrada para ningún token.
- 4Enviar la factura
Pon la solicitud de factura en
invoice.jsony el token en la variable de entornoINKVOICE_TOKEN, y envíala a/xrechnung. La respuesta es el archivo XRechnung. Si hay un error, curl termina con un código de salida distinto de 0, y el archivo contiene el cuerpo del error, si lo tiene (véase «Errores»);--fail-with-bodynecesita curl 7.76 o posterior.curl --fail-with-body -X POST https://api.inkvoice.net/api/v1/xrechnung \ -H "Authorization: Bearer $INKVOICE_TOKEN" \ -H "Content-Type: application/json" \ --data @invoice.json -o xrechnung.xml
Rutas
Todas las rutas están bajo https://api.inkvoice.net/api/v1. Cada llamada, salvo openapi.json, necesita un token de acceso personal como Authorization: Bearer inkv_…. No se acepta un inicio de sesión web, y los navegadores no pueden llamar a la API (sin CORS). Crear y comprobar necesitan un token con «Lectura y escritura»; un token de solo lectura solo puede consultar el uso.
| Ruta | Cuerpo | Respuesta |
|---|---|---|
POST /xrechnung | La solicitud de factura en JSON | El archivo XRechnung, application/xml |
POST /zugferd | La solicitud de factura en JSON | El PDF ZUGFeRD, application/pdf |
POST /check | El propio archivo, como application/pdf, application/xml, text/xml o application/octet-stream | Lo que informó el conjunto de reglas, en JSON |
GET /usage | Ninguno | Las llamadas contadas en el periodo más reciente, por ruta, en JSON. No es una llamada a la API |
GET /openapi.json | Ninguno | La descripción de la API, OpenAPI 3.1, legible sin token |
La solicitud de factura
La solicitud es JSON de como máximo 512 KiB, con number, issueDate, dueDate, currency, taxRate, taxCategoryCode, seller, buyer y lines (dueDate no anterior a la fecha de emisión). El vendedor y el comprador necesitan cada uno un name y un email (la dirección electrónica que exige XRechnung), y el vendedor un taxNumber (NIF-IVA o número fiscal). taxRate es mayor que 0 para S y 0 para Z, E y AE. taxExemptionReason es obligatorio para E y AE y se rechaza para S y Z. Para AE, el comprador también necesita un NIF-IVA en taxNumber (BT-48). /xrechnung también exige buyerReference (BT-10) e iban (BR-DE-1), que son opcionales en /zugferd. Si se omite deliveryDate, se indica la fecha de emisión como fecha de entrega. En /check, un cuerpo de más de 8 MiB recibe 413 request_too_large, y un archivo XML, o el XML dentro de un PDF, de más de 512 KiB recibe 422 e_invoice_file_xml_too_large.
{
"number": "2026-0001",
"issueDate": "2026-11-16",
"dueDate": "2026-11-30",
"currency": "EUR",
"taxRate": 19,
"taxCategoryCode": "S",
"buyerReference": "04011000-1234512345-06",
"iban": "DE02120300000000202051",
"seller": {
"name": "Muster GmbH",
"email": "rechnung@example.com",
"addressLine": "Musterstraße 1",
"postalCode": "10115",
"city": "Berlin",
"country": "DE",
"taxNumber": "DE123456789"
},
"buyer": {
"name": "Beispiel AG",
"email": "eingang@example.com",
"addressLine": "Beispielweg 2",
"postalCode": "20095",
"city": "Hamburg",
"country": "DE"
},
"lines": [
{
"description": "Beratung",
"quantity": 8,
"unitPrice": 95
}
]
}Cada miembro, obligatorio u opcional, se describe en la descripción de la API.
Qué informa la comprobación
La comprobación ejecuta, dentro de InkVoice, la configuración XRechnung de KoSIT (KoSIT rules, XRechnung 3.0.2 (2026-08-31)) y las reglas ZF_250 de FeRD (ZUGFeRD rules, ZF_250, 1.09.2 (2026-08-04)). Cuando también se ejecutó la hoja de estilo EN 16931 CII de CEN, la configuración termina en , EN 16931 CII 1.3.16. No ejecuta el KoSIT Prüftool ni Mustang, y no prueba si un PDF cumple la norma PDF/A. El campo validator de la respuesta nombra el conjunto de reglas y la versión que juzgaron el archivo.
Los conjuntos de reglas siguen las versiones que fija InkVoice, y un cambio se anuncia en openapi.json. Esta página indica las versiones actuales.
accept o reject dice lo que ese conjunto de reglas informó sobre el archivo, con sus mensajes. No dice que la factura cumpla los requisitos legales ni que un destinatario vaya a aceptarla. not_checked, con un notCheckedReason, significa que ningún conjunto de reglas juzgó el archivo.
curl --fail-with-body -X POST https://api.inkvoice.net/api/v1/check \
-H "Authorization: Bearer $INKVOICE_TOKEN" \
-H "Content-Type: application/xml" \
--data-binary @xrechnung.xmlCon qué se prueban los archivos creados
Los archivos creados no se comprueban al crearlos. Envía uno a /check para que se compruebe; eso es una llamada a la API. Los archivos los genera el código del generador gratuito de InkVoice: el XML es el del generador gratuito para la misma factura, y el PDF incrusta ese XML sin línea de mención. En la batería de pruebas del generador gratuito, cada escenario de las tablas de prueba (combinaciones por pares, para cada perfil) lo acepta el KoSIT Prüftool 1.6.3 con la configuración XRechnung 3.0.2 (2026-08-31), y Mustang 2.26.0 como EN 16931 en PDF/A-3b. Ambos se ejecutan como herramientas aparte en las pruebas, no en la API.
La API no puede crear facturas rectificativas ni abonos, varios tipos de IVA en una factura, entregas intracomunitarias (K), exportaciones (G), ni descuentos y recargos a nivel de documento. Una factura tiene una sola categoría de IVA (S, Z, E o AE) y un solo tipo para todas las líneas. La batería de pruebas no cubre texto en sistemas de escritura sin fuente incluida. Los importes se escriben con dos decimales en todas las monedas; para JPY y KWD, la batería muestra que los conjuntos de reglas lo aceptan, no que sea la unidad fraccionaria de la moneda.
Errores
Un rechazo con código tiene el cuerpo { error, code, args }; error es un texto fijo en inglés, así que compara por code.
| Estado | Código | Significado | ¿Cuenta? |
|---|---|---|---|
| 400 | – | La solicitud tiene errores. El cuerpo es { errors: [...] }, que nombra rutas como seller.name. | No |
| 401 | – | Sin token de acceso, o con uno que no se acepta. Sin cuerpo. | No |
| 403 | – | La API no está permitida para el token («Permitir la API para desarrolladores», paso 3), o un token de solo lectura llamó a una ruta de creación o de comprobación. Sin cuerpo. | No |
| 404 | – | La API está desactivada, o la ruta no existe. | No |
| 413 | request_too_large | El cuerpo es mayor de lo que acepta la ruta. | No |
| 415 | – | El cuerpo tiene un tipo de contenido que la ruta no lee. Sin cuerpo. | No |
| 422 | developer_plan_required | El espacio de trabajo no tiene un plan de desarrollador activo. | No |
| 422 | api_call_limit_reached | Se han agotado las llamadas incluidas. args.included indica las llamadas incluidas, args.date el último día UTC del periodo. | No |
| 422 | e_invoice_file_empty, e_invoice_file_encrypted, e_invoice_file_no_invoice_xml, e_invoice_file_not_an_invoice, e_invoice_file_not_xml, e_invoice_file_number_out_of_range, e_invoice_file_older_zugferd, e_invoice_file_several_invoice_xml, e_invoice_file_too_complex, e_invoice_file_too_large, e_invoice_file_unreadable, e_invoice_file_xml_too_large | En /check: el archivo no se puede leer como factura. | No |
| 429 | rate_limited | Demasiadas llamadas. Vuelve a intentarlo tras Retry-After segundos. | No |
| 429 | e_invoice_check_busy | En /check: demasiadas comprobaciones a la vez. Vuelve a intentarlo tras Retry-After segundos. | No |
Límites
La API limita cuántas llamadas pueden hacer un token, un espacio de trabajo y una dirección por minuto y a la vez. Por encima de un límite responde 429 con Retry-After en segundos, y la llamada no cuenta. No hay ninguna promesa de disponibilidad, tiempo de respuesta ni rendimiento.
Descripción de la API y versiones
La descripción de la API es OpenAPI 3.1 en https://api.inkvoice.net/api/v1/openapi.json, legible sin token. La v1 solo cambia añadiendo (nuevos miembros opcionales, rutas o códigos); cualquier otro cambio pasa a /api/v2.
Condiciones
Se aplican las AGB (condiciones generales, Ziffer 4a), el anexo «Entwickler-API» (API para desarrolladores) del AVV (contrato de encargo del tratamiento) y la Datenschutzerklärung (política de privacidad). Esta página traduce la Leistungsbeschreibung (descripción del servicio) prevista en la Ziffer 4a (apartado 4a) de las AGB; la página en alemán es la vinculante.
El plan de desarrollador se contrata en la configuración de tu espacio de trabajo.