Documents

Validate, parse and generate e-invoices.

Validate an e-invoice (XRechnung, EN 16931, ZUGFeRD / Factur-X, French rules, Peppol BIS, CIUS-RO, KSeF, FatturaPA)

POST

https://einvoice-api-main-f5141d8.zuplo.app

/v1/validate

The format is detected from the content: CII or UBL XML, KSeF FA(3) or FatturaPA XML, or a PDF with an embedded factur-x.xml. For a seller in France the French rules (BR-FR) run in addition. For PDFs, PDF/A-3 conformance (veraPDF), the attachment and the Factur-X XMP metadata are checked as well. Send the document as the raw body or as multipart with a part named file.

Validate an e-invoice (XRechnung, EN 16931, ZUGFeRD / Factur-X, French rules, Peppol BIS, CIUS-RO, KSeF, FatturaPA) › query Parameters

ruleset

string[] · style: form · explode: true

Pin a rule-set version instead of the default, as <id>@<version> (see GET /v1/formats). Repeat the parameter or separate values with commas. Preview versions (status preview) can only be pinned on /v1/preview/validate; elsewhere they give 400 preview-ruleset.

Validate an e-invoice (XRechnung, EN 16931, ZUGFeRD / Factur-X, French rules, Peppol BIS, CIUS-RO, KSeF, FatturaPA) › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Validate an e-invoice (XRechnung, EN 16931, ZUGFeRD / Factur-X, French rules, Peppol BIS, CIUS-RO, KSeF, FatturaPA) › Request Body

string

Validate an e-invoice (XRechnung, EN 16931, ZUGFeRD / Factur-X, French rules, Peppol BIS, CIUS-RO, KSeF, FatturaPA) › Responses

Validation result (also for invalid documents).

ValidationResponse

requestId

string · required

valid

boolean · required

Summary · required

Finding[] · required

format

string · enum

Enum values:

xrechnung

en16931

zugferd

peppol-bis

ksef

fr-ctc

cius-ro

hr-cius

container

string · enum

Enum values:

XML

PDF

syntax

string · enum

Enum values:

CII

UBL

KSEF

FATTURAPA

profile

string

guidelineId

string

Specification identifier (BT-24) found in the document; for KSeF the form code (KodFormularza/@kodSystemowy, e.g. FA (3)); for FatturaPA the versione attribute (FPR12, FPA12).

attachmentName

string

Name of the embedded invoice XML (PDFs only).

RulesetRef[]

POST/v1/validate

curl https://einvoice-api-main-f5141d8.zuplo.app/v1/validate \
  --request POST \
  --header 'Content-Type: application/xml' \
  --header 'Authorization: Bearer <token>' \
  --data 'string'

Example Request Body

string

xml

Example Responses

{
  "requestId": "7dda6c33-1d07-43ba-a875-dfa1966801ed",
  "valid": true,
  "format": "xrechnung",
  "container": "XML",
  "syntax": "UBL",
  "profile": "XRECHNUNG",
  "guidelineId": "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0",
  "rulesets": [
    {
      "id": "xrechnung",
      "version": "3.0.2",
      "release": "2026-08-31"
    }
  ],
  "summary": {
    "fatal": 0,
    "error": 0,
    "warning": 0,
    "info": 0
  },
  "findings": []
}

json

application/json

Validate against the upcoming rule sets before they become mandatory (paid plans)

POST

https://einvoice-api-main-f5141d8.zuplo.app

/v1/preview/validate

Like /v1/validate, but where the rule-set owner (KoSIT, FeRD) has published an upcoming release that is not in force yet, the document is validated against that release instead. Use it to find out early whether your invoices will still pass. Rule sets used this way are marked preview: true in rulesets, with the date from which they become mandatory (effectiveFrom) when it is known. Documents that no upcoming release covers are validated against the rules in force and get an info finding PREVIEW-NONE; this is also the case while no upcoming release has been published (GET /v1/formats lists them with status: preview). ruleset pins may name preview and current versions. The verdict of /v1/validate is never affected.

Validate against the upcoming rule sets before they become mandatory (paid plans) › query Parameters

ruleset

string[] · style: form · explode: true

Validate against the upcoming rule sets before they become mandatory (paid plans) › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Validate against the upcoming rule sets before they become mandatory (paid plans) › Request Body

string

Validate against the upcoming rule sets before they become mandatory (paid plans) › Responses

Validation result against the upcoming rule sets (also for invalid documents).

ValidationResponse

requestId

string · required

valid

