RechnungsAPIv1.0.10
RechnungsAPI Dokumentation
EN-16931-konforme E-Rechnungen (XRechnung & ZUGFeRD) erzeugen, validieren, extrahieren und analysieren – über eine einfache REST- + JSON-Schnittstelle.
v1.0.10 — Produktiv
https://onefinancebe.finbc.deAuthentifizierung
Alle Anfragen werden mit einem Bearer-Token authentifiziert. Senden Sie ihn bei jedem Aufruf im Authorization-Header. Tokens sind kontogebunden – geben Sie sie nicht weiter und committen Sie sie nicht.
Header-Format
json
Authorization: Bearer <your-token>
- Melden Sie sich im Dashboard an unter rechnungsapi.de.
- Öffnen Sie Ihr Profil und kopieren Sie unten den API-Token.
- Speichern Sie den Token sicher (Env-Variable oder Secret-Manager) und übergeben Sie ihn bei jeder Anfrage.
Sicherheitshinweis: Behandeln Sie Ihren API-Token wie ein Passwort. Rotieren Sie ihn bei Verdacht auf Leaks sofort über das Dashboard.
Schnellstart
Machen Sie Ihren ersten Aufruf in unter einer Minute. Das folgende Beispiel erzeugt eine XRechnung-XML aus einer minimalen Rechnungs-Payload.
curl -X POST "https://onefinancebe.finbc.de/api/v1/zugferd/createXinvoiceFromJson" \
-H "Authorization: Bearer $RECHNUNGSAPI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"invoice": {
"invoiceNumber": "INV-2025-0001",
"invoiceIssueDate": "2025-06-01",
"invoiceTypeCode": "380",
"invoiceCurrencyCode": "EUR",
"buyerReference": "PO-12345"
}
}'Setzen Sie die Umgebungsvariable RECHNUNGSAPI_TOKEN auf Ihren API-Token, bevor Sie das Snippet ausführen.
Endpunkte
Alle Endpunkte sind POST und akzeptieren application/json. Wählen Sie den Workflow passend zu Ihrem Anwendungsfall – Erzeugung, Analyse, Extraktion oder Validierung.
Rechnungserzeugung
POST
/api/v1/zugferd/createXinvoiceFromJsonXRechnung aus JSON erzeugen
Erzeugt eine valide XRechnungs-XML-Datei aus strukturierten JSON-Rechnungsdaten nach EN 16931. Gibt das XML und Validierungsfehler zurück.
| Field | Type | Required | Description |
|---|---|---|---|
invoice | object | required | Rechnungsobjekt nach EN 16931 Feldmapping. |
Beispiel
json
{
"invoice": {
"invoiceNumber": "String | BT-1",
"invoiceIssueDate": "Date | BT-2",
"invoiceTypeCode": "String | BT-3",
"invoiceCurrencyCode": "String | BT-5",
"vatAccountingCurrencyCode": "String | BT-6",
"valueAddedTaxPointDate": "String | BT-7",
"valueAddedTaxPointDateCode": "String | BT-8",
"paymentDueDate": "Date | BT-9",
"buyerReference": "String | BT-10",
"projectReference": {
"projectReferenceIdentifier": "String | BT-11",
"projectReferenceName": "String | BT-11-0"
},
"contractReference": "String | BT-12",
"purchaseOrderReference": "String | BT-13",
"salesOrderReference": "String | BT-14",
"receivingAdviceReference": "String | BT-15",
"despatchAdviceReference": "String | BT-16",
"tenderOrLotReference": "String | BT-17",
"invoicedObjectIdentifier": "String | BT-18",
"buyerAccountingReference": "String | BT-19",
"paymentTerms": "String | BT-20",
"invoiceNote": [
{
"invoiceNoteSubjectCode": "String | BT-21",
"invoiceNote": "String | BT-22"
}
],
"processControl": {
"businessProcessTypeIdentifier": "String | BT-23",
"specificationIdentifier": "String | BT-24"
},
"precedingInvoiceReference": [
{
"precedingInvoiceReference": "String | BT-25",
"precedingInvoiceIssueDate": "Date | BT-26"
}
],
"seller": {
"sellerName": "String | BT-27",
"sellerTradingName": "String | BT-28",
"sellerIdentifier": [
"String | BT-29"
],
"sellerLegalRegistrationIdentifier": "String | BT-30",
"sellerVatIdentifier": "String | BT-31",
"sellerTaxRegistrationIdentifier": "String | BT-32",
"sellerAdditionalLegalInformation": "String | BT-33",
"sellerElectronicAddress": "String | BT-34",
"sellerPostalAddress": {
"sellerAddressLine1": "String | BT-35",
"sellerAddressLine2": "String | BT-36",
"sellerAddressLine3": "String | BT-162",
"sellerCity": "String | BT-37",
"sellerPostCode": "String | BT-38",
"sellerCountrySubdivision": "String | BT-39",
"sellerCountryCode": "String | BT-40"
},
"sellerContact": {
"sellerContactPoint": "String | BT-41",
"sellerContactTelephoneNumber": "String | BT-42",
"sellerContactEmailAddress": "String | BT-43"
}
},
"buyer": {
"buyerName": "String | BT-44",
"buyerTradingName": "String | BT-45",
"buyerIdentifier": "String | BT-46",
"buyerLegalRegistrationIdentifier": "String | BT-47",
"buyerVatIdentifier": "String | BT-48",
"buyerElectronicAddress": "String | BT-49",
"buyerPostalAddress": {
"buyerAddressLine1": "String | BT-50",
"buyerAddressLine2": "String | BT-51",
"buyerAddressLine3": "String | BT-163",
"buyerCity": "String | BT-52",
"buyerPostCode": "String | BT-53",
"buyerCountrySubdivision": "String | BT-54",
"buyerCountryCode": "String | BT-55"
},
"buyerContact": {
"buyerContactPoint": "String | BT-56",
"buyerContactTelephoneNumber": "String | BT-57",
"buyerContactEmailAddress": "String | BT-58"
}
},
"payee": {
"payeeName": "String | BT-59",
"payeeIdentifier": "String | BT-60",
"payeeLegalRegistrationIdentifier": "String | BT-61"
},
"sellerTaxRepresentativeParty": {
"sellerTaxRepresentativeName": "String | BT-62",
"sellerTaxRepresentativeVatIdentifier": "String | BT-63",
"sellerTaxRepresentativePostalAddress": {
"taxRepresentativeAddressLine1": "String | BT-64",
"taxRepresentativeAddressLine2": "String | BT-65",
"taxRepresentativeAddressLine3": "String | BT-164",
"taxRepresentativeCity": "String | BT-66",
"taxRepresentativePostCode": "String | BT-67",
"taxRepresentativeCountrySubdivision": "String | BT-68",
"taxRepresentativeCountryCode": "String | BT-69"
}
},
"deliveryInformation": {
"deliverToPartyName": "String | BT-70",
"deliverToLocationIdentifier": "String | BT-71",
"actualDeliveryDate": "Date | BT-72",
"deliverToAddress": {
"deliverToAddressLine1": "String | BT-75",
"deliverToAddressLine2": "String | BT-76",
"deliverToAddressLine3": "String | BT-165",
"deliverToCity": "String | BT-77",
"deliverToPostCode": "String | BT-78",
"deliverToCountrySubdivision": "String | BT-79",
"deliverToCountryCode": "String | BT-80"
}
},
"invoicingPeriod": {
"invoicingPeriodStartDate": "Date | BT-73",
"invoicingPeriodEndDate": "Date | BT-74"
},
"paymentInstructions": {
"paymentMeansTypeCode": "String | BT-81",
"paymentMeansText": "String | BT-82",
"remittanceInformation": "String | BT-83",
"creditTransfer": [
{
"paymentAccountIdentifier": "String | BT-84",
"paymentAccountName": "String | BT-85",
"paymentServiceProviderIdentifier": "String | BT-86"
}
],
"paymentCardInformation": {
"paymentCardPrimaryAccountNumber": "String | BT-87",
"paymentCardHolderName": "String | BT-88"
},
"directDebit": {
"mandateReferenceIdentifier": "String | BT-89",
"bankAssignedCreditorIdentifier": "String | BT-90",
"debitedAccountIdentifier": "String | BT-91"
}
},
"documentLevelAllowances": [
{
"documentLevelAllowanceAmount": "Decimal | BT-92",
"documentLevelAllowanceBaseAmount": "Decimal | BT-93",
"documentLevelAllowancePercentage": "Decimal | BT-94",
"documentLevelAllowanceVatCategoryCode": "String | BT-95",
"documentLevelAllowanceVatRate": "Decimal | BT-96",
"documentLevelAllowanceReason": "String | BT-97",
"documentLevelAllowanceReasonCode": "String | BT-98"
}
],
"documentLevelCharges": [
{
"documentLevelChargeAmount": "Decimal | BT-99",
"documentLevelChargeBaseAmount": "Decimal | BT-100",
"documentLevelChargePercentage": "Decimal | BT-101",
"documentLevelChargeVatCategoryCode": "String | BT-102",
"documentLevelChargeVatRate": "Decimal | BT-103",
"documentLevelChargeReason": "String | BT-104",
"documentLevelChargeReasonCode": "String | BT-105"
}
],
"documentTotals": {
"sumOfInvoiceLineNetAmount": "Decimal | BT-106",
"sumOfAllowancesOnDocumentLevel": "Decimal | BT-107",
"sumOfChargesOnDocumentLevel": "Decimal | BT-108",
"invoiceTotalAmountWithoutVat": "Decimal | BT-109",
"invoiceTotalVatAmount": "Decimal | BT-110",
"invoiceTotalVatAmountInAccountingCurrency": "Decimal | BT-111",
"invoiceTotalAmountWithVat": "Decimal | BT-112",
"paidAmount": "Decimal | BT-113",
"roundingAmount": "Decimal | BT-114",
"amountDueForPayment": "Decimal | BT-115"
},
"vatBreakdown": [
{
"vatCategoryTaxableAmount": "Decimal | BT-116",
"vatCategoryTaxAmount": "Decimal | BT-117",
"vatCategoryCode": "String | BT-118",
"vatCategoryRate": "Decimal | BT-119",
"vatExemptionReasonText": "String | BT-120",
"vatExemptionReasonCode": "String | BT-121"
}
],
"additionalSupportingDocuments": [
{
"supportingDocumentReference": "String | BT-122",
"supportingDocumentDescription": "String | BT-123",
"externalDocumentLocation": "String | BT-124",
"attachedDocument": "String | BT-125"
}
],
"invoiceLine": [
{
"invoiceLineIdentifier": "String | BT-126",
"invoiceLineNote": "String | BT-127",
"invoiceLineObjectIdentifier": "String | BT-128",
"invoicedQuantity": "Decimal | BT-129",
"invoicedQuantityUnitOfMeasureCode": "String | BT-130",
"invoiceLineNetAmount": "Decimal | BT-131",
"referencedPurchaseOrderLineReference": "String | BT-132",
"invoiceLineBuyerAccountingReference": "String | BT-133",
"invoiceLinePeriod": {
"invoiceLinePeriodStartDate": "Date | BT-134",
"invoiceLinePeriodEndDate": "Date | BT-135"
},
"invoiceLineAllowances": [
{
"invoiceLineAllowanceAmount": "Decimal | BT-136",
"invoiceLineAllowanceBaseAmount": "Decimal | BT-137",
"invoiceLineAllowancePercentage": "Decimal | BT-138",
"invoiceLineAllowanceReason": "String | BT-139",
"invoiceLineAllowanceReasonCode": "String | BT-140"
}
],
"invoiceLineCharges": [
{
"invoiceLineChargeAmount": "Decimal | BT-141",
"invoiceLineChargeBaseAmount": "Decimal | BT-142",
"invoiceLineChargePercentage": "Decimal | BT-143",
"invoiceLineChargeReason": "String | BT-144",
"invoiceLineChargeReasonCode": "String | BT-145"
}
],
"priceDetails": {
"itemNetPrice": "Decimal | BT-146",
"itemPriceDiscount": "Decimal | BT-147",
"itemGrossPrice": "Decimal | BT-148",
"itemPriceBaseQuantity": "Decimal | BT-149",
"itemPriceBaseQuantityUnitOfMeasure": "String | BT-150"
},
"lineVatInformation": [
{
"invoicedItemVatCategoryCode": "String | BT-151",
"invoicedItemVatRate": "Decimal | BT-152"
}
],
"itemInformation": {
"itemName": "String | BT-153",
"itemDescription": "String | BT-154",
"itemSellersIdentifier": "String | BT-155",
"itemBuyersIdentifier": "String | BT-156",
"itemStandardIdentifier": "String | BT-157",
"itemStandardIdentifierSchemeIdentifier": "String | BT-157-1",
"itemClassificationIdentifier": [
{
"itemClassificationIdentifier": "String | BT-158",
"itemClassificationIdentifierListIdentifier": "String | BT-158-1",
"itemClassificationIdentifierListVersionIdentifier": "String | BT-158-2"
}
],
"itemCountryOfOrigin": "String | BT-159",
"itemAttributes": [
{
"itemAttributeName": "String | BT-160",
"itemAttributeValue": "String | BT-161"
}
]
}
}
]
}
}Beispielantwort
json
{
"valid": false,
"message": "xInvoice generated",
"numberOfXInvoiceErrors": 1,
"xInvoice": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><rsm:CrossIndustryInvoice xmlns:rsm=\"urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100\">...</rsm:CrossIndustryInvoice>",
"xInvoiceErrors": [
{
"id": "BR-CO-25",
"line": null,
"location": "/rsm:CrossIndustryInvoice",
"message": "In case the Amount due for payment (BT-115) is positive, either the Payment due date (BT-9) or the Payment terms (BT-20) shall be present.",
"schemaFile": "EN16931-CII-validation",
"type": "fatal"
}
]
}Playground
Diesen Endpunkt live im Browser testen.
POST
/api/v1/zugferd/createZugferdFromJsonZUGFeRD aus JSON + PDF erzeugen
Kombiniert strukturierte JSON-Rechnungsdaten mit einem vorhandenen PDF zu einem ZUGFeRD-konformen PDF/A-3-Dokument mit eingebetteter XRechnungs-XML.
| Field | Type | Required | Description |
|---|---|---|---|
invoice | object | required | Rechnungsobjekt. |
invoicePdf64 | string (base64) | required | Base64-kodiertes PDF für die XML-Einbettung. |
Beispiel
json
{
"invoice": {
"invoiceNumber": "String | BT-1",
"invoiceIssueDate": "Date | BT-2",
"invoiceTypeCode": "String | BT-3",
"invoiceCurrencyCode": "String | BT-5",
"vatAccountingCurrencyCode": "String | BT-6",
"valueAddedTaxPointDate": "String | BT-7",
"valueAddedTaxPointDateCode": "String | BT-8",
"paymentDueDate": "Date | BT-9",
"buyerReference": "String | BT-10",
"projectReference": {
"projectReferenceIdentifier": "String | BT-11",
"projectReferenceName": "String | BT-11-0"
},
"contractReference": "String | BT-12",
"purchaseOrderReference": "String | BT-13",
"salesOrderReference": "String | BT-14",
"receivingAdviceReference": "String | BT-15",
"despatchAdviceReference": "String | BT-16",
"tenderOrLotReference": "String | BT-17",
"invoicedObjectIdentifier": "String | BT-18",
"buyerAccountingReference": "String | BT-19",
"paymentTerms": "String | BT-20",
"invoiceNote": [
{
"invoiceNoteSubjectCode": "String | BT-21",
"invoiceNote": "String | BT-22"
}
],
"processControl": {
"businessProcessTypeIdentifier": "String | BT-23",
"specificationIdentifier": "String | BT-24"
},
"precedingInvoiceReference": [
{
"precedingInvoiceReference": "String | BT-25",
"precedingInvoiceIssueDate": "Date | BT-26"
}
],
"seller": {
"sellerName": "String | BT-27",
"sellerTradingName": "String | BT-28",
"sellerIdentifier": [
"String | BT-29"
],
"sellerLegalRegistrationIdentifier": "String | BT-30",
"sellerVatIdentifier": "String | BT-31",
"sellerTaxRegistrationIdentifier": "String | BT-32",
"sellerAdditionalLegalInformation": "String | BT-33",
"sellerElectronicAddress": "String | BT-34",
"sellerPostalAddress": {
"sellerAddressLine1": "String | BT-35",
"sellerAddressLine2": "String | BT-36",
"sellerAddressLine3": "String | BT-162",
"sellerCity": "String | BT-37",
"sellerPostCode": "String | BT-38",
"sellerCountrySubdivision": "String | BT-39",
"sellerCountryCode": "String | BT-40"
},
"sellerContact": {
"sellerContactPoint": "String | BT-41",
"sellerContactTelephoneNumber": "String | BT-42",
"sellerContactEmailAddress": "String | BT-43"
}
},
"buyer": {
"buyerName": "String | BT-44",
"buyerTradingName": "String | BT-45",
"buyerIdentifier": "String | BT-46",
"buyerLegalRegistrationIdentifier": "String | BT-47",
"buyerVatIdentifier": "String | BT-48",
"buyerElectronicAddress": "String | BT-49",
"buyerPostalAddress": {
"buyerAddressLine1": "String | BT-50",
"buyerAddressLine2": "String | BT-51",
"buyerAddressLine3": "String | BT-163",
"buyerCity": "String | BT-52",
"buyerPostCode": "String | BT-53",
"buyerCountrySubdivision": "String | BT-54",
"buyerCountryCode": "String | BT-55"
},
"buyerContact": {
"buyerContactPoint": "String | BT-56",
"buyerContactTelephoneNumber": "String | BT-57",
"buyerContactEmailAddress": "String | BT-58"
}
},
"payee": {
"payeeName": "String | BT-59",
"payeeIdentifier": "String | BT-60",
"payeeLegalRegistrationIdentifier": "String | BT-61"
},
"sellerTaxRepresentativeParty": {
"sellerTaxRepresentativeName": "String | BT-62",
"sellerTaxRepresentativeVatIdentifier": "String | BT-63",
"sellerTaxRepresentativePostalAddress": {
"taxRepresentativeAddressLine1": "String | BT-64",
"taxRepresentativeAddressLine2": "String | BT-65",
"taxRepresentativeAddressLine3": "String | BT-164",
"taxRepresentativeCity": "String | BT-66",
"taxRepresentativePostCode": "String | BT-67",
"taxRepresentativeCountrySubdivision": "String | BT-68",
"taxRepresentativeCountryCode": "String | BT-69"
}
},
"deliveryInformation": {
"deliverToPartyName": "String | BT-70",
"deliverToLocationIdentifier": "String | BT-71",
"actualDeliveryDate": "Date | BT-72",
"deliverToAddress": {
"deliverToAddressLine1": "String | BT-75",
"deliverToAddressLine2": "String | BT-76",
"deliverToAddressLine3": "String | BT-165",
"deliverToCity": "String | BT-77",
"deliverToPostCode": "String | BT-78",
"deliverToCountrySubdivision": "String | BT-79",
"deliverToCountryCode": "String | BT-80"
}
},
"invoicingPeriod": {
"invoicingPeriodStartDate": "Date | BT-73",
"invoicingPeriodEndDate": "Date | BT-74"
},
"paymentInstructions": {
"paymentMeansTypeCode": "String | BT-81",
"paymentMeansText": "String | BT-82",
"remittanceInformation": "String | BT-83",
"creditTransfer": [
{
"paymentAccountIdentifier": "String | BT-84",
"paymentAccountName": "String | BT-85",
"paymentServiceProviderIdentifier": "String | BT-86"
}
],
"paymentCardInformation": {
"paymentCardPrimaryAccountNumber": "String | BT-87",
"paymentCardHolderName": "String | BT-88"
},
"directDebit": {
"mandateReferenceIdentifier": "String | BT-89",
"bankAssignedCreditorIdentifier": "String | BT-90",
"debitedAccountIdentifier": "String | BT-91"
}
},
"documentLevelAllowances": [
{
"documentLevelAllowanceAmount": "Decimal | BT-92",
"documentLevelAllowanceBaseAmount": "Decimal | BT-93",
"documentLevelAllowancePercentage": "Decimal | BT-94",
"documentLevelAllowanceVatCategoryCode": "String | BT-95",
"documentLevelAllowanceVatRate": "Decimal | BT-96",
"documentLevelAllowanceReason": "String | BT-97",
"documentLevelAllowanceReasonCode": "String | BT-98"
}
],
"documentLevelCharges": [
{
"documentLevelChargeAmount": "Decimal | BT-99",
"documentLevelChargeBaseAmount": "Decimal | BT-100",
"documentLevelChargePercentage": "Decimal | BT-101",
"documentLevelChargeVatCategoryCode": "String | BT-102",
"documentLevelChargeVatRate": "Decimal | BT-103",
"documentLevelChargeReason": "String | BT-104",
"documentLevelChargeReasonCode": "String | BT-105"
}
],
"documentTotals": {
"sumOfInvoiceLineNetAmount": "Decimal | BT-106",
"sumOfAllowancesOnDocumentLevel": "Decimal | BT-107",
"sumOfChargesOnDocumentLevel": "Decimal | BT-108",
"invoiceTotalAmountWithoutVat": "Decimal | BT-109",
"invoiceTotalVatAmount": "Decimal | BT-110",
"invoiceTotalVatAmountInAccountingCurrency": "Decimal | BT-111",
"invoiceTotalAmountWithVat": "Decimal | BT-112",
"paidAmount": "Decimal | BT-113",
"roundingAmount": "Decimal | BT-114",
"amountDueForPayment": "Decimal | BT-115"
},
"vatBreakdown": [
{
"vatCategoryTaxableAmount": "Decimal | BT-116",
"vatCategoryTaxAmount": "Decimal | BT-117",
"vatCategoryCode": "String | BT-118",
"vatCategoryRate": "Decimal | BT-119",
"vatExemptionReasonText": "String | BT-120",
"vatExemptionReasonCode": "String | BT-121"
}
],
"additionalSupportingDocuments": [
{
"supportingDocumentReference": "String | BT-122",
"supportingDocumentDescription": "String | BT-123",
"externalDocumentLocation": "String | BT-124",
"attachedDocument": "String | BT-125"
}
],
"invoiceLine": [
{
"invoiceLineIdentifier": "String | BT-126",
"invoiceLineNote": "String | BT-127",
"invoiceLineObjectIdentifier": "String | BT-128",
"invoicedQuantity": "Decimal | BT-129",
"invoicedQuantityUnitOfMeasureCode": "String | BT-130",
"invoiceLineNetAmount": "Decimal | BT-131",
"referencedPurchaseOrderLineReference": "String | BT-132",
"invoiceLineBuyerAccountingReference": "String | BT-133",
"invoiceLinePeriod": {
"invoiceLinePeriodStartDate": "Date | BT-134",
"invoiceLinePeriodEndDate": "Date | BT-135"
},
"invoiceLineAllowances": [
{
"invoiceLineAllowanceAmount": "Decimal | BT-136",
"invoiceLineAllowanceBaseAmount": "Decimal | BT-137",
"invoiceLineAllowancePercentage": "Decimal | BT-138",
"invoiceLineAllowanceReason": "String | BT-139",
"invoiceLineAllowanceReasonCode": "String | BT-140"
}
],
"invoiceLineCharges": [
{
"invoiceLineChargeAmount": "Decimal | BT-141",
"invoiceLineChargeBaseAmount": "Decimal | BT-142",
"invoiceLineChargePercentage": "Decimal | BT-143",
"invoiceLineChargeReason": "String | BT-144",
"invoiceLineChargeReasonCode": "String | BT-145"
}
],
"priceDetails": {
"itemNetPrice": "Decimal | BT-146",
"itemPriceDiscount": "Decimal | BT-147",
"itemGrossPrice": "Decimal | BT-148",
"itemPriceBaseQuantity": "Decimal | BT-149",
"itemPriceBaseQuantityUnitOfMeasure": "String | BT-150"
},
"lineVatInformation": [
{
"invoicedItemVatCategoryCode": "String | BT-151",
"invoicedItemVatRate": "Decimal | BT-152"
}
],
"itemInformation": {
"itemName": "String | BT-153",
"itemDescription": "String | BT-154",
"itemSellersIdentifier": "String | BT-155",
"itemBuyersIdentifier": "String | BT-156",
"itemStandardIdentifier": "String | BT-157",
"itemStandardIdentifierSchemeIdentifier": "String | BT-157-1",
"itemClassificationIdentifier": [
{
"itemClassificationIdentifier": "String | BT-158",
"itemClassificationIdentifierListIdentifier": "String | BT-158-1",
"itemClassificationIdentifierListVersionIdentifier": "String | BT-158-2"
}
],
"itemCountryOfOrigin": "String | BT-159",
"itemAttributes": [
{
"itemAttributeName": "String | BT-160",
"itemAttributeValue": "String | BT-161"
}
]
}
}
]
},
"invoicePdf64": "JVBERi0xLjQK..."
}Beispielantwort
json
{
"message": "ZUGFeRD created",
"zugferdValid": false,
"xInvoiceValid": false,
"numberOfZugferdErrors": 1,
"numberOfxInvoiceErrors": 1,
"zugferd": "JVBERi0xLjcKJY/6qbAKMyAwIG9iago8PC9...",
"zugferdErrorList": [],
"xInvoice": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><rsm:CrossIndustryInvoice>...</rsm:CrossIndustryInvoice>",
"xInvoiceErrorList": []
}Playground
Diesen Endpunkt live im Browser testen.
POST
/api/v1/zugferd/createZugferdPdfFromXinvoiceZUGFeRD-PDF aus XRechnung erstellen
Erstellt ein ZUGFeRD-konformes PDF/A-3, indem eine vorhandene XRechnungs-XML in ein PDF-Dokument eingebettet wird.
| Field | Type | Required | Description |
|---|---|---|---|
xInvoiceXml | string | required | XRechnungs-XML als String. |
invoicePdf64 | string (base64) | required | Base64-kodiertes PDF für die XML-Einbettung. |
Beispiel
json
{
"xInvoiceXml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><rsm:CrossIndustryInvoice>...</rsm:CrossIndustryInvoice>",
"invoicePdf64": "JVBERi0xLjQK..."
}Beispielantwort
json
{
"valid": false,
"message": "zugferd created",
"numberOfZugferdErrors": 0,
"zugferdFile": "JVBERi0xLjcKJaOIwOMKMyAwIG9iago...",
"zugferdErrors": []
}Playground
Diesen Endpunkt live im Browser testen.
POST
/api/v1/zugferd/createInvoicePdfFromJsonZUGFeRD-Rechnungs-PDF aus JSON erzeugen (Template)
Erzeugt ein ZUGFeRD-konformes Rechnungs-PDF aus JSON-Daten über ein eigenes Word- oder Design-Template. Ab 2027 in Deutschland verpflichtend.
| Field | Type | Required | Description |
|---|---|---|---|
invoice | object | required | Rechnungsobjekt. |
templateId | string | required | ID des Templates für die PDF-Erzeugung. |
Beispiel
json
{
"templateId": "your-template-id",
"invoice": {
"invoiceNumber": "String | BT-1",
"invoiceIssueDate": "Date | BT-2",
"invoiceTypeCode": "String | BT-3",
"invoiceCurrencyCode": "String | BT-5",
"vatAccountingCurrencyCode": "String | BT-6",
"valueAddedTaxPointDate": "String | BT-7",
"valueAddedTaxPointDateCode": "String | BT-8",
"paymentDueDate": "Date | BT-9",
"buyerReference": "String | BT-10",
"projectReference": {
"projectReferenceIdentifier": "String | BT-11",
"projectReferenceName": "String | BT-11-0"
},
"contractReference": "String | BT-12",
"purchaseOrderReference": "String | BT-13",
"salesOrderReference": "String | BT-14",
"receivingAdviceReference": "String | BT-15",
"despatchAdviceReference": "String | BT-16",
"tenderOrLotReference": "String | BT-17",
"invoicedObjectIdentifier": "String | BT-18",
"buyerAccountingReference": "String | BT-19",
"paymentTerms": "String | BT-20",
"invoiceNote": [
{
"invoiceNoteSubjectCode": "String | BT-21",
"invoiceNote": "String | BT-22"
}
],
"processControl": {
"businessProcessTypeIdentifier": "String | BT-23",
"specificationIdentifier": "String | BT-24"
},
"precedingInvoiceReference": [
{
"precedingInvoiceReference": "String | BT-25",
"precedingInvoiceIssueDate": "Date | BT-26"
}
],
"seller": {
"sellerName": "String | BT-27",
"sellerTradingName": "String | BT-28",
"sellerIdentifier": [
"String | BT-29"
],
"sellerLegalRegistrationIdentifier": "String | BT-30",
"sellerVatIdentifier": "String | BT-31",
"sellerTaxRegistrationIdentifier": "String | BT-32",
"sellerAdditionalLegalInformation": "String | BT-33",
"sellerElectronicAddress": "String | BT-34",
"sellerPostalAddress": {
"sellerAddressLine1": "String | BT-35",
"sellerAddressLine2": "String | BT-36",
"sellerAddressLine3": "String | BT-162",
"sellerCity": "String | BT-37",
"sellerPostCode": "String | BT-38",
"sellerCountrySubdivision": "String | BT-39",
"sellerCountryCode": "String | BT-40"
},
"sellerContact": {
"sellerContactPoint": "String | BT-41",
"sellerContactTelephoneNumber": "String | BT-42",
"sellerContactEmailAddress": "String | BT-43"
}
},
"buyer": {
"buyerName": "String | BT-44",
"buyerTradingName": "String | BT-45",
"buyerIdentifier": "String | BT-46",
"buyerLegalRegistrationIdentifier": "String | BT-47",
"buyerVatIdentifier": "String | BT-48",
"buyerElectronicAddress": "String | BT-49",
"buyerPostalAddress": {
"buyerAddressLine1": "String | BT-50",
"buyerAddressLine2": "String | BT-51",
"buyerAddressLine3": "String | BT-163",
"buyerCity": "String | BT-52",
"buyerPostCode": "String | BT-53",
"buyerCountrySubdivision": "String | BT-54",
"buyerCountryCode": "String | BT-55"
},
"buyerContact": {
"buyerContactPoint": "String | BT-56",
"buyerContactTelephoneNumber": "String | BT-57",
"buyerContactEmailAddress": "String | BT-58"
}
},
"payee": {
"payeeName": "String | BT-59",
"payeeIdentifier": "String | BT-60",
"payeeLegalRegistrationIdentifier": "String | BT-61"
},
"sellerTaxRepresentativeParty": {
"sellerTaxRepresentativeName": "String | BT-62",
"sellerTaxRepresentativeVatIdentifier": "String | BT-63",
"sellerTaxRepresentativePostalAddress": {
"taxRepresentativeAddressLine1": "String | BT-64",
"taxRepresentativeAddressLine2": "String | BT-65",
"taxRepresentativeAddressLine3": "String | BT-164",
"taxRepresentativeCity": "String | BT-66",
"taxRepresentativePostCode": "String | BT-67",
"taxRepresentativeCountrySubdivision": "String | BT-68",
"taxRepresentativeCountryCode": "String | BT-69"
}
},
"deliveryInformation": {
"deliverToPartyName": "String | BT-70",
"deliverToLocationIdentifier": "String | BT-71",
"actualDeliveryDate": "Date | BT-72",
"deliverToAddress": {
"deliverToAddressLine1": "String | BT-75",
"deliverToAddressLine2": "String | BT-76",
"deliverToAddressLine3": "String | BT-165",
"deliverToCity": "String | BT-77",
"deliverToPostCode": "String | BT-78",
"deliverToCountrySubdivision": "String | BT-79",
"deliverToCountryCode": "String | BT-80"
}
},
"invoicingPeriod": {
"invoicingPeriodStartDate": "Date | BT-73",
"invoicingPeriodEndDate": "Date | BT-74"
},
"paymentInstructions": {
"paymentMeansTypeCode": "String | BT-81",
"paymentMeansText": "String | BT-82",
"remittanceInformation": "String | BT-83",
"creditTransfer": [
{
"paymentAccountIdentifier": "String | BT-84",
"paymentAccountName": "String | BT-85",
"paymentServiceProviderIdentifier": "String | BT-86"
}
],
"paymentCardInformation": {
"paymentCardPrimaryAccountNumber": "String | BT-87",
"paymentCardHolderName": "String | BT-88"
},
"directDebit": {
"mandateReferenceIdentifier": "String | BT-89",
"bankAssignedCreditorIdentifier": "String | BT-90",
"debitedAccountIdentifier": "String | BT-91"
}
},
"documentLevelAllowances": [
{
"documentLevelAllowanceAmount": "Decimal | BT-92",
"documentLevelAllowanceBaseAmount": "Decimal | BT-93",
"documentLevelAllowancePercentage": "Decimal | BT-94",
"documentLevelAllowanceVatCategoryCode": "String | BT-95",
"documentLevelAllowanceVatRate": "Decimal | BT-96",
"documentLevelAllowanceReason": "String | BT-97",
"documentLevelAllowanceReasonCode": "String | BT-98"
}
],
"documentLevelCharges": [
{
"documentLevelChargeAmount": "Decimal | BT-99",
"documentLevelChargeBaseAmount": "Decimal | BT-100",
"documentLevelChargePercentage": "Decimal | BT-101",
"documentLevelChargeVatCategoryCode": "String | BT-102",
"documentLevelChargeVatRate": "Decimal | BT-103",
"documentLevelChargeReason": "String | BT-104",
"documentLevelChargeReasonCode": "String | BT-105"
}
],
"documentTotals": {
"sumOfInvoiceLineNetAmount": "Decimal | BT-106",
"sumOfAllowancesOnDocumentLevel": "Decimal | BT-107",
"sumOfChargesOnDocumentLevel": "Decimal | BT-108",
"invoiceTotalAmountWithoutVat": "Decimal | BT-109",
"invoiceTotalVatAmount": "Decimal | BT-110",
"invoiceTotalVatAmountInAccountingCurrency": "Decimal | BT-111",
"invoiceTotalAmountWithVat": "Decimal | BT-112",
"paidAmount": "Decimal | BT-113",
"roundingAmount": "Decimal | BT-114",
"amountDueForPayment": "Decimal | BT-115"
},
"vatBreakdown": [
{
"vatCategoryTaxableAmount": "Decimal | BT-116",
"vatCategoryTaxAmount": "Decimal | BT-117",
"vatCategoryCode": "String | BT-118",
"vatCategoryRate": "Decimal | BT-119",
"vatExemptionReasonText": "String | BT-120",
"vatExemptionReasonCode": "String | BT-121"
}
],
"additionalSupportingDocuments": [
{
"supportingDocumentReference": "String | BT-122",
"supportingDocumentDescription": "String | BT-123",
"externalDocumentLocation": "String | BT-124",
"attachedDocument": "String | BT-125"
}
],
"invoiceLine": [
{
"invoiceLineIdentifier": "String | BT-126",
"invoiceLineNote": "String | BT-127",
"invoiceLineObjectIdentifier": "String | BT-128",
"invoicedQuantity": "Decimal | BT-129",
"invoicedQuantityUnitOfMeasureCode": "String | BT-130",
"invoiceLineNetAmount": "Decimal | BT-131",
"referencedPurchaseOrderLineReference": "String | BT-132",
"invoiceLineBuyerAccountingReference": "String | BT-133",
"invoiceLinePeriod": {
"invoiceLinePeriodStartDate": "Date | BT-134",
"invoiceLinePeriodEndDate": "Date | BT-135"
},
"invoiceLineAllowances": [
{
"invoiceLineAllowanceAmount": "Decimal | BT-136",
"invoiceLineAllowanceBaseAmount": "Decimal | BT-137",
"invoiceLineAllowancePercentage": "Decimal | BT-138",
"invoiceLineAllowanceReason": "String | BT-139",
"invoiceLineAllowanceReasonCode": "String | BT-140"
}
],
"invoiceLineCharges": [
{
"invoiceLineChargeAmount": "Decimal | BT-141",
"invoiceLineChargeBaseAmount": "Decimal | BT-142",
"invoiceLineChargePercentage": "Decimal | BT-143",
"invoiceLineChargeReason": "String | BT-144",
"invoiceLineChargeReasonCode": "String | BT-145"
}
],
"priceDetails": {
"itemNetPrice": "Decimal | BT-146",
"itemPriceDiscount": "Decimal | BT-147",
"itemGrossPrice": "Decimal | BT-148",
"itemPriceBaseQuantity": "Decimal | BT-149",
"itemPriceBaseQuantityUnitOfMeasure": "String | BT-150"
},
"lineVatInformation": [
{
"invoicedItemVatCategoryCode": "String | BT-151",
"invoicedItemVatRate": "Decimal | BT-152"
}
],
"itemInformation": {
"itemName": "String | BT-153",
"itemDescription": "String | BT-154",
"itemSellersIdentifier": "String | BT-155",
"itemBuyersIdentifier": "String | BT-156",
"itemStandardIdentifier": "String | BT-157",
"itemStandardIdentifierSchemeIdentifier": "String | BT-157-1",
"itemClassificationIdentifier": [
{
"itemClassificationIdentifier": "String | BT-158",
"itemClassificationIdentifierListIdentifier": "String | BT-158-1",
"itemClassificationIdentifierListVersionIdentifier": "String | BT-158-2"
}
],
"itemCountryOfOrigin": "String | BT-159",
"itemAttributes": [
{
"itemAttributeName": "String | BT-160",
"itemAttributeValue": "String | BT-161"
}
]
}
}
]
}
}Beispielantwort
json
{
"message": "invoice and pdf created",
"fileName": "in-2525-4n4_20250805_1755765122.pdf",
"fileExtension": "pdf",
"fileSize": 78573,
"filecontentB64": "JVBERi0xLjQK..."
}Beispielantwort
json
{
"message": "invoice and pdf created",
"fileName": "in-2525-4n4_20250805_1755765122.pdf",
"fileExtension": "pdf",
"fileSize": 78573,
"filecontentB64": "JVBERi0xLjQK..."
}Playground
Diesen Endpunkt live im Browser testen.
PDF Analyse
POST
/api/v1/zugferd/createJSONFromAnalysedPdfRechnungs-PDF analysieren
Analysiert das übergebene Rechnungs-PDF und extrahiert strukturierte Daten: Käufer, Verkäufer, Positionen, MwSt. und Gesamtbeträge. Ideal als Einstiegspunkt für PDF-basierte Rechnungsworkflows.
| Field | Type | Required | Description |
|---|---|---|---|
pdfInvoiceBase64 | string | required | Base64-kodierter Inhalt der PDF-Rechnung. |
Beispiel
json
{
"pdfInvoiceBase64": "JVBERi0xLjQKJf..."
}Beispielantwort
json
{
"apiStatus": 200,
"invoice": [
{
"invoiceNumber": "String | BT-1",
"invoiceIssueDate": "Date | BT-2",
"invoiceTypeCode": "String | BT-3",
"invoiceCurrencyCode": "String | BT-5",
"vatAccountingCurrencyCode": "String | BT-6",
"valueAddedTaxPointDate": "String | BT-7",
"valueAddedTaxPointDateCode": "String | BT-8",
"paymentDueDate": "Date | BT-9",
"buyerReference": "String | BT-10",
"projectReference": {
"projectReferenceIdentifier": "String | BT-11",
"projectReferenceName": "String | BT-11-0"
},
"contractReference": "String | BT-12",
"purchaseOrderReference": "String | BT-13",
"salesOrderReference": "String | BT-14",
"receivingAdviceReference": "String | BT-15",
"despatchAdviceReference": "String | BT-16",
"tenderOrLotReference": "String | BT-17",
"invoicedObjectIdentifier": "String | BT-18",
"buyerAccountingReference": "String | BT-19",
"paymentTerms": "String | BT-20",
"invoiceNote": [
{
"invoiceNoteSubjectCode": "String | BT-21",
"invoiceNote": "String | BT-22"
}
],
"processControl": {
"businessProcessTypeIdentifier": "String | BT-23",
"specificationIdentifier": "String | BT-24"
},
"precedingInvoiceReference": [
{
"precedingInvoiceReference": "String | BT-25",
"precedingInvoiceIssueDate": "Date | BT-26"
}
],
"seller": {
"sellerName": "String | BT-27",
"sellerTradingName": "String | BT-28",
"sellerIdentifier": [
"String | BT-29"
],
"sellerLegalRegistrationIdentifier": "String | BT-30",
"sellerVatIdentifier": "String | BT-31",
"sellerTaxRegistrationIdentifier": "String | BT-32",
"sellerAdditionalLegalInformation": "String | BT-33",
"sellerElectronicAddress": "String | BT-34",
"sellerPostalAddress": {
"sellerAddressLine1": "String | BT-35",
"sellerAddressLine2": "String | BT-36",
"sellerAddressLine3": "String | BT-162",
"sellerCity": "String | BT-37",
"sellerPostCode": "String | BT-38",
"sellerCountrySubdivision": "String | BT-39",
"sellerCountryCode": "String | BT-40"
},
"sellerContact": {
"sellerContactPoint": "String | BT-41",
"sellerContactTelephoneNumber": "String | BT-42",
"sellerContactEmailAddress": "String | BT-43"
}
},
"buyer": {
"buyerName": "String | BT-44",
"buyerTradingName": "String | BT-45",
"buyerIdentifier": "String | BT-46",
"buyerLegalRegistrationIdentifier": "String | BT-47",
"buyerVatIdentifier": "String | BT-48",
"buyerElectronicAddress": "String | BT-49",
"buyerPostalAddress": {
"buyerAddressLine1": "String | BT-50",
"buyerAddressLine2": "String | BT-51",
"buyerAddressLine3": "String | BT-163",
"buyerCity": "String | BT-52",
"buyerPostCode": "String | BT-53",
"buyerCountrySubdivision": "String | BT-54",
"buyerCountryCode": "String | BT-55"
},
"buyerContact": {
"buyerContactPoint": "String | BT-56",
"buyerContactTelephoneNumber": "String | BT-57",
"buyerContactEmailAddress": "String | BT-58"
}
},
"payee": {
"payeeName": "String | BT-59",
"payeeIdentifier": "String | BT-60",
"payeeLegalRegistrationIdentifier": "String | BT-61"
},
"sellerTaxRepresentativeParty": {
"sellerTaxRepresentativeName": "String | BT-62",
"sellerTaxRepresentativeVatIdentifier": "String | BT-63",
"sellerTaxRepresentativePostalAddress": {
"taxRepresentativeAddressLine1": "String | BT-64",
"taxRepresentativeAddressLine2": "String | BT-65",
"taxRepresentativeAddressLine3": "String | BT-164",
"taxRepresentativeCity": "String | BT-66",
"taxRepresentativePostCode": "String | BT-67",
"taxRepresentativeCountrySubdivision": "String | BT-68",
"taxRepresentativeCountryCode": "String | BT-69"
}
},
"deliveryInformation": {
"deliverToPartyName": "String | BT-70",
"deliverToLocationIdentifier": "String | BT-71",
"actualDeliveryDate": "Date | BT-72",
"deliverToAddress": {
"deliverToAddressLine1": "String | BT-75",
"deliverToAddressLine2": "String | BT-76",
"deliverToAddressLine3": "String | BT-165",
"deliverToCity": "String | BT-77",
"deliverToPostCode": "String | BT-78",
"deliverToCountrySubdivision": "String | BT-79",
"deliverToCountryCode": "String | BT-80"
}
},
"invoicingPeriod": {
"invoicingPeriodStartDate": "Date | BT-73",
"invoicingPeriodEndDate": "Date | BT-74"
},
"paymentInstructions": {
"paymentMeansTypeCode": "String | BT-81",
"paymentMeansText": "String | BT-82",
"remittanceInformation": "String | BT-83",
"creditTransfer": [
{
"paymentAccountIdentifier": "String | BT-84",
"paymentAccountName": "String | BT-85",
"paymentServiceProviderIdentifier": "String | BT-86"
}
],
"paymentCardInformation": {
"paymentCardPrimaryAccountNumber": "String | BT-87",
"paymentCardHolderName": "String | BT-88"
},
"directDebit": {
"mandateReferenceIdentifier": "String | BT-89",
"bankAssignedCreditorIdentifier": "String | BT-90",
"debitedAccountIdentifier": "String | BT-91"
}
},
"documentLevelAllowances": [
{
"documentLevelAllowanceAmount": "Decimal | BT-92",
"documentLevelAllowanceBaseAmount": "Decimal | BT-93",
"documentLevelAllowancePercentage": "Decimal | BT-94",
"documentLevelAllowanceVatCategoryCode": "String | BT-95",
"documentLevelAllowanceVatRate": "Decimal | BT-96",
"documentLevelAllowanceReason": "String | BT-97",
"documentLevelAllowanceReasonCode": "String | BT-98"
}
],
"documentLevelCharges": [
{
"documentLevelChargeAmount": "Decimal | BT-99",
"documentLevelChargeBaseAmount": "Decimal | BT-100",
"documentLevelChargePercentage": "Decimal | BT-101",
"documentLevelChargeVatCategoryCode": "String | BT-102",
"documentLevelChargeVatRate": "Decimal | BT-103",
"documentLevelChargeReason": "String | BT-104",
"documentLevelChargeReasonCode": "String | BT-105"
}
],
"documentTotals": {
"sumOfInvoiceLineNetAmount": "Decimal | BT-106",
"sumOfAllowancesOnDocumentLevel": "Decimal | BT-107",
"sumOfChargesOnDocumentLevel": "Decimal | BT-108",
"invoiceTotalAmountWithoutVat": "Decimal | BT-109",
"invoiceTotalVatAmount": "Decimal | BT-110",
"invoiceTotalVatAmountInAccountingCurrency": "Decimal | BT-111",
"invoiceTotalAmountWithVat": "Decimal | BT-112",
"paidAmount": "Decimal | BT-113",
"roundingAmount": "Decimal | BT-114",
"amountDueForPayment": "Decimal | BT-115"
},
"vatBreakdown": [
{
"vatCategoryTaxableAmount": "Decimal | BT-116",
"vatCategoryTaxAmount": "Decimal | BT-117",
"vatCategoryCode": "String | BT-118",
"vatCategoryRate": "Decimal | BT-119",
"vatExemptionReasonText": "String | BT-120",
"vatExemptionReasonCode": "String | BT-121"
}
],
"additionalSupportingDocuments": [
{
"supportingDocumentReference": "String | BT-122",
"supportingDocumentDescription": "String | BT-123",
"externalDocumentLocation": "String | BT-124",
"attachedDocument": "String | BT-125"
}
],
"invoiceLine": [
{
"invoiceLineIdentifier": "String | BT-126",
"invoiceLineNote": "String | BT-127",
"invoiceLineObjectIdentifier": "String | BT-128",
"invoicedQuantity": "Decimal | BT-129",
"invoicedQuantityUnitOfMeasureCode": "String | BT-130",
"invoiceLineNetAmount": "Decimal | BT-131",
"referencedPurchaseOrderLineReference": "String | BT-132",
"invoiceLineBuyerAccountingReference": "String | BT-133",
"invoiceLinePeriod": {
"invoiceLinePeriodStartDate": "Date | BT-134",
"invoiceLinePeriodEndDate": "Date | BT-135"
},
"invoiceLineAllowances": [
{
"invoiceLineAllowanceAmount": "Decimal | BT-136",
"invoiceLineAllowanceBaseAmount": "Decimal | BT-137",
"invoiceLineAllowancePercentage": "Decimal | BT-138",
"invoiceLineAllowanceReason": "String | BT-139",
"invoiceLineAllowanceReasonCode": "String | BT-140"
}
],
"invoiceLineCharges": [
{
"invoiceLineChargeAmount": "Decimal | BT-141",
"invoiceLineChargeBaseAmount": "Decimal | BT-142",
"invoiceLineChargePercentage": "Decimal | BT-143",
"invoiceLineChargeReason": "String | BT-144",
"invoiceLineChargeReasonCode": "String | BT-145"
}
],
"priceDetails": {
"itemNetPrice": "Decimal | BT-146",
"itemPriceDiscount": "Decimal | BT-147",
"itemGrossPrice": "Decimal | BT-148",
"itemPriceBaseQuantity": "Decimal | BT-149",
"itemPriceBaseQuantityUnitOfMeasure": "String | BT-150"
},
"lineVatInformation": [
{
"invoicedItemVatCategoryCode": "String | BT-151",
"invoicedItemVatRate": "Decimal | BT-152"
}
],
"itemInformation": {
"itemName": "String | BT-153",
"itemDescription": "String | BT-154",
"itemSellersIdentifier": "String | BT-155",
"itemBuyersIdentifier": "String | BT-156",
"itemStandardIdentifier": "String | BT-157",
"itemStandardIdentifierSchemeIdentifier": "String | BT-157-1",
"itemClassificationIdentifier": [
{
"itemClassificationIdentifier": "String | BT-158",
"itemClassificationIdentifierListIdentifier": "String | BT-158-1",
"itemClassificationIdentifierListVersionIdentifier": "String | BT-158-2"
}
],
"itemCountryOfOrigin": "String | BT-159",
"itemAttributes": [
{
"itemAttributeName": "String | BT-160",
"itemAttributeValue": "String | BT-161"
}
]
}
}
]
}
]
}Playground
Diesen Endpunkt live im Browser testen.
Extraktion
POST
/api/v1/zugferd/extractXInvoiceFromZugferdToJsonXRechnung aus ZUGFeRD als JSON extrahieren
Extrahiert die eingebettete XRechnungs-XML aus einem ZUGFeRD-PDF und gibt sie als strukturiertes JSON-Objekt für die Weiterverarbeitung zurück.
| Field | Type | Required | Description |
|---|---|---|---|
zugferd64 | string (base64) | required | Das ZUGFeRD-PDF-Dokument als Base64-kodierter String. |
Beispiel
json
{
"zugferd64": "JVBERi0xLjcKJbe3wvUKMyAwIG9iago8PC9UeXBl..."
}Beispielantwort
json
{
"invoice": {
"invoiceNumber": "String | BT-1",
"invoiceIssueDate": "Date | BT-2",
"invoiceTypeCode": "String | BT-3",
"invoiceCurrencyCode": "String | BT-5",
"vatAccountingCurrencyCode": "String | BT-6",
"valueAddedTaxPointDate": "String | BT-7",
"valueAddedTaxPointDateCode": "String | BT-8",
"paymentDueDate": "Date | BT-9",
"buyerReference": "String | BT-10",
"projectReference": {
"projectReferenceIdentifier": "String | BT-11",
"projectReferenceName": "String | BT-11-0"
},
"contractReference": "String | BT-12",
"purchaseOrderReference": "String | BT-13",
"salesOrderReference": "String | BT-14",
"receivingAdviceReference": "String | BT-15",
"despatchAdviceReference": "String | BT-16",
"tenderOrLotReference": "String | BT-17",
"invoicedObjectIdentifier": "String | BT-18",
"buyerAccountingReference": "String | BT-19",
"paymentTerms": "String | BT-20",
"invoiceNote": [
{
"invoiceNoteSubjectCode": "String | BT-21",
"invoiceNote": "String | BT-22"
}
],
"processControl": {
"businessProcessTypeIdentifier": "String | BT-23",
"specificationIdentifier": "String | BT-24"
},
"precedingInvoiceReference": [
{
"precedingInvoiceReference": "String | BT-25",
"precedingInvoiceIssueDate": "Date | BT-26"
}
],
"seller": {
"sellerName": "String | BT-27",
"sellerTradingName": "String | BT-28",
"sellerIdentifier": [
"String | BT-29"
],
"sellerLegalRegistrationIdentifier": "String | BT-30",
"sellerVatIdentifier": "String | BT-31",
"sellerTaxRegistrationIdentifier": "String | BT-32",
"sellerAdditionalLegalInformation": "String | BT-33",
"sellerElectronicAddress": "String | BT-34",
"sellerPostalAddress": {
"sellerAddressLine1": "String | BT-35",
"sellerAddressLine2": "String | BT-36",
"sellerAddressLine3": "String | BT-162",
"sellerCity": "String | BT-37",
"sellerPostCode": "String | BT-38",
"sellerCountrySubdivision": "String | BT-39",
"sellerCountryCode": "String | BT-40"
},
"sellerContact": {
"sellerContactPoint": "String | BT-41",
"sellerContactTelephoneNumber": "String | BT-42",
"sellerContactEmailAddress": "String | BT-43"
}
},
"buyer": {
"buyerName": "String | BT-44",
"buyerTradingName": "String | BT-45",
"buyerIdentifier": "String | BT-46",
"buyerLegalRegistrationIdentifier": "String | BT-47",
"buyerVatIdentifier": "String | BT-48",
"buyerElectronicAddress": "String | BT-49",
"buyerPostalAddress": {
"buyerAddressLine1": "String | BT-50",
"buyerAddressLine2": "String | BT-51",
"buyerAddressLine3": "String | BT-163",
"buyerCity": "String | BT-52",
"buyerPostCode": "String | BT-53",
"buyerCountrySubdivision": "String | BT-54",
"buyerCountryCode": "String | BT-55"
},
"buyerContact": {
"buyerContactPoint": "String | BT-56",
"buyerContactTelephoneNumber": "String | BT-57",
"buyerContactEmailAddress": "String | BT-58"
}
},
"payee": {
"payeeName": "String | BT-59",
"payeeIdentifier": "String | BT-60",
"payeeLegalRegistrationIdentifier": "String | BT-61"
},
"sellerTaxRepresentativeParty": {
"sellerTaxRepresentativeName": "String | BT-62",
"sellerTaxRepresentativeVatIdentifier": "String | BT-63",
"sellerTaxRepresentativePostalAddress": {
"taxRepresentativeAddressLine1": "String | BT-64",
"taxRepresentativeAddressLine2": "String | BT-65",
"taxRepresentativeAddressLine3": "String | BT-164",
"taxRepresentativeCity": "String | BT-66",
"taxRepresentativePostCode": "String | BT-67",
"taxRepresentativeCountrySubdivision": "String | BT-68",
"taxRepresentativeCountryCode": "String | BT-69"
}
},
"deliveryInformation": {
"deliverToPartyName": "String | BT-70",
"deliverToLocationIdentifier": "String | BT-71",
"actualDeliveryDate": "Date | BT-72",
"deliverToAddress": {
"deliverToAddressLine1": "String | BT-75",
"deliverToAddressLine2": "String | BT-76",
"deliverToAddressLine3": "String | BT-165",
"deliverToCity": "String | BT-77",
"deliverToPostCode": "String | BT-78",
"deliverToCountrySubdivision": "String | BT-79",
"deliverToCountryCode": "String | BT-80"
}
},
"invoicingPeriod": {
"invoicingPeriodStartDate": "Date | BT-73",
"invoicingPeriodEndDate": "Date | BT-74"
},
"paymentInstructions": {
"paymentMeansTypeCode": "String | BT-81",
"paymentMeansText": "String | BT-82",
"remittanceInformation": "String | BT-83",
"creditTransfer": [
{
"paymentAccountIdentifier": "String | BT-84",
"paymentAccountName": "String | BT-85",
"paymentServiceProviderIdentifier": "String | BT-86"
}
],
"paymentCardInformation": {
"paymentCardPrimaryAccountNumber": "String | BT-87",
"paymentCardHolderName": "String | BT-88"
},
"directDebit": {
"mandateReferenceIdentifier": "String | BT-89",
"bankAssignedCreditorIdentifier": "String | BT-90",
"debitedAccountIdentifier": "String | BT-91"
}
},
"documentLevelAllowances": [
{
"documentLevelAllowanceAmount": "Decimal | BT-92",
"documentLevelAllowanceBaseAmount": "Decimal | BT-93",
"documentLevelAllowancePercentage": "Decimal | BT-94",
"documentLevelAllowanceVatCategoryCode": "String | BT-95",
"documentLevelAllowanceVatRate": "Decimal | BT-96",
"documentLevelAllowanceReason": "String | BT-97",
"documentLevelAllowanceReasonCode": "String | BT-98"
}
],
"documentLevelCharges": [
{
"documentLevelChargeAmount": "Decimal | BT-99",
"documentLevelChargeBaseAmount": "Decimal | BT-100",
"documentLevelChargePercentage": "Decimal | BT-101",
"documentLevelChargeVatCategoryCode": "String | BT-102",
"documentLevelChargeVatRate": "Decimal | BT-103",
"documentLevelChargeReason": "String | BT-104",
"documentLevelChargeReasonCode": "String | BT-105"
}
],
"documentTotals": {
"sumOfInvoiceLineNetAmount": "Decimal | BT-106",
"sumOfAllowancesOnDocumentLevel": "Decimal | BT-107",
"sumOfChargesOnDocumentLevel": "Decimal | BT-108",
"invoiceTotalAmountWithoutVat": "Decimal | BT-109",
"invoiceTotalVatAmount": "Decimal | BT-110",
"invoiceTotalVatAmountInAccountingCurrency": "Decimal | BT-111",
"invoiceTotalAmountWithVat": "Decimal | BT-112",
"paidAmount": "Decimal | BT-113",
"roundingAmount": "Decimal | BT-114",
"amountDueForPayment": "Decimal | BT-115"
},
"vatBreakdown": [
{
"vatCategoryTaxableAmount": "Decimal | BT-116",
"vatCategoryTaxAmount": "Decimal | BT-117",
"vatCategoryCode": "String | BT-118",
"vatCategoryRate": "Decimal | BT-119",
"vatExemptionReasonText": "String | BT-120",
"vatExemptionReasonCode": "String | BT-121"
}
],
"additionalSupportingDocuments": [
{
"supportingDocumentReference": "String | BT-122",
"supportingDocumentDescription": "String | BT-123",
"externalDocumentLocation": "String | BT-124",
"attachedDocument": "String | BT-125"
}
],
"invoiceLine": [
{
"invoiceLineIdentifier": "String | BT-126",
"invoiceLineNote": "String | BT-127",
"invoiceLineObjectIdentifier": "String | BT-128",
"invoicedQuantity": "Decimal | BT-129",
"invoicedQuantityUnitOfMeasureCode": "String | BT-130",
"invoiceLineNetAmount": "Decimal | BT-131",
"referencedPurchaseOrderLineReference": "String | BT-132",
"invoiceLineBuyerAccountingReference": "String | BT-133",
"invoiceLinePeriod": {
"invoiceLinePeriodStartDate": "Date | BT-134",
"invoiceLinePeriodEndDate": "Date | BT-135"
},
"invoiceLineAllowances": [
{
"invoiceLineAllowanceAmount": "Decimal | BT-136",
"invoiceLineAllowanceBaseAmount": "Decimal | BT-137",
"invoiceLineAllowancePercentage": "Decimal | BT-138",
"invoiceLineAllowanceReason": "String | BT-139",
"invoiceLineAllowanceReasonCode": "String | BT-140"
}
],
"invoiceLineCharges": [
{
"invoiceLineChargeAmount": "Decimal | BT-141",
"invoiceLineChargeBaseAmount": "Decimal | BT-142",
"invoiceLineChargePercentage": "Decimal | BT-143",
"invoiceLineChargeReason": "String | BT-144",
"invoiceLineChargeReasonCode": "String | BT-145"
}
],
"priceDetails": {
"itemNetPrice": "Decimal | BT-146",
"itemPriceDiscount": "Decimal | BT-147",
"itemGrossPrice": "Decimal | BT-148",
"itemPriceBaseQuantity": "Decimal | BT-149",
"itemPriceBaseQuantityUnitOfMeasure": "String | BT-150"
},
"lineVatInformation": [
{
"invoicedItemVatCategoryCode": "String | BT-151",
"invoicedItemVatRate": "Decimal | BT-152"
}
],
"itemInformation": {
"itemName": "String | BT-153",
"itemDescription": "String | BT-154",
"itemSellersIdentifier": "String | BT-155",
"itemBuyersIdentifier": "String | BT-156",
"itemStandardIdentifier": "String | BT-157",
"itemStandardIdentifierSchemeIdentifier": "String | BT-157-1",
"itemClassificationIdentifier": [
{
"itemClassificationIdentifier": "String | BT-158",
"itemClassificationIdentifierListIdentifier": "String | BT-158-1",
"itemClassificationIdentifierListVersionIdentifier": "String | BT-158-2"
}
],
"itemCountryOfOrigin": "String | BT-159",
"itemAttributes": [
{
"itemAttributeName": "String | BT-160",
"itemAttributeValue": "String | BT-161"
}
]
}
}
]
}
}Playground
Diesen Endpunkt live im Browser testen.
Validierung
POST
/api/v1/zugferd/validateXinvoiceXMLXRechnung-XML validieren
Validiert XRechnungs-XML gegen EN 16931 und XRechnung-Business-Regeln. Gibt strukturierte Fehler mit Regel-IDs und Positionen zurück, damit Verstöße vor dem Versand behoben werden können.
| Field | Type | Required | Description |
|---|---|---|---|
xinvoiceXML | string | required | XRechnungs-XML-Inhalt als String. |
Beispiel
json
{
"xinvoiceXML": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>..."
}Beispielantwort
json
{
"valid": false,
"message": "validated. (7835)",
"xInvoiceErrors": [
{
"id": "BR-CO-25",
"line": null,
"location": "/rsm:CrossIndustryInvoice",
"message": "In case the Amount due for payment (BT-115) is positive, either the Payment due date (BT-9) or the Payment terms (BT-20) shall be present.",
"schemaFile": "EN16931-CII-validation",
"type": "fatal"
}
]
}Playground
Diesen Endpunkt live im Browser testen.
POST
/api/v1/zugferd/validateZugferdPdfZUGFeRD-PDF validieren
Validiert ein bestehendes ZUGFeRD-PDF inkl. eingebettetem XML gegen EN 16931. Liefert ein klares Bestanden/Nicht-bestanden mit einer detaillierten Fehlerliste.
| Field | Type | Required | Description |
|---|---|---|---|
zugferdFile64 | string (base64) | required | Base64-kodiertes ZUGFeRD-PDF. |
Beispiel
json
{
"zugferdFile64": "JVBERi0xLjQK..."
}Beispielantwort
json
{
"valid": false,
"message": "File was validated",
"numberOfZugferdErrors": 10,
"zugferdErrors": [
{
"id": "BR-CO-25",
"line": null,
"location": "/rsm:CrossIndustryInvoice",
"message": "In case the Amount due for payment (BT-115) is positive, either the Payment due date (BT-9) or the Payment terms (BT-20) shall be present.",
"schemaFile": "EN16931-CII-validation",
"type": "fatal"
}
]
}Playground
Diesen Endpunkt live im Browser testen.
Rechnungsobjekt – Referenz
Das Rechnungsobjekt folgt dem europäischen Semantik-Standard EN 16931. Jedes Feld ist einem Business Term (BT-*) oder einer Business Group (BG-*) zugeordnet. Die folgenden Tabellen zeigen, welche Felder Pflicht und welche optional sind – gruppiert nach ihrer Rolle in der Rechnung.
Wie diese Tabellen zu lesen sind
- Pflichtfelder müssen vorhanden sein, damit die Rechnung gegen EN 16931 valide ist.
- Mit „Min. 1 Pflicht“ markierte Arrays müssen mindestens einen Eintrag enthalten (z. B. Rechnungspositionen, USt-Aufschlüsselung).
- Verschachtelte Felder werden mit Punktnotation dargestellt (z. B. sellerPostalAddress.sellerCity).
required
Pflichtfelder auf einen Blick
Dies sind die Mindest-Pflichtfelder für eine valide EN-16931-Rechnung. Alles Übrige in den Tabellen unten ist optional und kann weggelassen werden.
Kopfdaten (BT-1 bis BT-26)
- BT-1
invoiceNumber - BT-2
invoiceIssueDate - BT-3
invoiceTypeCode - BT-5
invoiceCurrencyCode - BT-10
buyerReference
Verkäufer (BG-4, BT-27 bis BT-43)
- BT-27
sellerName - BT-31
sellerVatIdentifier - BT-34
sellerElectronicAddress - BT-37
sellerPostalAddress.sellerCity - BT-38
sellerPostalAddress.sellerPostCode - BT-40
sellerPostalAddress.sellerCountryCode
Käufer (BG-7, BT-44 bis BT-58)
- BT-44
buyerName - BT-49
buyerElectronicAddress - BT-52
buyerPostalAddress.buyerCity - BT-53
buyerPostalAddress.buyerPostCode - BT-55
buyerPostalAddress.buyerCountryCode
Zahlungsanweisungen (BG-16, BT-81 bis BT-91)
- BT-81
paymentMeansTypeCode
Rechnungsbeträge (BG-22, BT-106 bis BT-115)
- BT-106
sumOfInvoiceLineNetAmount - BT-109
invoiceTotalAmountWithoutVat - BT-110
invoiceTotalVatAmount - BT-112
invoiceTotalAmountWithVat - BT-115
amountDueForPayment
USt-Aufschlüsselung (BG-23, BT-116 bis BT-121)· ≥ 1
- BT-116
vatCategoryTaxableAmount - BT-117
vatCategoryTaxAmount - BT-118
vatCategoryCode - BT-119
vatCategoryRate
Rechnungspositionen (BG-25, BT-126 bis BT-161)· ≥ 1
- BT-126
invoiceLineIdentifier - BT-129
invoicedQuantity - BT-130
invoicedQuantityUnitOfMeasureCode - BT-131
invoiceLineNetAmount - BT-146
priceDetails.itemNetPrice - BT-151
lineVatInformation[].invoicedItemVatCategoryCode - BT-152
lineVatInformation[].invoicedItemVatRate - BT-153
itemInformation.itemName
Kopfdaten (BT-1 bis BT-26)
Top-Level-Rechnungsdaten: Nummer, Datumsangaben, Währung und Referenzen. Diese Felder identifizieren das Dokument und seinen Geschäftskontext.
| BT | Field | Type | Pflicht | Beschreibung |
|---|---|---|---|---|
| BT-1 | invoiceNumber | string | required | Eindeutige Rechnungsnummer des Verkäufers. |
| BT-2 | invoiceIssueDate | date | required | Ausstellungsdatum der Rechnung. Format JJJJMMTT oder JJJJ-MM-TT. |
| BT-3 | invoiceTypeCode | string | required | Rechnungsart: 380 = Rechnung, 381 = Gutschrift, 384 = Korrekturrechnung. |
| BT-5 | invoiceCurrencyCode | string | required | ISO-4217-Währungscode der Rechnung (z. B. EUR). |
| BT-6 | vatAccountingCurrencyCode | string | optional | Währung für die USt-Buchhaltung, falls abweichend von der Rechnungswährung. |
| BT-7 | valueAddedTaxPointDate | date | optional | USt-Stichtag – Datum, an dem die USt fällig wird. |
| BT-8 | valueAddedTaxPointDateCode | string | optional | Code, der angibt, welches Datum den USt-Stichtag bestimmt. |
| BT-9 | paymentDueDate | date | optional | Fälligkeitsdatum der Zahlung. Pflicht, sofern ein offener Betrag und kein Zahlungsbedingungstext vorhanden ist. |
| BT-10 | buyerReference | string | required | Käuferreferenz (Leitweg-ID bei der öffentlichen Verwaltung, sonst eine mit dem Käufer vereinbarte Referenz). |
| BT-11 | projectReference | object | optional | Optionale Projektreferenz (Kennung + Name). |
| BT-12 | contractReference | string | optional | Kennung des zugrunde liegenden Vertrags. |
| BT-13 | purchaseOrderReference | string | optional | Bestellreferenz des Käufers. |
| BT-14 | salesOrderReference | string | optional | Auftragsreferenz des Verkäufers. |
| BT-17 | tenderOrLotReference | string | optional | Ausschreibungs- oder Losreferenz. |
| BT-19 | buyerAccountingReference | string | optional | Buchhaltungsreferenz des Käufers. |
| BT-20 | paymentTerms | string | optional | Zahlungsbedingungen als Freitext. Pflicht, wenn BT-9 fehlt. |
| BT-21/22 | invoiceNote | array | optional | Freitext-Hinweise zur Rechnung, jeweils mit optionalem Themencode. |
| BT-23/24 | processControl | object | optional | Geschäftsprozess- und Spezifikations-Identifikatoren. |
| BT-25/26 | precedingInvoiceReference | array | optional | Referenz auf eine vorhergehende Rechnung (für Korrekturen / Gutschriften). |
Verkäufer (BG-4, BT-27 bis BT-43)
Identifikations- und Kontaktdaten des Rechnungsstellers.
| BT | Field | Type | Pflicht | Beschreibung |
|---|---|---|---|---|
| BT-27 | sellerName | string | required | Eingetragener Firmenname des Verkäufers. |
| BT-28 | sellerTradingName | string | optional | Geschäftsname, falls vom Firmennamen abweichend. |
| BT-29 | sellerIdentifier | string[] | optional | Zusätzliche Verkäufer-Identifikatoren (z. B. GLN). |
| BT-30 | sellerLegalRegistrationIdentifier | string | optional | Handelsregisternummer. |
| BT-31 | sellerVatIdentifier | string | required | Umsatzsteuer-Identifikationsnummer des Verkäufers. |
| BT-32 | sellerTaxRegistrationIdentifier | string | optional | Steuernummer. |
| BT-33 | sellerAdditionalLegalInformation | string | optional | Weitere Rechtsangaben (Geschäftsführer, Registergericht usw.). |
| BT-34 | sellerElectronicAddress | string | required | Elektronische Adresse des Verkäufers (i. d. R. Postfach für E-Rechnungen oder E-Mail). |
| BT-35 | sellerPostalAddress.sellerAddressLine1 | string | optional | Straße und Hausnummer (Zeile 1). |
| BT-37 | sellerPostalAddress.sellerCity | string | required | Ort. |
| BT-38 | sellerPostalAddress.sellerPostCode | string | required | Postleitzahl. |
| BT-40 | sellerPostalAddress.sellerCountryCode | string | required | ISO-3166-1 alpha-2 Ländercode (z. B. DE). |
| BT-41/42/43 | sellerContact | object | optional | Ansprechpartner: Name, Telefon, E-Mail. |
Käufer (BG-7, BT-44 bis BT-58)
Identifikations- und Kontaktdaten des Rechnungsempfängers.
| BT | Field | Type | Pflicht | Beschreibung |
|---|---|---|---|---|
| BT-44 | buyerName | string | required | Eingetragener Firmenname des Käufers. |
| BT-45 | buyerTradingName | string | optional | Geschäftsname, falls vom Firmennamen abweichend. |
| BT-46 | buyerIdentifier | string | optional | Zusätzlicher Käufer-Identifikator. |
| BT-47 | buyerLegalRegistrationIdentifier | string | optional | Handelsregisternummer des Käufers. |
| BT-48 | buyerVatIdentifier | string | optional | Umsatzsteuer-Identifikationsnummer des Käufers. |
| BT-49 | buyerElectronicAddress | string | required | Elektronische Adresse des Käufers. |
| BT-50 | buyerPostalAddress.buyerAddressLine1 | string | optional | Straße und Hausnummer (Zeile 1). |
| BT-52 | buyerPostalAddress.buyerCity | string | required | Ort. |
| BT-53 | buyerPostalAddress.buyerPostCode | string | required | Postleitzahl. |
| BT-55 | buyerPostalAddress.buyerCountryCode | string | required | ISO-3166-1 alpha-2 Ländercode. |
| BT-56/57/58 | buyerContact | object | optional | Ansprechpartner: Name, Telefon, E-Mail. |
Zahlungsanweisungen (BG-16, BT-81 bis BT-91)
Wie der Käufer zahlen soll. Verwenden Sie je nach Zahlungsart-Code entweder Überweisung, Karte oder Lastschrift.
| BT | Field | Type | Pflicht | Beschreibung |
|---|---|---|---|---|
| BT-81 | paymentMeansTypeCode | string | required | UNTDID 4461 Zahlungsmittelcode (z. B. 58 = SEPA-Überweisung, 30 = Überweisung, 48 = Kreditkarte). |
| BT-82 | paymentMeansText | string | optional | Freitext-Zahlungsanweisungen. |
| BT-83 | remittanceInformation | string | optional | Verwendungszweck (vom Käufer bei Zahlung anzugeben). |
| BT-84 | creditTransfer[].paymentAccountIdentifier | string | optional | IBAN oder Kontonummer für die Zahlung. |
| BT-85 | creditTransfer[].paymentAccountName | string | optional | Kontoinhaber. |
| BT-86 | creditTransfer[].paymentServiceProviderIdentifier | string | optional | BIC der Empfängerbank. |
| BT-87/88 | paymentCardInformation | object | optional | Kartenzahlungsinformationen (PAN, Karteninhaber). |
| BT-89/90/91 | directDebit | object | optional | Lastschriftmandat-Informationen. |
Rechnungsbeträge (BG-22, BT-106 bis BT-115)
Beträge auf Dokumentenebene. Diese müssen mit der Summe der Positionen und der USt-Aufschlüsselung übereinstimmen.
| BT | Field | Type | Pflicht | Beschreibung |
|---|---|---|---|---|
| BT-106 | sumOfInvoiceLineNetAmount | decimal | required | Summe der Nettobeträge aller Rechnungspositionen. |
| BT-107 | sumOfAllowancesOnDocumentLevel | decimal | optional | Summe der Nachlässe auf Dokumentenebene. |
| BT-108 | sumOfChargesOnDocumentLevel | decimal | optional | Summe der Zuschläge auf Dokumentenebene. |
| BT-109 | invoiceTotalAmountWithoutVat | decimal | required | Rechnungs-Gesamtbetrag ohne USt (Nettosumme). |
| BT-110 | invoiceTotalVatAmount | decimal | required | Gesamter USt-Betrag. |
| BT-111 | invoiceTotalVatAmountInAccountingCurrency | decimal | optional | Gesamt-USt in der Buchhaltungswährung (BT-6), falls von BT-5 abweichend. |
| BT-112 | invoiceTotalAmountWithVat | decimal | required | Rechnungs-Gesamtbetrag inkl. USt (Bruttosumme). |
| BT-113 | paidAmount | decimal | optional | Bereits bezahlter Betrag. |
| BT-114 | roundingAmount | decimal | optional | Rundungsbetrag. |
| BT-115 | amountDueForPayment | decimal | required | Zu zahlender Betrag (BT-112 − BT-113 + BT-114). |
USt-Aufschlüsselung (BG-23, BT-116 bis BT-121)
Array · Min. 1 PflichtArray mit USt-Zwischensummen. Mindestens ein Eintrag ist Pflicht, mit einer Zeile pro Kombination aus USt-Kategorie und -Satz.
| BT | Field | Type | Pflicht | Beschreibung |
|---|---|---|---|---|
| BT-116 | vatCategoryTaxableAmount | decimal | required | Steuerbarer Betrag für diese USt-Kategorie. |
| BT-117 | vatCategoryTaxAmount | decimal | required | USt-Betrag für diese Kategorie (BT-116 × BT-119 / 100). |
| BT-118 | vatCategoryCode | string | required | USt-Kategorie: S (Standard), Z (Nullsatz), E (Befreit), AE (Umkehr der Steuerschuld), K (Innergemeinschaftlich), G (Ausfuhr), O (Außerhalb), L (Kanarische Inseln), M (Ceuta/Melilla). |
| BT-119 | vatCategoryRate | decimal | required | USt-Satz in Prozent (z. B. 19 für 19 %). |
| BT-120 | vatExemptionReasonText | string | optional | Pflicht bei Steuerbefreiung oder Nullsatz. Freitext-Begründung. |
| BT-121 | vatExemptionReasonCode | string | optional | Kodierte Befreiungsgründe (z. B. VATEX-EU-AE, VATEX-EU-IC). |
Rechnungspositionen (BG-25, BT-126 bis BT-161)
Array · Min. 1 PflichtArray der Rechnungspositionen. Jede Position beschreibt ein Produkt oder eine Leistung und muss Identifikation, Menge, Nettopreis, Positions-Nettobetrag und USt-Zuordnung enthalten.
| BT | Field | Type | Pflicht | Beschreibung |
|---|---|---|---|---|
| BT-126 | invoiceLineIdentifier | string | required | Eindeutige Positionsnummer innerhalb der Rechnung. |
| BT-127 | invoiceLineNote | string | optional | Freitext-Hinweis zur Position. |
| BT-128 | invoiceLineObjectIdentifier | string | optional | Objektkennung, auf die die Position verweist. |
| BT-129 | invoicedQuantity | decimal | required | In Rechnung gestellte Menge. |
| BT-130 | invoicedQuantityUnitOfMeasureCode | string | required | UN/ECE Empfehlung 20 Maßeinheit (z. B. H87 = Stück, HUR = Stunde, KGM = Kilogramm). |
| BT-131 | invoiceLineNetAmount | decimal | required | Positions-Nettobetrag (Menge × Nettopreis − Positionsnachlässe + Positionszuschläge). |
| BT-132 | referencedPurchaseOrderLineReference | string | optional | Referenz auf eine Bestellposition des Käufers. |
| BT-133 | invoiceLineBuyerAccountingReference | string | optional | Buchungsreferenz für diese Position. |
| BT-134/135 | invoiceLinePeriod | object | optional | Leistungszeitraum dieser Position (Start/Ende). |
| BT-136 to BT-140 | invoiceLineAllowances | array | optional | Nachlässe/Rabatte auf Positionsebene. |
| BT-141 to BT-145 | invoiceLineCharges | array | optional | Zuschläge auf Positionsebene. |
| BT-146 | priceDetails.itemNetPrice | decimal | required | Netto-Stückpreis (nach Artikel-Preisrabatt). |
| BT-147 | priceDetails.itemPriceDiscount | decimal | optional | Rabatt auf den Brutto-Stückpreis zur Ermittlung des Nettopreises. |
| BT-148 | priceDetails.itemGrossPrice | decimal | optional | Brutto-Stückpreis vor Rabatt. |
| BT-149/150 | priceDetails.itemPriceBaseQuantity | object | optional | Bezugsmenge des Stückpreises + Maßeinheit. |
| BT-151 | lineVatInformation[].invoicedItemVatCategoryCode | string | required | USt-Kategorie der Position (passt zu einem Eintrag in vatBreakdown). |
| BT-152 | lineVatInformation[].invoicedItemVatRate | decimal | required | USt-Satz der Position. |
| BT-153 | itemInformation.itemName | string | required | Artikelbezeichnung auf der Rechnung. |
| BT-154 | itemInformation.itemDescription | string | optional | Ausführliche Artikelbeschreibung. |
| BT-155 | itemInformation.itemSellersIdentifier | string | optional | Artikelnummer des Verkäufers. |
| BT-156 | itemInformation.itemBuyersIdentifier | string | optional | Artikelnummer des Käufers. |
| BT-157 | itemInformation.itemStandardIdentifier | string | optional | Standardartikelkennung (z. B. GTIN). Pflicht, wenn BT-157-1 gesetzt ist. |
| BT-157-1 | itemInformation.itemStandardIdentifierSchemeIdentifier | string | optional | ISO-6523-Schema für BT-157. Pflicht, wenn BT-157 gesetzt ist. |
| BT-158 | itemInformation.itemClassificationIdentifier | array | optional | Artikelklassifizierungen (z. B. UNSPSC, eCl@ss) mit Schema und Version. |
| BT-159 | itemInformation.itemCountryOfOrigin | string | optional | ISO-3166-1 alpha-2 Herkunftsland. |
| BT-160/161 | itemInformation.itemAttributes | array | optional | Artikelmerkmale als Name/Wert-Paare (z. B. Farbe, Größe). |
Optionale Parteien, Zeiträume und Anpassungen auf Dokumentenebene
Diese Gruppen sind komplett optional. Verwenden Sie sie nur wenn relevant – ansonsten weglassen. Die internen Felder folgen denselben EN-16931-Mapping-Konventionen.
| BT | Field | Type | Pflicht | Beschreibung |
|---|---|---|---|---|
| BG-10 / BT-59 to BT-61 | payee | object | optional | Zahlungsempfänger, falls vom Verkäufer abweichend. |
| BG-11 / BT-62 to BT-69 | sellerTaxRepresentativeParty | object | optional | Steuervertreter des Verkäufers (üblicherweise für Verkäufer außerhalb der EU). |
| BG-13 / BT-70 to BT-80 | deliveryInformation | object | optional | Lieferpartei, Ort und tatsächliches Lieferdatum. |
| BG-14 / BT-73, BT-74 | invoicingPeriod | object | optional | Leistungszeitraum auf Rechnungsebene. |
| BG-20 / BT-92 to BT-98 | documentLevelAllowances | array | optional | Nachlässe/Rabatte auf Dokumentenebene. |
| BG-21 / BT-99 to BT-105 | documentLevelCharges | array | optional | Zuschläge auf Dokumentenebene. |
| BG-24 / BT-122 to BT-125 | additionalSupportingDocuments | array | optional | Zusätzliche Belege (Stundennachweis, Lieferschein usw.). Entweder externe URL oder Base64-Anhang. |
Fehler
RechnungsAPI verwendet konventionelle HTTP-Status-Codes für Transport-Fehler. Fachliche Validierungsergebnisse (EN-16931- / XRechnung-Regelverstöße) werden mit HTTP 200 in einer strukturierten Fehlerliste zurückgegeben – siehe Schema unten.
| Code | Bezeichnung | Beschreibung |
|---|---|---|
| 200 | OK | Anfrage verarbeitet. Bei Validierungs- und Erzeugungs-Endpunkten zusätzlich das Feld `valid` prüfen – HTTP 200 bedeutet nicht, dass die Rechnung valide ist. |
| 400 | Ungültige Anfrage | Ungültiges JSON oder ungültige Rechnungsdaten. Der Response-Body listet die betroffenen Felder. |
| 401 | Nicht autorisiert | Fehlender oder ungültiger Authorization-Header / Bearer-Token. |
| 402 | Zahlung erforderlich | Kein aktives Abo oder API-Kontingent aufgebraucht. Bitte Support kontaktieren oder Plan upgraden. |
| 412 | Vorbedingung fehlgeschlagen | Erforderliche Eingabe (PDF, XML oder Rechnungsdaten) fehlt im Request-Body. |
| 500 | Serverfehler | Unerwarteter serverseitiger Fehler. Mit exponentiellem Backoff erneut versuchen; bei dauerhaftem Fehler Support mit Request-ID kontaktieren. |
Schema eines Validierungsfehlers
Jeder Eintrag in `xInvoiceErrors` / `zugferdErrors` folgt diesem Schema. Nutzen Sie `id` und `location`, um zur fehlerhaften Stelle zu springen.
json
{
"id": "BR-CO-25",
"line": null,
"location": "/rsm:CrossIndustryInvoice",
"message": "In case the Amount due for payment (BT-115) is positive, either the Payment due date (BT-9) or the Payment terms (BT-20) shall be present.",
"schemaFile": "EN16931-CII-validation",
"type": "fatal"
}