Overview

Jakamo Purchase Order API (PO API) is an XML-based REST API over HTTPS. The PO API is for sending purchase orders to Jakamo and receiving suppliers’ order confirmations back to the ERP via Jakamo. PO API can be used to send purchase orders to multiple supplier companies in Jakamo via one integration.

There are two similar Jakamo environments available:

• Test environment is for testing purposes (technical testing and user testing).
• Production environment is for the live use with other Jakamo companies (suppliers).

Requirements how to get started

Request demo accounts from Jakamo if you are interested in to create purchase order integration towards Jakamo. Contact our sales team via email  sales@thejakamo.com or our support team via support@thejakamo.com. The company can do its Jakamo production account registration independently on the Jakamo registration page.

There are few technical capabilities needed to be able to connect to Jakamo APIs:

• Basic knowledge of ERP programming and REST APIs
• Ability to authenticate using basic authentication method
• Ability to create an UBL XML mapping for purchase order data
• Ability to extract order from the ERP and create an Order message (UBL XML)
• Ability to GET order confirmation data (UBL XML OrderReponse) from the Jakamo PO API
• Ability to POST OrderChange (UBL XML) to the Jakamo PO API
• Ability to POST StatusMessage (Received) to the Jakamo PO API
• Ability to handle Jakamo message queue (PO API queue handling, incoming message handling)
• Ability to handle error situations – basically reading PO API responses and acting accodingly

Authorization

Jakamo PO API uses basic authentication as an authentication method. The username and password for the PO API are set inside your Jakamo company account in the “Integrations” settings with the PO integration’s “Change credentials” functionality. If you have multiple integrations enabled in your Jakamo account, please use different credentials for each integration.

Jakamo PO API endpoints

Example requests

Download PO example package

Order-to-delivery process in Jakamo

Purchase order sending and order confirmation handling process via purchase order integration and Jakamo user interface.

1. Creating a new order

A new order created in the ERP system can be sent to Jakamo by posting the new Order message to Jakamo PO API with an HTTP POST request.

In Jakamo, new order is immediately shared with supplier and the order will have the status “Waiting for supplier confirmation”.

2. Revising the order

The order which already exist in Jakamo can be modified by posting the OrderChange message, which is referring to that existing order, to Jakamo PO API with an HTTP POST request. If order is already received or cancelled in Jakamo, you can not reopen the order in Jakamo by sending OrderChange message to it.

In Jakamo, if the supplier has confirmed the order you are revising, the revised order will then have the status “Waiting for supplier confirmation” if any of the following values differs from the supplier’s order confirmation:

• Ordered quantity (OrderChange/OrderLine/LineItem/Quantity)
• Price (OrderChange/OrderLine/LineItem/Price/PriceAmount)
• Requested delivery date (OrderChange/OrderLine/LineItem/Delivery/RequestedDeliveryPeriod/EndDate)
• Seller’s item identifier (OrderChange/OrderLine/LineItem/Item/SellersItemIdentification/ID)
  • Only if customer have this identifier check and comparison activated in their integration setting (activated by Jakamo)

3. Order confirmation

Order can be confirmed as requested by the supplier or supplier can propose changes. Changes means differences in ordered and confirmed quantities, ordered and confirmed prices, and requested and confirmed delivery time. Also, if additional comparison setting is on, also Identifier (SellersItemIdentification) can be difference.

Order confirmed partially

The supplier can confirm order partially. This means that they can leave order line or lines out of their confirmation. This is a basic functionality in Jakamo and it can be done in the order confirmation form in the UI and via SO integration if supplier has it enabled towards Jakamo. If supplier leaves line or lines unconfirmed, these lines will return in the OrderResponse message with an empty quantity, price and delivery date values and with LineStatusCode “Open”.

Order can be confirmed partially also by marking order confirmation lines as a Draft. This allows supplier to confirm order line or lines as a draft. It means that the confirmation is done with preliminary values and will be confirmed later on with more exact values. Confirming line or lines as a Draft will return LineStatusCode “Draft” for that order line in the OrderResponse. This is a separate PO integration setting which is set off as a default.

Order confirmed as requested

