Billbee Multi-Channel ERP to ZUGFeRD 2.3 (EN 16931 / Extended) Integration & Schema Crosswalk
Why Native Billbee Multi-Channel ERP Exports Fail ZUGFeRD 2.3 (EN 16931 / Extended) Validation
1. Billbee's `/api/v1/orders` exposes `InvoiceNumber` and `InvoiceDate` as free-form strings with no enforced ISO-8601 date serialization, so `ram:IssueDateTime` is emitted without the mandatory `format="102"` (CCYYMMDD) attribute, triggering BR-03/BR-CO-03 date-format failures in CII-D16B.
2. `Buyer.VatId` is returned as a raw string with no scheme identifier; ZUGFeRD 2.3 requires the VAT ID under `ram:SpecifiedTaxRegistration/ram:ID` with `schemeID="VA"` (BT-48) and a separate `ram:PartyIdentification` for the Leitweg-ID (BT-10), which Billbee never populates, causing BR-DE-15 / PEPPOL-EN16931-R020 violations.
3. `OrderItems[].TotalPrice` and `TaxRate1` are returned as floating-point decimals with variable scale (e.g. `19.9`, `7`), so line-level `ram:LineTotalAmount` and `ram:ApplicableTradeTax/ram:Rate` fail BR-CO-10/BR-CO-15 rounding reconciliation against `ram:TaxTotalAmount` unless explicitly normalized to 2-decimal HALF_UP and 2-decimal rate scale respectively.
Mandatory Billbee Multi-Channel ERP to ZUGFeRD 2.3 (EN 16931 / Extended) Field Crosswalk Matrix
Deterministic attribute mapping from Billbee Multi-Channel ERP payloads to EN 16931 Business Terms (BT) and CII-D16B XPaths.
| Billbee Multi-Channel ERP Source Field | EN 16931 Business Term | Target CII-D16B XPath | Card. | Transformation & Normalization Rule | Schematron Rule |
|---|---|---|---|---|---|
| InvoiceNumber string, e.g. "RE-2024-00417" | BT-1 | /rsm:CrossIndustryInvoice/rsm:ExchangedDocument/ram:ID | 1..1 | Trim whitespace; reject empty/null; if length > 35 truncate to 35 chars per CII maxLength; do NOT prefix or alter the merchant-assigned invoice number. | BR-02 ↗ |
| InvoiceDate string (ISO-8601 or locale), e.g. "2024-03-14T00:00:00" | BT-2 | /rsm:CrossIndustryInvoice/rsm:ExchangedDocument/ram:IssueDateTime/udt:DateTimeString | 1..1 | Parse to date; serialize as CCYYMMDD and set attribute format="102" on udt:DateTimeString; if only a datetime is supplied, strip time component and use the calendar date in the seller's timezone. | BR-01 ↗ |
| Buyer.VatId string, e.g. "DE123456789" | BT-48 | /rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeAgreement/ram:BuyerTradeParty/ram:SpecifiedTaxRegistration/ram:ID | 0..1 | Strip spaces and hyphens; uppercase; validate against country prefix regex ^[A-Z]{2}[0-9A-Z]{2,12}$; emit with schemeID="VA"; if empty, omit the element entirely (do not emit empty ID). | BR-DE-15 ↗ |
| OrderItems[].TotalPrice decimal (float), e.g. 19.9 | BT-131 | /rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/ram:IncludedSupplyChainTradeLineItem/ram:SpecifiedLineTradeSettlement/ram:SpecifiedTradeSettlementLineMonetarySummation/ram:LineTotalAmount | 1..1 | Convert to decimal via string cast (avoid binary float); round HALF_UP to exactly 2 decimal places; multiply by quantity only if TotalPrice is unit price (Billbee returns line total, so pass through); ensure sum of LineTotalAmount equals BT-106 within 0.01 tolerance. | BR-CO-10 ↗ |
Test Your Billbee Multi-Channel ERP ZUGFeRD 2.3 (EN 16931 / Extended) XML Export Live
Validate your generated CII-D16B payload against EN 16931 & ZUGFeRD 2.3 (EN 16931 / Extended) rules directly in your browser.
Missing <cbc:CustomizationID> or value does not declare EN 16931 CIUS compliance.
Remediation: Insert <cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0</cbc:CustomizationID>.
Found invalid or lowercase currency code "eur". Expected uppercase ISO 4217 (e.g. "EUR").
Remediation: Replace <cbc:DocumentCurrencyCode>eur</cbc:DocumentCurrencyCode> with uppercase "EUR".
Peppol Schematron forbids empty elements such as <cbc:AdditionalStreetName></cbc:AdditionalStreetName> serialized from null ERP fields.
Remediation: Strip empty <cbc:AdditionalStreetName> nodes prior to XML serialization.
Missing <cbc:EndpointID schemeID="..."> inside <cac:AccountingSupplierParty>/<cac:Party>.
Remediation: Add <cbc:EndpointID schemeID="9930">DE123456789</cbc:EndpointID> as the first child of Seller <cac:Party>.
Buyer <cbc:EndpointID> is either missing or lacks the mandatory EAS @schemeID attribute.
Remediation: Add schemeID="9930" (or "0088" for GLN / "0204" for Leitweg-ID) to Buyer <cbc:EndpointID>.
No <cbc:BuyerReference> (BT-10) found. Mandatory in XRechnung 3.0 (BR-DE-15) and required in Peppol BIS 3.0 (PEPPOL-EN16931-R003) when OrderReference is absent.
Remediation: Insert <cbc:BuyerReference>991-12849-74</cbc:BuyerReference> in the document header.
Mathematical discrepancy of 0.05 EUR between InvoiceLine sum (199.95) and LegalMonetaryTotal/LineExtensionAmount (200.00).
Remediation: Set cbc:LineExtensionAmount and cbc:TaxExclusiveAmount to 199.95.
TaxSubtotal/TaxableAmount reports 200.00, but Standard rated ("S") lines total 199.95.
Remediation: Recalculate BT-116 = 199.95, VAT BT-117 = 37.99, and PayableAmount BT-115 = 237.94.
Other ERP to E-Invoicing Compliance Bridges
Unlock Pro Batch XML / PDF Converter ($29/mo) →4 mandatory EN 16931 Business Term mappings
4 mandatory EN 16931 Business Term mappings
4 mandatory EN 16931 Business Term mappings
4 mandatory EN 16931 Business Term mappings