Read ZUGFeRD XML

The Read ZUGFeRD XML endpoint allows users to extract structured invoice data from a ZUGFeRD-compliant XML document. This endpoint processes the provided XML file and returns key invoice details, such as invoice number, buyer and seller information, payment references, and itemized trade line data. It helps automate invoice handling and integration into financial or ERP systems.

Note:   This feature is available in DRUID 8.9 and higher. To use this Druid Vision service, you must have at least one Identity Vision API service enabled for your tenant. If not, please contact Druid Tech Support.

Request

Method POST
API Resource URL (Endpoint) *.druidplatform.com/api/document-processing/read-zugferd-xml
Params

Enter the ZUGFeRD standard version.
Authorization

Select Bearer Token. If you already have a Druid Vision Token generated for an Identity API service in the DRUID Portal, provide that token. For details on obtaining the token, refer to Druid Vision.

If you don't have a token, generate one using the Authentication endpoint from Webhooks. For more information, see Webhooks.
Body

The request body is an XML file following the ZUGFeRD standard.

Copy
XML file example body content
<?xml version="1.0" encoding="utf-8"?>
<rsm:CrossIndustryDocument xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:rsm="urn:ferd:CrossIndustryDocument:invoice:1p0" xmlns:ram="urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:12" xmlns:udt="urn:un:unece:uncefact:data:standard:UnqualifiedDataType:15">
    <rsm:SpecifiedExchangedDocumentContext>
        <ram:TestIndicator>
            <udt:Indicator>false</udt:Indicator>
        </ram:TestIndicator>
        <ram:GuidelineSpecifiedDocumentContextParameter>
            <ram:ID>urn:ferd:CrossIndustryDocument:invoice:1p0:basic</ram:ID>
        </ram:GuidelineSpecifiedDocumentContextParameter>
    </rsm:SpecifiedExchangedDocumentContext>
    <rsm:HeaderExchangedDocument>
        <ram:ID>string</ram:ID>
        <ram:Name>string</ram:Name>
        <ram:TypeCode>380</ram:TypeCode>
        <ram:IssueDateTime>
            <udt:DateTimeString format="102">20241204</udt:DateTimeString>
        </ram:IssueDateTime>
        <ram:IncludedNote>
            <ram:ContentCode>EEV</ram:ContentCode>
            <ram:Content>string</ram:Content>
        </ram:IncludedNote>
    </rsm:HeaderExchangedDocument>
    <rsm:SpecifiedSupplyChainTradeTransaction>
        <ram:ApplicableSupplyChainTradeAgreement>
            <ram:BuyerReference>string</ram:BuyerReference>
            <ram:SellerTradeParty>
                <ram:ID>string</ram:ID>
                <ram:Name>string</ram:Name>
                <ram:PostalTradeAddress>
                    <ram:PostcodeCode>string</ram:PostcodeCode>
                    <ram:LineOne>string</ram:LineOne>
                    <ram:CityName>string</ram:CityName>
                </ram:PostalTradeAddress>
                <ram:SpecifiedTaxRegistration>
                    <ram:ID schemeID="FC">string</ram:ID>
                </ram:SpecifiedTaxRegistration>
            </ram:SellerTradeParty>
            <ram:BuyerTradeParty>
                <ram:ID>string</ram:ID>
                <ram:Name>string</ram:Name>
                <ram:DefinedTradeContact>
                    <ram:PersonName>string</ram:PersonName>
                    <ram:DepartmentName>string</ram:DepartmentName>
                    <ram:TelephoneUniversalCommunication>
                        <ram:CompleteNumber>string</ram:CompleteNumber>
                    </ram:TelephoneUniversalCommunication>
                    <ram:FaxUniversalCommunication>
                        <ram:CompleteNumber>string</ram:CompleteNumber>
                    </ram:FaxUniversalCommunication>
                    <ram:EmailURIUniversalCommunication>
                        <ram:URIID>string</ram:URIID>
                    </ram:EmailURIUniversalCommunication>
                </ram:DefinedTradeContact>
                <ram:PostalTradeAddress>
                    <ram:PostcodeCode>string</ram:PostcodeCode>
                    <ram:LineOne>string</ram:LineOne>
                    <ram:LineTwo>string</ram:LineTwo>
                    <ram:CityName>string</ram:CityName>
                </ram:PostalTradeAddress>
                <ram:SpecifiedTaxRegistration>
                    <ram:ID schemeID="FC">string</ram:ID>
                </ram:SpecifiedTaxRegistration>
            </ram:BuyerTradeParty>
            <ram:BuyerOrderReferencedDocument>
                <ram:IssueDateTime>2024-12-04T11:57:50</ram:IssueDateTime>
                <ram:ID>string</ram:ID>
            </ram:BuyerOrderReferencedDocument>
        </ram:ApplicableSupplyChainTradeAgreement>
        <ram:ApplicableSupplyChainTradeDelivery>
            <ram:ActualDeliverySupplyChainEvent>
                <ram:OccurrenceDateTime>
                    <udt:DateTimeString format="102">20241204</udt:DateTimeString>
                </ram:OccurrenceDateTime>
            </ram:ActualDeliverySupplyChainEvent>
            <ram:DeliveryNoteReferencedDocument>
                <ram:IssueDateTime>2024-12-04T11:57:50</ram:IssueDateTime>
                <ram:ID>string</ram:ID>
            </ram:DeliveryNoteReferencedDocument>
        </ram:ApplicableSupplyChainTradeDelivery>
        <ram:ApplicableSupplyChainTradeSettlement>
            <ram:InvoiceCurrencyCode>Unknown</ram:InvoiceCurrencyCode>
            <ram:PaymentReference>string</ram:PaymentReference>
            <ram:ApplicableTradeTax>
                <ram:CalculatedAmount currencyID="Unknown">0.00</ram:CalculatedAmount>
                <ram:TypeCode>Unknown</ram:TypeCode>
                <ram:BasisAmount currencyID="Unknown">0.00</ram:BasisAmount>
                <ram:CategoryCode>S</ram:CategoryCode>
                <ram:ApplicablePercent>0.00</ram:ApplicablePercent>
            </ram:ApplicableTradeTax>
            <ram:SpecifiedLogisticsServiceCharge>
                <ram:AppliedTradeTax />
            </ram:SpecifiedLogisticsServiceCharge>
            <ram:SpecifiedTradePaymentTerms>
                <ram:Description>string</ram:Description>
                <ram:DueDateDateTime>
                    <udt:DateTimeString format="102">20241204</udt:DateTimeString>
                </ram:DueDateDateTime>
            </ram:SpecifiedTradePaymentTerms>
            <ram:SpecifiedTradeSettlementMonetarySummation>
                <ram:LineTotalAmount currencyID="Unknown">0.00</ram:LineTotalAmount>
                <ram:ChargeTotalAmount currencyID="Unknown">0.00</ram:ChargeTotalAmount>
                <ram:AllowanceTotalAmount currencyID="Unknown">0.00</ram:AllowanceTotalAmount>
                <ram:TaxBasisTotalAmount currencyID="Unknown">0.00</ram:TaxBasisTotalAmount>
                <ram:TaxTotalAmount currencyID="Unknown">0.00</ram:TaxTotalAmount>
                <ram:GrandTotalAmount currencyID="Unknown">0.00</ram:GrandTotalAmount>
                <ram:TotalPrepaidAmount currencyID="Unknown">0.00</ram:TotalPrepaidAmount>
                <ram:DuePayableAmount currencyID="Unknown">0.00</ram:DuePayableAmount>
            </ram:SpecifiedTradeSettlementMonetarySummation>
        </ram:ApplicableSupplyChainTradeSettlement>
        <ram:IncludedSupplyChainTradeLineItem>
            <ram:AssociatedDocumentLineDocument>
                <ram:LineID>1</ram:LineID>
                <ram:IncludedNote>
                    <ram:Content>string</ram:Content>
                </ram:IncludedNote>
            </ram:AssociatedDocumentLineDocument>
            <ram:SpecifiedSupplyChainTradeDelivery>
                <ram:BilledQuantity unitCode="Unknown">0.0000</ram:BilledQuantity>
            </ram:SpecifiedSupplyChainTradeDelivery>
            <ram:SpecifiedSupplyChainTradeSettlement>
                <ram:BillingSpecifiedPeriod>
                    <ram:StartDateTime>
                        <udt:DateTimeString format="102">20241204</udt:DateTimeString>
                    </ram:StartDateTime>
                    <ram:EndDateTime>
                        <udt:DateTimeString format="102">20241204</udt:DateTimeString>
                    </ram:EndDateTime>
                </ram:BillingSpecifiedPeriod>
                <ram:SpecifiedTradeSettlementMonetarySummation>
                    <ram:LineTotalAmount currencyID="Unknown">0.00</ram:LineTotalAmount>
                </ram:SpecifiedTradeSettlementMonetarySummation>
            </ram:SpecifiedSupplyChainTradeSettlement>
            <ram:SpecifiedTradeProduct>
                <ram:SellerAssignedID>string</ram:SellerAssignedID>
                <ram:BuyerAssignedID>string</ram:BuyerAssignedID>
                <ram:Name>string</ram:Name>
                <ram:Description>string</ram:Description>
            </ram:SpecifiedTradeProduct>
        </ram:IncludedSupplyChainTradeLineItem>
    </rsm:SpecifiedSupplyChainTradeTransaction>
