When utilizing Oioubl format, to send invoices or credit notes to Peppol recipients, the recipient may use a Peppol-specific identifier scheme not natively supported by Oioubl. To ensure proper routing and identification, Sproom supports including a UBLExtension element in your document to specify the Peppol identifier. The UBLExtension will be used for overriding the identifiers in the document body, when Sproom is sending the document to the Peppol recipient.
Include a UBLExtension when the recipient’s Peppol identifier scheme isn't supported in Oioubl.
The UBLExtension supports overriding two identifiers for AccountingCustomerParty:
Endpoint ID: The electronic address scheme and number for document routing
LegalEntity CompanyID: The business registration identifier (if the desired identifier scheme is not supported natively in OIOUBL)
How to add the UBLExtension to your Oioubl document
Insert the UBLExtension at the beginning of your Invoice or CreditNote XML, before other elements:
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2"
xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2">
<ext:UBLExtensions>
<ext:UBLExtension>
<cbc:ID>SproomPartyIdentifierSchemes</cbc:ID>
<cbc:Name>Party Identifier Schemes</cbc:Name>
<ext:ExtensionAgencyID>Sproom</ext:ExtensionAgencyID>
<ext:ExtensionContent>
<sproom:PartyIdentifiers xmlns:sproom="urn:sproom:extensions:partySchemes:1.0">
<!-- Add overrides for identifiers here -->
<IdentifierOverride>
<TargetElementPath>/element/to/override </TargetElementPath>
<Identifier schemeId="scheme">value</identifier>
</IdentifierOverride>
</sproom:PartyIdentifiers>
</ext:ExtensionContent>
</ext:UBLExtension>
</ext:UBLExtensions>
<!-- Rest of your Oioubl document -->
<cbc:UBLVersionID>2.0</cbc:UBLVersionID>
...
</Invoice>
Note: The organization identifiers from your UblExtension will override the existing values of the Oioubl document.
Note 2: The Oioubl document must pass schematron validation, thus you must add an Oioubl valid scheme for the Endpoint.
Structure of the UBLExtension
The UblExtension must follow the official Oioubl guideline (see here).
The element must contain the required fields:
ID - with value set to SproomPartyIdentifierSchemes
Name- with value set to Party Identifier Schemes
ExtensionAgencyID - with value set to Sproom
IdentifierOverride Class
Field | Type | Required | Description |
TargetElementPath | string | Yes | The X-path to the element being overridden - namespaces are not used:: AccountingCustomerParty/Party/{ElementName} where ElementName is EndpointID or PartyLegalEntity/CompanyID. Example: AccountingCustomerParty/Party/EndpointID |
Identifier | Identifier | Yes | Container object holding the original identifier details including the scheme ID and value. See Identifier class below. |
Identifier Class
Same class as used in OIOUBL: https://oioubl21.oioubl.dk/datatypes/en/Identifier.html only the schemeId and the Value is actually read by Sproom, and the schemeId allows any value, not just the ones from the OIOUBL codelists.
Field | Type | Required | Description |
@schemeId | string | Yes | The original Peppol BIS3 scheme identifier (e.g., 0245, 0177,NL:KVK, or any valid Peppol scheme). Used to override the identifier with the desired scheme when converting from Oioubl to Peppol BIS3. Note: The schemeId can be either the Peppol ISO code or the Oioubl alphanumeric value. |
Value | string | Yes | The actual identifier value/number (e.g., 1234567890). Represents the company registration number, endpoint ID, or other identifier value that corresponds to the scheme. |
Example 1: Using a Peppol Endpoint Identifier not supported in OIOUBL
Your Peppol recipient uses an endpoint scheme (e.g. ID: 0245 - Tax identification number DIČ Slovakia) that is not recognized in Oioubl. Include the original scheme and number in the extension and set the endpoint scheme to an Oioubl valid scheme (like 9950 - Slovakia VAT number) and number. Since the EndpointID is overridden by the extension, you can choose to put any valid EndpointID here, but we encourage that you either put something relevant and valid (like the recipients actual VAT number) or an identifier of your own (maybe your own CVR or GLN), just to be absolutely sure that no system anywhere would at some point route this document to someone unrelated.
The original Oioubl document shall pass schematron validation and Sproom will use the value from the UBL Extensions to properly route the document:
<ext:UBLExtensions>
<ext:UBLExtension>
<cbc:ID>SproomPartyIdentifierSchemes</cbc:ID>
<cbc:Name>Party Identifier Schemes</cbc:Name>
<ext:ExtensionAgencyID>Sproom</ext:ExtensionAgencyID>
<ext:ExtensionContent>
<PartyIdentifiers xmlns="urn:sproom:extensions:partySchemes:1.0">
<IdentifierOverride>
<TargetElementPath>AccountingCustomerParty/Party/EndpointID</TargetElementPath>
<Identifier schemeId="0245">1023456789</Identifier>
</IdentifierOverride>
</PartyIdentifiers>
</ext:ExtensionContent>
</ext:UBLExtension>
</ext:UBLExtensions>
In your main document body, the EndpointID could appear as (the actual value here will not be used by Sproom, but as mentioned, we do not encourage using something at random) :
<cac:AccountingCustomerParty>
<cac:Party>
<cbc:EndpointID schemeID="9950">SK1023456789</cbc:EndpointID>
...
</cac:Party>
</cac:AccountingCustomerParty>
Example 2: Overriding a Company ID Scheme
Your Peppol recipient uses a PartyLegalEntity/CompanyID scheme (ID: 0106) that is not valid value for a CompanyId in Oioubl. Include the original scheme in the extension:
<ext:UBLExtensions>
<ext:UBLExtension>
<cbc:ID>SproomPartyIdentifierSchemes</cbc:ID>
<cbc:Name>Party Identifier Schemes</cbc:Name>
<ext:ExtensionAgencyID>Sproom</ext:ExtensionAgencyID>
<ext:ExtensionContent>
<PartyIdentifiers xmlns="urn:sproom:extensions:partySchemes:1.0">
<IdentifierOverride>
<TargetElementPath>AccountingCustomerParty/Party/PartyLegalEntity/CompanyID</TargetElementPath>
<Identifier schemeId="0106">123456789</Identifier>
</IdentifierOverride>
</PartyIdentifiers>
</ext:ExtensionContent>
</ext:UBLExtension>
</ext:UBLExtensions>
In your main document body, the CompanyID could appear as:
<cac:PartyLegalEntity>
<cbc:CompanyID schemeID="ZZZ">123456789</cbc:CompanyID>
</cac:PartyLegalEntity>
Note that even though the actual value of the CompanyID doesn’t matter in Sproom, as the extension will override it, we encourage you to use the “ZZZ” schemeId and the real value, to have the document body reflect the intent as well as possible.
Example 3: Overriding Multiple Identifiers
If both EndpointID and PartyLegalEntity/CompanyID have Peppol-specific schemes, include both in the extension:
<ext:UBLExtensions>
<ext:UBLExtension>
<cbc:ID>SproomPartyIdentifierSchemes</cbc:ID>
<cbc:Name>Party Identifier Schemes</cbc:Name>
<ext:ExtensionAgencyID>Sproom</ext:ExtensionAgencyID>
<ext:ExtensionContent>
<PartyIdentifiers xmlns="urn:sproom:extensions:partySchemes:1.0">
<IdentifierOverride> <TargetElementPath>AccountingCustomerParty/Party/EndpointID</TargetElementPath>
<Identifier schemeId="0245">1023456789</Identifier>
</IdentifierOverride>
<IdentifierOverride> <TargetElementPath>AccountingCustomerParty/Party/PartyLegalEntity/CompanyID</TargetElementPath>
<Identifier schemeId="0088">1234567891234</Identifier>
</IdentifierOverride>
</PartyIdentifiers>
</ext:ExtensionContent>
</ext:UBLExtension>
</ext:UBLExtensions>
Important Notes
Place UBLExtension at the start of the Invoice or CreditNote XML as specified by the OIOUBL schema (https://oioubl21.oioubl.dk/Classes/en/Invoice.html)
Set the overridden Endpoint organization identifier's schemeID to an Oioubl-valid value. We encourage using a real, relevant value of the recipient if possible, and otherwise of your own.
Documents remain fully compliant with standard Oioubl processing.
The document with the extension will validate against XSD schema and Oioubl schematron rules, as UBLExtension is a part of the OIOUBL format.
Sending Your Document to Sproom
Submit your Oioubl document with the UBLExtension via POST /api/documents (or any other integration channel).Sproom will:
Validate the document structure and extension format.
Override the specified identifiers when processing the document
Route the document to the recipient specified by the EndpointID from the extension (if given)
If the overridden EndpointID is invalid or not registered for reception of the document type, the sending will fail in the same way as other documents that can’t be delivered.