Ir al contenido

Alemania — E-INVOICE DE (Unified API)

En Alemania, fiskaly admite el envío y la recepción de facturas electrónicas B2B. La facturación electrónica está regulada por el Ministerio Federal de Finanzas (BMF — Bundesministerium der Finanzen). Todas las facturas electrónicas deben cumplir con la EN 16931, que se satisface mediante formatos como XRechnung, ZUGFeRD o Peppol BIS 3.0 Billing. fiskaly no archiva las facturas electrónicas alemanas: consulte Archivo.

fiskaly genera facturas electrónicas conformes con la EN 16931 y las entrega a través de uno de dos canales. El canal se elige por factura en el destinatario (recipients[].invoicing): por correo electrónico — como ZUGFeRD o XRechnung — o a través de la red PEPPOL, como XRechnung.

Las dos direcciones se configuran de forma distinta:

Esta página cubre los requisitos específicos de Alemania que complementan la Integración general paso a paso. Asegúrate de tener a mano la siguiente información del contribuyente antes de continuar:

  • fiscalization.vat_id_number — Número de identificación fiscal a efectos del IVA (Umsatzsteuer-ID), 9 dígitos sin el prefijo DE
  • fiscalization.tax_id_number — Número de identificación fiscal personal (Steuer-ID), 11 dígitos. Obligatorio para Taxpayers de tipo INDIVIDUAL.
  • name — Nombre legal registrado y nombre comercial de la empresa o de la persona física
  • address — Domicilio social registrado de la empresa o de la persona física

Envío de facturas electrónicas: requisitos del destinatario

Sección titulada «Envío de facturas electrónicas: requisitos del destinatario»

Para enviar una factura electrónica, indicas el destinatario y cómo debe llegarle el documento directamente en el registro de la factura. Cuando creas la factura (TRANSACTION::INVOICE) con createRecord, añades el destinatario a su array recipients.

Como explica la Integración general paso a paso, cada destinatario debe ser de tipo BUSINESS y tener el bloque invoicing completado. Además de los datos estándar de toda factura electrónica (nombre, dirección e identificación fiscal del destinatario, líneas de factura, etc.), en Alemania se añade el canal de entrega en el propio destinatario:

  • recipients[].type = BUSINESS
  • recipients[].identification.type = VAT — la factura electrónica alemana identifica al comprador por su número de IVA
  • recipients[].address.country = DE — los destinatarios deben estar en Alemania
  • recipients[].invoicing.type = EMAIL o PEPPOL — el canal de entrega
  • recipients[].invoicing.email — (solo EMAIL) la dirección de correo electrónico del destinatario
  • recipients[].invoicing.format — (solo EMAIL, opcional) el formato del documento
  • recipients[].invoicing.identifier — (solo PEPPOL) el PEPPOL Network Identifier del destinatario, en la forma <código de esquema>:<valor> — normalmente 9930:<número de IVA> para una empresa alemana
invoicing.typeTambién obligatorioCómo lo entrega fiskaly
EMAILinvoicing.emailPor correo electrónico a esa dirección, como ZUGFeRD o XRechnung según invoicing.format.
PEPPOLinvoicing.identifierAl punto de acceso PEPPOL del destinatario, como XRechnung — consulte la limitación de XRechnung.

El canal se elige por factura, no de forma fija para cada destinatario — la misma empresa puede recibir una factura por correo electrónico y la siguiente a través de PEPPOL.

Cada entrada de payments es un pago ya recibido (CASH, CARD, ONLINE, VOUCHER, OTHER) o el importe aún pendiente (OUTSTANDING). Los pagos recibidos aparecen en la factura como importe ya pagado, y la fecha de la entrada OUTSTANDING pasa a ser la fecha de vencimiento de la factura. Para una factura pagada por completo, omita OUTSTANDING.

Todo pago necesita type y details.amount. Algunos tipos necesitan más:

typeTambién obligatorio
CASH—
CARDnumber (número de tarjeta enmascarado, por ejemplo ************1234) y kind
ONLINEname, por ejemplo el proveedor de pagos
VOUCHERnumber y kind
OTHER— (name es opcional)
OUTSTANDINGconcept (GOOD, SERVICE o INVOICE) y details.date, la fecha de vencimiento

