Jakamo API

Purchase orders

The Jakamo Purchase order API is an XML based API over HTTPS/REST.

With the Jakamo purchase order API it is possible to bring purchase order data from ERP-systems to Jakamo. This document is intended to help building Jakamo connectors for ERP-systems.
 
The Jakamo purchase order API uses it's own internal authentication system. Authentication tokens must be generated in Jakamo specifically for this purpose. Authentication methods described earlier in this document do not apply to purchase order integrations.

Getting ready

Preparations can be done in minutes by following these steps:

  • Let us know that you wish to integrate your ERP with Jakamo.
    We will add integration settings page to your Jakamo account. Enabling Jakamo integrations requires a Jakamo Enterprise plan. After enabling integrations, integration settings can be found in the dropdown menu in the upper left corner.

  • Create username and password and generate an authentication token
    On the integration settings page, you must create a username and a password for the integration. Later this spring (2018), it will be also possible to create and display a token directly in settings page. Currently the actual token is a base64 hash from the integration username and password.

  • Map ERP users to Jakamo users
    ERP users who act as purchasers must have personal accounts in Jakamo. If the purchaser has the identifier "jbond" in the ERP, it will be transferred in the XML data. This identifier must be linked to the Jakamo user. Simply click add user to create user mappings between Jakamo and the ERP-system. The integration requires passing this user information in the XML data.

  • Map ERP suppliers to Jakamo relationships
    Integrations page: Create a mapping between the ERP company (supplier) and the Jakamo relationship by clicking “add company”.

  • Authenticate with headers, push XML and start dancing
    Set your authentication token in the HTTP headers. Post order XML.

Process

Authorization

The purchase order API requires a base64 hashed token to be sent in the HTTP request headers. The username and the password must be added to the Jakamo integrations page. You must generate a base64 hash from the username and the password (eg. running the following command in a *nix terminal: echo -n 'username:password' | base64).

Key Value
Content-Type application/xml
Authorization basic [token_here]

Example: Sending purchase orders to Jakamo (HTTP POST)

This is used for sending purchase order data that is being pushed from ERP to the endpoint. This is an absolute minimal set of XML-data that can be sent to Jakamo. Simply authenticate and post the purchase order xml-data to endpoint.
 
The technical structure and explanations can be found here

Endpoint

HTTP POST https://www.thejakamo.com/api/order Authorization: Basic [token] Content-type: application/xml

Example XML

<?xml version="1.0" encoding="utf-8"?> <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>test_example_minimal</cbc:ID> <!-- CHANGE THIS TO TEST: Unique order ID --> <cbc:IssueDate>2018-06-21</cbc:IssueDate> <cac:BuyerCustomerParty> <cac:Party> <cac:PartyIdentification> <cbc:ID>buyerpartyid</cbc:ID> </cac:PartyIdentification> </cac:Party> <cac:BuyerContact> <cbc:ID>example_user</cbc:ID> <!-- CHANGE THIS TO TEST: User reference --> </cac:BuyerContact> </cac:BuyerCustomerParty> <cac:Delivery> <cac:RequestedDeliveryPeriod> <cbc:EndDate>2018-12-12</cbc:EndDate> </cac:RequestedDeliveryPeriod> </cac:Delivery> <cac:SellerSupplierParty> <cac:Party> <cac:PartyIdentification> <cbc:ID>sellerpartyid</cbc:ID> <!-- CHANGE THIS TO TEST: Supplier reference --> </cac:PartyIdentification> </cac:Party> </cac:SellerSupplierParty> <cac:OrderLine> <cac:LineItem> <cbc:ID>1</cbc:ID> <cbc:Quantity unitCode="kpl">2.00</cbc:Quantity> <cac:Delivery> <cbc:ID>1</cbc:ID> <cbc:Quantity unitCode="kpl">2.00</cbc:Quantity> <cac:RequestedDeliveryPeriod> <cbc:EndDate>2018-09-12</cbc:EndDate> </cac:RequestedDeliveryPeriod> </cac:Delivery> <cac:Price> <cbc:PriceAmount currencyID="EUR">1</cbc:PriceAmount> <cbc:BaseQuantity unitCode="">1</cbc:BaseQuantity> </cac:Price> <cac:Item> <cbc:Name>Tuotenimi X</cbc:Name> <cac:BuyersItemIdentification> <cbc:ID>TUOTE123456</cbc:ID> </cac:BuyersItemIdentification> <cac:SellersItemIdentification> <cbc:ID></cbc:ID> </cac:SellersItemIdentification> <cac:ClassifiedTaxCategory> <cbc:Percent>24</cbc:Percent> <cac:TaxScheme> <cbc:ID>VAT</cbc:ID> </cac:TaxScheme> </cac:ClassifiedTaxCategory> </cac:Item> </cac:LineItem> </cac:OrderLine> </Order>