Supplier can confirm the order as requested in the purchase order. In Jakamo, order will have the status “Confirmed” after all the ordered and confirmed values matches. This means ordered and confirmed quantity, price in the order and confirmed price, and requested and confirmed delivery date. If additional Identifier comparison setting is on, also buyer’s SellersItemIdentication and supplier’s SellersItemIdentification should match.

Order confirmed with changes

Supplier can confirm the order with changes compared to the requested in the purchase order. If confirmed values differs from the ordered values, order is “Waiting for customer action” in Jakamo. Customer need to approve or reject the proposed changes.

4. Retrieving order confirmation

Supplier can confirm the order in Jakamo user interface or via sales order integration (if they have integration towards Jakamo in use). Jakamo will generate the OrderResponse message to the PO API queue, which means that from the customer’s point of view, it is technically irrelevant how the confirmation was made by the supplier.

New OrderResponse message can be retrieved from the Jakamo PO API queue with an HTTP GET request. PO API incoming message queue will return the oldest message from the queue, see more information about the PO API queue handling from the chapter “Handling incoming message queue”.

a) Only pass confirmed orders to the response queue from Jakamo

Integration setting that will block OrderResponses until all the lines are confirmed as requested in Jakamo. This can be useful if comparing requested and confirmed values cannot be done inside ERP / Connector.

b) Utilize LineStatusCodes on OrderResponse message

All the OrderResponses can be generated immediatelty to the response queue. The handling process for each order line can be configured based on the LineStatusCode of the order line. For example, you may read in only “Confirmed” order lines to your system.

• Open = Order line is not confirmed yet
• Draft = Order line is confirmed as “Draft”
• Confirmed = Order line is confirmed as requested
• Confirmed with Changes = Order line is confirmed with changes compared to requested
• Started receiving = One ore more delivery batches for the order line has received
• Received = Order line is already received by you
• Cancelled = Order line is cancelled by you or by supplier

5. Accepting or rejecting the order confirmation

If supplier’s confirmation deviates from customer’s order, order confirmation must be approve or reject by customer. The deviations on the order confirmation can be managed and approved or rejected in Jakamo user interface, or in the external system (e.g. ERP) and indicate the desicion (approval or rejection) with an OrderChange message or by using simple confirmation. You can select the more suitable way for you.

Approving or rejecting order confirmation in Jakamo UI

Holding back the entire order until all the lines are “Confirmed”

It is possible to have additional OrderResponse message generated to PO API queue from the customer’s approval in Jakamo UI. This is an additional integration setting.

Approving or rejecting order confirmation in the external system

All the OrderResponses can be retrieved from the PO API queue and handle in the external system, typically in the ERP. If the values in OrderResponse can be approved, confirmation can be approved by sending OrderChange message with approved values in the message. This will update order status in Jakamo as “Confirmed”. If only some of the lines are approved, OrderChange message may contain confirmed values only for those approved lines and ordered values on the “rejected” lines. This will change the order status “Waiting for supplier confirmation” in Jakamo and supplier need to do re-confirmation.

Simple confirmation (accepting the supplier’s proposed changes)

Customer can also use the simply confirmation to be able to approve the changes on the supplier’s order confirmation. OrderResponse contains Jakamo-Confirm-Url in the OrderResponse message headers. Changes can be approved by customer 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 values to match supplier’s confirmed values.

6. Cancellation of the order or order line

Customer can cancel the entire order, or one or several order lines.

Cancelling the entire order

Customer can cancel the enitre order. Techncially there are two different ways how to do the cancellation:

a) By sending StatusMessage “Cancelled” to the order by sending the message to the Jakamo PO API with an HTTP PUT request.
b) By inlcuding LineStatusCode “Cancelled” to each order line that order contains in the OrderChange message.

After order is cancelled in Jakamo, the Jakamo status for the order is “Cancelled”.

Cancelling the order line

The customer can cancel order lines from the order. Technically there are three different ways how to do the cancellation:

a) Order line quantity can be set to 0 (zero) via OrderChange message. If order line quantity and delivery quantity are both 0, an order line will be cancelled in Jakamo.
b) Order line can include LineStatusCode “Cancelled” in the OrderChange message. If order line include LineStatusCode “Cancelled”, that order line will be cancelled in Jakamo.

The enitre order line element can be leave 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

7. Order rejected by the supplier

