Sales Order API

1. Overview

Jakamo Sales Orders (SO) API is an XML-based REST API over HTTPS. The SO API is for querying incoming sales orders from the SO API and sending an order confirmation back to the customer via Jakamo. When implemented, the result resembles the “EDI” connection between a customer company and a supplier company. SO API can be used to receive sales orders from multiple customer companies that use Jakamo via one integration.

See the user guide instructions to Orders application on Orders User Guide page.

You may also find the FAQ regading SO integration here: SO Technical FAQ

1.1 Requirements how to get started

Request demo accounts from Jakamo Support Team (support@thejakamo.com) to create a SO integration from your system.

There are two similar Jakamo environments available for you: the test environment and the production environment.

• Test environment is for testing purposes. Start your integration testing and user training in a test environment.
• Production environment is for the live use with other Jakamo companies.

Technical capabilities needed

• Basic knowledge of ERP programming and REST API
• Ability to authenticate (basic authentication) and GET order data from the Jakamo SO API
• Ability to create a comprehensive mapping to import purchase order data
• Ability to import purchase orders (as sales orders) to the ERP
• Ability to extract order confirmation from the ERP and create an OrderResponse (UBL XML)
• Ability to POST OrderResponse to the Jakamo SO API
• Ability to handle Jakamo message queue (incoming messages)

1.2 Steps to go to production

The transition from the Jakamo test environment to the Jakamo production environment requires the following actions:

1. Production account establishment in Jakamo.

Create the Jakamo production account via the registration page. Please ensure that there is only one production account existing for your company in Jakamo (avoid creating a double account).

2. Sales order integration activation.

Sales order integration activation for the Jakamo production account. Ask Jakamo Support Team (support@thejakamo.com) to activate the SO integration for you in the production environment. After the integration is available in the Jakamo production account, the Integrations page appears in the dropdown menu in the Jakamo user interface. The integrations setting page are available for company admin users.

3. API authentication method.

Select SO API authentication methdod in the Jakamo production account on the Integrations page. It is preferred to use OAuth2.0. If using basic authentication, determine a cryptic username and password. Please ensure using different usernames and passwords in each enabled integration in use.

4. User and company mappings configuration in Jakamo.

Define user and company mappings on the Jakamo Integrations page.

5. Message endpoint configuration.

Change messages’ endpoint configurations from demo to production (see Jakamo SO API endpoints).

6. Everything is ready!

You are now ready to receive orders from your customers and confirm them via Jakamo!

2. Authorization

Jakamo SO API uses OAuth2.0 or basic authentication as an authentication method. OAuth2.0 is the preferred method. Find step-by-step instructions on how to move from basic authentication to use OAuth2.0.

For basic authentication, the username and password for the API are set inside the Jakamo account in the Integrations settings with the CHANGE CREDENTIALS functionality. If you have multiple integrations enabled towards your Jakamo company account, please use different credentials for each integration.

3. SO API endpoints

Jakamo environment	HTTP request	Jakamo API endpoint
Test environment	GET	https://demo.thejakamo.com/api/order/response
Test environment	POST	https://demo.thejakamo.com/api/orderresponse
Test environment	PUT	https://demo.thejakamo.com/api/orderresponse/{order_id}
Production environment	GET	https://thejakamo.com/api/order/response
Production environment	POST	https://thejakamo.com/api/orderresponse
Production environment	PUT	https://thejakamo.com/api/orderresponse/{order_id}

4. SO API request response messages

Jakamo Sales Order API will return the HTTP response status code and in some cases additional information in the response body. A successfully posted message will return the HTTP response status code 200 OK. If there is an error and a message is not posted to the API, Jakamo API will return 400 Bad Requests or 500 Internal Server Errors.

The table below presents the most common responses from Jakamo Sales Order API.

HTTP response status code	Response body	Additional information
200 OK		Message is successfully posted to Jakamo SO API.
400 Bad Request	Authentication failed.	Authentication failed because of an incorrect username or password or incorrect authentication method. Make sure you use the integration credentials defined in Jakamo Integrations and correct authentication method in use.
400 Bad Request	Incorrect order response	Missing mandatory element. Review your OrderResponse message and check that all mandatory information is there. Check that any mandatory element is not empty. Find tips from SO API FAQ.
400 Bad Request	Cannot find order.	OrderResponse/OrderReference/ID element value does not match an existing purchase order. Check that the order you are trying to confirm is in Jakamo.
400 Bad Request	No customer mapping found	Missing mapping in OrderResponse/BuyerCustomerParty/Party/PartyIdentification/ID. Check that there is a mapping between this identifier and the customer company account on the Jakamo Integrations page.
400 Bad Request	Errors in SellerContact element. Missing mapping?	Missing mapping in OrderResponse/SellerSupplierParty/SellerContact/ID. Check that there is a mapping between this identifier and your company's Jakamo user on the Jakamo Integrations page. SellerContact/ID is mandatory information.
400 Bad Request	LineItem missing Quantity	Quantity element is incorrect or missing from OrderResponse/OrderLine/LineItem. Check that there is quantity in OrderResponse/OrderLine/LineItem/Quantity.
400 Bad Request	Price\PriceAmount is required.	The price element is incorrect or missing from OrderResponse/OrderLine/LineItem. Check that there is price information on OrderResponse/OrderLine/LineItem/Price.
500 Internal Server Error		A generic error message is given when no more specific message is suitable. For example, messages do not follow the UBL structure.

5. Handling incoming message queue

See the general Jakamo API queue handling instructions from incoming message queue handling page.

All incoming messages come to the same endpoint and they can be fetched from the queue by HTTP GET to the endpoint.

The SO API will return messages from the queue one message at a time. Running multiple GET requests would always return the same message if the message is not cleared from the queue. The oldest undeleted message in the queue will be returned first. Incoming messages can be Order (UBL) and optionally OrderChange (UBL) messages.

After processing the incoming message (validate, save it on the disk, parse, import, etc.), the message should be cleared from the queue. All incoming messages contain a value in the “X-Acknowledge-Uri” header. Simply HTTP POST to that address to remove the message from the queue. No message body content is needed when sending a POST request to remove the message from the queue. SO API will return HTTP response code 200 OK and body message <Info>Message cleared from the queue</Info> if your request was correct.

6. The sales order intake and order confirmation process in Jakamo

Here is presented the basic sales order intake and order confirmation process in Jakamo from a technical perspective. Below can be found all the requests explained more in detail with example messages. See a user instructions to Order-to-delivery process on Orders User Guide page.

6.1 Retrieving a new order

The supplier can retrieve customer orders from Jakamo SO API with an HTTP GET request. Order can be retrieved directly to the supplier’s ERP system or the integration platform where the order message can be translated and forwarded into the ERP.

Example: Retrieving new order from Jakamo (HTTP GET)

