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 18 Punch out CWA 17029-110” CEN WS/BII 3.
The purpose of this document is to describe a common format for the shopping cart 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 this Peppol BIS Punch out. It is based on the CEN WS/BII 18 Punch out.
This document identifies, explains and justifies the business requirements for the Punch Out-process. It provides syntax bindings to UBL 2.1 (Universal Business Language). It also includes a syntax implementation guide.
The Punch Out BIS describes a process where the buyer accesses the seller’s web-based catalogue, and adds and/or configures items (such as a PC) to a product or service list. The product- or service lists are sent to the buyers procurement system, and can later be used as a basis for an order or an item comparison in the buyers catalogue tool. The order is prepared and sent from the buyers procurement system, not from the sellers website.
2.1. Scope
The intention of this BIS is the synchronization of the Punch Out catalogue information between the selling and the buying side in a business relationship, where the selling side is the source of the information and the buying side the receiver. In this BIS, the selling side can be any Economic Operator and the buying side any Contracting Authority. The intended scope for this BIS includes business-to-government (B2G) and business-to-business (B2B) relationships. Although this BIS is a basis for an EDI agreement between two parties, it does not address all business level details of such an agreement. It is the provider’s responsibility that data contained in the shopping cart transaction is valid from a technical, as well as a business point of view.
The transaction, specified in this BIS are intended to be exchanged between the procurement systems of contracting authorities and systems for shopping cart transactions of economic operators. This document recognizes that when using Punch Out it is common to use synchronous message transfer methods but technical specification of that including the login- and logout transactions are outside scope of this BIS.
In this BIS, synchronization of shopping cart transaction information covers the submission of new information, no update or deletion of information is covered by this BIS. In case of an update/change, the buyer will simply generate a new product- or service list by repeating the process.
The information sourced with the Punch Out BIS may be used in a subsequent business process, such as Ordering. The order transaction is outside scope of this BIS, we then refer to the Peppol BIS Order Only or Peppol BIS Ordering.
2.2. Goals and Objectives
The following main business goals to be gained by implementing a {cenbii} Punch out profile are the following and apply to this BIS.
| ID | Description |
|---|---|
G18-001 |
This profile enables quick and easy comparison of different products/services, from different sellers, in the buyer’s procurement system or catalogue tool. |
G18-002 |
The profile enables buyers to receive up to date information on the products/services, such as price and availability. |
G18-003 |
The effort to distribute catalogue information can be substantially reduced for sellers with large catalogues. |
G18-004 |
This profile enables the buyer to use their normal ordering approval procedure. |
G18-005 |
The profile enables buyers to configure their own products (i.e. PC:s or chemical products) on the seller’s website, and receive product-/service-information back to their own system. |
G18-006 |
Increased order accuracy by ensuring high data quality in the procurement system of the buyer. |
G18-007 |
Personalize shopping experience - the sellers' product/services can be presented with photos, customized promotions and recommended accessories. |
G18-008 |
This profile enables the buyer to use their catalogue tool with up-date information transferred from the sellers system. |
2.3. Parties and roles
The table below gives the definitions of the parties and roles of the punch out 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 (ReceiverParty) |
The buyer is the legal person or organization acting on behalf of the customer and who buys or purchases the goods or services. In the Punch Out BIS the buyer accesses the punch out system, selects the items and quantities he wants and completes the action by punching-out. |
Seller (ProviderParty) |
The seller is the legal person or organization acting on behalf of the supplier and who sells goods or services to the customer. In the Punch Out BIS the seller provides the punch out system into which the buyer logs on. The seller is responsible for providing up-to-date information on items and other relevant information in the punch out system. |
The following diagram links the business processes to the roles performed by the Business Partners.
2.4. Benefits
Based on success with automation of invoicing there is a growing interest in automation of ordering. This approach has two dimensions: Support further automation of invoicing and using structured catalogues as basis for ordering. The Punch Out process is a sourcing process that proceeds and supports the ordering. It enables the buyer to retrieve information from the seller and use that information to place an order that can then be used in an order-to-invoice matching process. The Punch Out is a specific type of a sourcing process that supports the growing use of purchasing web portals offered by sellers. Implementing this BIS is an important step for many companies and government agencies towards full procurement automation.
For the sellers, the buyers automated purchasing process can be integrated into their web portals to provide up to date information on items, quantities and prices.
For the procuring agency, up to date item information and prices can be retrieved when required and used for comparison and selection and input to ordering.
Other potential benefits of using this BIS are, among others:
-
Can be used by procuring agencies as step towards automation of procurement. The flexibility of the specifications allows the buyers to gradually automate and structure ordering, based on a cost/benefit approach.
-
SME can offer their trading partners the option of exchanging standardized documents in a uniform way and thereby move all procurement sourcing information into electronic form.
-
Large companies can implement this BIS as standardized documents for general operations.
-
Can be used as basis for restructuring of in-house processes of sourcing and ordering.
-
Significant saving can be realized by the procuring agency by automating and streamlining in-house processing.
-
Significant saving can be realized by the sellers by automating and streamlining in-house processing. Linking to picking and invoicing can be improved significantly based on increased order quality, restructuring of invoice dispute resolution and shorter payment cycles.
-
For the procuring agency, sourcing and ordering can be structured.
2.5. Interoperability
This Peppol BIS structure is based on the European Interoperability Framework 2.0 EIF. This Peppol BIS applies the Framework as follows:
- Legal Interoperability
-
-
Legal:
-
In implementations supporting public sector buyers, the use of this BIS has to be monitored in order to secure that the parties 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 business 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 conforms 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 CEN WS/BII. These choices are intended to lower the implementation threshold by limiting options for implementers and thereby increase interoperability of Peppol 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
-
-
Technical Interaction (eSignature Validation):
-
Not mandatory in this Peppol BIS. Not supported.
-
-
3. Process and typical use cases
The Punch Out BIS includes the sending of Shopping cart information from a Seller to a Buyer.
3.1. Process flow
The Punch Out process flow can be described as follows:
The Buyer is “re-directed” from his procurement system to the seller’s Punch Out enabled website. The buyer searches the website.
At the website the buyer search and select articles which are added to a shopping cart.
When the the buyer checks out of the website, a transaction (Punch Out) with item information of the selected item is sent to the buyer’s procurement system.
3.3. Use case 1 – Punch out used for ordering
This use case describes when a buyer uses the Punch out to retrieve item information that he can use in his procurement systems for ordering.
| Use Case number | 1 |
|---|---|
Use Case Name |
Punch Out used for ordering |
Use Case Description |
The customer/buyer is working in the in-house procurement system, selects a seller that has a Punch Out Catalogue, and clicks to see that seller’s products.The procurement system then automatically sends a login request to the seller’s website, and the procurement system opens the remote website. |
Parties involved |
Buyer |
Assumptions |
The Seller has a website that allows the customer/buyer to automatically log into from his purchasing system. The seller’s website shows what items are contracted. |
The flow |
The buyer searches the website for items needed, and chooses to add some to the shopping cart. It is clearly visible which items are contracted. After selecting all required items, the buyer then chooses to check out. A transaction with information of the selected items is sent to the buyer’s procurement system, all information being real time, resulting in correct and up to date information on price, availability and lead-time. Seller’s website logs out the buyer, and the buyer is redirected back to the procurement system. The buyer then follows the normal order approval procedure, and places an order based on the items in the cart. |
Result |
The buyer has received information about the items that he selected into his cart in a message that is structured like a catalogue that can be imported into his purchasing system and used as basis for an order. |
XML example file |
See Appendix A for a sample file illustrating Use Case 1 in the download section on the main page. |
3.4. Use case 2 – User cancels session
This use case describe when, after having selected items into a shopping cart, the buyer cancels.
| Use Case number | 2 |
|---|---|
Use Case Name |
User cancels session |
Use Case Description |
After having logged into a website which allows Punch Out and selected items into a shopping cart, the buyer cancels the process. |
Parties involved |
Buyer |
Assumptions |
The Seller has a website that allows the customer/buyer to automatically log into from his purchasing system. |
The flow |
The customer/buyer is working in their procurement system, looking for a seller of office supplies. The buyer selects a seller to see that seller’s products. The selected seller provides Punch Out catalogue. The procurement system then automatically sends a login request to the seller’s website, and the procurement system opens the website. The buyer searches the website for the items needed, and add these to the shopping cart. After selecting some items, the buyer chooses to cancel instead of doing a check out. The procurement system automatically logout of the seller’s website, and the buyer is redirected back to the procurement system. |
Result |
Buyer has aborted his connection to the website. The shopping cart has been cleared and no commitments have been made. |
XML example file |
None specific for this use case. |
3.5. Use case 3 – User configures product/services
This use case describes a process where a buyer uses a punch out system to configure a product by selecting several components and features from a catalogue.
| Use Case number | 3 |
|---|---|
Use Case Name |
User configures product/services |
Use Case Description |
The buyer uses the functionality in the sellers website to configure a product or a service. |
Parties involved |
Buyer |
Assumptions |
The Seller has a website that allows the customer/buyer to automatically log into from his purchasing system. |
The flow |
The customer/buyer is working in their procurement system, and is searching for a seller of PC’s. The buyer selects a seller to see that seller’s products. The selected seller’s catalogue is Punch Out enabled. The procurement system then automatically sends a login request to the seller’s website, and the procurement system opens the website. The buyer then use the functionality in the seller’s website to select and configure a PC. When the buyer checks out of the website the item information of the configured item is automatically sent to the buyer’s procurement system. The procurement system automatically logout of the seller’s website, and the buyer is redirected back to the procurement system. From the procurement system, the buyer follows the normal ordering procedures when ordering the PC, using the identifier of the configured item as a reference for the seller. |
Result |
The buyer has retrieved information about a configured item. |
XML example file |
None specific for this use case. |
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 without time zone [hh]:[mm]:[ss]
- format with UTC timezone [hh]:[mm]:[ss]Z
- format for other zones [hh]:[mm]:[ss]±[hh:mm] with zone is given as difference from UTC.
|
Time may 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. Description of selected parts of the shopping cart message
A shopping cart message must at minimum contain the following information:
-
The cart identifier.
-
The date and time when the shopping cart message was created.
-
Identifier of the business process that it belongs to.
-
Identifier of the message specification that applies to the shopping cart message.
-
The name of the party that provides the cart message, i.e. the seller.
-
The name of the party that receives the cart message, i.e. the buyer.
-
One or more message lines each of which contains at minimum the following:
-
A line identifier.
-
The line quantity.
-
The name of the item.
-
The price of the item.
-
The TAX category and percentage rate for the item.
-
In addition to the mandatory information the shopping cart may optionally contain additional information details. The following sections detail how different parts of the shopping cart message are used.
6.1. The Shopping Cart
6.1.1. Identification and dates.
In the beginning of the shopping cart message there is information that identifies the shopping cart itself which allows for managing it in a processing flow as well as referencing it from other documents and processes. This is given by an identifier as well as the date and time when the shopping cart message is created. This would normally be the time when the buyer punches out from the sellers web store.
The identifier is created by the seller and may be of any format. The issue date and time must not be in the future.
<cbc:ID>1387</cbc:ID>
<cbc:IssueDate>2016-08-01</cbc:IssueDate>
<cbc:IssueTime>09:00:00</cbc:IssueTime>The shopping cart also includes two identifiers that identify the process that the shopping cart is used in. The specification that define how the shopping cart message is structured and how its information shall be processed is stated with the customization ID. The process it self is the Punch Out process as defined in this BIS specification, and is stated in the Profile ID element.
These ID’s is always the same for all shopping cart messages that comply to this version of Peppol BIS 18A. Each shopping cart message must comply to the specification referenced.
Details on valid values for both customization ID and profile ID can be found in Customization and Profile identifiers
6.1.2. Sellers conditions
The shopping cart allows the seller to set conditions on how the buyer may order.
The seller may set a limit of the validity time for the information in the shopping cart. A shopping cart is valid from the time it is issued until the time stated in the validity period. That time may not be before the time when the cart is issued. If only validity end date is given the cart is valid until end of that day in the sellers time zone. The seller may also set validity time for individual lines.
<cac:ValidityPeriod>
<cbc:EndDate>2016-08-31</cbc:EndDate>
<cbc:EndTime>18:00:00</cbc:EndTime>
</cac:ValidityPeriod>The seller may set the condition that the offer made in the shopping cart is only valid if all items in the cart are ordered.
This means that the buyer may not select only certain items or change the quantities of the items listed in the cart.
This is given by the complete cart indicator, using the element cbc:ActionCode.
If the value of the indicator is "true" the buyer must either order all or none of the cart.
The default value of the indicator is "false" meaning that if the element is not included in the message the buyer may order part of the cart.
<cbc:ActionCode>true</cbc:ActionCode>The seller may reference a contract that governs the offer made in the shopping cart. The terms and conditions of a referenced contract supersedes the information given in individual shopping carts.
<cac:ReferencedContract>
<cbc:ID>CRT1387</cbc:ID>
</cac:ReferencedContract>Further information on contracts and reference to contract on line can be found in Contract reference
6.1.3. Parties
The following parties/roles may be specified in the message:
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 given in the
cac:ProviderPartyin UBL Catalogue 2.1 and is mandatory in the Peppol BIS Shopping Cart message. -
The seller must be identified with a name but may additionally be identified with an identifier.
-
The endpoint identifier is the Peppol network address Peppol eDelivery Network Specifications and the schemeID identifies the governance of the identifier used, in line with Peppol Policy for identifiers, policy 8.
<cac:ProviderParty>
<cbc:EndpointID schemeID="0192">987654325</cbc:EndpointID>
<cac:PartyIdentification>
<cbc:ID schemeID="0088">5790000435951</cbc:ID>
</cac:PartyIdentification>
<cac:PartyLegalEntity>
<cbc:RegistrationName>ABC Supplier Ltd.</cbc:RegistrationName>
</cac:PartyLegalEntity>
</cac:ProviderParty>Buyer
-
The buyer is the legal person or organization acting on behalf of the customer who buys or purchases the goods or services.
-
The buyer is given in the
cac:ReceiverPartyin UBL Catalogue 2.1 and is mandatory in the Peppol BIS Shopping cart message. The buyer must be identified with his name but may additionally be identified with the sellers customer identifier and/or a registered identifier. -
The endpoint identifier is the Peppol network address Peppol eDelivery Network Specifications and the schemeID identifies the governance of the identifier used, in line with Peppol Policy for identifiers, policy 8.
<cac:ReceiverParty>
<cbc:EndpointID schemeID="0192">123456785</cbc:EndpointID>
<cac:PartyIdentification>
<cbc:ID schemeID="0088">5790000435944</cbc:ID>
</cac:PartyIdentification>
<cac:PartyLegalEntity>
<cbc:RegistrationName>DEF Customer Ltd.</cbc:RegistrationName>
</cac:PartyLegalEntity>
<cac:Contact>
<cbc:ID>buyers ref no</cbc:ID>
</cac:Contact>
</cac:ReceiverParty>6.2. The shopping cart line
Each shopping cart line must have an id to support processing and referencing of individual lines . The ID is created by the seller and may be of any structure.
| A line id must be unique within the shopping cart message, but does not need to be in sequential order in the transaction. |
Example of a series of line identifiers is 1, 2, 3, 4, 5 … or any other structure.
<cac:CatalogueLine>
<cbc:ID>2</cbc:ID>
<!-- Code omitted -->6.2.1. Configured products
-
The seller may define a configured product in a shopping cart and then list the individual items that are part of the configured product in a structured way as described in this clause.
-
The seller may also describe a configured product in an unstructured way as item description.
-
The items that are part of a configured product reference the Sellers Item number for the configured product that it is part of.
-
No reference is made from the configured product to the item.
| A shopping cart line that is part of a configured product can not be ordered individually. |
-
If configured products are part of a shopping cart that has complete cart indicator as true, then a full ordering of the cart means purchase of its configured products only but not additionally the individual items that are part of them.
-
These items can be offered individually with additional lines in the cart where the item is not stated as "part of" the configured product.
-
If information for individual items conflict with the information given for the configured items the configured item supersedes.
To indicate that an item that is part of a configured product, cac:AdditionalItemProperty is used.
The name "PartOf" in cac:AdditionalItemProperty has dedicated meaning in the Peppol PunchOut message.
Example below shows that Item PC01 is configured by 1 of item 12345 and 2 of item 6789. The order will be ONLY on Item PC01.
<cac:CatalogueLine>
<cbc:ID>1</cbc:ID>
<!-- Code omitted for clarity -->
<cac:RequiredItemLocationQuantity>
<cac:Price>
<cbc:PriceAmount currencyID="EUR">1000.00</cbc:PriceAmount>
<cbc:BaseQuantity unitCode="C62">1</cbc:BaseQuantity>
</cac:Price>
<cac:DeliveryUnit>
<cbc:BatchQuantity unitCode="C62">1</cbc:BatchQuantity>
</cac:DeliveryUnit>
</cac:RequiredItemLocationQuantity>
<!-- Code omitted for clarity -->
<cac:SellersItemIdentification>
<cbc:ID>PC01</cbc:ID>
</cac:SellersItemIdentification>
<!-- Code omitted for clarity -->
</cac:Item>
</cac:CatalogueLine>
<!-- An item that is part of the configured product -->
<cac:CatalogueLine>
<cbc:ID>2</cbc:ID>
<cac:RequiredItemLocationQuantity>
<cac:Price>
<cbc:PriceAmount currencyID="EUR">1100.00</cbc:PriceAmount>
<cbc:BaseQuantity unitCode="C62">1</cbc:BaseQuantity>
</cac:Price>
<cac:DeliveryUnit>
<cbc:BatchQuantity unitCode="C62">1</cbc:BatchQuantity>
</cac:DeliveryUnit>
</cac:RequiredItemLocationQuantity>
<!-- Code omitted for clarity -->
<cac:SellersItemIdentification>
<cbc:ID>12345</cbc:ID>
</cac:SellersItemIdentification>
<!-- Code omitted for clarity -->
<cac:AdditionalItemProperty>
<cbc:Name>PartOf</cbc:Name>
<cbc:Value>PC01</cbc:Value>
</cac:AdditionalItemProperty>
</cac:Item>
</cac:CatalogueLine>
<!-- Another item, two of which are part of the configured product -->
<cac:CatalogueLine>
<cbc:ID>3</cbc:ID>
<cac:RequiredItemLocationQuantity>
<cac:Price>
<cbc:PriceAmount currencyID="EUR">20.00</cbc:PriceAmount>
</cac:Price>
<cac:DeliveryUnit>
<cbc:BatchQuantity unitCode="HUR">2</cbc:BatchQuantity>
</cac:DeliveryUnit>
</cac:RequiredItemLocationQuantity>
<!-- Code omitted for clarity -->
<cac:SellersItemIdentification>
<cbc:ID>6789</cbc:ID>
</cac:SellersItemIdentification>
<!-- Code omitted for clarity -->
<cac:AdditionalItemProperty>
<cbc:Name>PartOf</cbc:Name>
<cbc:Value>PC01</cbc:Value>
</cac:AdditionalItemProperty>
<!-- Code omitted for clarity -->| The sum of the price multiplied by quantity of the items contained in the configured item does not have to equal the price of the configured product. The price of the contained items may show the pr. unit price but the configured price may include a price reduction. |
6.2.2. Availability dates and lead time
A shopping cart line may state the item availability date which is first day before the end of which the particular item can and will be shipped from the seller. If availability date is before the cart issue date then the item is immediately available. The availability of all items in the cart ends when the validity period of the cart ends.
<cac:LineValidityPeriod>
<cbc:StartDate>2014-12-31</cbc:StartDate>
</cac:LineValidityPeriod>A shopping cart line may state the lead time for the item. This is the maximum number of working days that may pass from the day the seller receives an order until the day the item is shipped from the seller. The seller may ship earlier.
A lead day of one (1) means that an item will be shipped no later than the end of next working day according to the sellers regional calendar.
<cac:RequiredItemLocationQuantity>
<cbc:LeadTimeMeasure unitCode="DAY">10</cbc:LeadTimeMeasure>
<!-- code omitted for clairty -->When an availability start date is earlier than the end of the lead time the seller may ship at or before the end of the lead time.
6.2.3. Contract reference
-
An individual line may reference a contract.
-
Different lines may reference different contracts.
-
If a contract is referenced on the cart level that contract applies to all items in the shopping cart and is only superseded by the line reference where there is a conflict.
As example, if a cart level contract reference give payment terms and the line level contract only states delivery conditions for the item, then the payment terms apply as well.
An example of line level contract reference is as follows. "Contracted item indicator", should be used when shopping from sellers webshop under framework agreements.
<cbc:ContractSubdivision>234235</cbc:ContractSubdivision>6.3. The shoppingcart Item information
6.3.1. Product identification
Which identifier to use depends on what is known at the time of ordering or what is commonly used in the relevant business sector.
| Each cart line MUST have an item name and an identifier. |
Product identification must be done using one or both of the identifiers described below:
-
Sellers ID
-
Standard ID, e.g. the GS1 Global Trade Item Number (GTIN) used by the seller
Manufacturers item identification can not be used alone to identify a product.
<cac:SellersItemIdentification>
<cbc:ID>PC01</cbc:ID>
</cac:SellersItemIdentification>
<cac:ManufacturersItemIdentification>
<cbc:ID>PC01349087993</cbc:ID>
</cac:ManufacturersItemIdentification>
<cac:StandardItemIdentification>
<cbc:ID schemeID="0160">1234567890123</cbc:ID>
</cac:StandardItemIdentification>
<!-- Code omitted for clarity -->
<cac:ManufacturerParty>
<cac:PartyName>
<cbc:Name>The PC Manufacturing Party</cbc:Name>
</cac:PartyName>
</cac:ManufacturerParty>6.3.2. Item name and description
Description of a product can be sent in cac:Item/cbc:Description.
The Product name is sent in cac:Item/cbc:Name.
The Name is preferably short so that it is suitable for use in a order or invoice line or as a heading. A description allows for longer text that describes the item in detail.
<cbc:Description>21 inch monitor.</cbc:Description>
<cbc:Name>Monitor</cbc:Name>6.3.3. Item properties
A shopping cart line may state if the item described in the line is a service by stating the item property ServiceIndicator as true. The line may also identify that the item is not a service with the value false.
There is no default value so if the ServiceIndicator is not given the item may be either a service or not.
<cac:AdditionalItemProperty>
<cbc:Name>ServiceIndicator</cbc:Name>
<cbc:Value>true</cbc:Value>
</cac:AdditionalItemProperty>A shopping cart line may give a list of various attributes of an item such as size, colour. For each property the property name and value must be given.
Additionally the seller may give a property code, using an identified code list, to support automation in comparison of attribute and if the attribute value can be quantified it may be restated with the Unit of measure as an attribute.
<cac:AdditionalItemProperty>
<cbc:Name>RAM memory</cbc:Name>
<cbc:NameCode listID="PropertyCodeList">Item property code</cbc:NameCode>
<cbc:Value>16 GB</cbc:Value>
<cbc:ValueQuantity unitCode="AD">16000000</cbc:ValueQuantity>
</cac:AdditionalItemProperty>The name "ServiceIndicator" in cac:AdditionalItemProperty has dedicated meaning in the Peppol PunchOut message.
6.3.4. Item classification and labelling
A shopping cart line may give information about the classification of items eg. UNSPSC code
<cac:CommodityClassification>
<cbc:ItemClassificationCode listID="MP" listVersionID="20.0601">14111511</cbc:ItemClassificationCode>
</cac:CommodityClassification>A shopping cart line may give information about labels and certifications that apply to the item. Examples of such are environmental, health, social, quality, cultural and so fort. For each label the name of the label must be given and the certificate of the label as well. If a label has no levels it is recommended to set the type as active.
Due to UBL syntax requirements (see UBL Catalogue 2.1) the tags cbc:CertificateTypeCode and cac:IssuerParty must also be included when the certificate class is used.
These elements are not required by this Peppol BIS but in order to comply with the syntax requirement it is recommended to fill in the elements with the word "NA".
<cac:Certificate>
<cbc:ID>EU Ecolabel</cbc:ID>
<cbc:CertificateTypeCode>NA</cbc:CertificateTypeCode>
<cbc:CertificateType>Social</cbc:CertificateType>
<cac:IssuerParty>
<cac:PartyName>
<cbc:Name>NA</cbc:Name>
</cac:PartyName>
</cac:IssuerParty>
</cac:Certificate>6.3.5. 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. |
6.3.6. Prices and quantities
-
Each line in the Shopping Cart must show the number of items that have been selected by the buyer.
-
For each item there must be a price.
-
The price must be given for the same units as the quantity but the number of units that the price is based on may be different than the quantity.
A buyer may select 360 pieces of an item where the price is €24 for each dozen (12 pieces). In this case the item unit is pieces, and the price for each piece is €24/12 or €2 for each item. Base quantity is optional, with default value 1; when some other base quantity applies it must be stated.
In the shopping cart message this information would be given as follows:
<cac:RequiredItemLocationQuantity>
<cac:Price>
<cbc:PriceAmount currencyID="EUR">24.00</cbc:PriceAmount>
<cbc:BaseQuantity unitCode="C62">12</cbc:BaseQuantity>
</cac:Price>
<cac:DeliveryUnit>
<cbc:BatchQuantity unitCode="C62">360</cbc:BatchQuantity>
</cac:DeliveryUnit>
</cac:RequiredItemLocationQuantity>6.3.7. Attached Item Specifications and main image
Non-XML documents can be sent as attachments to the Peppol BIS Shopping Cart to further specify the item. This could be pictures, drawings or time sheets or other documents relevant for the order. 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.
One of these attachments can be identified specifically as being the main image for the item. Identifying it specifically allows automated retrieval of the image into the image location in the receiving system.
It is recommended to send attachments as embedded, binary objects and not as external references.
Valid codes can be found in Mime codes.
<cac:ItemSpecificationDocumentReference>
<cbc:ID>PC01specs.pdf</cbc:ID>
<cac:Attachment>
<cbc:EmbeddedDocumentBinaryObject mimeCode="application/pdf" filename="specification.pdf"
>UGVyc29uYWwgY29tcHV0ZXIgcHJvZHVjdCBpbmZvcm1hdGlvbg==</cbc:EmbeddedDocumentBinaryObject>
</cac:Attachment>
</cac:ItemSpecificationDocumentReference>When sending an object that is the main image for the item the following example applies.
<cac:ItemSpecificationDocumentReference>
<cbc:ID>PC01image.jpg</cbc:ID>
<cbc:DocumentTypeCode>PRODUCT_IMAGE</cbc:DocumentTypeCode>(1)
<cac:Attachment>
<cbc:EmbeddedDocumentBinaryObject mimeCode="image/jpeg" filename="computer-image.jpg"
>UjBsR09EbGhjZ0dTQUxNQUFBUUNBRU1tQ1p0dU1GUXhEUzhi</cbc:EmbeddedDocumentBinaryObject>
</cac:Attachment>
</cac:ItemSpecificationDocumentReference>| 1 | cbc:DocumentTypeCode MAINIMAGE identifies this as the main image for the item. |
7. 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:
7.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. |
7.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 |
|---|---|---|
Shopping Cart (Trdm077) |
urn:fdc:peppol.eu:poacc:trns:punch_out:3 |
urn:fdc:peppol.eu:poacc:bis:punch_out:3 |
7.3. Namespaces
The shopping cart data model is in this Peppol BIS bound to the UBL 2.1 of the Catalogue document type UBL Catalogue 2.1. The target namespace for the UBL-Catalogue-2.1 is:
urn:oasis:names:specification:ubl:schema:xsd:Catalogue-2
8. Message transport
The transactions defined in this BISs need to be transferred from the sending party to the receiving party through an agreed transport network and protocol. The Peppol BIS BIS is specified independent of a transport network but it is designed with the requirement of the Peppol network in mind and does not specifically support other transport network that may be used.
8.1. The Peppol network
The Peppol transport network is a four corner transport network that allows senders and receivers to exchange messages from one service provider to another by using a single identifier for the parties.
There are some challenges related to the delay of message transfer when using an asynchronous exchange model like the Peppol network. The user who created the shopping cart will have to wait for the message to be received in the purchasing system and there is no specified maximum time limit set for this. When the message is received, it will need to be directed to an identified user or user session. There is no business term in the shopping cart for this purpose other than the Buyer reference identifier (tir77-045). Before using this BIS together with an asynchronous transfer model, the parties should agree on time limits and reference mechanisms.
Details about the Peppol network can be found at [PeppolTransp]
8.2. Synchronous message transfer
It is recognized that the use of Punch Out often requires synchronous methods for retrieving that data directly from the sellers shopping cart into the buyers purchasing system. Several methods are available including the following:
-
Direct database connections with HTTP using database interface specifications.
-
File download using Wget, HTTP, FTP or similar technology.
The following clauses only briefly introduce examples of transfer mechanisms. Analysis of what is the most suitable methods and technical specification are not in scope for this BIS and are not provided by Peppol.
8.2.1. Direct HTTP database connections
Direct database connection using HTTP are common when retrieving shopping carts. Most commonly these methods retrieve the data directly from the catalogue in structured format using input names as field identifiers. In order to read the data correctly into the buyer’s database its structure must be clearly defined.
This Peppol BIS provides a detailed structure of the shopping cart data, using UBL XML and detailed semantic specifications and rules. Such an XML message can be retrieved as payload with an HTTP connection. Once that XML file has been retrieved and saved it can be processes in the same way as an XML file that has been delivered, e.g., through the Peppol network.
A profile for such a message transfer is specified in the document "Peppol synchronous message transfer protocol" provided by OpenPeppol and may be used to transfer Punch Out messages.
8.2.2. Internet file transfer
Since the data of the shopping cart generated by using this Punch Out BIS is captured into a single structured XML file, it lends itself to normal file transfer over the Internet. Such a file transfer can be done with several methods including.
-
File Transfer Protocol (FTP).
-
Wget over FTP or HTTP.