Example: Changing / updating purchase order data (HTTP PUT)

This is used for sending revised purchase order data to Jakamo. This is used when it is necessary correct an error in the purchase order data.
 
This can be also used if the supplier confirms an order with different order information (quantity, price etc.) and the supplier must "approve" the confirmed amount with the revised purchase order.
 
There are two main differences to purchase order data.
1) Use HTTP PUT https://www.thejakamo.com/api/order/[order id] to update information (instead of POST)
2) Change Order root element to OrderChange.

Endpoint

HTTP POST https://www.thejakamo.com/api/order/[order id] Authorization: Basic [token] Content-type: application/xml

Example XML

<?xml version="1.0" encoding="utf-8"?> <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>test_example_minimal</cbc:ID> <!-- CHANGE THIS TO TEST: Unique order ID --> <cbc:IssueDate>2018-06-21</cbc:IssueDate> <cac:BuyerCustomerParty> <cac:Party> <cac:PartyIdentification> <cbc:ID>buyerpartyid</cbc:ID> </cac:PartyIdentification> </cac:Party> <cac:BuyerContact> <cbc:ID>example_user</cbc:ID> <!-- CHANGE THIS TO TEST: User reference --> </cac:BuyerContact> </cac:BuyerCustomerParty> <cac:Delivery> <cac:RequestedDeliveryPeriod> <cbc:EndDate>2018-12-12</cbc:EndDate> </cac:RequestedDeliveryPeriod> </cac:Delivery> <cac:SellerSupplierParty> <cac:Party> <cac:PartyIdentification> <cbc:ID>sellerpartyid</cbc:ID> <!-- CHANGE THIS TO TEST: Supplier reference --> </cac:PartyIdentification> </cac:Party> </cac:SellerSupplierParty> <cac:OrderLine> <cac:LineItem> <cbc:ID>1</cbc:ID> <cbc:Quantity unitCode="kpl">2.00</cbc:Quantity> <cac:Delivery> <cbc:ID>1</cbc:ID> <cbc:Quantity unitCode="kpl">2.00</cbc:Quantity> <cac:RequestedDeliveryPeriod> <cbc:EndDate>2018-09-12</cbc:EndDate> </cac:RequestedDeliveryPeriod> </cac:Delivery> <cac:Price> <cbc:PriceAmount currencyID="EUR">1</cbc:PriceAmount> <cbc:BaseQuantity unitCode="">1</cbc:BaseQuantity> </cac:Price> <cac:Item> <cbc:Name>Product X</cbc:Name> <cac:BuyersItemIdentification> <cbc:ID>PRODUCT3456</cbc:ID> </cac:BuyersItemIdentification> <cac:SellersItemIdentification> <cbc:ID></cbc:ID> </cac:SellersItemIdentification> <cac:ClassifiedTaxCategory> <cbc:Percent>24</cbc:Percent> <cac:TaxScheme> <cbc:ID>VAT</cbc:ID> </cac:TaxScheme> </cac:ClassifiedTaxCategory> </cac:Item> </cac:LineItem> </cac:OrderLine> </OrderChange>

Example: Cancelling an entire order

An order can be cancelled using status messages. A status message is sent from the ERP to Jakamo to set the status for a specific order.
 
NOTE: An order can be revised by sending a purchase order with new data to this endpoint.

Endpoint

HTTP PUT https://www.thejakamo.com/api/order/[order id] Authorization: Basic [token] Content-type: application/xml
XML: Cancelling entire order
<StatusMessage> <OrderID>id</OrderID> <!-- CHANGE THIS TO TEST: Order id --> <Status>Cancelled</Status> <!-- Entire order is being cancelled, no need to refer to order lines etc --> <BuyerCustomerID>id</BuyerCustomerID> <! -- Not used at Jakamo side --> <SellerSupplierID>id</SellerSupplierID> <! -- Not used at Jakamo side --> </StatusMessage>

Example: Marking goods "received" in the ERP

An order can be marked as received when goods arrive to the buyer. This is also a status message that is sent from the ERP to Jakamo.

Endpoint

HTTP PUT https://www.thejakamo.com/api/order/[order id] Authorization: Basic [token] Content-type: application/xml
XML: Marking order lines received
<StatusMessage> <OrderID>id</OrderID> <!-- CHANGE THIS TO TEST: Order id --> <EventDate>2016-08-10</EventDate> <Status>Received</Status> <OrderLine> <OrderLineID>10</OrderLineID> <Delivery> <DeliveryID>2</DeliveryID> </Delivery> <Delivery> <DeliveryID>1</DeliveryID> </Delivery> </OrderLine> <OrderLine> <OrderLineID>20</OrderLineID> <Delivery> <DeliveryID>1</DeliveryID> <Note>Received 990</Note> </Delivery> <Delivery> <DeliveryID>2</DeliveryID> <Note>Received 30</Note> </Delivery> </OrderLine> <BuyerCustomerID>id</BuyerCustomerID> <!-- Not used at Jakamo side --> <SellerSupplierID>id</SellerSupplierID> <!-- Not used at Jakamo side --> </StatusMessage>