concept solo se acepta en OUTSTANDING. En cualquier otro tipo de pago, la solicitud se rechaza con 400.

En Alemania, el registro en la red PEPPOL es opcional: decides activarlo System por System.

Indícalo en el System E_INVOICE_SERVICE con createSystem:

{
"content": {
"type": "E_INVOICE_SERVICE",
"location": { "id": "..." },
"software": { "...": "..." },
"registrations": [{ "type": "PEPPOL" }]
}
}

O añádelo a un System existente con updateSystem:

{
"content": {
"registrations": [{ "type": "PEPPOL" }]
}
}

Lo que se deriva de esa elección:

  • registrations omitido — el System solo envía por correo electrónico. No interviene ningún Proof of Ownership y el System pasa directamente al modo OPERATIVE.
  • registrations incluye PEPPOL — se requiere un Proof of Ownership. Al ponerlo en servicio, el state del System pasa a COMMISSIONED pero su mode pasa a DEGRADED, y el System incluye una entrada de registro que indica que falta el Proof of Ownership.

Para llevar el System al modo OPERATIVE, sube el Proof of Ownership como se describe en el paso 11 de la guía general de integración. La verificación tarda hasta 72 horas; cuando termina, el System cambia de estado automáticamente y la entrada de registro se elimina. El contenido que debe mostrar el documento se describe en la sección Proof of Ownership.

En el destinatario de tu solicitud createRecord, establece:

  • recipients[].invoicing.type = PEPPOL
  • recipients[].invoicing.identifier — el PEPPOL Network Identifier del destinatario

Antes de usarlo hacen falta dos cosas: tu System E_INVOICE_SERVICE debe estar registrado en la red PEPPOL (consulta Registro en PEPPOL) y debes disponer del PEPPOL Network Identifier del destinatario. Del esquema del identificador se encarga fiskaly.

Las facturas enviadas por esta vía se generan como XRechnung. recipients[].invoicing.format no interviene aquí: en este canal el formato no es seleccionable.

Envío por correo electrónico: elegir el formato del documento

Sección titulada «Envío por correo electrónico: elegir el formato del documento»

Cuando el canal es EMAIL, decides qué formato de documento genera fiskaly. Indícalo en el mismo destinatario de tu solicitud createRecord, mediante recipients[].invoicing.format:

ValorFormato
ZUGFERD_V2 (predeterminado)ZUGFeRD — un documento híbrido: un PDF/A-3 legible por personas con el XML estructurado incrustado en su interior.
XRECHNUNG_V3XRechnung — una factura XML puramente estructurada, sin capa PDF.

El campo es opcional: si lo omites, fiskaly genera ZUGFERD_V2. Ambos formatos cumplen con la EN 16931.

fiskaly envía el correo en nombre del vendedor, desde no-reply.e-invoicing@fiskaly.com. El asunto es «Your Invoice» y el texto está en inglés. El correo indica el vendedor y remite al destinatario al vendedor para cualquier consulta sobre la factura.

El correo se envía justo después de crear la factura (el procesamiento es asíncrono, ver más abajo). No hay un disparador de envío separado: para retrasar la entrega, retrasa la llamada a createRecord.

La factura se adjunta como invoice_<id>.xml (XRechnung) o invoice_<id>.pdf (ZUGFeRD), donde <id> es el ID del Record E_INVOICE::TRANSMISSION.

Toda factura enviada por PEPPOL se genera como XRechnung, al igual que toda factura por correo con XRECHNUNG_V3. XRechnung exige dos campos que ZUGFeRD no exige:

CampoRegla de XRechnungValor
document.references.buyerBR-DE-15De 1 a 32 caracteres: letras, dígitos, espacios y . - _ /. Obligatorio en toda factura, no solo para compradores del sector público.
seller.phoneBR-DE-6Teléfono de contacto del vendedor en formato E.164, por ejemplo +49301234567.

Cada factura requiere dos llamadas a createRecord, como se describe en el paso 12 de la guía de integración general: una INTENTION y después una TRANSACTION::INVOICE que la referencia. Envíe cada llamada con una nueva clave de idempotencia. Sustituya los ID y los valores por los suyos.