<Order xmlns:qdt="urn:oasis:names:specification:ubl:schema:xsd:QualifiedDatatypes-2" xmlns:ccts="urn:oasis:names:specification:ubl:schema:xsd:CoreComponentParameters-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:udt="urn:un:unece:uncefact:data:draft:UnqualifiedDataTypesSchemaModule:2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:oasis:names:specification:ubl:schema:xsd:Order-2">
    <cbc:UBLVersionID>2.1</cbc:UBLVersionID>
    <cbc:CustomizationID>Jakamo</cbc:CustomizationID>
    <cbc:ID>purchase_order_number-1234</cbc:ID>
    <cbc:IssueDate>2023-12-14</cbc:IssueDate>
    <cbc:Note>Additional info</cbc:Note>
    <cbc:Note>Additional info row 2</cbc:Note>
    <cbc:Note/>
    <cbc:DocumentCurrencyCode>EUR</cbc:DocumentCurrencyCode>
    <cbc:CustomerReference>CUSTOMER_REF_1234567890</cbc:CustomerReference>
    <cac:AdditionalDocumentReference>
        <cbc:ID>Shipping mark X</cbc:ID>
        <cbc:DocumentTypeCode>SM</cbc:DocumentTypeCode>
    </cac:AdditionalDocumentReference>
    <cac:AdditionalDocumentReference>
        <cbc:ID>Delivery method X</cbc:ID>
        <cbc:DocumentTypeCode>ZZZ</cbc:DocumentTypeCode>
    </cac:AdditionalDocumentReference>
    <cac:ProjectReference>
        <cbc:ID>PROJECT_REF_1</cbc:ID>
    </cac:ProjectReference>
    <cac:BuyerCustomerParty>
        <cac:Party>
            <cac:PartyIdentification>
                <cbc:ID>customer_id</cbc:ID> <!-- This PartyIdentification/ID is defined by supplier their Jakamo Integrations settings, for example customer number on supplier's systems -->
            </cac:PartyIdentification>
            <cac:PartyName>
                <cbc:Name>Customer Company AB</cbc:Name>
            </cac:PartyName>
        </cac:Party>
        <cac:BuyerContact>
            <cbc:Name>Bertha Buyer</cbc:Name>
            <cbc:ElectronicMail>bertha.buyer@company.com</cbc:ElectronicMail>
        </cac:BuyerContact>
    </cac:BuyerCustomerParty>
    <cac:SellerSupplierParty>
        <cac:Party>
            <cac:PartyIdentification>
                <cbc:ID>seller_id</cbc:ID>
            </cac:PartyIdentification>
            <cac:PartyName>
                <cbc:Name>Test Supplier Ltd.</cbc:Name>
            </cac:PartyName>
        </cac:Party>
    </cac:SellerSupplierParty>
    <cac:AccountingCustomerParty>
        <cac:Party>
            <cac:PartyIdentification>
                <cbc:ID>ACCO_1</cbc:ID>
            </cac:PartyIdentification>
            <cac:PartyName>
                <cbc:Name>Accounting Party Ltd.</cbc:Name>
            </cac:PartyName>
            <cac:PostalAddress>
                <cbc:Postbox>12345</cbc:Postbox>
                <cbc:StreetName/>
                <cbc:AdditionalStreetName/>
                <cbc:CityName>Seinäjoki, FINLAND</cbc:CityName>
                <cbc:PostalZone>60100</cbc:PostalZone>
                <cbc:CountrySubentity/>
                <cbc:CountrySubentityCode/>
                <cac:Country>
                    <cbc:IdentificationCode/>
                </cac:Country>
            </cac:PostalAddress>
        </cac:Party>
    </cac:AccountingCustomerParty>
    <cac:Delivery>
        <cac:DeliveryLocation>
            <cac:Address>
                <cbc:Floor/>
                <cbc:StreetName>Jakamokatu 2</cbc:StreetName>
                <cbc:AdditionalStreetName/>
                <cbc:BuildingName/>
                <cbc:CityName>Seinäjoki</cbc:CityName>
                <cbc:PostalZone>60100</cbc:PostalZone>
                <cbc:CountrySubentity/>
                <cbc:CountrySubentityCode/>
                <cac:Country>
                    <cbc:IdentificationCode>FI</cbc:IdentificationCode>
                    <cbc:Name>FINLAND</cbc:Name>
                </cac:Country>
            </cac:Address>
        </cac:DeliveryLocation>
        <cac:DeliveryParty>
            <cac:PartyIdentification>
                <cbc:ID>12345</cbc:ID>
            </cac:PartyIdentification>
            <cac:PartyName>
                <cbc:Name>Delivery Party Ltd.</cbc:Name>
            </cac:PartyName>
        </cac:DeliveryParty>
    </cac:Delivery>
    <cac:DeliveryTerms>
        <cbc:ID>FCA</cbc:ID>
        <cac:DeliveryLocation>
            <cbc:Description>Seinäjoki</cbc:Description>
        </cac:DeliveryLocation>
    </cac:DeliveryTerms>
    <cac:PaymentTerms>
        <cbc:ID>within 60 days Due net</cbc:ID>
        <cbc:Note>within 60 days Due net</cbc:Note>
    </cac:PaymentTerms>
    <cac:OrderLine>
        <cbc:Note>Orderline additional info 1</cbc:Note>
        <cbc:Note>Orderline additional info 2</cbc:Note>
        <cbc:Note>Orderline additional info 3</cbc:Note>
        <cbc:Note/>
        <cac:LineItem>
            <cbc:ID>1</cbc:ID>
            <cbc:Quantity unitCode="PCE">100</cbc:Quantity>
            <cbc:LineExtensionAmount currencyID="EUR">960</cbc:LineExtensionAmount>
            <cac:Delivery>
                <cbc:ID>DELIVERY_ID_1</cbc:ID>
                <cbc:Quantity unitCode="PCE">100</cbc:Quantity>
                <cac:DeliveryLocation>
                    <cac:Address>
                        <cbc:Floor/>
                        <cbc:StreetName>Tamperekatu 5</cbc:StreetName>
                        <cbc:AdditionalStreetName/>
                        <cbc:BuildingName/>
                        <cbc:CityName>Tampere</cbc:CityName>
                        <cbc:PostalZone>30100</cbc:PostalZone>
                        <cbc:CountrySubentity/>
                        <cbc:CountrySubentityCode/>
                        <cac:Country>
                            <cbc:IdentificationCode>FI</cbc:IdentificationCode>
                            <cbc:Name>FINLAND</cbc:Name>
                        </cac:Country>
                    </cac:Address>
                </cac:DeliveryLocation>
                <cac:RequestedDeliveryPeriod>
                    <cbc:EndDate>2024-01-28</cbc:EndDate>
                </cac:RequestedDeliveryPeriod>
                <cac:DocumentReference>
                    <cbc:ID>PROJECT_NUMBER_1</cbc:ID>
                    <cbc:DocumentTypeCode>AEP</cbc:DocumentTypeCode>
                </cac:DocumentReference>
            </cac:Delivery>
            <cac:AllowanceCharge>
                <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
                <cbc:AllowanceChargeReasonCode>ZZZ</cbc:AllowanceChargeReasonCode>
                <cbc:MultiplierFactorNumeric>0.2</cbc:MultiplierFactorNumeric>
                <cbc:Amount currencyID="EUR">240</cbc:Amount>
                <cbc:BaseAmount currencyID="EUR">1200</cbc:BaseAmount>
            </cac:AllowanceCharge>
            <cac:Price>
                <cbc:PriceAmount currencyID="EUR">120</cbc:PriceAmount>
                <cbc:BaseQuantity unitCode="PCE">10</cbc:BaseQuantity>
                <cbc:OrderableUnitFactorRate>1</cbc:OrderableUnitFactorRate>
            </cac:Price>
            <cac:Item>
                <cbc:Description>ISO 4014 - M16x80 - 8.8 tZn</cbc:Description>
                <cbc:Name>HEX HEAD SCREW M16x80mm</cbc:Name>
                <cac:BuyersItemIdentification>
                    <cbc:ID>PART12345</cbc:ID>
                    <cbc:ExtendedID>REVISION_123</cbc:ExtendedID>
                </cac:BuyersItemIdentification>
                <cac:SellersItemIdentification>
                    <cbc:ID>PART54321</cbc:ID>
                </cac:SellersItemIdentification>
                <cac:ManufacturersItemIdentification>
                    <cbc:ID>PART_666</cbc:ID>
                </cac:ManufacturersItemIdentification>
                <cac:ItemSpecificationDocumentReference>
                    <cbc:ID>Drawing XYZ</cbc:ID>
                    <cbc:DocumentTypeCode>174</cbc:DocumentTypeCode>
                </cac:ItemSpecificationDocumentReference>
                <cac:ItemSpecificationDocumentReference>
                    <cbc:ID>work breakdown: MF-201008-01-02-01-00001</cbc:ID>
                    <cbc:DocumentTypeCode>AOL</cbc:DocumentTypeCode>
                </cac:ItemSpecificationDocumentReference>
                <cac:ItemSpecificationDocumentReference>
                    <cbc:ID>STANDARD: ISO 4014</cbc:ID>
                    <cbc:DocumentTypeCode>GA</cbc:DocumentTypeCode>
                </cac:ItemSpecificationDocumentReference>
                <cac:ItemSpecificationDocumentReference>
                    <cbc:ID>1 meter</cbc:ID>
                    <cbc:DocumentTypeCode listID="AttributeList">LENGTH</cbc:DocumentTypeCode>
                </cac:ItemSpecificationDocumentReference>
                <cac:ItemSpecificationDocumentReference>
                    <cbc:ID>1kg</cbc:ID>
                    <cbc:DocumentTypeCode listID="AttributeList">WEIGHT</cbc:DocumentTypeCode>
                </cac:ItemSpecificationDocumentReference>
                <cac:ItemSpecificationDocumentReference>
                    <cbc:ID>0.3 meters</cbc:ID>
                    <cbc:DocumentTypeCode listID="AttributeList">DIAMETER</cbc:DocumentTypeCode>
                </cac:ItemSpecificationDocumentReference>
                <cac:ClassifiedTaxCategory>
                    <cbc:Percent>24</cbc:Percent>
                    <cac:TaxScheme>
                        <cbc:ID>VAT</cbc:ID>
                    </cac:TaxScheme>
                </cac:ClassifiedTaxCategory>
                <cac:ManufacturerParty>
                    <cac:PartyName>
                        <cbc:Name>Manufacturer Ltd.</cbc:Name>
                    </cac:PartyName>
                </cac:ManufacturerParty>
            </cac:Item>
        </cac:LineItem>
        <cac:DocumentReference>
            <cbc:ID>CONTRACT_REFERENCE_1</cbc:ID>
            <cbc:DocumentTypeCode>315</cbc:DocumentTypeCode>
        </cac:DocumentReference>
    </cac:OrderLine>