Retrieving information from Jakamo

Endpoint

HTTP GET https://www.thejakamo.com/api/order/response Authorization: Basic [token] Content-type: application/xml

Jakamo stores all outgoing messages in a queue. By making a HTTP GET request to the response endpoint Jakamo delivers the first message in the queue. Generally speaking messages can be status messages or order confirmations that the supplier has made in Jakamo.
 
Messages in the response queue must be cleared after they have been processed. The response message contains an X-Acknowledge-Uri header. Posting to this URI removes the message from the queue.

Example: Retrieving an order confirmation from Jakamo to the ERP

The supplier must confirm an order to let the buyer know that they can deliver what is been ordered. Once the supplier has confirmed the order in Jakamo, it can be retrieved via the API. The order confirmation structure follows the UBL schema. Full documentation of the UBL response message structures and descriptions can be found here

Endpoint

HTTP GET https://www.thejakamo.com/api/order/response Authorization: Basic [token] Content-type: application/xml
Example XML (output): Order confirmation
<OrderResponse 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="urn:oasis:names:specification:ubl:schema:xsd:OrderResponse-2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:oasis:names:specification:ubl:schema:xsd:OrderResponse-2 ..\xsd\maindoc\UBL-OrderResponse-2.1.xsd"> <cbc:UBLVersionID>1</cbc:UBLVersionID> <cbc:CustomizationID>1</cbc:CustomizationID> <cbc:ID>853</cbc:ID> <cbc:IssueDate>2018-04-05</cbc:IssueDate> <cbc:IssueTime></cbc:IssueTime> <cac:OrderReference> <cbc:ID>test_example_minimal</cbc:ID> </cac:OrderReference> <cac:SellerSupplierParty> <cac:Party> <cac:PartyIdentification> <cbc:ID schemeID="" schemeAgencyID="92">123</cbc:ID> </cac:PartyIdentification> </cac:Party> </cac:SellerSupplierParty> <cac:BuyerCustomerParty> <cac:Party> <cac:PartyIdentification> <cbc:ID schemeID="" schemeAgencyID="92">114</cbc:ID> </cac:PartyIdentification> </cac:Party> </cac:BuyerCustomerParty> <cac:OrderLine> <cac:LineItem> <cbc:ID>1</cbc:ID> <cbc:Quantity>2</cbc:Quantity> <cac:Price> <cbc:PriceAmount currencyID="">1</cbc:PriceAmount> <cbc:BaseQuantity unitCode="UN/ECE rec 20 unit code"></cbc:BaseQuantity> </cac:Price> <cac:Delivery> <cbc:ID>1</cbc:ID> <cbc:Quantity>2</cbc:Quantity> <cac:PromisedDeliveryPeriod> <cbc:StartDate>2018-09-12 00:00:00</cbc:StartDate> <cbc:EndDate>2018-09-12 00:00:00</cbc:EndDate> </cac:PromisedDeliveryPeriod> <cac:AdditionalDocumentReference> <cbc:ID>Open</cbc:ID> <cbc:DocumentTypeCode>JDS</cbc:DocumentTypeCode> </cac:AdditionalDocumentReference> </cac:Delivery> <cac:Item> <cbc:Name>Product X</cbc:Name> <cbc:Description></cbc:Description> </cac:Item> </cac:LineItem> </cac:OrderLine> </OrderResponse>

Example: Retrieving "delivered" status from Jakamo

When an order is completed and delivered by the supplier, they set the delivered status for the order or certain order rows in Jakamo. This information can be accessed by the buyer via the API.
 
If there are delivered -status messages, they will show up in Jakamo response queue.

Endpoint

HTTP GET https://www.thejakamo.com/api/order/response Authorization: Basic [token] Content-type: application/xml
Example XML (output): "Delivered" status message
<StatusMessage> <OrderID>id</OrderID> <!-- CHANGE THIS TO TEST: Order id --> <Status>Delivered</Status> <OrderLine> <OrderLineID>10</OrderLineID> <Delivery> <DeliveryID>2</DeliveryID> </Delivery> <Delivery> <DeliveryID>1</DeliveryID> </Delivery> </OrderLine> <OrderLine> <OrderLineID>20</OrderLineID> <Delivery> <DeliveryID>1</DeliveryID> </Delivery> <Delivery> <DeliveryID>2</DeliveryID> </Delivery> </OrderLine> <BuyerCustomerID>id</BuyerCustomerID> <!-- Not used at Jakamo side --> <SellerSupplierID>id</SellerSupplierID> <!-- Not used at Jakamo side --> </StatusMessage>