> For the complete documentation index, see [llms.txt](https://docs.younium.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.younium.com/e-invoicing-integrations/peppol.md). # Peppol ## Overview The Peppol integration is Younium’s UBL 2.1 document builder for European e-invoicing. It transforms posted invoices and credit notes into Peppol BIS Billing 3.0 XML (`urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0`). The same XML is consumed by AutoInvoice (Maventa), APIX, and KSeF workflows; Peppol itself does not send documents to a network operator. ## Authentication Peppol generation runs inside Younium and does not use external credentials. Transmission over the network is handled by AutoInvoice, APIX, or another connector, each of which requests the Peppol document from Younium and sends it on. ## Eligibility and pre-validation Before XML is built, `PeppolValidation.PreValidate` runs. Failure throws an API error listing all validation messages. Required on the invoice: invoice address country name, payment term reference, your reference, invoice lines with tax items. Required on the account: organisation number, name; electronic invoice address and scheme must both be set or both omitted (if only one is set, address is treated as empty). Required on the legal entity: address country, organisation number, tax registration number, bank account, BIC. Attachments, when supplied, must use MIME types PDF, PNG, JPG, CSV, XLSX, or ODS. Multi-order invoices (no single `Order` on the invoice, not on-account) copy `YourOrderNumber`, `YourReference`, `OurReference`, and `ReferenceNumber` from underlying orders only when all orders agree on each field; otherwise fields stay as on the invoice. ## Default reference values When AutoInvoice settings exist and invoice fields are empty, defaults are applied from AutoInvoice settings before validation: | Younium Field | Source when empty | | ------------------------- | ------------------------------------------- | | `Invoice.YourReference` | `AutoInvoiceSettings.DefaultYourReference` | | `Invoice.OurReference` | `AutoInvoiceSettings.DefaultOurReference` | | `Invoice.ReferenceNumber` | `AutoInvoiceSettings.DefaultBuyerReference` | ## Document type selection | Condition | UBL document type | | --------------------------------- | ---------------------------------- | | `Invoice.TotalAmount.Amount >= 0` | `InvoiceType` (type code `380`) | | `Invoice.TotalAmount.Amount < 0` | `CreditNoteType` (type code `381`) | Credit notes for Dutch (`NL`) buyers include `BillingReference` to the debited invoice number when a credited line links to an original line; otherwise `N/A` is used for manual credits. ## Invoice and credit note header mapping | Younium Field | UBL (Peppol) element | | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | Fixed profile string | `CustomizationID` → `urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0` | | Fixed profile string | `ProfileID` → `urn:fdc:peppol.eu:2017:poacc:billing:01:1.0` | | `Invoice.InvoiceNumber` | `ID` (fallback `"no id"`) | | `Invoice.InvoiceDate` | `IssueDate`, `TaxPointDate` | | `Invoice.Notes` | `Note` | | `Invoice.Currency.Code` or `Invoice.TotalAmount.CurrencyCode` | `DocumentCurrencyCode` | | `Invoice.ReferenceNumber` | `BuyerReference` | | `Invoice.YourOrderNumber` | `OrderReference/ID` | | Service period min/max across lines | `InvoicePeriod` | | `Invoice.DueDate` | `DueDate` (invoices only) | | `InvoiceType` commercial / credit codes | `InvoiceTypeCode` / `CreditNoteTypeCode` | ## Party mapping — supplier (legal entity) | Younium Field | UBL party element | | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | `ApplicationLegalEntity` address and identifiers | `AccountingSupplierParty/Party` | | Country-based scheme from `GetSchemeIDByCountryCode`, translated via `ToEndpointScheme` | `EndpointID/@schemeID` | | `ApplicationLegalEntity.OrganizationNumber` (with country rules) | `EndpointID` value | | Legal entity name, address, tax ID | `PartyName`, `PostalAddress`, `PartyTaxScheme`, `PartyLegalEntity` | Supplier scheme IDs by legal entity country include: `0007` (SE), `0192` (NO), `0184` (DK/FO/GL), `0212` (FI/AX — see Finland below), `0106` (NL), `0208` (BE), `0183` (CH), `0191` (EE), `0196` (IS), `0218` (LV), `0199` (DE, AT, LU, default). ### Finland and Åland (FI/AX) Finnish and Åland parties are identified by ICD `0212` (Finnish Organisation Identifier — the bare Y-tunnus), but the network address they are reached at uses a different scheme: EAS `0216`, with a value in OVT format (`"0037"` followed by the 8-digit Y-tunnus, no dash — for example `003723821658`). Younium derives the `0216` endpoint automatically from the `0212` identifier wherever a Finnish or Åland party is built, for both the supplier and the customer; a customer account still carrying the withdrawn `0037` scheme is translated the same way rather than rejected. A Finnish organisation number is normalised first — hyphen and any `FI` VAT prefix removed — before it is used in either the endpoint or the identification fields; the VAT identifier itself keeps its `FI` prefix. A customer already reachable on a different scheme (for example GLN `0088`) is left untouched, since the translation is triggered by the resolved scheme, not by the country alone. ## Party mapping — customer (account) Resolution: if `Account.ElectronicInvoiceAddress` is set, use it with `Account.ElectronicInvoiceAddressScheme` (default scheme `0088` GLN when scheme missing); otherwise use `Account.OrganizationNumber` with ICD `0007`. Swedish organisation numbers are hyphen-stripped. Danish accounts use `EnsureDanishOrganizationNumber` logic on org/tax numbers. | Younium Field | UBL party element | | ------------------------------------ | ---------------------------------------------------------------- | | Resolved electronic address + scheme | `AccountingCustomerParty/Party/EndpointID` | | `Account.Name` | `PartyName` | | Invoice or default invoice address | `PostalAddress` | | `Account.TaxRegistrationNumber` | `PartyTaxScheme/CompanyID` (Polish NIP: special prefix handling) | | `Account.OrganizationNumber` | `PartyIdentification`, `PartyLegalEntity/CompanyID` | When legal entity has KSeF fully enabled (`EnableKSeF` and active KSeF settings), Polish customer party rules apply (EAS `9945`, stripped NIP on identification). ## Payment means | Younium Field | UBL element | | ------------------------------------------------------- | --------------------------------------------------------------------- | | Default: `LegalEntity.BankAccount`, `LegalEntity.BIC` | `PaymentMeans` code `30` (credit transfer) | | SEK + `LegalEntity.Bankgiro` | Account = bankgiro (no hyphens), branch `SE:BANKGIRO` | | `Invoice.BankAccount` when default for invoice currency | Giro, account number, or IBAN (first non-empty); BIC or `SE:BANKGIRO` | | `Invoice.OCRNumber` or `Invoice.InvoiceNumber` | `PaymentID` (Norway: OCR only, may be empty) | | Danish FIK | `PaymentMeans` code `93`, FIK in `PaymentID` | | Denmark supplier + credit | Code `42`, absolute amounts on lines and totals | ## Monetary totals and tax | Younium Field | UBL element | | ----------------------------------------------------------------------------------- | -------------------------------------------------------------- | | `Invoice.Subtotal` | `LegalMonetaryTotal/LineExtensionAmount`, `TaxExclusiveAmount` | | Sum of tax subtotals (BR-CO-14) | `TaxTotal/TaxAmount`, `TaxInclusiveAmount` | | `Invoice.TotalAmount`, rounded to 2 decimals, minus `TaxInclusiveAmount` (BR-CO-16) | `PayableRoundingAmount` | | `Invoice.TotalAmount`, rounded to 2 decimals | `PayableAmount` | | Tax items grouped by normalised rate | `TaxSubtotal` (BT-116/BT-117 rules) | | Zero-rate lines | Category `Z`; standard rate `S` | Younium calculates VAT per invoice line, while the Peppol file reports VAT per tax rate category (the `TaxSubtotal` breakdown above). On an invoice with several lines, or with a rate such as 25.5%, the two figures can differ from each other by a cent or two, because line-level rounding does not average out the same way category-level rounding does. The payable rounding amount absorbs that difference, so the payable amount on the Peppol file always matches the total the customer sees on the Younium invoice and PDF, even though the VAT total in the tax breakdown reflects the category-level figure. Any invoice-level rounding Younium applies is already included in `Invoice.TotalAmount`, so the same field covers both without double-counting. Credit notes for NO and DK use absolute line and header amounts (`forceAbsoluteAmount`); the payable rounding amount and payable amount follow the same sign as the rest of the totals block. Sweden keeps negative amounts on credit lines with positive quantity in several mixed debit/credit cases. ## Invoice line mapping | Younium Field | UBL line element | | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | Line index `i` (0-based Peppol; 1-based when `isKSeF`) | `ID` | | Quantity and unit price from `GetUnitPriceAndQuantityThatAddsUpToRoundedSubtotal` | `InvoicedQuantity` / `CreditedQuantity` (`unitCode` `XPP`) | | `InvoiceLine.Subtotal` | `LineExtensionAmount` | | `ProductName` + `ChargeDescription`, or charge description only if `InvoiceSettings.MapOnlyChargeNameToElectronicInvoice` | `Item/Name` | | `InvoiceLine.TaxItems` | `Item/ClassifiedTaxCategory` | | `InvoiceLine.Notes` | `Note` | | Unit price currency | `Price/PriceAmount` | | `ServicePeriodStartDate`, `ServicePeriodEndDate` | `InvoicePeriod` on line | ## Attachments | Younium Field | UBL element | | ------------------------------------------------------- | -------------------------------------------------- | | `EmailAttachment.FileName`, `FileData`, `MediaTypeName` | `AdditionalDocumentReference` with embedded binary | ## KSeF interaction When the legal entity has KSeF enabled and KSeF integration is active, Peppol XML is built with `isKSeF = true` (1-based line IDs and Polish party rules). Submission to Poland’s KSeF is documented under the KSeF and AutoInvoice articles. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.younium.com/e-invoicing-integrations/peppol.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.