</Order>

6.2 Confirm the order

The supplier can confirm the order by sending the confirmation information to Jakamo with an OrderResponse message with an HTTP POST request. The order can be confirmed as the customer had requested, or the supplier can propose a change to ordered quantities, prices, and delivery dates.

Confirmed as requested: If the order is confirmed as requested, the order will have the status Confirmed in Jakamo. Order is confirmed in Jakamo when the customer’s requested order values and the supplier’s confirmed order values match.

Confirmed with changes: If the supplier proposes a change to delivery details, the order will have the status Waiting for customer action in Jakamo. In this case, the proposed changes must be accepted by the customer before the order can achieve Confirmed status. If the customer rejects the order confirmation, the order will need to reconfirm. In this case, the order status in Jakamo is Waiting for supplier confirmation.

Example: Sending an order confirmation to Jakamo (HTTP POST)

<OrderResponse xmlns="urn:oasis:names:specification:ubl:schema:xsd:OrderResponse-2" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:oasis:names:specification:ubl:schema:xsd:OrderResponse-2 http://docs.oasis-open.org/ubl/os-UBL-2.1/xsd/maindoc/UBL-OrderResponse-2.1.xsd urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2 http://docs.oasis-open.org/ubl/os-UBL-2.1/xsd/common/UBL-CommonAggregateComponents-2.1.xsd cac urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2 http://docs.oasis-open.org/ubl/os-UBL-2.1/xsd/common/UBL-CommonBasicComponents-2.1.xsd cbc ">
  <cbc:UBLVersionID>2.1</cbc:UBLVersionID>
  <cbc:CustomizationID>Jakamo</cbc:CustomizationID>
  <cbc:ID>123456789</cbc:ID>
  <cbc:IssueDate>2023-01-10</cbc:IssueDate>
  <cac:OrderReference>
      <cbc:ID>purchase_order_number-1234</cbc:ID>
  </cac:OrderReference>
  <cbc:Note>Additional info to order confirmation header (UI: supplier response/note)</cbc:Note>
  <cac:SellerSupplierParty>
      <cac:Party>
          <cac:PartyIdentification>
              <cbc:ID>erp_id</cbc:ID>
          </cac:PartyIdentification>
          <cac:PartyName>
              <cbc:Name>Test Supplier Ltd.</cbc:Name>
          </cac:PartyName>
      </cac:Party>
      <cac:SellerContact>
          <cbc:ID>seller_id</cbc:ID>
      </cac:SellerContact>
  </cac:SellerSupplierParty>
  <cac:BuyerCustomerParty>
      <cac:Party>
          <cac:PartyIdentification>
              <cbc:ID>customer_id</cbc:ID>
          </cac:PartyIdentification>
          <cac:PartyName>
              <cbc:Name>Customer Company AB</cbc:Name>
          </cac:PartyName>
      </cac:Party>
  </cac:BuyerCustomerParty>
  <cac:OrderLine>
      <cbc:Note>Additional info to order confirmation row</cbc:Note>
      <cac:LineItem>
          <cbc:ID>1</cbc:ID>  <!-- OrderResponse's LineItem/IDs must match with the Order's LineItem/IDs made by customer, because Jakamo has to know which order line is being confirmed -->
          <cbc:Quantity unitCode="PCS">100.00</cbc:Quantity>
          <cac:Delivery>
              <cbc:ID>DELIVERY_ID_1</cbc:ID>
              <cbc:Quantity unitCode="PCS">100.00</cbc:Quantity>
              <cac:PromisedDeliveryPeriod>
                  <cbc:EndDate>2023-01-28</cbc:EndDate>
              </cac:PromisedDeliveryPeriod>
          </cac:Delivery>
          <cac:Price>
              <cbc:PriceAmount currencyID="EUR">120.00</cbc:PriceAmount>
          </cac:Price>
          <cac:Item>
              <cbc:Name>HEX HEAD SCREW M16x80mm</cbc:Name>
              <cac:BuyersItemIdentification>
                  <cbc:ID>PART12345</cbc:ID>
              </cac:BuyersItemIdentification>
              <cac:SellersItemIdentification>
                  <cbc:ID>PART54321</cbc:ID>
              </cac:SellersItemIdentification>
          </cac:Item>
      </cac:LineItem>
      <cac:DocumentReference>
          <cbc:ID>THIS IS A ORDER CONFIRMATION PER LINE NOTE TEXT</cbc:ID>
          <cbc:DocumentTypeCode>OSF</cbc:DocumentTypeCode>
      </cac:DocumentReference>
  </cac:OrderLine>
