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://www.thejakamo.com/api/order/response
Production environment	POST	https://www.thejakamo.com/api/orderresponse
Production environment	PUT	https://www.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	Incorrect order response (line_item_missing_item)	Mandatory OrderResponse/OrderLine/LineItem/Item element is missing from the OrderResponse.
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.
400 Bad Request	LineItem\LineStatusCode is invalid.	Only use LineStatusCode value Draft when appropriate, or leave LineStatusCode out of the OrderResponse message.
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.

Beware with the mappings!

To be able to retrieve orders from Jakamo order queue, you need to have Jakamo integration mappings ready so that Jakamo knows which customer will send the orders to you. Define COMPANY AND USER mappings in the Jakamo Integration page before proceeding to fetch from the messages from the queue.

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.

Beware with the mappings!

To be able to send orders from Jakamo order queue, you need to have Jakamo integration mappings ready so that Jakamo knows which customer will receive the orders. Define COMPANY AND USER mappings in the Jakamo Integration page before proceeding to fetch from the messages from the queue.

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> <!-- JAKAMO COMPANY MAPPING https://support.thejakamo.com/docs/user-guide/company-settings/integrations#31-add-new-partner-company --> 
          </cac:PartyIdentification>
          <cac:PartyName>
              <cbc:Name>Test Supplier Ltd.</cbc:Name>
          </cac:PartyName>
      </cac:Party>
      <cac:SellerContact>
          <cbc:ID>seller_id</cbc:ID> <!-- JAKAMO USER MAPPING -->
      </cac:SellerContact>
  </cac:SellerSupplierParty>
  <cac:BuyerCustomerParty>
      <cac:Party>
          <cac:PartyIdentification>
              <cbc:ID>customer_id</cbc:ID> <!-- JAKAMO COMPANY MAPPING -->
          </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. 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.

7.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.

7.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 below.

7.3 Mappings in sales order integration (external identifiers)

info

The following instructions are for companies using SO integration and Jakamo to receive orders from customer companies and send order confirmations to customers via Jakamo. Company mapping in sales order integration is following the rules of basic company mapping.

Special functionality for sales order (SO) integration mapping is the ability to create routing rules based on both, your identifiers and identifiers customers send to you with their Order message. This might be necessary if you have multiple customer numbers in your system to refer one customer in Jakamo, or if there is a need to separate customer orders based on e.g. the delivery location, sites, or other information in the order.

If you want to create special routing rules, fill in the external information fields when creating a new company mapping. Otherwise, leave External identifier empty. External information fields are the 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 the external identifier is the customer's buyer customer party identifier, select this.
- Seller supplier party: If the external identifier is the customer's seller supplier party identifier, select this.
Compound rule member: If you want to create a compound rule by using both the 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 its 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.

How do I define the necessary identifiers?

You may need to contact and discuss with your customer to find out which identifiers they are using, for example for delivery locations. Jakamo's support team can also help by defining identifiers. Contact Jakamo support (support@thejakamo.com) and we will help you.

Example: Sales order company mapping with external identifiers

This is an example of SO integration mappings with external identifiers in use.

You want to have customer number 33333 on the order message you will retrieve to your internal system when your customer's order includes

buyer customer party identifier FI82828 and
seller supplier party identifier 7382729.

Create two separate mappings for that Company identifier 33333. Select Compound rule member selection for both two mappings. After that, compound rule mappings are shown as a pair in the company mapping list and both of the mappings need to be fulfilled to have identifier 33333 on the retrieved order. See the example below for the step-by-step instructions:

Define in first mapping the external buyer customer party identifier and company identifier you want to have used.

Define in the second mapping the external seller supplier party identifier and company identifier you want to have use with.

After creating two separate mappings, compound rule is on. On the Company strings these compound rule mappings are having COMPOUND tag. Both of the compound rules must be fulfilled before order include identifier 33333 on the Order in sales order integration.

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.

1. Overview​

1.1 Requirements how to get started​

1.2 Steps to go to production​

1. Production account establishment in Jakamo.​

2. Sales order integration activation.​

3. API authentication method.​

4. User and company mappings configuration in Jakamo.​

5. Message endpoint configuration.​

6. Everything is ready!​

2. Authorization​

3. SO API endpoints​

4. SO API request response messages​

5. Handling incoming message queue​

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

6.1 Retrieving a new order​

6.2 Confirm the order​

6.2.1 Simple confirmation​

6.3 Supplier updates the order confirmation​

6.4 Customer updates the order​

6.5 Customer cancels the order​

6.6 Supplier sending "Delivered" information​

6.7 Empty queue​

7. User and company mapping in the Jakamo integration settings​

7.1 User mapping - Map your ERP users to your Jakamo users​

7.2 Customer mapping - Map your ERP customers to Jakamo companies​

7.3 Mappings in sales order integration (external identifiers)​

Example: Sales order company mapping with external identifiers​