</rsm:CrossIndustryDocument>

Response

The response returns the extracted invoice details in JSON format.

Copy

Example response

{
  "InvoiceNo": "INV-123456",
  "InvoiceDate": "2024-12-04T00:00:00",
  "PaymentReference": "PAY-789",
  "OrderNo": "ORD-56789",
  "OrderDate": "2024-12-04T11:57:50",
  "Buyer": {
    "ID": {
      "ID": "BUYER-001",
      "SchemeID": 1
    },
    "Name": "Buyer Company",
    "City": "Berlin",
    "Postcode": "10115",
    "Street": "Main Street 10"
  },
  "Seller": {
    "ID": {
      "ID": "SELLER-001",
      "SchemeID": 1
    },
    "Name": "Seller Company",
    "City": "Munich",
    "Postcode": "80331",
    "Street": "Business Road 5"
  },
  "TradeLineItems": [
    {
      "SellerAssignedID": "ITEM-001",
      "BuyerAssignedID": "PROD-567",
      "Name": "Product A",
      "Description": "Electronic component",
      "BilledQuantity": 10,
      "LineTotalAmount": 100.00,
      "UnitCode": "PCE"
    }
  ],
  "GrandTotalAmount": 100.00,
  "DuePayableAmount": 100.00
}

If the request contains invalid data, an error message is returned in JSON format.