</OrderResponse>

Find tips and typically asked questions related to confirming orders via SO API from SO Technical FAQ.

6.2.1 Simple confirmation

Supplier can also use the simple confirmation endpoint to to approve the customer's new order, or to approve any changes by the customer to an existing order.

Jakamo-Confirm-Url is contained in the Order message headers when it is retrieved from the queue. Order can be approved by supplier and order updated to be “Confirmed” in Jakamo by doing HTTP POST to that Jakamo-Confirm-Url address. This will update the order status to be “Confirmed” and update the order line confirmed values to match customer’s requested values.

Simple confirmation request also accepts parameters, given in message body. The following table lists available parameters.

Parameter name	Description
Note	Text. Text given as a Note parameter will appear as an addition to the usual automatically created order confirmation comment in comments section of the order.
EmphasizeOriginalAgreedDetails	Boolean. Not currently supported in SO integrations.

6.3 Supplier updates the order confirmation

You may easily do this by just sending a new OrderResponse with updated details. For example, if noticed that you cannot deliver goods as originally planned, just update the details in your OrderResponse and post it to Jakamo SO API.

Example: Updating an order confirmation (HTTP POST)

<OrderResponse xmlns="urn:oasis:names:specification:ubl:schema:xsd:OrderResponse-2" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:oasis:names:specification:ubl:schema:xsd:OrderResponse-2 http://docs.oasis-open.org/ubl/os-UBL-2.1/xsd/maindoc/UBL-OrderResponse-2.1.xsd urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2 http://docs.oasis-open.org/ubl/os-UBL-2.1/xsd/common/UBL-CommonAggregateComponents-2.1.xsd cac urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2 http://docs.oasis-open.org/ubl/os-UBL-2.1/xsd/common/UBL-CommonBasicComponents-2.1.xsd cbc ">
  <cbc:UBLVersionID>2.1</cbc:UBLVersionID>
  <cbc:CustomizationID>Jakamo</cbc:CustomizationID>
  <cbc:ID>123456789</cbc:ID>
  <cbc:IssueDate>2023-01-10</cbc:IssueDate>
  <cac:OrderReference>
      <cbc:ID>purchase_order_number-1234</cbc:ID>
  </cac:OrderReference>
  <cbc:Note>Additional info to order confirmation header (UI: supplier response/note)</cbc:Note>
  <cac:SellerSupplierParty>
      <cac:Party>
          <cac:PartyIdentification>
              <cbc:ID>erp_id</cbc:ID>
          </cac:PartyIdentification>
          <cac:PartyName>
              <cbc:Name>Test Supplier Ltd.</cbc:Name>
          </cac:PartyName>
      </cac:Party>
      <cac:SellerContact>
          <cbc:ID>seller_id</cbc:ID>
      </cac:SellerContact>
  </cac:SellerSupplierParty>
  <cac:BuyerCustomerParty>
      <cac:Party>
          <cac:PartyIdentification>
              <cbc:ID>customer_id</cbc:ID>
          </cac:PartyIdentification>
          <cac:PartyName>
              <cbc:Name>Customer Company AB</cbc:Name>
          </cac:PartyName>
      </cac:Party>
  </cac:BuyerCustomerParty>
  <cac:OrderLine>
      <cbc:Note>Additional info to order confirmation row</cbc:Note>
      <cac:LineItem>
          <cbc:ID>1</cbc:ID>  <!-- LineItem ID needs to match with the LineItem ID's in the order made by customer -->
          <cbc:Quantity unitCode="PCS">100.00</cbc:Quantity>
          <cac:Delivery>
              <cbc:ID>DELIVERY_ID_1</cbc:ID>
              <cbc:Quantity unitCode="PCS">100.00</cbc:Quantity>
              <cac:PromisedDeliveryPeriod>
                  <cbc:EndDate>2024-01-22</cbc:EndDate>
              </cac:PromisedDeliveryPeriod>
          </cac:Delivery>
          <cac:Price>
              <cbc:PriceAmount currencyID="EUR">120.00</cbc:PriceAmount>
          </cac:Price>
          <cac:Item>
              <cbc:Name>HEX HEAD SCREW M16x80mm</cbc:Name>
              <cac:BuyersItemIdentification>
                  <cbc:ID>PART12345</cbc:ID>
              </cac:BuyersItemIdentification>
              <cac:SellersItemIdentification>
                  <cbc:ID>PART54321</cbc:ID>
              </cac:SellersItemIdentification>
          </cac:Item>
      </cac:LineItem>
      <cac:DocumentReference>
          <cbc:ID>THIS IS A ORDER CONFIRMATION PER LINE NOTE TEXT</cbc:ID>
          <cbc:DocumentTypeCode>OSF</cbc:DocumentTypeCode>
      </cac:DocumentReference>
  </cac:OrderLine>
</OrderResponse>

6.4 Customer updates the order

The customer can change the order (typically customer may change ordered quantities, prices or delivery dates) by posting OrderChange message to Jakamo. OrderChange message can be restricted or allowed to pass to the sales order API queue by the supplier.

As a default, OrderChange messages are not passed to SO API queue. If the OrderChange message is restricted to pass to the SO API queue, the supplier will get notified from Jakamo that they have the order waiting for supplier confirmation in Jakamo, and the order confirmation process is handled manually in the Jakamo user interface.

If the OrderChange message is allowed to pass to the SO API queue, the OrderChange message can be retrieved from the Jakamo SO API with HTTP GET. Infrom Jakamo Support if you want to have OrderChange messages also to API queue.