boolean · required

Summary · required

Finding[] · required

format

string · enum

Enum values:

xrechnung

en16931

zugferd

peppol-bis

ksef

fr-ctc

cius-ro

hr-cius

container

string · enum

Enum values:

XML

PDF

syntax

string · enum

Enum values:

CII

UBL

KSEF

FATTURAPA

profile

string

guidelineId

string

Specification identifier (BT-24) found in the document; for KSeF the form code (KodFormularza/@kodSystemowy, e.g. FA (3)); for FatturaPA the versione attribute (FPR12, FPA12).

attachmentName

string

Name of the embedded invoice XML (PDFs only).

RulesetRef[]

POST/v1/preview/validate

curl https://einvoice-api-main-f5141d8.zuplo.app/v1/preview/validate \
  --request POST \
  --header 'Content-Type: application/xml' \
  --header 'Authorization: Bearer <token>' \
  --data 'string'

Example Request Body

string

xml

Example Responses

{
  "requestId": "6c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "valid": true,
  "format": "xrechnung",
  "container": "XML",
  "syntax": "UBL",
  "profile": "XRECHNUNG",
  "guidelineId": "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0",
  "rulesets": [
    {
      "id": "xrechnung",
      "version": "3.0.3",
      "release": "2027-01-31",
      "preview": true,
      "effectiveFrom": "2027-08-01"
    }
  ],
  "summary": {
    "fatal": 0,
    "error": 0,
    "warning": 0,
    "info": 0
  },
  "findings": []
}

json

application/json

Parse an invoice into normalized JSON, with validation and recomputed totals

POST

https://einvoice-api-main-f5141d8.zuplo.app

/v1/parse

Validates like /v1/validate and returns the invoice in the normalized EN 16931 model (schema) plus calculation. Totals are recomputed server-side: differences in BT-106…BT-115 and the VAT breakdown are listed exactly; line net amounts and VAT amounts per category are additionally checked with a tolerance of 0.01 (CALC-* warnings). Content outside EN 16931 (for example ZUGFeRD EXTENDED) is not mapped and listed in a PARSE-UNMAPPED finding.

Parse an invoice into normalized JSON, with validation and recomputed totals › query Parameters

ruleset

string[] · style: form · explode: true

Parse an invoice into normalized JSON, with validation and recomputed totals › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Parse an invoice into normalized JSON, with validation and recomputed totals › Request Body

string

Parse an invoice into normalized JSON, with validation and recomputed totals › Responses

Parse result. invoice is absent if the document cannot be read as CII or UBL.

ParseResponse

requestId

string · required

valid

boolean · required

Summary · required

Finding[] · required

format

string · enum

Enum values:

xrechnung

en16931

zugferd

peppol-bis

ksef

fr-ctc

cius-ro

hr-cius

container

string · enum

Enum values:

XML

PDF

syntax

string · enum

Enum values:

CII

UBL

KSEF

FATTURAPA

profile

string

guidelineId

string

attachmentName

string

RulesetRef[]

NormalizedInvoice

Syntax-neutral representation of an EN 16931 invoice or credit note. Output of POST /v1/parse and input of POST /v1/generate. Each property carries its EN 16931 business term in 'x-bt'. Code-list values are validated by the rule sets, not by this schema.

Example: {"invoiceNumber":"RE-2026-0042","issueDate":"2026-10-18","typeCode":"380","currency":"EUR","dueDate":"2026-11-17","buyerReference":"04011000-12345-34","seller":{"name":"Muster Software GmbH","vatId":"DE123456789","electronicAddress":{"value":"rechnung@muster-software.example","schemeId":"EM"},"address":{"line1":"Hauptstraße 1","city":"Berlin","postCode":"10115","countryCode":"DE"},"contact":{"name":"Erika Beispiel","phone":"+49 30 1234567","email":"buchhaltung@muster-software.example"}},"buyer":{"name":"Beispielamt der Stadt Musterstadt","electronicAddress":{"value":"04011000-12345-34","schemeId":"0204"},"address":{"line1":"Rathausplatz 5","city":"Musterstadt","postCode":"12345","countryCode":"DE"}},"payment":{"meansCode":"58","creditTransfers":[{"accountId":"DE02120300000000202051","accountName":"Muster Software GmbH"}],"terms":"Zahlbar innerhalb von 30 Tagen ohne Abzug."},"lines":[{"id":"1","quantity":"10","unitCode":"HUR","netAmount":"1000.00","price":{"netPrice":"100.00"},"vat":{"categoryCode":"S","rate":"19"},"item":{"name":"Beratungsleistung"}}],"vatBreakdown":[{"categoryCode":"S","rate":"19","taxableAmount":"1000.00","taxAmount":"190.00"}],"totals":{"lineNetTotal":"1000.00","taxExclusiveAmount":"1000.00","vatTotal":"190.00","taxInclusiveAmount":"1190.00","amountDue":"1190.00"}}