Supplier can reject the entire order from the Jakamo UI. There is a functionality “Reject” available in Jakamo order item before supplier has done their confirmation. The rejecting will generate an OrderResponse message to the PO API queue with a LineStatusCode “Cancelled” for each order line in the order. The Jakamo status for the order rejected by the supplier is “Rejected by the supplier”.

If supplier has confirmed the order in Jakamo, order cannot be rejected by the supplier from the UI by using “Reject” functionality. If supplier has to cancel the entire order after order is already confirmed, supplier can confirm the order again (by editing the order confirmation) and setting all order line quantities as 0. This confirmation will propose the cancellation for each order line. This proposal need to be accept or reject by the customer. If customer accept the quantity change, the entire order will be cancelled.

8. Sending “Received” information

Customer can mark the purchase order or purchase order lines as received in Jakamo. The “Received” status can be set to the order line or delivery batch in Jakamo by putting StatusMessage in to the Jakamo PO API. If the StatusMessage is sent to the order line, it will mark the PO line in Jakamo as “Received”. If the StatusMessage is used to mark one or more delivery batches as received, the delivery batch will be marked as “Received” and the order line will achieve status “Started receiving” in Jakamo. If all order line’s delivery batches are received, order line status will set as “Received”. If all the order lines are received, the entire order will achieve “Received” status.

Handling incoming message queue

All incoming messages come through the same endpoint and they can be fetched from the API queue by HTTP GET to the certain endpoint (https://demo.thejakamo.com/api/order/response in Jakamo test environment or https://www.thejakamo.com/api/order/response in Jakamo production environment).

The PO 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 OrderResponse (UBL) and StatusMessage 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. PO API will return HTTP response code 200 OK and body message <Info>Message cleared from the queue</Info> if your request was correct.

Request response messages

Jakamo Sales Order API will return HTTP response status code and in some cases additional information in the response body. A successfully posted message will return 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 Request or 500 Internal Server Error.

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

UBL schemas and message mapping

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

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

User and company mappings in the Jakamo integration settings

Mapping configurations to identify buyer and supplier in 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.

User mapping – Map your ERP users to your Jakamo users

ERP users (buyers, purchasers, supplier responsibles) who will create purchase orders via Jakamo must have their personal user accounts in Jakamo. User has to have some identifier (string, email address, username, buyer number…) in the ERP, and that identifier will be transferred in the XML data (Order/BuyerCustomerParty/BuyerContact/ID). This ERP identifier must be linked to the Jakamo user so that Jakamo can identify the message sender. The PO integration requires passing this user information in the Order message when making new order or order change.

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 that you send in Order/BuyerCustomerParty/BuyerContact/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. It is not used in purchase order integration.

Vendor mapping – Map your ERP suppliers to Jakamo companies

A relationship with the supplier company in Jakamo has to be established before any messages can be received or sent via Jakamo. A supplier has to have some identifier (string, for example vendor number) in the ERP, and it will be transferred in the XML data (Order/SellerSupplierParty/Party/PartyIdentification/ID). This ERP identifier must be linked to the Jakamo company so that Jakamo can identify the receiving 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 supplier) 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 incoming in Order/SellerSupplierParty/Party/PartyIdentification/ID. Jakamo company refers to the supplier account that needs to be mapped to this supplier identifier. Jakamo company dropdown menu include a list of supplier companies your account have relation established in Jakamo.

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 Jakamo company registration page. Please ensure that there is only one production account existing for your company in Jakamo (avoid to create a douple account).

2. Purchase order integration activation

Purchase order integration activation for the Jakamo production account. Ask Jakamo support (support@thejakamo.com) to activate the PO 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 for company admins.

3. Integration credentials creation

Create integration credentials (PO integration authentication credentials) in the Jakamo production account on the “Integrations” page under Integration Credentials. Determine cryptic username and password. Please ensure using different usernames and passwords in each enabled integration in use (see chapter Authorization).

4. User and company mappings configuration in Jakamo

Define user and company mappings on the Jakamo “Integrations” page (see chapter User and company mappings in the Jakamo integration settings).

5. Message endpoint configuration

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

6. Everything is ready! You can now send orders to your suppliers and you are able to receive order confirmations from your suppliers through Jakamo.