Example: Retrieving an order update (OrderChange) from Jakamo (HTTP GET)

<OrderChange xmlns:qdt="urn:oasis:names:specification:ubl:schema:xsd:QualifiedDatatypes-2" xmlns:ccts="urn:oasis:names:specification:ubl:schema:xsd:CoreComponentParameters-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:udt="urn:un:unece:uncefact:data:draft:UnqualifiedDataTypesSchemaModule:2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:oasis:names:specification:ubl:schema:xsd:Order-2">
    <cbc:UBLVersionID>2.1</cbc:UBLVersionID>
    <cbc:CustomizationID>Jakamo</cbc:CustomizationID>
    <cbc:ID>purchase_order_number-1234</cbc:ID>
    <cbc:IssueDate>2023-12-14</cbc:IssueDate>
    <cbc:Note>Additional info</cbc:Note>
    <cbc:Note>Additional info row 2</cbc:Note>
    <cbc:Note/>
    <cbc:DocumentCurrencyCode>EUR</cbc:DocumentCurrencyCode>
    <cbc:CustomerReference>CUSTOMER_REF_1234567890</cbc:CustomerReference>
    <cac:AdditionalDocumentReference>
        <cbc:ID>Shipping mark X</cbc:ID>
        <cbc:DocumentTypeCode>SM</cbc:DocumentTypeCode>
    </cac:AdditionalDocumentReference>
    <cac:AdditionalDocumentReference>
        <cbc:ID>Delivery method X</cbc:ID>
        <cbc:DocumentTypeCode>ZZZ</cbc:DocumentTypeCode>
    </cac:AdditionalDocumentReference>
    <cac:ProjectReference>
        <cbc:ID>PROJECT_REF_1</cbc:ID>
    </cac:ProjectReference>
    <cac:BuyerCustomerParty>
        <cac:Party>
            <cac:PartyIdentification>
                <cbc:ID>customer_id</cbc:ID>
            </cac:PartyIdentification>
            <cac:PartyName>
                <cbc:Name>Customer Company AB</cbc:Name>
            </cac:PartyName>
        </cac:Party>
        <cac:BuyerContact>
            <cbc:Name>Bertha Buyer</cbc:Name>
            <cbc:ElectronicMail>bertha.buyer@company.com</cbc:ElectronicMail>
        </cac:BuyerContact>
    </cac:BuyerCustomerParty>
    <cac:SellerSupplierParty>
        <cac:Party>
            <cac:PartyIdentification>
                <cbc:ID>seller_id</cbc:ID>
            </cac:PartyIdentification>
            <cac:PartyName>
                <cbc:Name>Test Supplier Ltd.</cbc:Name>
            </cac:PartyName>
        </cac:Party>
    </cac:SellerSupplierParty>
    <cac:AccountingCustomerParty>
        <cac:Party>
            <cac:PartyIdentification>
                <cbc:ID>ACCO_1</cbc:ID>
            </cac:PartyIdentification>
            <cac:PartyName>
                <cbc:Name>Accounting Party Ltd.</cbc:Name>
            </cac:PartyName>
            <cac:PostalAddress>
                <cbc:Postbox>12345</cbc:Postbox>
                <cbc:StreetName/>
                <cbc:AdditionalStreetName/>
                <cbc:CityName>Seinäjoki, FINLAND</cbc:CityName>
                <cbc:PostalZone>60100</cbc:PostalZone>
                <cbc:CountrySubentity/>
                <cbc:CountrySubentityCode/>
                <cac:Country>
                    <cbc:IdentificationCode/>
                </cac:Country>
            </cac:PostalAddress>
        </cac:Party>
    </cac:AccountingCustomerParty>
    <cac:Delivery>
        <cac:DeliveryLocation>
            <cac:Address>
                <cbc:Floor/>
                <cbc:StreetName>Jakamokatu 2</cbc:StreetName>
                <cbc:AdditionalStreetName/>
                <cbc:BuildingName/>
                <cbc:CityName>Seinäjoki</cbc:CityName>
                <cbc:PostalZone>60100</cbc:PostalZone>
                <cbc:CountrySubentity/>
                <cbc:CountrySubentityCode/>
                <cac:Country>
                    <cbc:IdentificationCode>FI</cbc:IdentificationCode>
                    <cbc:Name>FINLAND</cbc:Name>
                </cac:Country>
            </cac:Address>
        </cac:DeliveryLocation>
        <cac:DeliveryParty>
            <cac:PartyIdentification>
                <cbc:ID>12345</cbc:ID>
            </cac:PartyIdentification>
            <cac:PartyName>
                <cbc:Name>Delivery Party Ltd.</cbc:Name>
            </cac:PartyName>
        </cac:DeliveryParty>
    </cac:Delivery>
    <cac:DeliveryTerms>
        <cbc:ID>FCA</cbc:ID>
        <cac:DeliveryLocation>
            <cbc:Description>Seinäjoki</cbc:Description>
        </cac:DeliveryLocation>
    </cac:DeliveryTerms>
    <cac:PaymentTerms>
        <cbc:ID>within 60 days Due net</cbc:ID>
        <cbc:Note>within 60 days Due net</cbc:Note>
    </cac:PaymentTerms>
    <cac:OrderLine>
        <cbc:Note>Orderline additional info 1</cbc:Note>
        <cbc:Note>Orderline additional info 2</cbc:Note>
        <cbc:Note>Orderline additional info 3</cbc:Note>
        <cbc:Note/>
        <cac:LineItem>
            <cbc:ID>1</cbc:ID>
            <cbc:Quantity unitCode="PCE">1000</cbc:Quantity>
            <cbc:LineExtensionAmount currencyID="EUR">9600</cbc:LineExtensionAmount>
            <cac:Delivery>
                <cbc:ID>DELIVERY_ID_1</cbc:ID>
                <cbc:Quantity unitCode="PCE">1000</cbc:Quantity>
                <cac:DeliveryLocation>
                    <cac:Address>
                        <cbc:Floor/>
                        <cbc:StreetName>Tamperekatu 5</cbc:StreetName>
                        <cbc:AdditionalStreetName/>
                        <cbc:BuildingName/>
                        <cbc:CityName>Tampere</cbc:CityName>
                        <cbc:PostalZone>30100</cbc:PostalZone>
                        <cbc:CountrySubentity/>
                        <cbc:CountrySubentityCode/>
                        <cac:Country>
                            <cbc:IdentificationCode>FI</cbc:IdentificationCode>
                            <cbc:Name>FINLAND</cbc:Name>
                        </cac:Country>
                    </cac:Address>
                </cac:DeliveryLocation>
                <cac:RequestedDeliveryPeriod>
                    <cbc:EndDate>2024-01-04</cbc:EndDate>
                </cac:RequestedDeliveryPeriod>
                <cac:DocumentReference>
                    <cbc:ID>PROJECT_NUMBER_1</cbc:ID>
                    <cbc:DocumentTypeCode>AEP</cbc:DocumentTypeCode>
                </cac:DocumentReference>
            </cac:Delivery>
            <cac:AllowanceCharge>
                <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
                <cbc:AllowanceChargeReasonCode>ZZZ</cbc:AllowanceChargeReasonCode>
                <cbc:MultiplierFactorNumeric>0.2</cbc:MultiplierFactorNumeric>
                <cbc:Amount currencyID="EUR">240</cbc:Amount>
                <cbc:BaseAmount currencyID="EUR">12000</cbc:BaseAmount>
            </cac:AllowanceCharge>
            <cac:Price>
                <cbc:PriceAmount currencyID="EUR">120</cbc:PriceAmount>
                <cbc:BaseQuantity unitCode="PCE">10</cbc:BaseQuantity>
                <cbc:OrderableUnitFactorRate>1</cbc:OrderableUnitFactorRate>
            </cac:Price>
            <cac:Item>
                <cbc:Description>ISO 4014 - M16x80 - 8.8 tZn</cbc:Description>
                <cbc:Name>HEX HEAD SCREW M16x80mm</cbc:Name>
                <cac:BuyersItemIdentification>
                    <cbc:ID>PART12345</cbc:ID>
                    <cbc:ExtendedID>REVISION_123</cbc:ExtendedID>
                </cac:BuyersItemIdentification>
                <cac:SellersItemIdentification>
                    <cbc:ID>PART54321</cbc:ID>
                </cac:SellersItemIdentification>
                <cac:ManufacturersItemIdentification>
                    <cbc:ID>PART_666</cbc:ID>
                </cac:ManufacturersItemIdentification>
                <cac:ItemSpecificationDocumentReference>
                    <cbc:ID>Drawing XYZ</cbc:ID>
                    <cbc:DocumentTypeCode>174</cbc:DocumentTypeCode>
                </cac:ItemSpecificationDocumentReference>
                <cac:ItemSpecificationDocumentReference>
                    <cbc:ID>work breakdown: MF-201008-01-02-01-00001</cbc:ID>
                    <cbc:DocumentTypeCode>AOL</cbc:DocumentTypeCode>
                </cac:ItemSpecificationDocumentReference>
                <cac:ItemSpecificationDocumentReference>
                    <cbc:ID>STANDARD: ISO 4014</cbc:ID>
                    <cbc:DocumentTypeCode>GA</cbc:DocumentTypeCode>
                </cac:ItemSpecificationDocumentReference>
                <cac:ItemSpecificationDocumentReference>
                    <cbc:ID>1 meter</cbc:ID>
                    <cbc:DocumentTypeCode listID="AttributeList">LENGTH</cbc:DocumentTypeCode>
                </cac:ItemSpecificationDocumentReference>
                <cac:ItemSpecificationDocumentReference>
                    <cbc:ID>1kg</cbc:ID>
                    <cbc:DocumentTypeCode listID="AttributeList">WEIGHT</cbc:DocumentTypeCode>
                </cac:ItemSpecificationDocumentReference>
                <cac:ItemSpecificationDocumentReference>
                    <cbc:ID>0.3 meters</cbc:ID>
                    <cbc:DocumentTypeCode listID="AttributeList">DIAMETER</cbc:DocumentTypeCode>
                </cac:ItemSpecificationDocumentReference>
                <cac:ClassifiedTaxCategory>
                    <cbc:Percent>24</cbc:Percent>
                    <cac:TaxScheme>
                        <cbc:ID>VAT</cbc:ID>
                    </cac:TaxScheme>
                </cac:ClassifiedTaxCategory>
                <cac:ManufacturerParty>
                    <cac:PartyName>
                        <cbc:Name>Manufacturer Ltd.</cbc:Name>
                    </cac:PartyName>
                </cac:ManufacturerParty>
            </cac:Item>
        </cac:LineItem>
        <cac:DocumentReference>
            <cbc:ID>CONTRACT_REFERENCE_1</cbc:ID>
            <cbc:DocumentTypeCode>315</cbc:DocumentTypeCode>
        </cac:DocumentReference>
    </cac:OrderLine>