Calculation

POST/v1/parse

curl https://einvoice-api-main-f5141d8.zuplo.app/v1/parse \
  --request POST \
  --header 'Content-Type: application/xml' \
  --header 'Authorization: Bearer <token>' \
  --data 'string'

Example Request Body

string

xml

Example Responses

{
  "requestId": "0b1d6f7e-8d8f-4c8e-9a51-2f8c1e0d6a10",
  "valid": false,
  "format": "xrechnung",
  "container": "XML",
  "syntax": "UBL",
  "profile": "XRECHNUNG",
  "guidelineId": "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0",
  "rulesets": [
    {
      "id": "xrechnung",
      "version": "3.0.2",
      "release": "2026-08-31"
    }
  ],
  "summary": {
    "fatal": 1,
    "error": 0,
    "warning": 0,
    "info": 0
  },
  "invoice": {
    "invoiceNumber": "RE-2026-0042",
    "issueDate": "2026-10-18",
    "typeCode": "380",
    "currency": "EUR",
    "buyerReference": "04011000-12345-34",
    "context": {
      "businessProcessType": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
      "specificationIdentifier": "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0"
    },
    "seller": {
      "name": "Muster Software GmbH",
      "vatId": "DE123456789",
      "address": {
        "city": "Berlin",
        "countryCode": "DE"
      }
    },
    "buyer": {
      "name": "Beispielamt der Stadt Musterstadt",
      "address": {
        "city": "Musterstadt",
        "countryCode": "DE"
      }
    },
    "lines": [
      {
        "id": "1",
        "quantity": "10",
        "unitCode": "HUR",
        "netAmount": "1000.00",
        "price": {
          "netPrice": "100.00"
        },
        "vat": {
          "categoryCode": "S",
          "rate": "19"
        },
        "item": {
          "name": "Beratungsleistung"
        }
      }
    ],
    "vatBreakdown": [
      {
        "taxableAmount": "1000.00",
        "taxAmount": "190.00",
        "categoryCode": "S",
        "rate": "19"
      }
    ],
    "totals": {
      "lineNetTotal": "1000.00",
      "taxExclusiveAmount": "1000.00",
      "vatTotal": "190.00",
      "taxInclusiveAmount": "1190.00",
      "amountDue": "1.00"
    }
  },
  "calculation": {
    "consistent": false,
    "differences": [
      {
        "field": "BT-115",
        "rule": "BR-CO-16",
        "declared": "1.00",
        "computed": "1190.00"
      }
    ]
  },
  "findings": [
    {
      "severity": "fatal",
      "ruleId": "BR-CO-16",
      "message": "Amount due for payment (BT-115) = Invoice total amount with VAT (BT-112) - Paid amount (BT-113) + Rounding amount (BT-114).",
      "xpath": "/ubl:Invoice[1]/cac:LegalMonetaryTotal[1]",
      "source": "schematron:xrechnung@3.0.2"
    }
  ]
}

json

application/json

Generate XRechnung, EN 16931, ZUGFeRD / Factur-X, CIUS-RO, Peppol BIS, KSeF FA(3) or FatturaPA from normalized JSON

POST

https://einvoice-api-main-f5141d8.zuplo.app

/v1/generate

Input is the normalized invoice (the same schema /v1/parse returns). BT-24 is set from format; BT-23 (context.businessProcessType) is taken from the input when given. en16931-cii and en16931-ubl write plain EN 16931 (BT-24 urn:cen.eu:en16931:2017), e.g. for France, where BT-23 must be a billing framework code such as S1 and the French rules apply to sellers in France. hr-cius-ubl writes the Croatian eRačun: BT-23 must be P1-P12 or P99:..., and issueTime and seller.operator (name and OIB) are required by the Croatian rules; VAT categories S (25, 13, 5 %), Z, E, AE, K, G and O are supported. Every generated document is validated before it is returned; if it is not valid, the response is 422 with the findings and no document. For PDF formats a neutral layout is rendered, or send multipart with your own PDF/A-1, -2 or -3 in the part pdf and the XML is embedded into it.

