Advance Shipping Notice API
1. Overview
Advance 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 includes, so the customer can prepare for that delivery.
Jakamo 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 to receive 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.
See user instructions for the ASN functionality from the ASN User Guide page.
1.1 Requirements how to get started
Request demo accounts from Jakamo Support Team (support@thejakamo.com) to create an ASN integration from your system. The use of ASN requires also purchase order integration implemented towards Jakamo by the customer company.
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.
1.2 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
The first step is to ask for ASN integration activation for the Jakamo production account. Ask Jakamo Support Team (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 hidden menu in the Jakamo user interface. The integrations setting page is available for company admin users.
2. Integration credentials creation
Create integration credentials in the Jakamo production account on the Integrations settings page under Integration Credentials. Determine a 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 the test environment to the production environment. Check ASN API endpoints here.
5. Everything is ready!
You can now receive ASN messages from your partners via Jakamo.
2. Authorization
Jakamo ASN 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. ASN API endpoints
| Jakamo environment | HTTP request | Jakamo API endpoint |
|---|---|---|
| Test environment | GET | https://demo.thejakamo.com/api/asn/queue |
| Production environment | GET | https://www.thejakamo.com/api/asn/queue |
4. ASN API request response messages
Jakamo ASN API will always 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, 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.
| HTTP response status code | Response body | Additional information |
|---|---|---|
| 200 OK | ASN message | ASN message successfully retrieved from the ASN API. |
| 200 OK | Incoming message queue is empty, no more new messages in the queue. | |
| 200 OK | Request to remove the message from the API queue have been successfully completed. | |
| 404 Not Found | Check the endpoint address. | |
| 400 Bad Request | Check the authentication method and integration credentials. |
5. Handling incoming message queue
See the general Jakamo API queue handling instructions from incoming message queue handling page.
All incoming ASN messages will come to the same endpoint and can be fetched from the queue by HTTP GET to the certain endpoint. 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.
6. ASN process in Jakamo
The ASN process starts when the supplier is about to deliver a shipment and starts to create and build a new shipment in Jakamo. The supplier will build the shipment in Jakamo by adding delivered items to the shipping units. The supplier will mark the shipment as dispatched and Jakamo will then generate the ASN message to the customer's API queue.
See a detailed description of the ASN process in Jakamo from the ASN User Guide page.
Example: New ASN message retrieved from Jakamo by the customer company (.json)
{
"ID": "87", // This is Jakamo generated unique id for ASN message
"shipmentNumber": "ASNTEST2000", // Shipment No. provided by a supplier or auto-generated by Jakamo (number JAXXXXXXXX)
"status": "DISPATCHED",
"dispatchCompanyName": "James Universal Imports",
"dispatchContactName": "James Testperson",
"dispatchContactEmail": "james@example.com",
"dispatchStreetName": "Test Street",
"dispatchBuildingNumber": "44",
"dispatchAdditionalStreetName": null,
"dispatchCity": "Tampere",
"dispatchPostalZone": "44500",
"dispatchCountry": "Finland",
"shippingUnits": [
{
"shippingUnitNumber": "1111",
"type": "Pallet",
"items": [
{
"orderNumber": "ASN1234",
"lineNumber": "2",
"quantity": "30",
"sellersItemID": "Heat Diffuser 1234",
"buyersItemID": "Heat Diffuser 1234",
"buyersItemName": "Heat Diffuser 1234",
"batchNumber": "1",
"manufacturingBatch": "33333",
"expirationDate": "2022-12-14",
"serialNumbers": [
"12345",
"23456",
"34567"
]
}
],
"dimensions": {
"mass": 100,
"massUnit": "kg",
"length": 2,
"width": 3,
"height": 4,
"diameter": 5,
"lengthUnit": "m"
}
},
{
"shippingUnitNumber": "2222",
"type": "Pallet",
"items": [
{
"orderNumber": "ASN1234",
"lineNumber": "1",
"quantity": "10",
"sellersItemID": "Radiator 12345",
"buyersItemID": "Radiator 12345",
"buyersItemName": "Radiator",
"batchNumber": "1",
"manufacturingBatch": "33333",
"expirationDate": "2022-12-14",
"serialNumbers": [
"9999999",
"8888888",
"777777"
]
},
{
"orderNumber": "ASN1234",
"lineNumber": "3",
"quantity": "50",
"sellersItemID": "Mounting kit 12345",
"buyersItemID": "Mounting kit 12345",
"buyersItemName": "Mounting kit 12345",
"batchNumber": "1",
"manufacturingBatch": "33333",
"expirationDate": "2022-12-14",
"serialNumbers": [
"22222",
"33333",
"44444"
]
}
],
"dimensions": {
"mass": 3,
"massUnit": "kg",
"length": 4,
"width": 5,
"height": 6,
"diameter": 7,
"lengthUnit": "m"
}
}
],
"buyer": {
"companyName": "Postman Test CLIENT",
"companyID": "clientcompany"
},
"supplier": {
"companyName": "Postman Test SUPPLIER",
"companyID": "testsupplier"
},
"dispatchDatetime": "2022-12-14T11:24:00+00:00"
}
7. Company mappings in the Jakamo integration settings
See the general company mapping instructions from the Jakamo User Guide Integrations page.
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 eefers 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.
7.1 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.
7.2 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.
Didn't you find what you were looking for? Send email to Jakamo support (support@thejakamo.com) and we will help you.