Intention
{
"content": {
"type": "INTENTION",
"system": {
"id": "<E_INVOICE_SERVICE System ID>"
},
"operation": {
"type": "TRANSACTION"
}
}
}
Factura por correo como ZUGFeRD
{
"content": {
"type": "TRANSACTION",
"record": {
"id": "<INTENTION Record ID>"
},
"operation": {
"type": "INVOICE",
"document": {
"number": "RE-2026-0001",
"issued_at": "2026-10-05T10:00:00+02:00"
},
"entries": [
{
"type": "SALE",
"data": {
"type": "ITEM",
"text": "Consulting service",
"unit": {
"quantity": "2",
"price": {
"exclusive": "100.00",
"inclusive": "119.00"
}
},
"value": {
"base": "200.00"
},
"vat": {
"type": "VAT_RATE",
"code": "STANDARD",
"percentage": "19.00",
"amount": "38.00",
"exclusive": "200.00",
"inclusive": "238.00"
}
},
"details": {
"concept": "SERVICE"
}
}
],
"recipients": [
{
"type": "BUSINESS",
"name": "Beispiel GmbH",
"address": {
"line": {
"type": "STREET_NUMBER",
"street": "Alexanderplatz",
"number": "1"
},
"code": "10178",
"city": "Berlin",
"country": "DE"
},
"identification": {
"type": "VAT",
"number": "369204173"
},
"invoicing": {
"type": "EMAIL",
"email": "invoices@beispiel-gmbh.de",
"format": "ZUGFERD_V2"
}
}
],
"payments": [
{
"type": "OUTSTANDING",
"details": {
"amount": "238.00",
"currency": "EUR",
"date": "2026-11-04"
},
"concept": "SERVICE"
}
],
"breakdown": [
{
"type": "VAT_RATE",
"code": "STANDARD",
"percentage": "19.00",
"amount": "38.00",
"exclusive": "200.00",
"inclusive": "238.00"
}
],
"totals": {
"vat": {
"amount": "38.00",
"exclusive": "200.00",
"inclusive": "238.00"
}
}
}
}
}
Factura por correo como XRechnung
{
"content": {
"type": "TRANSACTION",
"record": {
"id": "<INTENTION Record ID>"
},
"operation": {
"type": "INVOICE",
"document": {
"number": "RE-2026-0001",
"issued_at": "2026-10-05T10:00:00+02:00",
"references": {
"buyer": "PO-4711"
}
},
"seller": {
"name": "Max Mustermann",
"phone": "+49301234567",
"email": "billing@example-seller.de"
},
"entries": [
{
"type": "SALE",
"data": {
"type": "ITEM",
"text": "Consulting service",
"unit": {
"quantity": "2",
"price": {
"exclusive": "100.00",
"inclusive": "119.00"
}
},
"value": {
"base": "200.00"
},
"vat": {
"type": "VAT_RATE",
"code": "STANDARD",
"percentage": "19.00",
"amount": "38.00",
"exclusive": "200.00",
"inclusive": "238.00"
}
},
"details": {
"concept": "SERVICE"
}
}
],
"recipients": [
{
"type": "BUSINESS",
"name": "Beispiel GmbH",
"address": {
"line": {
"type": "STREET_NUMBER",
"street": "Alexanderplatz",
"number": "1"
},
"code": "10178",
"city": "Berlin",
"country": "DE"
},
"identification": {
"type": "VAT",
"number": "369204173"
},
"invoicing": {
"type": "EMAIL",
"email": "invoices@beispiel-gmbh.de",
"format": "XRECHNUNG_V3"
}
}
],
"payments": [
{
"type": "OUTSTANDING",
"details": {
"amount": "238.00",
"currency": "EUR",
"date": "2026-11-04"
},
"concept": "SERVICE"
}
],
"breakdown": [
{
"type": "VAT_RATE",
"code": "STANDARD",
"percentage": "19.00",
"amount": "38.00",
"exclusive": "200.00",
"inclusive": "238.00"
}
],
"totals": {
"vat": {
"amount": "38.00",
"exclusive": "200.00",
"inclusive": "238.00"
}
}
}
}
}
Factura por PEPPOL (XRechnung)
{
"content": {
"type": "TRANSACTION",
"record": {
"id": "<INTENTION Record ID>"
},
"operation": {
"type": "INVOICE",
"document": {
"number": "RE-2026-0001",
"issued_at": "2026-10-05T10:00:00+02:00",
"references": {
"buyer": "PO-4711"
}
},
"seller": {
"name": "Max Mustermann",
"phone": "+49301234567",
"email": "billing@example-seller.de"
},
"entries": [
{
"type": "SALE",
"data": {
"type": "ITEM",
"text": "Consulting service",
"unit": {
"quantity": "2",
"price": {
"exclusive": "100.00",
"inclusive": "119.00"
}
},
"value": {
"base": "200.00"
},
"vat": {
"type": "VAT_RATE",
"code": "STANDARD",
"percentage": "19.00",
"amount": "38.00",
"exclusive": "200.00",
"inclusive": "238.00"
}
},
"details": {
"concept": "SERVICE"
}
}
],
"recipients": [
{
"type": "BUSINESS",
"name": "Beispiel GmbH",
"address": {
"line": {
"type": "STREET_NUMBER",
"street": "Alexanderplatz",
"number": "1"
},
"code": "10178",
"city": "Berlin",
"country": "DE"
},
"identification": {
"type": "VAT",
"number": "369204173"
},
"invoicing": {
"type": "PEPPOL",
"identifier": "9930:DE369204173"
}
}
],
"payments": [
{
"type": "OUTSTANDING",
"details": {
"amount": "238.00",
"currency": "EUR",
"date": "2026-11-04"
},
"concept": "SERVICE"
}
],
"breakdown": [
{
"type": "VAT_RATE",
"code": "STANDARD",
"percentage": "19.00",
"amount": "38.00",
"exclusive": "200.00",
"inclusive": "238.00"
}
],
"totals": {
"vat": {
"amount": "38.00",
"exclusive": "200.00",
"inclusive": "238.00"
}
}
}
}
}

