Empezar gratis

La API de factura electrónica de InkVoice

Crea archivos XRechnung y ZUGFeRD a partir de JSON y haz que se comprueben archivos de factura electrónica desde tu propio código. Plan de desarrollador, 19 € al mes, 1000 llamadas a la API incluidas.

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.

Qué hace la API y qué no hace
  • 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 (accept o reject) cuenta, aunque no leas la respuesta. Las llamadas rechazadas o fallidas, las comprobaciones con not_checked y la consulta del uso no cuentan.
  • Una vez agotadas las llamadas incluidas, las siguientes se rechazan con api_call_limit_reached hasta 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

  1. 1
    Contratar 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.

  2. 2
    Crear 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.

  3. 3
    Permitirlo 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.

  4. 4
    Enviar la factura

    Pon la solicitud de factura en invoice.json y el token en la variable de entorno INKVOICE_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-body necesita 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.

RutaCuerpoRespuesta
POST /xrechnungLa solicitud de factura en JSONEl archivo XRechnung, application/xml
POST /zugferdLa solicitud de factura en JSONEl PDF ZUGFeRD, application/pdf
POST /checkEl propio archivo, como application/pdf, application/xml, text/xml o application/octet-streamLo que informó el conjunto de reglas, en JSON
GET /usageNingunoLas llamadas contadas en el periodo más reciente, por ruta, en JSON. No es una llamada a la API
GET /openapi.jsonNingunoLa 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.xml

Con 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.

EstadoCódigoSignificado¿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
413request_too_largeEl 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
422developer_plan_requiredEl espacio de trabajo no tiene un plan de desarrollador activo.No
422api_call_limit_reachedSe han agotado las llamadas incluidas. args.included indica las llamadas incluidas, args.date el último día UTC del periodo.No
422e_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_largeEn /check: el archivo no se puede leer como factura.No
429rate_limitedDemasiadas llamadas. Vuelve a intentarlo tras Retry-After segundos.No
429e_invoice_check_busyEn /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.

Empieza con una cuenta gratuita

El plan de desarrollador se contrata en la configuración de tu espacio de trabajo.

Última actualización: 15 de noviembre de 2026. Este artículo es una orientación general y no constituye asesoramiento fiscal ni jurídico.