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.

There are two Jakamo environments available

• Test environment
• Production environment

Requirements how to get started

Request demo accounts from Jakamo to create sales order integration to your ERP system. Contact via email at sales@thejakamo.com or support@thejakamo.com. The company can do its production account registration independently on the Jakamo company registration page.

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 order (as a sales order) 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)

Authorization

The API uses basic authentication as an authentication method. 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 in your Jakamo account, please use different credentials for each integration.

Process

Basic sales order intake and order confirmation process in Jakamo

1. Retrieving the 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.

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 the original quantities, prices and delivery dates.

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 details and supplier’s confirmed order details match. 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 customer reject the order confirmation, the order will need to reconfirm. In this case, order status in Jakamo is ”Waiting for supplier confirmation”.

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

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. If the OrderChange message is restricted to pass to the SO API queue, the supplier will get notified that they have the order waiting for supplier confirmation in Jakamo, and the order confirmation process is handled manually in the Jakamo user interface.

4. Customer cancel the order. Customer can cancel the entire order or some of the order lines with OrderChange message or with StatusMessage. Cancelling can be done by setting the ordered quantity to zero or using LineStatusCode “Cancelled”. In Jakamo, the order or order line will achieve the status “Cancelled”. Customer can cancel the entire order with StatusMessage “Cancelled”.

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

Incoming message queue handling

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

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.

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.

  Example requests

• Postman APP Collection: demo requests and data
• XML example files for Order, OrderResponse and StatusMessage

Jakamo implementation Package (.zip)

Mapping and schema

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.

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.

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

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

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 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. Sales order integration activation

Sales order integration activation for the Jakamo production account. Ask Jakamo support (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 for company admins.

3. Integration credentials creation

Create integration credentials (SO 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.

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 as follow

6. Everything is ready! You can receive orders and order changes from your customer and send order confirmations and “Delivered” status messages.