</OrderChange>

6.5 Customer cancels the order

Customer can cancel the entire order or some of the order lines with OrderChange message or with StatusMessage. In Jakamo, the order or order line will achieve the status “Cancelled”.

Customer can cancel the entire order with StatusMessage “Cancelled”.

Example 1: Retrieving a cancellation update (StatusMessage "Cancelled") from Jakamo (HTTP GET)

<StatusMessage>
<OrderID>purchase_order_number-1234</OrderID>
<Status>Cancelled</Status>
<BuyerCustomerID>customer_id</BuyerCustomerID>
<SellerSupplierID>seller_id</SellerSupplierID>
</StatusMessage>

Customer can cancel order lines by setting the ordered quantity to zero, using LineStatusCode “Cancelled” on cancelled order lines, or by leaving the entire order line out from the OrderChange message. According to UBL standard, if order line is not include in the OrderChange message, this line is interpreted as cancelled.

Example 2: Retrieving a cancellation update (OrderChange including LineStatusCode "Cancelled") from Jakamo (HTTP GET)

<OrderChange xmlns:qdt="urn:oasis:names:specification:ubl:schema:xsd:QualifiedDatatypes-2" xmlns:ccts="urn:oasis:names:specification:ubl:schema:xsd:CoreComponentParameters-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:udt="urn:un:unece:uncefact:data:draft:UnqualifiedDataTypesSchemaModule:2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:oasis:names:specification:ubl:schema:xsd:Order-2">
    <cbc:UBLVersionID>2.1</cbc:UBLVersionID>
    <cbc:CustomizationID>Jakamo</cbc:CustomizationID>
    <cbc:ID>purchase_order_number-1234</cbc:ID>
    <cbc:IssueDate>2023-12-14</cbc:IssueDate>
    <cbc:Note>Additional info</cbc:Note>
    <cbc:Note>Additional info row 2</cbc:Note>
    <cbc:Note/>
    <cbc:DocumentCurrencyCode>EUR</cbc:DocumentCurrencyCode>
    <cbc:CustomerReference>CUSTOMER_REF_1234567890</cbc:CustomerReference>
    <cac:AdditionalDocumentReference>
        <cbc:ID>Shipping mark X</cbc:ID>
        <cbc:DocumentTypeCode>SM</cbc:DocumentTypeCode>
    </cac:AdditionalDocumentReference>
    <cac:AdditionalDocumentReference>
        <cbc:ID>Delivery method X</cbc:ID>
        <cbc:DocumentTypeCode>ZZZ</cbc:DocumentTypeCode>
    </cac:AdditionalDocumentReference>
    <cac:ProjectReference>
        <cbc:ID>PROJECT_REF_1</cbc:ID>
    </cac:ProjectReference>
    <cac:BuyerCustomerParty>
        <cac:Party>
            <cac:PartyIdentification>
                <cbc:ID>customer_id</cbc:ID>
            </cac:PartyIdentification>
            <cac:PartyName>
                <cbc:Name>Customer Company AB</cbc:Name>
            </cac:PartyName>
        </cac:Party>
        <cac:BuyerContact>
            <cbc:Name>Bertha Buyer</cbc:Name>
            <cbc:ElectronicMail>bertha.buyer@company.com</cbc:ElectronicMail>
        </cac:BuyerContact>
    </cac:BuyerCustomerParty>
    <cac:SellerSupplierParty>
        <cac:Party>
            <cac:PartyIdentification>
                <cbc:ID>seller_id</cbc:ID>
            </cac:PartyIdentification>
            <cac:PartyName>
                <cbc:Name>Test Supplier Ltd.</cbc:Name>
            </cac:PartyName>
        </cac:Party>
    </cac:SellerSupplierParty>
    <cac:AccountingCustomerParty>
        <cac:Party>
            <cac:PartyIdentification>
                <cbc:ID>ACCO_1</cbc:ID>
            </cac:PartyIdentification>
            <cac:PartyName>
                <cbc:Name>Accounting Party Ltd.</cbc:Name>
            </cac:PartyName>
            <cac:PostalAddress>
                <cbc:Postbox>12345</cbc:Postbox>
                <cbc:StreetName/>
                <cbc:AdditionalStreetName/>
                <cbc:CityName>Seinäjoki, FINLAND</cbc:CityName>
                <cbc:PostalZone>60100</cbc:PostalZone>
                <cbc:CountrySubentity/>
                <cbc:CountrySubentityCode/>
                <cac:Country>
                    <cbc:IdentificationCode/>
                </cac:Country>
            </cac:PostalAddress>
        </cac:Party>
    </cac:AccountingCustomerParty>
    <cac:Delivery>
        <cac:DeliveryLocation>
            <cac:Address>
                <cbc:Floor/>
                <cbc:StreetName>Jakamokatu 2</cbc:StreetName>
                <cbc:AdditionalStreetName/>
                <cbc:BuildingName/>
                <cbc:CityName>Seinäjoki</cbc:CityName>
                <cbc:PostalZone>60100</cbc:PostalZone>
                <cbc:CountrySubentity/>
                <cbc:CountrySubentityCode/>
                <cac:Country>
                    <cbc:IdentificationCode>FI</cbc:IdentificationCode>
                    <cbc:Name>FINLAND</cbc:Name>
                </cac:Country>
            </cac:Address>
        </cac:DeliveryLocation>
        <cac:DeliveryParty>
            <cac:PartyIdentification>
                <cbc:ID>12345</cbc:ID>
            </cac:PartyIdentification>
            <cac:PartyName>
                <cbc:Name>Delivery Party Ltd.</cbc:Name>
            </cac:PartyName>
        </cac:DeliveryParty>
    </cac:Delivery>
    <cac:DeliveryTerms>
        <cbc:ID>FCA</cbc:ID>
        <cac:DeliveryLocation>
            <cbc:Description>Seinäjoki</cbc:Description>
        </cac:DeliveryLocation>
    </cac:DeliveryTerms>
    <cac:PaymentTerms>
        <cbc:ID>within 60 days Due net</cbc:ID>
        <cbc:Note>within 60 days Due net</cbc:Note>
    </cac:PaymentTerms>
    <cac:OrderLine>
        <cbc:Note>Orderline additional info 1</cbc:Note>
        <cbc:Note>Orderline additional info 2</cbc:Note>
        <cbc:Note>Orderline additional info 3</cbc:Note>
        <cbc:Note/>
        <cac:LineItem>
            <cbc:ID>1</cbc:ID>
            <cbc:LineStatusCode>Cancelled</cbc:LineStatusCode>
            <cbc:Quantity unitCode="PCE">1000</cbc:Quantity>
            <cbc:LineExtensionAmount currencyID="EUR">9600</cbc:LineExtensionAmount>
            <cac:Delivery>
                <cbc:ID>DELIVERY_ID_1</cbc:ID>
                <cbc:Quantity unitCode="PCE">1000</cbc:Quantity>
                <cac:DeliveryLocation>
                    <cac:Address>
                        <cbc:Floor/>
                        <cbc:StreetName>Tamperekatu 5</cbc:StreetName>
                        <cbc:AdditionalStreetName/>
                        <cbc:BuildingName/>
                        <cbc:CityName>Tampere</cbc:CityName>
                        <cbc:PostalZone>30100</cbc:PostalZone>
                        <cbc:CountrySubentity/>
                        <cbc:CountrySubentityCode/>
                        <cac:Country>
                            <cbc:IdentificationCode>FI</cbc:IdentificationCode>
                            <cbc:Name>FINLAND</cbc:Name>
                        </cac:Country>
                    </cac:Address>
                </cac:DeliveryLocation>
                <cac:RequestedDeliveryPeriod>
                    <cbc:EndDate>2024-01-04</cbc:EndDate>
                </cac:RequestedDeliveryPeriod>
                <cac:DocumentReference>
                    <cbc:ID>PROJECT_NUMBER_1</cbc:ID>
                    <cbc:DocumentTypeCode>AEP</cbc:DocumentTypeCode>
                </cac:DocumentReference>
            </cac:Delivery>
            <cac:AllowanceCharge>
                <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
                <cbc:AllowanceChargeReasonCode>ZZZ</cbc:AllowanceChargeReasonCode>
                <cbc:MultiplierFactorNumeric>0.2</cbc:MultiplierFactorNumeric>
                <cbc:Amount currencyID="EUR">240</cbc:Amount>
                <cbc:BaseAmount currencyID="EUR">12000</cbc:BaseAmount>
            </cac:AllowanceCharge>
            <cac:Price>
                <cbc:PriceAmount currencyID="EUR">120</cbc:PriceAmount>
                <cbc:BaseQuantity unitCode="PCE">10</cbc:BaseQuantity>
                <cbc:OrderableUnitFactorRate>1</cbc:OrderableUnitFactorRate>
            </cac:Price>
            <cac:Item>
                <cbc:Description>ISO 4014 - M16x80 - 8.8 tZn</cbc:Description>
                <cbc:Name>HEX HEAD SCREW M16x80mm</cbc:Name>
                <cac:BuyersItemIdentification>
                    <cbc:ID>PART12345</cbc:ID>
                    <cbc:ExtendedID>REVISION_123</cbc:ExtendedID>
                </cac:BuyersItemIdentification>
                <cac:SellersItemIdentification>
                    <cbc:ID>PART54321</cbc:ID>
                </cac:SellersItemIdentification>
                <cac:ManufacturersItemIdentification>
                    <cbc:ID>PART_666</cbc:ID>
                </cac:ManufacturersItemIdentification>
                <cac:ItemSpecificationDocumentReference>
                    <cbc:ID>Drawing XYZ</cbc:ID>
                    <cbc:DocumentTypeCode>174</cbc:DocumentTypeCode>
                </cac:ItemSpecificationDocumentReference>
                <cac:ItemSpecificationDocumentReference>
                    <cbc:ID>work breakdown: MF-201008-01-02-01-00001</cbc:ID>
                    <cbc:DocumentTypeCode>AOL</cbc:DocumentTypeCode>
                </cac:ItemSpecificationDocumentReference>
                <cac:ItemSpecificationDocumentReference>
                    <cbc:ID>STANDARD: ISO 4014</cbc:ID>
                    <cbc:DocumentTypeCode>GA</cbc:DocumentTypeCode>
                </cac:ItemSpecificationDocumentReference>
                <cac:ItemSpecificationDocumentReference>
                    <cbc:ID>1 meter</cbc:ID>
                    <cbc:DocumentTypeCode listID="AttributeList">LENGTH</cbc:DocumentTypeCode>
                </cac:ItemSpecificationDocumentReference>
                <cac:ItemSpecificationDocumentReference>
                    <cbc:ID>1kg</cbc:ID>
                    <cbc:DocumentTypeCode listID="AttributeList">WEIGHT</cbc:DocumentTypeCode>
                </cac:ItemSpecificationDocumentReference>
                <cac:ItemSpecificationDocumentReference>
                    <cbc:ID>0.3 meters</cbc:ID>
                    <cbc:DocumentTypeCode listID="AttributeList">DIAMETER</cbc:DocumentTypeCode>
                </cac:ItemSpecificationDocumentReference>
                <cac:ClassifiedTaxCategory>
                    <cbc:Percent>24</cbc:Percent>
                    <cac:TaxScheme>
                        <cbc:ID>VAT</cbc:ID>
                    </cac:TaxScheme>
                </cac:ClassifiedTaxCategory>
                <cac:ManufacturerParty>
                    <cac:PartyName>
                        <cbc:Name>Manufacturer Ltd.</cbc:Name>
                    </cac:PartyName>
                </cac:ManufacturerParty>
            </cac:Item>
        </cac:LineItem>
        <cac:DocumentReference>
            <cbc:ID>CONTRACT_REFERENCE_1</cbc:ID>
            <cbc:DocumentTypeCode>315</cbc:DocumentTypeCode>
        </cac:DocumentReference>
    </cac:OrderLine>
