Overview

Advanced shipping notice (ASN) provides detailed information about delivery to the customer via Jakamo. The purpose of an ASN is for a supplier to notify the customer when shipping is delivered and what the shipment include, so the customer can prepare for that delivery.

ASN API is intended to be used for receiving information in advance about incoming shipments. ASN API is a JSON-based API over HTTPS and REST. This API is meant for customer companies in the Jakamo network for receiving ASN notifications from multiple suppliers.

In the Jakamo user interface, ASN functionality is available in the Orders application Shipments tab. The Shipments tab is available after ASN integration is activated to the customer account and ASN parties are mapped in the Integrations tab. The Shipments tab is available to the suppliers that are mapped in the customer’s ASN integration.

Requirements how to get started

Request demo accounts from Jakamo to create an ASN integration from your system. Contact via email at sales@thejakamo.com or support@thejakamo.com. Use of ASN require also purchase order integration implemented towards Jakamo by the customer company.

There are two Jakamo environments available

• Test environment
• Production environment

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.

ASN process in Jakamo

The ASN process starts when supplier create and build a new shipment in Jakamo.

Step 1 Supplier insert shipment number and select the customer company. User can add dispatch contact and location information.

Step 2 Supplier search order or orders from Jakamo which will be delivered with the shipment. User can select the purchase orders and PO lines which they want to add to the shipment. One shipment can contain order lines from different purchase orders.

Step 3 Supplier build the shipment structure. User can assing selected order lines to the physical shipment units. Shipment units (e.g. box, parcel, pallet) can be determined by customer, or shipment creator can create their own units. One shipment can contain multiple shipment units. Each shipment unit can have an unique identifier number (shippingUnitNumber).

Step 4 Before dispatch, user can review the shipment content and save the shipment. Saved shipment will be appear in the List view of Shipment tab as an open shipment. Open shipment is visible to the customer company in the List view Received tab. User can save the shipment also as a draft and continue building later. If ASN is saved as a draft, it is not shared to the customer.

Step 5 Supplier has to mark shipment as dispathed in Jakamo to inform that shipment is now delivered. Dispatch can be done immediately after saving the shipment, or at any point from the ASN list view. Dispatching the ASN in Jakamo generates the ASN message to customer’s ASN API queue and it is immediately retrievable.

Incoming message queue handling

All incoming ASN messages will come to the same endpoint and can be fetched from the queue by HTTP GET to the certain endpoint

• https://demo.thejakamo.com/api/asn/queue (Jakamo test environment)
• https://www.thejakamo.com/api/asn/queue (Jakamo production environment)

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

Clearing the queue: After processing the incoming message (for example, validate, save it on the disk, parse, or import), 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.

API request response messages

Jakamo ASN API will always 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, it will return response code 400 Bad Request or 500 Internal Server Error.

The table below presents the most common API request responses from Jakamo ASN API.

Example requests

Example of ASN message retrieved from Jakamo API: ASN message example

ASN API endpoints

Company mapping in the Jakamo integration settings

ASN message parties need to be mapped to correct Jakamo company accounts in Jakamo. Information in the ASN message (in ASN/buyer/companyID and in ASN/supplier/companyID), e.g. vendor number on your system needs to connect to supplier’s Jakamo account. Mapping configurations to identify customer and supplier company are managed in the Jakamo “Integrations” settings page. From that page can be found all the integrations company has in use. ASN integration settings are available for you after the integration is activated for you in the Jakamo test environment and Jakamo production environment by Jakamo.

Create new company mappings on the “Integrations” page. Select the ASN integration and create company mapping under the Company Strings header. Click Add Company button and fill in the necessary information.

• Company identifier refers to the identifier string coming with the ASN message (identifier for you company or identifier for supplier, e.g. vendor number).
• Jakamo company refers to the Jakamo company account, either your own account or supplier’s Jakamo account. Select from the dropdown menu the correct party you are creating the mapping. Jakamo company dropdown menu include your company account and all the supplier companies your account have relation established in Jakamo.

Save the mapping by hitting OK.

Map your company to your Jakamo company account

To be able to have information in the ASN message about your company (ASN/buyer/companyID), mapping for your own company should be done. Create a mapping between your company identifier and your Jakamo account.

• Company identifier: Fill in the identifier for your own company you want to receive via ASN message.
• Jakamo company: Select your own Jakamo company account from the dropdown menu.

Map your ERP supplier to supplier’s Jakamo company account

A relationship with the supplier company in Jakamo has to be established before any ASN messages can be created or received via Jakamo. The supplier has to have some identifier (string) in the ERP, which will be transferred in the ASN JSON data (ASN/supplier/companyID). This ERP identifier must be linked to the Jakamo company so that Jakamo can identify the message party.

Create a mapping between your supplier identifier and the Jakamo relationship. To be able to add a mapping, the relationship with that company has to exist in Jakamo.

• Company identifier: Fill in the identifier for your supplier (e.g. vendor number) to be able to identify the supplier in your system.
• Jakamo company: Select your supplier’s Jakamo company account from the dropdown menu.

Steps to go to production

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

1. ASN integration activation

ASN integration activation for the Jakamo production account. Ask Jakamo support (support@thejakamo.com) to activate the ASN integration for you in the production environment. After the integration is available in the Jakamo production account, the “Integrations” page appears in the upper-left extra menu in the Jakamo user interface for company admins.

2. Integration credentials creation

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

3. Company mappings configuration in Jakamo

Define company mappings on the Jakamo “Integrations” page.

4. Message endpoint configuration

Change messages’ endpoint configurations from test environment to production environment.

5. Everything is ready! You can receive ASN messages from your partners via Jakamo.