The Peppol Business Interoperability Specification, “BIS” from here on after, has been developed by the OpenPeppol AISBL Post Award Coordinating Community and is published as part of the Peppol specifications.
Link to main site of documentation
1. Introduction to openPeppol and BIS
This BIS is a result of work within OpenPeppol and is published as part of the Peppol specifications.
This Peppol BIS provides a set of specifications for implementing a Peppol business process. The document is concerned with clarifying requirements for ensuring interoperability of pan-European Public eProcurement and provides guidelines for supporting these requirements and how to implement them. This Peppol BIS is based on the CEN WS/BII Profile “BII Profile 42 Order Agreement CWA 17029-124” CEN WS/BII 3.
The purpose of this document is to describe a common format for the order agreement in the European market, and to facilitate an efficient implementation and increased use of electronic collaboration regarding the ordering process based on this format.
1.1. Audience
The audience for this document is organizations wishing to be Peppol enabled for exchanging electronic business documents, and/or their ICT-suppliers.
These organizations may be:
-
Service providers
-
Contracting Authorities
-
Economic Operators
-
Software Developers
More specifically it is addressed towards the following roles:
-
ICT Architects
-
ICT Developers
-
Business Experts
For further information, please see Peppol BIS common text and introduction.
2. Principles and prerequisites
This chapter describes the principles and assumptions that underlie the use of Peppol Order Agreement. It is based on the CEN WS/BII 42 Order Agreement.
This profile identifies, explains and justifies the business requirements for the Order agreement process. It provides syntax bindings to UBL 2.1 (Universal Business Language). It also includes a syntax implementation guide.
The order agreement profile describes processes where the buyer, after purchasing items/services, receives a message with information documenting the purchase.
2.1. Prerequisites
The following are prerequisites for this BIS:
-
A buyer has purchased goods or services from the seller by any means.
-
The seller has to be registered in the buyer system with information as contact information and identifiers used for other BIS transaction e.g. BIS order and invoice (GLN, Organization number…)
2.2. Scope
The intended scope for this BIS includes business-to-government (B2G) and business-to-business (B2B) relationships. Although the BIS is a basis for an EDI agreement between two parties, it does not address all business level details of such an agreement/contract.
The order agreement represents the combined information of an order and an order confirmation, i.e. it represents an agreement entered upon by seller and buyer. The transaction, specified in this BIS is intended to be exchanged between the seller’s order management system and the of buyer’s purchasing system so that their respective systems get syncronised with regard to the information on the purchase.
The different uses of this BIS are described in Process and typical use cases.
This is an auxiliary BIS intended to complement the primary ordering BISs, such as Peppol BIS 28A. It allows the buyer to have information from less formalized purchase processes conveniently fed into the procurement system, thereby giving control over corresponding payments and better statistics. By opening for order agreement transactions, it is very important that the buyer’s system can verify that the seller is allowed to send an order agreement and that the process is described in the contract between seller and buyer to prevent fraud and to secure good quality in the transaction.
2.3. Goals and Objectives
The following main business goals to be gained by implementing a BII Order agreement profile are the following and apply to this BIS.
| ID | Description |
|---|---|
G-42-001 |
The profile enables buyers to receive real time information on the contracted products/services, resulting in correct and up to date information, such as price and availability based on a contract. |
G-42-002 |
The effort to distribute catalogue information can be substantially reduced for sellers with large catalogues. It does not even presume standardized catalogues. |
G-42-003 |
The profile enables the buyer to create an order in the seller’s web shop. |
G-42-004 |
The profile enables the buyer to buy services such as flight tickets on-line and receive the order information back in the purchasing system of the buyer. |
G-42-005 |
The profile enables buyers to configure their own products (i.e. pc’s or furniture) on the seller’s website, and receive order information back to the purchasing system of the buyer., |
G-42-006 |
Increased order accuracy by ensuring high data quality in the purchasing system of the buyer. |
G-42-007 |
Personalized shopping experience - the seller’s product/services can be presented with photos, customized promotions and recommended accessories |
G-42-008 |
The profile enables the buyer to receive the order information back in the purchasing system of the buyer also in the cases where the order is sent via e-mail, made in a telephone call or on a visit to the seller’s store. |
G-42-009 |
The profile enables the buyer to instruct the seller to send a reference chosen by the buyer in the Order Agreement transaction. |
G-42-010 |
The buyer wants precise order to invoice matching. |
G-42-011 |
The seller wants an efficient way to report services rendered when buyer cannot order through the purchasing system. |
G-42-012 |
The seller wants to match order and invoice automatically |
G-42-013 |
The buyer wants to document the services rendered based on contract when the order was executed by other channels or based on a service agreement |
G-42-014 |
The buyer wants to receive order agreement in a structured way in a general and interoperable file-format with no need for custom mappings or conversions. |
G-42-015 |
The seller wants order agreement using generally accepted standard formats/specifications. |
G-42-016 |
A buyer wants to collect certificate and label information in his orders for analytical purposes. |
2.4. Parties and roles
The table below gives the definitions of the parties and roles of the ordering process.
Business partners |
Description |
Customer |
The customer is the legal person or organization who is in demand of a product or service. Examples of customer roles: buyer, consignee/delivery part, debtor, contracting body. |
Supplier |
The supplier is the legal person or organization who provides a product or service. Examples of supplier roles: seller, consignor, creditor, economic operator. |
Role/actor |
Description |
Buyer (BuyerCustomerParty) |
The buyer is the legal person or organization acting on behalf of the customer and who buys or purchases the goods or services. |
Seller (SellerSupplierParty) |
The seller is the legal person or organization acting on behalf of the supplier and who sells goods or services to the customer. |
The following diagram links the business processes to the roles performed by the Business Partners.
2.5. Benefits
-
The ability to use existing order-invoice-matching processes even if order is not issued from a procurement system.
-
Capture ordering actions that happen in other processes such as web shops, phone or by requisition at warehouse/store and so forth.
-
Visibility of whole spending analysis in the ordering module by importing orders that are not sent directly from the ordering module.
-
Support for ordering processes where products/services are not necessarily described as standardized catalogue items.
2.6. Interoperability
This Peppol BIS structure is based on the European Interoperability Framework 2.0. Peppol BIS applies the Framework as follows:
-
Legal Interoperability
-
Legal:
-
In implementations supporting public sector buyers, the use of the Punch out BIS has to be monitored in order to secure that the buyers act in line with EU procurement directives.
-
-
-
Organizational interoperability
-
Organization (Organization/Business):
-
This Peppol BIS supports B2B and B2G.
-
This Peppol BIS supports cross border, regional and domestic ordering in EU and EEA.
-
This Peppol BIS can function as a component in an EDI agreement within a trading community.
-
This Peppol BIS supports linking of business processes within the sending and receiving organization. The process of order transmission in electronic form can be linked into internal processes of both sender and receiver, which may differ for various reasons.
-
-
Organization (Process):
-
This Peppol BIS supports a set of “common business processes” that is assumed to be supported by most enterprises whether public or private. These are processes that are used widely or understood as being relevant for most companies.
-
-
-
Semantic interoperability
-
Semantic: The set of information elements is assumed to be sufficient to support organizational business and processing requirements stated above.
-
A CORE Order Agreement cart message:
-
Data model, a set of elements that the receiver MUST be able to process.
-
Business rules, a set of business rules that ensure a common way of processing the information elements. The rules are stated in a way that allows for automated validation of document instances. Issuers and receivers can verify that the exchanged document conformes to the rules of this BIS.
Peppol adds business rules on top of the data model to clarify certain design choices left open by the {cenbii}. These choices are intended to lower the implementation threshold by limiting options for implementers and thereby increase interoperability of Peppol punch out transactions.
-
-
-
-
Technical interoperability
-
Technical Interaction (Process and semantic implementation):
-
Binding to OASIS UBL 2.1, see UBL 2.1
-
ISO/IEC 19757-3 Schematron, for automation of document validation, see Schematron
-
XSLT Stylesheet for presentation of content, see [XSLT]
-
-
Technical Interaction (eSignature Validation):
-
Not mandatory in this Peppol BIS. Not supported.
-
-
3. Process and typical use cases
The order agreement BIS includes the sending of information on agreed products/services from a Seller to a Buyer.
3.1. Process flow
The order agreement process flow can be described as follows:
-
A Buyer makes a purchase of goods or services from the Seller.
-
A Seller reports one or more accumulated purchases made under a framework agreement to the Buyer.
-
A purchase has been recorded in the Buyer´s purchasing system. The seller proceeds to invoice accordingly.
An Order Agreement may refer to a framework agreement for its terms and conditions; otherwise the Buyer’s terms and conditions apply.
3.2. Business process Diagram
3.2.1. Legend for BPMN diagrams
The diagrams are expressed in the BPMN notation. The diagram below serves as an explanation for the diagrams used in the process descriptions.
The following diagram shows the choreography of the business process implemented by the BIS.
Categories |
Description and Values |
Description |
The buyer doesn’t use the purchasing system to create an order. It’s done outside of this system. The seller creates an order in his ordering system based on requirements from the buyer and, after agreeing/committing to it, sends a copy of the order as an Order agreement to the buyer. |
Pre-conditions |
The seller’s ordering system must be able to send Order agreement transactions. The buyer’s purchasing system must be able to receive Order agreement transactions. The content of the order is agreed through use of web shop, phone, email, physical visit to shop or other means. |
Post-conditions |
The buyer has received an order agreement that is recorded in the purchasing system. |
Legal Implications |
By providing an Order agreement transaction the Seller commits himself the, quantities, prices and terms stated in the Order agreement transaction. |
3.3. Use case 1 – Web store used for booking tickets
This use case describes the process where a customer/buyer orders tickets.
Use Case number |
1 |
|---|---|
Use Case Name |
Web store used for booking tickets |
Use Case Description |
The buyer uses a website to buy tickets, such as for airfare or events. |
Parties involved |
|
Assumptions |
The seller has a website that allows the buyer to select and order tickets. |
The flow |
The buyer uses the website to book tickets. The buyer receives the tickets in the way as selected in the web shop (e.g. mobile ticket or pdf). The buyer then ends the web shop session. The purchase is recorded in the seller’s system. An order agreement transaction with all necessary information is sent from the seller’s system to the buyer’s purchasing system. The order agreement is recorded in the buyer’s purchasing system. An invoice is sent to the buyer, but this is outside of this BIS. If the buyer wishes to change a ticket in accordance with the its rules then he reenters the web store, changes the ticket and receives a new order agreement. The change procedure is a repetition of the initial one. |
Result |
The buyer and the seller have reached an agreement. An order has been placed for tickets and the buyer has received a structured message with its details. If the invoice has an order reference, the invoice can be matched automatically. |
XML example file |
See Appendix A for a sample file illustrating Use Case 1. |
3.4. Use case 2 – Web shop used for ordering items
This use case describes the process where a customer/buyer orders products in a web shop.
Use Case number |
2 |
|---|---|
Use Case Name |
Web shop used for ordering items |
Use Case Description |
The buyer uses a website to buy items. |
Parties involved |
|
Assumptions |
The seller has a website that allows the buyer to select and order items. |
The flow |
The buyer is working in the in-house purchasing system, selects a seller that has a web shop, and clicks to see that seller’s products. The buyer searches the website for items needed, and choose to add some to the order agreement. It is clearly visible which items are contracted. After selecting all required items, the buyer then chooses to buy the selected items. When the ordering is finalized in the web shop, the buyer ends the web shop session. The purchse is recorded in the seller’s system. An order agreement transaction with item information of the purchased items is sent from the seller to the. The order agreement is recorded in the buyer’s purchasing system. After the delivery of the goods the seller sends an invoice which matches the order and the delivery, but this is outside of this BIS. |
Result |
The buyer and the seller have reached an agreement. An order has been placed and the buyer has received a structured message with the order details. If the invoice has an order reference, the invoice can be matched automatically. |
XML example file |
See Appendix A for a sample file illustrating Use Case 2. |
3.5. Use case 3 – Telephone and e-mail is used to order items
Use Case number |
3 |
|---|---|
Use Case Name |
Telephone or e-mail order |
Use Case Description |
Buyer makes a purchase by calling the seller by telephone or by sending an email. |
Parties involved |
|
Assumptions |
The buyer has an account with the seller with necessary details to send him an order agreement. |
The flow |
The buyer is working in his purchasing system, and need to by printers and selects a seller of printers. The seller’s items are not in the purchasing system and the seller doesn’t offer a web shop. The buyer calls the seller on the telephone. The buyer orders the printer directly during the phone call, and also informs the seller what reference to use. An order agreement transaction with item information and price of the selected items is sent from the seller to the buyer’s purchasing system. The order agreement is recorded in the buyer’s purchasing system After the delivery of the goods, the seller sends an invoice which matches the order and the delivery, but this is outside of this BIS. |
Result |
The buyer and the seller have reached an agreement. An order has been placed and the buyer has received a structured message with the order details. If the invoice has an order reference, the invoice can be matched automatically. |
XML example file |
See Appendix A for a sample file illustrating Use Case 3. |
3.6. Use case 4 – Buyer visits the seller’s physical store.
This use case describes a process where the buyer physically enters the sellers store to buy and possibly take delivery of goods.
Use Case number |
4 |
|---|---|
Use Case Name |
User configures product/services |
Use Case Description |
A buyer physically makes a purchase and takes delivery. |
Parties involved |
|
Assumptions |
The buyer has an account with the seller with necessary details to send him an order agreement. |
The flow |
The buyer urgently need some items and may wish to discuss this with the seller before buying the items. After selecting the items he needs the buyer gets a receipt for the selected items. He may bring with him all the items when leaving the store or schedule a later delivery. The seller registers the order in the ordering system including a reference such as requisition number, person id, project id etc. An order agreement transaction with item information and price of the selected items is sent from the seller to the buyer’s purchasing system. The order agreement is recorded in the buyer’s purchasing system The buyer then follows the normal procedure to, if needed, complete the order. The seller sends an invoice which matches the order and delivery, but this is outside of this BIS. |
Result |
The buyer and the seller has reached an agreement. An order has been placed and the buyer has taken delivery of the products. The buyer has received a structured message with the order details. The invoice has a reference, to match the order. |
XML example file |
See Appendix A for a sample file illustrating Use Case 4. |
3.7. Use case 5 – Framework contract
The buyer has made a framework agreement with the seller for services such as maintenance or consulting. The framework agreement sets limits and terms within which the seller may provide services without individual orders from the buyer.
Use Case number |
5 |
|---|---|
Use Case Name |
Maintenance based on framework contract |
Use Case Description |
A seller who has a framework agreement that contracts him for certain services, items or consulting may react to events as contracted and at the end of a period send an order agreement listing the services that were carried out.
In each of these examples the buyer has made a framework contract with the seller allowing the seller to react to defined but not previously known events without receiving an order or request from the buyer for each event. |
Parties involved |
|
Assumptions |
The seller and buyer has a framework contract that define the service to be provided and its limits. |
The flow |
The seller of the services or items reacts to events as defined in the contract and carries out the service or delivers the items as contracted. Periodically, for example monthly, the seller lists all services and items that have been provided during the period. This is listed with order agreement lines and the total of the order agreement represents the total value of the services and items provided during the period which will be invoice by the seller. The seller sends the order agreement to the buyer who records it in his system. The seller proceeds to invoice immediately unless otherwise directed by the framework agreement. The buyer may have internal processes that verify these kind of order agreements differently than those initiated by himself. |
Result |
The buyer has registered a purchase order in his systems that allow him to order to invoice matching when the invoice is received. |
XML example file |
See Appendix A for a sample file illustrating Use Case 5. |
4. Semantic datatypes
Semantic data types are used to bridge the gap between the semantic concepts expressed by the information elements and the technical implementation. The semantic data types define the allowed value domain for the content, and any additional information components (attributes) needed in order to ensure its precise interpretation.
4.1. Primitive types
Semantic data type content may be of the following primitive types. These primitive types were taken from ISO 15000-5:2014, Annex A.
| Primitive type | Definition |
|---|---|
Binary |
A set of finite-length sequences of binary digits. |
Date |
Time point representing a calendar day on a time scale consisting of an origin and a succession of calendar ISO 8601:2004. |
Decimal |
A subset of the real numbers, which can be represented by decimal numerals. |
String |
A finite sequence of characters. |
4.2. Semantic data types
The different semantic data types are described in the tables below, where various features such as attributes, format, and decimals as well as the basic type are defined for each semantic data type. They are based on ISO 15000-5:2014.
When used in an instance document, each data element will contain data. In the below tables this is identified as the “content”. Whenever a business term is used this term shall always have content and therefore the content is always mandatory.
4.2.1. Amount
An amount states a numerical monetary value. The currency of the amount is defined as a separate business term.
| Amount is floating up to two fraction digits. |
| Component | Use | Primitive Type | Example |
|---|---|---|---|
Content |
Mandatory |
Decimal |
10000.25 |
4.2.2. Price Amount
A price amount states a numerical monetary amount value for data elements that contain item prices that may be multiplied by item quantities. The currency of the amount is defined as a separate business term.
| Unit price amount does not set restrictions on number of decimals, as contrast to the Amount type |
| Component | Use | Primitive Type | Example |
|---|---|---|---|
Content |
Mandatory |
Decimal |
10000.1234 |
4.2.3. Percentage
Percentages are given as fractions of a hundred (per cent) e.g. the value 34,78 % in percentage terms is given as 34,78.
| No restriction on number of decimals for percentages. |
| Component | Use | Primitive Type | Example |
|---|---|---|---|
Content |
Mandatory |
Decimal |
34.7812 |
4.2.4. Quantity
Quantities are used to state a number of units such as for items. The code for the Unit of Measure is defined as a separate business term.
| No restriction on number of decimals for quantities. |
| Component | Use | Primitive Type | Example |
|---|---|---|---|
Content |
Mandatory |
Decimal |
10000.1234 |
4.2.5. Code
Codes are used to specify allowed values in elements as well as for lists of options. Code is different from Identifier in that allowed values have standardized meanings that can be known by the recipient.
| Codes shall be entered exactly as shown in the selected code list |
| Component | Use | Primitive Type | Example |
|---|---|---|---|
Content |
Mandatory |
String |
Abc123 |
4.2.6. Identifier
Identifiers (IDs) are keys that are issued by the sender or recipient of a document or by a third party.
| The use of the attributes is specified for each information element. |
| Component | Use | Primitive Type | Example |
|---|---|---|---|
Content |
Mandatory |
String |
abc:123-DEF |
Scheme identifier |
Conditional |
String |
0088 |
Scheme version identifier |
Conditional |
String |
1.0 |
4.2.7. Date
Dates shall be in accordance to the “Calendar date complete representation” as specified by ISO 8601:2004, format YYYY-MM-DD.
| Dates shall not include timezone information. |
| Component | Use | Primitive Type | Example |
|---|---|---|---|
Content |
Mandatory |
Date |
2017-12-01 |
4.2.8. Time
Time shall be in accordance to the “Extended time format” as specified by ISO 8601:2004, format [hh]:[mm]:[ss].
| Time shall not include timezone information. Decimal fraction on seconds SHALL not be used. |
| Component | Use | Primitive Type | Example |
|---|---|---|---|
Content |
Mandatory |
Date |
09:30:12 |
4.2.9. Document Reference
Document Reference Types are identifiers that were assigned to a document or document line.
| Component | Use | Primitive Type | Example |
|---|---|---|---|
Content |
Mandatory |
String |
abc:123-DEF |
4.2.10. Text
Text is the actual wording of anything written or printed. Line breaks in the text may be present, and any line breaks should be preserved and respected by the receiver’s system
| Component | Use | Primitive Type | Example |
|---|---|---|---|
Content |
Mandatory |
String |
5% allowance when paid within 30 days |
4.2.11. Binary objects
Binary objects can be used to describe files which are transmitted together with the business document. Attachments shall be transmitted together with the business document. The binary object has two supplementary components: a Mime Code, which specifies the Mime type of the attachment and a Filename that is provided by (or on behalf of) the sender of the business document.
| Component | Use | Primitive Type | Example |
|---|---|---|---|
Content |
Mandatory |
Binary |
QmFzZTY0IGNvbnRlbnQgZXhhbXBsZQ== |
Mime Code |
Mandatory |
String |
image/jpeg |
Filename |
Mandatory |
String |
drawing5.jpg |
5. Code lists
5.1. Code lists for coded elements
Any element with the semantic data type = code, can mandate the use of a specific code list (or a fixed value). The applicable code lists can be found in the Code list section. In this section, you can find the valid codes, their names and description, and also links to where the same code list is used elsewhere in the transaction, or in other Peppol BIS v3. documents.
5.2. Code list for identifiers
5.2.1. Party identifiers and party legal registration identifier scheme
All party identifiers (cac:PartyIdentification/cbc:ID) and party legal registration identifier (cac:PartyLegalEntity/cbc:CompanyID) has an optional scheme identifier attribute (@schemeID).
If used, the value shall be chosen from the code list ICD codes
cac:PartyIdentification<cac:PartyIdentification>
<cbc:ID schemeID="0088">5790000435968</cbc:ID> (1)
</cac:PartyIdentification>| 1 | schemeID attribute is optional, but when used, the codes must be from ICD codes |
5.2.2. Electronic address identifier scheme identifier
All electronic address identifiers (cbc:EndpointID/@schemeID) use the Electronic Address Scheme code list (EAS),
maintained by CEF (CEF Code lists).
Valid values are found here: EAS codes.
cbc:EndpointID<cbc:EndpointID schemeID="0184">DK87654321</cbc:EndpointID> (1)| 1 | schemeID attribute is mandatory |
6. Calculations
6.1. Calculation of TAX amounts
6.1.1. Total TAX amount
The total TAX amount can be provided without providing the TAX breakdown, but if the TAX breakdown is present, the total TAX amount is the sum of all TAX Category TAX amounts.
\$"Total TAX amount" = sum("TAX category tax amount")\$
6.1.2. TAX Breakdown
One TAX Breakdown shall be provided for each distinct combination of TAX category code and TAX rate found in either the line TAX information or the Document level allowance or charges.
For each distinct combination of TAX category code and TAX rate the calculations are:
\$"TAX category taxable amount" = sum("Line net amounts")\$
\$+ "Document level charge amount" - "Document level allowance amount"\$
\$"TAX category tax amount" = "TAX category taxable amount" times ("TAX rate" div 100)\$
| For TAX Breakdown where the TAX Category indicates the invoice is not subject to TAX (e.g. (O) in EU), then the TAX category tax amount shall be zero. |
Please note that for the TAX rate, only significant decimals should be considered, i.e any difference in trailing zeros should not result in different TAX breakdowns.
Line 1 has category code = S and VAT rate = 25
Line 2 has category code = S and VAT rate = 25.00
This should result in only one VAT Breakdown.
<cac:TaxTotal>
<cbc:TaxAmount currencyID="EUR">283.2</cbc:TaxAmount>
<cac:TaxSubtotal>
<cbc:TaxableAmount currencyID="EUR">1200</cbc:TaxableAmount>(1)
<cbc:TaxAmount currencyID="EUR">283.20</cbc:TaxAmount>(2)
<cac:TaxCategory>
<cbc:ID>S</cbc:ID>
<cbc:Percent>23.6</cbc:Percent> (3)
<cac:TaxScheme>
<cbc:ID>VAT</cbc:ID>
</cac:TaxScheme>
</cac:TaxCategory>
</cac:TaxSubtotal>
</cac:TaxTotal>| 1 | The class cac:TaxCategory is used for tax category information |
| 2 | TAX category according to codelist Code list UNCL5305 |
| 3 | TAX rate |
6.2. Calculation of totals
The following elements show the legal monetary totals
| Element | Description | Formula |
|---|---|---|
|
Sum of line net amounts |
\$sum("cac:OrderLine/LineItem/cbc:LineExtensionAmount")\$ |
|
Sum of allowances on document level |
\$sum("cac:AllowanceCharge[ChargeIndicator='false']/cbc:Amount")\$ |
|
Sum of charges on document level |
\$sum("cac:AllowanceCharge[ChargeIndicator='true']/cbc:Amount")\$ |
|
Invoice total amount without VAT |
\$\ \ \ \ "cac:LegalMonetaryTotal/cbc:LineExtensionAmount"\$ |
|
Invoice total amount with VAT |
\$\ \ \ \ "cac:LegalMonetaryTotal/cbc:TaxExclusiveAmount"\$ |
|
Amount allready paid |
Not applicable |
|
Amount added for rounding of the payable amount |
Not applicable |
|
Amount due for payment |
\$\ \ \ \ "cac:LegalMonetaryTotal/cbc:TaxInclusiveAmount"\$ |
7. Description of selected parts of the order agreement message
Following clauses describe the use of individual sections of the order agreement transaction.
7.1. Parties
The following parties/roles may be specified in the message:
7.1.1. SellerSupplierParty (Seller)
The seller is the legal person or organization acting on behalf of the supplier and who sells goods or services to the buyer. The seller is mandatory in the Peppol BIS Order Agreement message.
<cac:SellerSupplierParty>
<cac:Party>
<cbc:EndpointID schemeID="0088">5790000436095</cbc:EndpointID>
<cac:PartyIdentification>
<cbc:ID schemeID="0007">5541277711</cbc:ID>
</cac:PartyIdentification>
<cac:PostalAddress>
<cbc:StreetName>Apt 56B, Whitehaven Mansions</cbc:StreetName>
<cbc:AdditionalStreetName>Sandhurst Sq</cbc:AdditionalStreetName>
<cbc:CityName>Brussels</cbc:CityName>
<cbc:PostalZone>1001</cbc:PostalZone>
<cbc:CountrySubentity>Brussels-Capital</cbc:CountrySubentity>
<cac:Country>
<cbc:IdentificationCode>BE</cbc:IdentificationCode>
</cac:Country>
</cac:PostalAddress>
<cac:PartyLegalEntity>
<cbc:RegistrationName>Seller Company Ltd</cbc:RegistrationName>
</cac:PartyLegalEntity>
<cac:Contact>
<cbc:Name>Hercule Poirot</cbc:Name>
<cbc:Telephone>123456</cbc:Telephone>
<cbc:ElectronicMail>mail@work.be</cbc:ElectronicMail>
</cac:Contact>
</cac:Party>
</cac:SellerSupplierParty>7.1.2. BuyerCustomerParty (Buyer)
The buyer is the legal person or organization acting on behalf of the customer and who buys or purchases the goods or services. The buyer is mandatory in the Peppol BIS Order Agreement message.
<cac:BuyerCustomerParty>
<cac:Party>
<cbc:EndpointID schemeID="0088">5790000436095</cbc:EndpointID>
<cac:PartyIdentification>
<cbc:ID schemeID="0007">5541277711</cbc:ID>
</cac:PartyIdentification>
<cac:PostalAddress>
<cbc:StreetName>Apt 56B, Whitehaven Mansions</cbc:StreetName>
<cbc:AdditionalStreetName>Sandhurst Sq</cbc:AdditionalStreetName>
<cbc:CityName>Brussels</cbc:CityName>
<cbc:PostalZone>1001</cbc:PostalZone>
<cbc:CountrySubentity>BE</cbc:CountrySubentity>
<cac:Country>
<cbc:IdentificationCode>SE</cbc:IdentificationCode>
</cac:Country>
</cac:PostalAddress>
<cac:PartyLegalEntity>
<cbc:RegistrationName>Buyer Ltd</cbc:RegistrationName>
</cac:PartyLegalEntity>
</cac:Party>
</cac:BuyerCustomerParty>7.1.3. OriginatorCustomerParty (Originator)
The unit initiating or requesting the ordered items. Most often the end user. The originator information is optional in the Peppol BIS Order Agreement message.
<cac:OriginatorCustomerParty>
<cac:Party>
<cac:PartyIdentification>
<cbc:ID schemeID="0007">5541277711</cbc:ID>
</cac:PartyIdentification>
<cac:PartyName>
<cbc:Name>Information services</cbc:Name>
</cac:PartyName>
</cac:Party>
</cac:OriginatorCustomerParty>7.1.4. AccountingCustomerParty (Invoicee)
The invoicee is the legal person or organization acting on behalf of the customer and who receives the invoice for the order. The invoicee information is optional in the Peppol BIS Order Agreement message.
<cac:AccountingCustomerParty>
<cac:Party>
<cac:PartyIdentification>
<cbc:ID schemeID="0007">5541277711</cbc:ID>
</cac:PartyIdentification>
<cac:PartyName>
<cbc:Name>Information services</cbc:Name>
</cac:PartyName>
</cac:Party>
</cac:AccountingCustomerParty>7.2. Delivery
Delivery gives information on when and where the goods and services are delivered.
-
Delivery location (
cac:Delivery/cac:DeliveryTerms/cac:DeliveryLocation) is where the supplier leaves the packages. -
Delivery party (
cac:Delivery/cac:DeliveryParty) is the party who will get the ordered items.
Delivery special terms may be used to inform how the the goods or service is delivered. E.g.
-
A ticket may be delivered as a pdf in mail - “Mail”.
-
Goods may have been collected at the store – “Customer pick up“
The delivery information is optional in the Peppol BIS Order Agreement message.
<cac:Delivery>
<cac:PromisedDeliveryPeriod>
<cbc:StartDate>2016-08-20</cbc:StartDate>
<cbc:StartTime>12:00:00</cbc:StartTime>
<cbc:EndDate>2016-08-30</cbc:EndDate>
<cbc:EndTime>18:00:00</cbc:EndTime>
</cac:PromisedDeliveryPeriod>
<cac:DeliveryParty>
<cac:PartyIdentification>
<cbc:ID schemeID="0007">5541277711</cbc:ID>
</cac:PartyIdentification>
<cac:PartyName>
<cbc:Name>Delivery party name</cbc:Name>
</cac:PartyName>
</cac:DeliveryParty>
</cac:Delivery>
<cac:DeliveryTerms>
<cbc:ID>1</cbc:ID>
<cbc:SpecialTerms>Customer pick up</cbc:SpecialTerms>
</cac:DeliveryTerms>7.3. References
When sending the order agreement transaction the seller may include a reference that the buyers gave to him during the purchase. This reference can be of different nature and since it originates from the buyer it is understood by him.
<cbc:CustomerReference>Buyer reference id</cbc:CustomerReference>The order agreement may refrence a previous order agreement. This may be relevant, as example, when the buyer has changed a previous order.
<cac:OrderReference>
<cbc:ID>Order id</cbc:ID>
</cac:OrderReference>The order agreement may reference a contract that applies to the purchase.
<cac:Contract>
<cbc:ID>contract id</cbc:ID>
</cac:Contract>7.4. Attachments on header level
Non-XML documents can be sent as attachments to the Peppol BIS Order Agreement. This could be time sheets or other documents relevant for the order agreement. The attachment can either be sent as a binary object encoded in Base64 embedded in the message or as a URI to an external address as a link.
It is recommended to send attachments as embedded, binary objects and not as external references.
| Attachments should be used for additional information and not as order copies. |
<cac:AdditionalDocumentReference>
<cbc:ID>Document id</cbc:ID>
<cbc:DocumentType>Document description</cbc:DocumentType>
<cac:Attachment>
<cbc:EmbeddedDocumentBinaryObject mimeCode="application/pdf" filename="file.pdf">
UjBsR09EbGhjZ0dTQUxNQUFBUUNBRU1tQ1p0dU1GUXhEUzhi</cbc:EmbeddedDocumentBinaryObject>
</cac:Attachment>
</cac:AdditionalDocumentReference>7.5. Attachments and document references on line level
Non-XML documents can be sent as attachments to the Peppol BIS Order Agreement on line level. This could comprise item specifications, time sheets or other documents relevant for the particular line in the order agreement. See the above information regarding attachments.
<cac:ItemSpecificationDocumentReference>
<cbc:ID>doc id</cbc:ID>
<cbc:DocumentType>Item specs</cbc:DocumentType>
<cac:Attachment>
<cbc:EmbeddedDocumentBinaryObject mimeCode="application/pdf"
filename="specs.pdf">
UjBsR09EbGhjZ0dTQUxNQUFBUUNBRU1tQ1p0dU1GUXhEUzhi</cbc:EmbeddedDocumentBinaryObject>
</cac:Attachment>
</cac:ItemSpecificationDocumentReference><cac:ItemSpecificationDocumentReference>
<cbc:ID>doc id</cbc:ID>
<cbc:DocumentType>Item specs</cbc:DocumentType>
<cac:Attachment>
<cac:ExternalReference>
<cbc:URI>https://joinup.ec.europa.eu/svn/peppol/PostAward/Ordering28A/20160310%20-%20PEPPOL_BIS_28a-101.pdf</cbc:URI>
</cac:ExternalReference>
</cac:Attachment>
</cac:ItemSpecificationDocumentReference>7.6. Product identification
Product identification may be done using the identifiers described below:
-
Sellers ID
-
Standard ID, e.g. the GS1 Global Trade Item Number (GTIN)
-
Buyers ID
The order agreement requires that an item has an identifier. This can be either the sellers identifier or a standard identifier. Which identifier to use depends on what is known at the time of the purchase or what is commonly used in the relevant business sector.
<cac:SellersItemIdentification>
<cbc:ID>123</cbc:ID>
</cac:SellersItemIdentification>
<cac:StandardItemIdentification>
<cbc:ID schemeID="0160">73123456001233</cbc:ID>
</cac:StandardItemIdentification>7.7. Product name and description
The Product name must be sent in the element cac:Item/cbc:Name on line level. Description of a product can be sent in cac:Item/cbc:Description.
The Product name is often sent in the order agreement from the buyer to the seller.
<cac:Item>
<cbc:Description>Description of the item</cbc:Description>
<cbc:Name>Item name</cbc:Name>7.8. Item labelling
Information about the items environmental, social, ethical and quality type of labelling. The UBL structure used for item labeling requires certain elements in addition to those used by this BIS. To fulfill the UBL requirements these are included with the dummy value NA.
<cac:Certificate>
<cbc:ID>EU Ecolabel</cbc:ID>
<cbc:CertificateTypeCode>NA</cbc:CertificateTypeCode>
<cbc:CertificateType>Environmental</cbc:CertificateType>
<cbc:Remarks>Item label value</cbc:Remarks>
<cac:IssuerParty>
<cac:PartyName>
<cbc:Name>NA</cbc:Name>
</cac:PartyName>
</cac:IssuerParty>
<cac:DocumentReference>
<cbc:ID>Item label reference</cbc:ID>
</cac:DocumentReference>
</cac:Certificate>7.9. Contracted item
If the purchased item is offered in accordance to an existing contract, this should be indicated in the order agreement message.
<cac:TransactionConditions>
<cbc:ActionCode>CT</cbc:ActionCode>
</cac:TransactionConditions>7.10. Classification
An item may be classified according to UNSPSC being the mandatory public classification schemes in some countries/sectors. As there is currently no code for UNSPSC in the used code list UNCL 7143, the code "MP" (Product/service identification number) is used. Products can also be classified according to regulatory schemes or classification schemes used in certain business sectors.
<cac:CommodityClassification>
<cbc:ItemClassificationCode listID="MP" listVersionID="20.0601">14111511</cbc:ItemClassificationCode>
</cac:CommodityClassification>7.11. Quantities and units
Various Quantities and Units can be stated in the Peppol BIS Order Agreement. These are both related to the ordering process and the logistics process.
The table below lists quantities and units in the format. To all quantities there must be a valid Unit of measure according to the Code list.
| Element name / (Tag name) | Description |
|---|---|
Price Quantity / (BaseQuantity) |
Quantity related to Price. |
Order Quantity / (Quantity) |
Quantity that is ordered, e.g. number of pieces or volume in litre . |
<cac:LineItem>
<cbc:ID>1</cbc:ID>
<cbc:Note>Line note</cbc:Note>
<cbc:Quantity unitCode="C62">120</cbc:Quantity>
<cbc:LineExtensionAmount currencyID="EUR">500</cbc:LineExtensionAmount>
<!-- code omitted for clarity -->
<cac:Price>
<cbc:PriceAmount currencyID="EUR">50</cbc:PriceAmount>
<cbc:BaseQuantity unitCode="C62">12</cbc:BaseQuantity>
</cac:Price>7.12. Prices
Prices must be exchanged in the Order Agreement transaction. The price may be 0 (zero)
Price sent is related to the articles or services within this order agreement
Prices includes allowances and/or charges but exclude TAX amounts
<cac:Price>
<cbc:PriceAmount currencyID="EUR">50</cbc:PriceAmount>
<cbc:BaseQuantity unitCode="C62">1</cbc:BaseQuantity>
</cac:Price>7.13. Allowances and Charges
The order agreement transaction has Allowance/charge on header level.
The element cac:AllowanceCharge with sub element cbc:ChargeIndicator indicates whether the instance is a charge (true) or an allowance (false).
Information on allowance and/or charges applies to the whole order agreement and is included in the calculation of the order agreement total amount.
-
Several allowances and charges may be supplied
-
Specification of TAX for allowances and charges,
cac:TaxCategorywith sub elements, shall be supplied -
The sum of all allowances and charges on the header level shall be specified in
cbc:AllowanceTotalAmountandcbc:ChargeTotalAmountrespectively. See Calculation of totals
Calculation of allowance/charge amount
Allowance and charge on document level consists of elements carrying information on the allowance/charge base amount and the allowance/charge percentage. These are, if present in the invoice instance, used for calculating the allowance/charge amount.
If base amount is present, the percentage shall also be present, and if percentage is present, the base amount shall also be present, and the calculation of the amount shall be:
\$"Amount" = "Base amount" times ("Percentage" div 100)\$
<cac:AllowanceCharge>
<cbc:ChargeIndicator>true</cbc:ChargeIndicator>(1)
<cbc:AllowanceChargeReasonCode>FC</cbc:AllowanceChargeReasonCode>
<cbc:AllowanceChargeReason>Freight service</cbc:AllowanceChargeReason>
<cbc:MultiplierFactorNumeric>2</cbc:MultiplierFactorNumeric>(4)
<cbc:Amount currencyID="EUR">20</cbc:Amount> (5)
<cbc:BaseAmount currencyID="EUR">1000</cbc:BaseAmount>(3)
<cac:TaxCategory>
<cbc:ID>S</cbc:ID>
<cbc:Percent>23.6</cbc:Percent>
<cac:TaxScheme>
<cbc:ID>VAT</cbc:ID>
</cac:TaxScheme>
</cac:TaxCategory>
</cac:AllowanceCharge>
<cac:AllowanceCharge>
<cbc:ChargeIndicator>false</cbc:ChargeIndicator>(2)
<cbc:AllowanceChargeReasonCode>65</cbc:AllowanceChargeReasonCode>
<cbc:AllowanceChargeReason>Production error discount</cbc:AllowanceChargeReason>
<cbc:Amount currencyID="EUR">10</cbc:Amount>
<cac:TaxCategory>
<cbc:ID>S</cbc:ID>
<cbc:Percent>23.6</cbc:Percent>
<cac:TaxScheme>
<cbc:ID>VAT</cbc:ID>
</cac:TaxScheme>
</cac:TaxCategory>
</cac:AllowanceCharge>| 1 | ChargeIndicator = true to indicate a charge |
| 2 | ChargeIndicator = false to indicate an allowance |
| 3 | Base amount, to be used with the percentage to calculate the amount |
| 4 | Charge percentage |
| 5 | \$"Amount" = "Base amount" times ("Percentage" div 100)\$ |
7.14. TAX information (TAX)
The chapters below describe the different TAX informations that can be provided in this BIS. In this context the term TAX applies to taxes such as VAT, GST and Sales Tax.
Please also see Code list UNCL5305 for details on the TAX category code list, and Total TAX amount for detailed explanation and example on how to perform the calculations for TAX Breakdown.
7.14.1. Line TAX Category
TAX information on line level is provided in the class cac:ClassifiedTaxCategory.
Each line may have the item TAX information including category code and percentage.
<cac:ClassifiedTaxCategory>
<cbc:ID>S</cbc:ID> (1)
<cbc:Percent>18</cbc:Percent>(2)
<cac:TaxScheme>
<cbc:ID>VAT</cbc:ID>(3)
</cac:TaxScheme>
</cac:ClassifiedTaxCategory>| 1 | TAX category according to codelist Code list UNCL5305 |
| 2 | The TAX percentage rate that applies to the item unless specific trade reasons apply such as exemptions |
| 3 | Value must identify the correct tax type. For example VAT, GST or sales tax. |
7.14.2. TAX info for allowance or charge
Document level allowance/charge is stated using the UBL element cac:AllowanceCharge. Further details on allowance and charge can be found in Allowances and Charges.
Each document level charge or allowance must have the Document level allowance or charge TAX category code, and for all TAX categories except when tax category indicates that the invoice is not subject to TAX (e.g. (O) in EU), then the TAX rate shall be provided.
<cac:AllowanceCharge>
<cbc:ChargeIndicator>true</cbc:ChargeIndicator>
<cbc:AllowanceChargeReason>Packing cost</cbc:AllowanceChargeReason>
<cbc:Amount currencyID="EUR">200</cbc:Amount>
<cac:TaxCategory>(1)
<cbc:ID>S</cbc:ID>(2)
<cbc:Percent>23.6</cbc:Percent>(3)
<cac:TaxScheme>
<cbc:ID>VAT</cbc:ID>
</cac:TaxScheme>
</cac:TaxCategory>
</cac:AllowanceCharge>| 1 | The class cac:TaxCategory is used for tax category information |
| 2 | TAX category according to codelist Code list UNCL5305 |
| 3 | TAX rate |
8. Peppol Identifiers
Peppol has defined a Peppol Policy for identifiers, policy 8 that specifies how to use identifiers in both its transport infrastructure and within the documents exchanged across that infrastructure. It also introduces principles for any identifiers used in the Peppol environment. The policies that apply to this BIS are the following:
8.1. Profiles and messages
All messages contains ProfileID and CustomizationID. ProfileID identifies what business process a given message is part of, and CustomizationID identifies the kind of message and the rules applied.
Profiles are connected to one business process, and may contain multiple document types. Valid document instances shall contain corresponding ProfileID and CustomizationID.
| CustomizationID is a string without spaces. The list below contains spaces in CustomizationID to make them easier to read. Make sure to remove any spaces before use. |
8.2. Customization and Profile identifiers
In the table below you will find the values to be used as the specification identifier and the business process type for this profile
| Type | Element cbc:CustomizationID |
Element cbc:ProfileID |
|---|---|---|
Order Agreement (Trdm110) |
urn:fdc:peppol.eu:poacc:trns:order_agreement:3 |
urn:fdc:peppol.eu:poacc:bis:order_agreement:3 |
8.3. Namespaces
The order agreement data model is in this Peppol BIS bound to the UBL 2.1 of the order response document type UBL Order Response 2.1. The target namespace for the UBL-OrderResponse-2.1 is:
urn:oasis:names:specification:ubl:schema:xsd:OrderResponse-2