El envío es asíncrono. createRecord responde en cuanto se acepta la TRANSACTION::INVOICE, y la factura y su transmisión se procesan después. No hay webhooks para esto, así que consulte el estado con retrieveRecord. Cada Record muestra su progreso en mode: PROCESSING mientras el procesamiento está en curso y FINISHED cuando ha terminado. state contiene entonces el resultado.

Cuando la TRANSACTION::INVOICE está en FINISHED, COMPLETED no significa por sí solo que la factura se haya enviado. Compruebe que sus logs no contengan ninguna entrada con "severity": "ERROR" y que used_in esté presente.

used_in.id es el Record E_INVOICE::TRANSMISSION. Consúltelo hasta que su mode sea FINISHED. Su state indica el resultado:

  • COMPLETED: la factura se ha entregado para su envío.
  • FAILED: la factura no se ha entregado. El motivo figura en los logs del Record.

En el caso del correo, COMPLETED significa que la factura se ha entregado a la pasarela de correo de fiskaly. No es posible confirmar la entrega en el buzón del destinatario, y los rebotes posteriores no se reflejan en el Record.

Si la pasarela de correo rechaza un correo de forma permanente, la transmisión termina en FAILED de inmediato. Los errores temporales se reintentan en segundo plano, por lo que la transmisión puede permanecer en PROCESSING durante un tiempo. Solo termina en FAILED cuando se agotan todos los reintentos.

Una factura fallida no se ha emitido. Envíela de nuevo como una nueva TRANSACTION::INVOICE (nueva INTENTION, nueva clave de idempotencia) con el mismo número de factura, no como CORRECTION. Para corregir una factura que ya ha llegado al comprador, emita una nota de crédito.

Para más detalles, consulte el artículo de soporte How to detect and handle failed invoices (en inglés).

Qué veCausa
Log ERROR either party.telephones or party.people[0].telephones is required (BR-DE-6), no se envía nadaXRechnung sin seller.phone
Log ERROR en la TRANSACTION::INVOICE, sin used_in, no se envía nadaXRechnung sin document.references.buyer
400 en createRecorddocument.references.buyer vacío u otro error de esquema
receiver does not support document typeDestinatario PEPPOL no registrado para XRechnung: consulte Envío por PEPPOL
422 Unprocessable Content en la puesta en servicioTaxpayer sin vat_id_number