</OrderChange>

6.6 Supplier sending "Delivered" information

Supplier can infom when order or order line is delivered by sending "Delivered" StatusMessage to Jakamo. This will update order or order line status in Jakamo as "Delivered"

Example: Sending "Delivered" status information to Jakamo (HTTP PUT)

<StatusMessage>
  <OrderID>purchase_order_number-1234</OrderID>
  <Status>Delivered</Status>
  <TrackingNumber>90901010</TrackingNumber>
  <OrderLine>
      <OrderLineID>1</OrderLineID>
      <Delivery>
          <DeliveryID>DELIVERY_ID_1</DeliveryID>
          <RealDeliveryDate>2024-02-01</RealDeliveryDate>
      </Delivery>
  </OrderLine>
</StatusMessage>

6.7 Empty queue

If the SO API queue is empty, the Jakamo SO API will return a status 200 OK and body message No more messages available if there are no new orders, order changes or status messages available.

7. UBL schemas and message mapping

OrderResponse message implementation package include OrderResponse message mapping form and cardinality, UBL subset documentation for OrderResponse, OrderResponse message schemas and XML examples.

Order message implementation package is available for you for example to view the Order message content. This package include Order message mapping form and cardinality, UBL subset documentation for Order, Order message schemas and more XML examples.

8. User and company mapping in the Jakamo integration settings