Generate XRechnung, EN 16931, ZUGFeRD / Factur-X, CIUS-RO, Peppol BIS, KSeF FA(3) or FatturaPA from normalized JSON › query Parameters

format

string · enum · required

Enum values:

xrechnung-cii

xrechnung-ubl

zugferd-en16931

facturx-basic

en16931-cii

en16931-ubl

cius-ro-ubl

hr-cius-ubl

Generate XRechnung, EN 16931, ZUGFeRD / Factur-X, CIUS-RO, Peppol BIS, KSeF FA(3) or FatturaPA from normalized JSON › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Generate XRechnung, EN 16931, ZUGFeRD / Factur-X, CIUS-RO, Peppol BIS, KSeF FA(3) or FatturaPA from normalized JSON › Request Body

NormalizedInvoice

invoiceNumber

string · minLength: 1 · required

issueDate

InvoiceDate · date · required

typeCode

string · pattern: ^[0-9]{1,3}$ · required

UNTDID 1001 code, e.g. 380 commercial invoice, 381 credit note, 384 corrected invoice, 389 self-billed invoice, 326 partial invoice.

Example: 380

currency

InvoiceCurrencyCode · pattern: ^[A-Z]{3}$ · required

ISO 4217.

Example: EUR

InvoiceSeller · required

InvoiceBuyer · required

object · required

issueTime

string · pattern: ^[0-9]{2}:[0-9]{2}:[…

Issue time hh:mm:ss. Not an EN 16931 term: read from and written to UBL cbc:IssueTime only by the national formats that require it (Croatia: HR-BT-2, mandatory in hr-cius).

Example: 12:00:00

vatAccountingCurrency

InvoiceCurrencyCode · pattern: ^[A-Z]{3}$

ISO 4217.

Example: EUR

taxPointDate

InvoiceDate · date

vatPointDateCode

string

UNTDID 2005 code (3, 35, 432).

dueDate

InvoiceDate · date

buyerReference

string

For XRechnung B2G this carries the Leitweg-ID.

projectReference

string

contractReference

string

purchaseOrderReference

string

salesOrderReference

string

receivingAdviceReference

string

despatchAdviceReference

string

tenderOrLotReference

string

InvoiceIdentifier

buyerAccountingReference

string

object

Process context detected by /parse. On /generate, BT-24 (specificationIdentifier) is set from the 'format' parameter (a conflicting value is rejected with 400); BT-23 (businessProcessType) is taken from the input when given, e.g. the French billing framework code such as S1 or B1 (BR-FR-08), and otherwise defaults per format.

object[]

object

InvoicePeriod

object

InvoiceDocumentAllowanceCharge[]

object[]

InvoiceInvoiceLine[] · minItems: 1

Absent for profiles without line items (MINIMUM, BASIC WL).

Generate XRechnung, EN 16931, ZUGFeRD / Factur-X, CIUS-RO, Peppol BIS, KSeF FA(3) or FatturaPA from normalized JSON › Responses

The generated, validated document.

string

POST/v1/generate

curl 'https://einvoice-api-main-f5141d8.zuplo.app/v1/generate?format=<string>' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "invoiceNumber": "RE-2026-0042",
  "issueDate": "2026-10-18",
  "typeCode": "380",
  "currency": "EUR",
  "dueDate": "2026-11-17",
  "buyerReference": "04011000-12345-34",
  "purchaseOrderReference": "BEST-2026-117",
  "notes": [
    {
      "subjectCode": "AAI",
      "text": "Vielen Dank für Ihren Auftrag."
    }
  ],
  "seller": {
    "name": "Muster Software GmbH",
    "vatId": "DE123456789",
    "electronicAddress": {
      "value": "rechnung@muster-software.example",
      "schemeId": "EM"
    },
    "address": {
      "line1": "Hauptstraße 1",
      "city": "Berlin",
      "postCode": "10115",
      "countryCode": "DE"
    },
    "contact": {
      "name": "Erika Beispiel",
      "phone": "+49 30 1234567",
      "email": "buchhaltung@muster-software.example"
    }
  },
  "buyer": {
    "name": "Beispielamt der Stadt Musterstadt",
    "electronicAddress": {
      "value": "04011000-12345-34",
      "schemeId": "0204"
    },
    "address": {
      "line1": "Rathausplatz 5",
      "city": "Musterstadt",
      "postCode": "12345",
      "countryCode": "DE"
    }
  },
  "delivery": {
    "actualDeliveryDate": "2026-10-15"
  },
  "payment": {
    "meansCode": "58",
    "creditTransfers": [
      {
        "accountId": "DE02120300000000202051",
        "accountName": "Muster Software GmbH"
      }
    ],
    "terms": "Zahlbar innerhalb von 30 Tagen ohne Abzug."
  },
  "lines": [
    {
      "id": "1",
      "quantity": "10",
      "unitCode": "HUR",
      "netAmount": "1000.00",
      "price": {
        "netPrice": "100.00"
      },
      "vat": {
        "categoryCode": "S",
        "rate": "19"
      },
      "item": {
        "name": "Beratungsleistung",
        "description": "Anforderungsanalyse E-Rechnung, Oktober 2026"
      }
    },
    {
      "id": "2",
      "quantity": "1",
      "unitCode": "C62",
      "netAmount": "250.00",
      "price": {
        "netPrice": "250.00"
      },
      "vat": {
        "categoryCode": "S",
        "rate": "19"
      },
      "item": {
        "name": "Softwarelizenz Jahresabonnement",
        "sellerItemId": "LIC-STD-12"
      }
    }
  ],
  "vatBreakdown": [
    {
      "taxableAmount": "1250.00",
      "taxAmount": "237.50",
      "categoryCode": "S",
      "rate": "19"
    }
  ],
  "totals": {
    "lineNetTotal": "1250.00",
    "taxExclusiveAmount": "1250.00",
    "vatTotal": "237.50",
    "taxInclusiveAmount": "1487.50",
    "amountDue": "1487.50"
  }
}'