Llame a retrieveRecord sobre la E_INVOICE::TRANSMISSION (used_in.id) con compliance-artifact para obtener la factura electrónica generada. La respuesta es un sobre JSON. Para XRechnung, content.compliance.artifact es:

{ "type": "application/xml", "data": "<base64>" }

Para ZUGFeRD, content.compliance.artifact es el PDF/A-3 con el XML incrustado:

{ "type": "application/pdf", "data": "<base64>" }

La guía Nota de crédito explica cuándo y cómo emitir una nota de crédito. Esta sección solo cubre lo que es específico de Alemania.

Una nota de crédito es un documento completo por sí mismo y no toma ningún dato de la factura original. Envía el mismo destinatario, canal y formato que en la factura. Para XRechnung, vuelve a enviar también seller.phone, seller.email y document.references.buyer. Sin ellos, no se envía nada y el record recibe un log ERROR (BR-DE-6, BR-DE-7, BR-DE-15).

Pagos en notas de crédito y facturas de anulación

Sección titulada «Pagos en notas de crédito y facturas de anulación»

En una nota de crédito, y en una factura que anula una nota de crédito (factura de anulación), payments describe lo que sigue pendiente en ese documento:

  • Parte liquidada: type: OTHER con details.amount y details.currency, sin fecha.
  • Importe pendiente de pago: type: OUTSTANDING con concept, details.amount, details.currency y details.date, la fecha de vencimiento (obligatoria).

La factura electrónica muestra la parte liquidada como ya pagada y el resto como pendiente de pago hasta la fecha de vencimiento. Ambos tipos se pueden combinar, tanto en notas de crédito como en facturas.

DocumentoSituaciónpayments
Nota de créditoReembolso ya pagado al clienteOTHER = importe abonado
Nota de créditoReembolso aún por pagarOUTSTANDING con fecha de vencimiento
Nota de créditoReembolso parcialOTHER (parte reembolsada) + OUTSTANDING (resto)
Factura de anulaciónReembolso pagado por completo, el cliente lo devuelveOUTSTANDING = importe total
Factura de anulaciónParte del reembolso pagada (p. ej., 50,00 de 119,00)OTHER 69.00 + OUTSTANDING 50.00
Factura de anulaciónNo se pagó nada, los documentos se compensanOTHER = importe total
Ejemplo: factura de anulación, parte del reembolso pagada
"payments": [
{
"type": "OTHER",
"details": {
"amount": "69.00",
"currency": "EUR"
}
},
{
"type": "OUTSTANDING",
"concept": "SERVICE",
"details": {
"amount": "50.00",
"currency": "EUR",
"date": "2026-11-30"
}
}
]

La recepción de facturas entrantes se realiza a través de PEPPOL, por lo que depende del mismo registro en PEPPOL que el envío por PEPPOL — incluido un Proof of Ownership verificado. Un Taxpayer que solo envía por correo electrónico no puede recibir.

Cuando registras un Taxpayer alemán en PEPPOL, fiskaly lo registra por defecto tanto para enviar como para recibir. Las facturas entrantes dirigidas al PEPPOL Identifier del System se asocian a ese System, y fiskaly crea para cada una un Record de tipo E_INVOICE::RECEPTION.

Llama a retrieveSystem para leer compliance.state:

  • TRANSMISSION_RECEPTION — el System puede enviar y recibir.
  • TRANSMISSION_ONLY — el System solo puede enviar.

Cada factura dirigida a tu Taxpayer se recibe y se almacena automáticamente como un Record — no hay webhook, así que consulta la API para detectar las nuevas:

  1. Llama a listRecords y filtra por E_INVOICE::RECEPTION.
  2. Para cada Record nuevo, llama a retrieveRecord con compliance-artifact para obtener el XML firmado.

listRecords devuelve los Records más recientes (limit es 10 por defecto, del más reciente al más antiguo), así que lleva la cuenta de los que ya has procesado.

Puede recuperar la factura electrónica generada de una factura enviada y el XML de una factura recibida.