Mapping configurations to identify buyer and supplier in the Jakamo are made in the Jakamo user interface on the Integrations page. Integrations settings are available for you after the integration is activated for you in the Jakamo test environment and Jakamo production environment by Jakamo. See Jakamo's general integration mappings instructions from User Guide.

8.1 User mapping - Map your ERP users to your Jakamo users

ERP users who make order confirmations must have personal accounts in Jakamo. Person has to have some identifier (string) in the ERP, and it will be transferred in the OrderResponse XML data (OrderResponse/SellerSupplierParty/SellerContact/ID). This ERP identifier must be linked to the Jakamo user so that Jakamo can identify the message sender. The SO integration requires passing this user information in the XML data when making order confirmation. ERP identifier for a user can be for example an email address, a series of numbers, or a combination of numbers and letters, like the seller ID in the ERP.

Create required user mappings on the Integrations page. From that page can be found all the integrations in use. Under the User Strings, click ADD USER and create user mappings between Jakamo users and users in the ERP system. To be able to add a mapping, the user has to have a personal user account in Jakamo.

• User identifier refers to the identifier string coming in OrderResponse/SellerSupplierParty/SellerContact/ID. Jakamo account refers to the users account in Jakamo.
• Jakamo account dropdown includes the users who has their user accounts established in Jakamo.

DefaultUser can be left unselected. DefaultUser tick box can be selected if retrieved Order wanted to be confirmed without checking or changing any values by posting only confirmation with Order’s Jakamo-Confirm-Url. The confirmation information is then used by DefaultUser.

8.2 Customer mapping - Map your ERP customers to Jakamo companies

A relationship with the customer company in Jakamo has to be established before any messages can be received or sent via Jakamo. Customer has to have some identifier (string) in the ERP, and it will be transferred in the OrderResponse XML data (OrderResponse/BuyerCustomerParty/PartyIdentification/ID). This ERP identifier must be linked to the Jakamo company so that Jakamo can identify the message party.

Create company mappings on the Integrations page. From that page can be found all the integrations in use. Under the Company Strings, click ADD COMPANY and create a mapping between your ERP company (a customer) and the Jakamo relationship. To be able to add a mapping, the relationship with that company has to exist in Jakamo.

• Company identifier refers to the identifier string coming in OrderResponse/BuyerCustomerParty/Party/PartyIdentification/ID. Jakamo company refers to the customer account that wants to be mapped to this customer identifier.
• Jakamo company dropdown menu include a list of customer companies your account have relation established in Jakamo.

If you want to create special routing rules, fill in the external information fields when creating a new company mapping. External information fields are following:

• External identifier: Fill in the identifier your customer sends to you via their Order. Define whether it is the external identifier customer's buyer customer party identifier or seller supplier party identifier.

• External mapping field:

  • Buyer customer party: If external identifier is customer's buyer customer party identifier, select this.
  • Seller supplier party: If external identifier is customer's seller supplier party identifier, select this.

• Compound rule member: If you want to create compound rule by using both buyer customer party identifier and seller supplier party identifier at the same time, select this and create the other half of the compound pair as an own mapping. If mapping is part of the compound mapping, it means that for the compound rule to be fulfilled, the second mapping condition must also be fulfilled.

See detailed instructions for external mappings in sales order integration and example from the User Guide.

Help & Support

Didn't you find what you were looking for? Send an email to Jakamo support (support@thejakamo.com) and we will help you.