Example Request Body

{
  "invoiceNumber": "RE-2026-0042",
  "issueDate": "2026-10-18",
  "typeCode": "380",
  "currency": "EUR",
  "dueDate": "2026-11-17",
  "buyerReference": "04011000-12345-34",
  "purchaseOrderReference": "BEST-2026-117",
  "notes": [
    {
      "subjectCode": "AAI",
      "text": "Vielen Dank für Ihren Auftrag."
    }
  ],
  "seller": {
    "name": "Muster Software GmbH",
    "vatId": "DE123456789",
    "electronicAddress": {
      "value": "rechnung@muster-software.example",
      "schemeId": "EM"
    },
    "address": {
      "line1": "Hauptstraße 1",
      "city": "Berlin",
      "postCode": "10115",
      "countryCode": "DE"
    },
    "contact": {
      "name": "Erika Beispiel",
      "phone": "+49 30 1234567",
      "email": "buchhaltung@muster-software.example"
    }
  },
  "buyer": {
    "name": "Beispielamt der Stadt Musterstadt",
    "electronicAddress": {
      "value": "04011000-12345-34",
      "schemeId": "0204"
    },
    "address": {
      "line1": "Rathausplatz 5",
      "city": "Musterstadt",
      "postCode": "12345",
      "countryCode": "DE"
    }
  },
  "delivery": {
    "actualDeliveryDate": "2026-10-15"
  },
  "payment": {
    "meansCode": "58",
    "creditTransfers": [
      {
        "accountId": "DE02120300000000202051",
        "accountName": "Muster Software GmbH"
      }
    ],
    "terms": "Zahlbar innerhalb von 30 Tagen ohne Abzug."
  },
  "lines": [
    {
      "id": "1",
      "quantity": "10",
      "unitCode": "HUR",
      "netAmount": "1000.00",
      "price": {
        "netPrice": "100.00"
      },
      "vat": {
        "categoryCode": "S",
        "rate": "19"
      },
      "item": {
        "name": "Beratungsleistung",
        "description": "Anforderungsanalyse E-Rechnung, Oktober 2026"
      }
    },
    {
      "id": "2",
      "quantity": "1",
      "unitCode": "C62",
      "netAmount": "250.00",
      "price": {
        "netPrice": "250.00"
      },
      "vat": {
        "categoryCode": "S",
        "rate": "19"
      },
      "item": {
        "name": "Softwarelizenz Jahresabonnement",
        "sellerItemId": "LIC-STD-12"
      }
    }
  ],
  "vatBreakdown": [
    {
      "taxableAmount": "1250.00",
      "taxAmount": "237.50",
      "categoryCode": "S",
      "rate": "19"
    }
  ],
  "totals": {
    "lineNetTotal": "1250.00",
    "taxExclusiveAmount": "1250.00",
    "vatTotal": "237.50",
    "taxInclusiveAmount": "1487.50",
    "amountDue": "1487.50"
  }
}

json

Example Responses

string

xml

Service