Forecast API
1. Overview
Jakamo Forecast API is XML based (UBL) REST API for receiving forecast data from customer systems and transmitting forecast information to the suppliers via Jakamo.
See user instructions of the Forecast functionality from the Forecasts User Guide page.
1.1 How to get started
Request demo accounts from Jakamo Support Team (support@thejakamo.com) to create a Forecast integration from your system to Jakamo.
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. Forecast integration activation
The first step is to ask for Forecast integration activation for the Jakamo production account. Ask Jakamo Support Team (support@thejakamo.com) to activate the forecast 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 are available for company admin users.
2. Integration credentials creation
Register OAuth2.0 application or create integration credentials in the Jakamo production account on the Integrations settings page under Integration Credentials.
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 Forecast API endpoints here.
5. Everything is ready!
You can now send Forecast messages to your partners via Jakamo.
2. Authorization
Jakamo Forecast 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.Determine a cryptic username and password.
3. Forecast API endpoints
| Jakamo environment | HTTP request | Jakamo API endpoint |
|---|---|---|
| Test environment | POST | https://demo.thejakamo.com/api/forecast |
| Production environment | POST | https://www.thejakamo.com/api/forecast |
| Test environment | GET | https://demo.thejakamo.com/api/mappedcompanies |
| Production environment | GET | https://thejakamo.com/api/mappedcompanies |
4. Request response messages
The table below presents the most common API request responses from Jakamo Forecast API.
| HTTP response status code | Response body | Additional information |
|---|---|---|
| 200 OK | Forecast message successfully sent to Jakamo. | |
| 400 Bad Request | Authentication failed. | Authentication failed because of an incorrect username or password or incorrect authentication method. Make sure you use the integration credentials defined in Jakamo “Integrations” and basic authentication as an authentication method. |
| 400 Bad Request | Cannot find sender party with given SenderParty\PartyIdentification\ID | Missing mapping in Forecast/SenderParty\PartyIdentification\ID. Add missing sender mapping (refer to your company) in Jakamo “Integrations”. |
| 400 Bad Request | Cannot find receiver party with given ReceiverParty\PartyIdentification\ID | Missing mapping in Forecast/ReceiverParty\PartyIdentification\ID. Add missing vendor mapping in Jakamo “Integrations”. |
| 400 Bad Request | Cannot find buyer customer party with given BuyerCustomerParty\Party\PartyIdentification\ID | Missing mapping in Forecast/BuyerCustomerParty\Party\PartyIdentification\ID. Add missing buyer mapping (refer to your company) in Jakamo “Integrations”. |
| 400 Bad Request | Cannot find seller supplier party with given SellerSupplierParty\Party\PartyIdentification\ID | Missing mapping in Forecast/SellerSupplierParty/Party/PartyIdentification/ID. Add missing vendor mapping in Jakamo “Integrations”. |
| 500 Internal Server Error | A generic error message, is given when no more specific message is suitable. For example, the mandatory element is missing, or mandatory information is incorrect. It might be also that you are missing the relation between your Business Unit and the supplier you are testing with. |
5. Forecast XML messages
Example 1: Send a new Forecast message to Jakamo (minimal)
Example: Send a new minimal Forecast message (HTTP POST)
<Forecast 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>20230604_A</cbc:ID>
<cbc:IssueDate>2023-06-02</cbc:IssueDate>
<cbc:ForecastPurposeCode>ORDER_FORECAST</cbc:ForecastPurposeCode>
<cac:ForecastPeriod>
<cbc:StartDate>2023-06-04</cbc:StartDate>
<cbc:EndDate>2023-07-01</cbc:EndDate>
</cac:ForecastPeriod>
<cac:SenderParty>
<cac:PartyIdentification>
<cbc:ID>erp_id</cbc:ID>
</cac:PartyIdentification>
<cac:Contact>
<cbc:Name>Buyer_contact_person</cbc:Name>
</cac:Contact>
</cac:SenderParty>
<cac:ReceiverParty>
<cac:PartyIdentification>
<cbc:ID>supplier_id</cbc:ID>
</cac:PartyIdentification>
</cac:ReceiverParty>
<cac:BuyerCustomerParty>
<cac:Party>
<cac:PartyIdentification>
<cbc:ID>erp_id</cbc:ID>
</cac:PartyIdentification>
</cac:Party>
</cac:BuyerCustomerParty>
<cac:SellerSupplierParty>
<cac:Party>
<cac:PartyIdentification>
<cbc:ID>supplier_id</cbc:ID>
</cac:PartyIdentification>
</cac:Party>
</cac:SellerSupplierParty>
<cac:ForecastLine>
<cbc:ID>1</cbc:ID>
<cbc:ForecastTypeCode>TOTAL</cbc:ForecastTypeCode>
<cac:ForecastPeriod>
<cbc:StartDate>2023-06-04</cbc:StartDate>
<cbc:EndDate>2023-06-04</cbc:EndDate>
</cac:ForecastPeriod>
<cac:SalesItem>
<cbc:Quantity unitCode="pcs">5</cbc:Quantity>
<cac:Item>
<cbc:Name>COVER HES880 HLCL 500V </cbc:Name>
<cac:BuyersItemIdentification>
<cbc:ID>4566789</cbc:ID>
</cac:BuyersItemIdentification>
<cac:SellersItemIdentification>
<cbc:ID></cbc:ID>
</cac:SellersItemIdentification>
</cac:Item>
</cac:SalesItem>
</cac:ForecastLine>
</Forecast>
Example 2: Send a new Forecast message to Jakamo
Example: Send a new Forecast message (HTTP POST)
<Forecast 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>29032023</cbc:ID>
<cbc:IssueDate>2023-03-29</cbc:IssueDate>
<cbc:ForecastPurposeCode>ORDER_FORECAST</cbc:ForecastPurposeCode>
<cac:ForecastPeriod>
<cbc:StartDate>2023-03-29</cbc:StartDate>
<cbc:EndDate>2023-03-29</cbc:EndDate>
</cac:ForecastPeriod>
<cac:SenderParty>
<cac:PartyIdentification>
<cbc:ID>erp_id</cbc:ID>
</cac:PartyIdentification>
<cac:PartyName>
<cbc:Name>Customer Company AB</cbc:Name>
</cac:PartyName>
<cac:Contact>
<cbc:Name>name@examplecompany.com</cbc:Name>
</cac:Contact>
</cac:SenderParty>
<cac:ReceiverParty>
<cac:PartyIdentification>
<cbc:ID>vendor_number</cbc:ID>
</cac:PartyIdentification>
<cac:PartyName>
<cbc:Name>Test Supplier Ltd.</cbc:Name>
</cac:PartyName>
</cac:ReceiverParty>
<cac:BuyerCustomerParty>
<cac:Party>
<cac:PartyIdentification>
<cbc:ID>erp_id</cbc:ID>
</cac:PartyIdentification>
</cac:Party>
</cac:BuyerCustomerParty>
<cac:SellerSupplierParty>
<cac:Party>
<cac:PartyIdentification>
<cbc:ID>Saha</cbc:ID>
</cac:PartyIdentification>
</cac:Party>
</cac:SellerSupplierParty>
<cac:ForecastLine>
<cbc:ID>1</cbc:ID>
<cbc:ForecastTypeCode>TOTAL</cbc:ForecastTypeCode>
<cac:ForecastPeriod>
<cbc:StartDate>2023-01-02</cbc:StartDate>
<cbc:EndDate>2023-01-02</cbc:EndDate>
</cac:ForecastPeriod>
<cac:SalesItem>
<cbc:Quantity unitCode="pcs">5</cbc:Quantity>
<cac:Item>
<cbc:Name>COVER HES880 HLCL 500V</cbc:Name>
<cac:BuyersItemIdentification>
<cbc:ID>83150154F</cbc:ID>
</cac:BuyersItemIdentification>
<cac:SellersItemIdentification>
<cbc:ID></cbc:ID>
</cac:SellersItemIdentification>
</cac:Item>
</cac:SalesItem>
</cac:ForecastLine>
<cac:ForecastLine>
<cbc:ID>2</cbc:ID>
<cbc:ForecastTypeCode>TOTAL</cbc:ForecastTypeCode>
<cac:ForecastPeriod>
<cbc:StartDate>2023-12-03</cbc:StartDate>
<cbc:EndDate>2023-12-03</cbc:EndDate>
</cac:ForecastPeriod>
<cac:SalesItem>
<cbc:Quantity unitCode="pcs">5</cbc:Quantity>
<cac:Item>
<cbc:Name>COVER HES880 HLCL 500V</cbc:Name>
<cac:BuyersItemIdentification>
<cbc:ID>83150154F</cbc:ID>
</cac:BuyersItemIdentification>
<cac:SellersItemIdentification>
<cbc:ID></cbc:ID>
</cac:SellersItemIdentification>
</cac:Item>
</cac:SalesItem>
</cac:ForecastLine>
<cac:ForecastLine>
<cbc:ID>3</cbc:ID>
<cbc:ForecastTypeCode>TOTAL</cbc:ForecastTypeCode>
<cac:ForecastPeriod>
<cbc:StartDate>2023-01-03</cbc:StartDate>
<cbc:EndDate>2023-01-03</cbc:EndDate>
</cac:ForecastPeriod>
<cac:SalesItem>
<cbc:Quantity unitCode="pcs">2830</cbc:Quantity>
<cac:Item>
<cbc:Name>MR7 Busbar brake DC+VC421</cbc:Name>
<cac:BuyersItemIdentification>
<cbc:ID>83150154F</cbc:ID>
</cac:BuyersItemIdentification>
<cac:SellersItemIdentification>
<cbc:ID></cbc:ID>
</cac:SellersItemIdentification>
</cac:Item>
</cac:SalesItem>
</cac:ForecastLine>
<cac:ForecastLine>
<cbc:ID>4</cbc:ID>
<cbc:ForecastTypeCode>TOTAL</cbc:ForecastTypeCode>
<cac:ForecastPeriod>
<cbc:StartDate>2023-02-03</cbc:StartDate>
<cbc:EndDate>2023-02-03</cbc:EndDate>
</cac:ForecastPeriod>
<cac:SalesItem>
<cbc:Quantity unitCode="pcs">2830</cbc:Quantity>
<cac:Item>
<cbc:Name>MR7 Busbar brake DC+VC421</cbc:Name>
<cac:BuyersItemIdentification>
<cbc:ID>83150154F</cbc:ID>
</cac:BuyersItemIdentification>
<cac:SellersItemIdentification>
<cbc:ID></cbc:ID>
</cac:SellersItemIdentification>
</cac:Item>
</cac:SalesItem>
</cac:ForecastLine>
<cac:ForecastLine>
<cbc:ID>5</cbc:ID>
<cbc:ForecastTypeCode>TOTAL</cbc:ForecastTypeCode>
<cac:ForecastPeriod>
<cbc:StartDate>2023-03-03</cbc:StartDate>
<cbc:EndDate>2023-03-03</cbc:EndDate>
</cac:ForecastPeriod>
<cac:SalesItem>
<cbc:Quantity unitCode="pcs">2830</cbc:Quantity>
<cac:Item>
<cbc:Name>MR7 Busbar brake DC+VC421</cbc:Name>
<cac:BuyersItemIdentification>
<cbc:ID>83150154F</cbc:ID>
</cac:BuyersItemIdentification>
<cac:SellersItemIdentification>
<cbc:ID></cbc:ID>
</cac:SellersItemIdentification>
</cac:Item>
</cac:SalesItem>
</cac:ForecastLine>
<cac:ForecastLine>
<cbc:ID>6</cbc:ID>
<cbc:ForecastTypeCode>TOTAL</cbc:ForecastTypeCode>
<cac:ForecastPeriod>
<cbc:StartDate>2023-05-03</cbc:StartDate>
<cbc:EndDate>2023-05-03</cbc:EndDate>
</cac:ForecastPeriod>
<cac:SalesItem>
<cbc:Quantity unitCode="pcs">6</cbc:Quantity>
<cac:Item>
<cbc:Name>KIINNITYSLEVY, TAKAVALO (RAL7024, M1)</cbc:Name>
<cac:BuyersItemIdentification>
<cbc:ID>13028873M</cbc:ID>
</cac:BuyersItemIdentification>
<cac:SellersItemIdentification>
<cbc:ID></cbc:ID>
</cac:SellersItemIdentification>
</cac:Item>
</cac:SalesItem>
</cac:ForecastLine>
<cac:ForecastLine>
<cbc:ID>7</cbc:ID>
<cbc:ForecastTypeCode>TOTAL</cbc:ForecastTypeCode>
<cac:ForecastPeriod>
<cbc:StartDate>2023-06-03</cbc:StartDate>
<cbc:EndDate>2023-06-03</cbc:EndDate>
</cac:ForecastPeriod>
<cac:SalesItem>
<cbc:Quantity unitCode="pcs">6</cbc:Quantity>
<cac:Item>
<cbc:Name>KIINNITYSLEVY, TAKAVALO (RAL7024, M1)</cbc:Name>
<cac:BuyersItemIdentification>
<cbc:ID>13028873M</cbc:ID>
</cac:BuyersItemIdentification>
<cac:SellersItemIdentification>
<cbc:ID></cbc:ID>
</cac:SellersItemIdentification>
</cac:Item>
</cac:SalesItem>
</cac:ForecastLine>
<cac:ForecastLine>
<cbc:ID>6</cbc:ID>
<cbc:ForecastTypeCode>TOTAL</cbc:ForecastTypeCode>
<cac:ForecastPeriod>
<cbc:StartDate>2023-07-03</cbc:StartDate>
<cbc:EndDate>2023-07-03</cbc:EndDate>
</cac:ForecastPeriod>
<cac:SalesItem>
<cbc:Quantity unitCode="pcs">6</cbc:Quantity>
<cac:Item>
<cbc:Name>JARRUSÄILIÖN KANSI SHEILA (SINIPASSIVOINTI)</cbc:Name>
<cac:BuyersItemIdentification>
<cbc:ID>45498404S</cbc:ID>
</cac:BuyersItemIdentification>
<cac:SellersItemIdentification>
<cbc:ID></cbc:ID>
</cac:SellersItemIdentification>
</cac:Item>
</cac:SalesItem>
</cac:ForecastLine>
<cac:ForecastLine>
<cbc:ID>8</cbc:ID>
<cbc:ForecastTypeCode>TOTAL</cbc:ForecastTypeCode>
<cac:ForecastPeriod>
<cbc:StartDate>2023-01-03</cbc:StartDate>
<cbc:EndDate>2023-01-03</cbc:EndDate>
</cac:ForecastPeriod>
<cac:SalesItem>
<cbc:Quantity unitCode="pcs">6</cbc:Quantity>
<cac:Item>
<cbc:Name>JARRUSÄILIÖN KANSI SHEILA (SINIPASSIVOINTI)</cbc:Name>
<cac:BuyersItemIdentification>
<cbc:ID>45498404S</cbc:ID>
</cac:BuyersItemIdentification>
<cac:SellersItemIdentification>
<cbc:ID></cbc:ID>
</cac:SellersItemIdentification>
</cac:Item>
</cac:SalesItem>
</cac:ForecastLine>
<cac:ForecastLine>
<cbc:ID>9</cbc:ID>
<cbc:ForecastTypeCode>TOTAL</cbc:ForecastTypeCode>
<cac:ForecastPeriod>
<cbc:StartDate>2023-01-03</cbc:StartDate>
<cbc:EndDate>2023-01-03</cbc:EndDate>
</cac:ForecastPeriod>
<cac:SalesItem>
<cbc:Quantity unitCode="pcs">4</cbc:Quantity>
<cac:Item>
<cbc:Name>HYDR.SÄILIÖN KANSI SHEILA</cbc:Name>
<cac:BuyersItemIdentification>
<cbc:ID>45499130S</cbc:ID>
</cac:BuyersItemIdentification>
<cac:SellersItemIdentification>
<cbc:ID></cbc:ID>
</cac:SellersItemIdentification>
</cac:Item>
</cac:SalesItem>
</cac:ForecastLine>
<cac:ForecastLine>
<cbc:ID>10</cbc:ID>
<cbc:ForecastTypeCode>TOTAL</cbc:ForecastTypeCode>
<cac:ForecastPeriod>
<cbc:StartDate>2022-12-10</cbc:StartDate>
<cbc:EndDate>2022-12-10</cbc:EndDate>
</cac:ForecastPeriod>
<cac:SalesItem>
<cbc:Quantity unitCode="pcs">4</cbc:Quantity>
<cac:Item>
<cbc:Name>HYDR.SÄILIÖN KANSI SHEILA</cbc:Name>
<cac:BuyersItemIdentification>
<cbc:ID>45499130S</cbc:ID>
</cac:BuyersItemIdentification>
<cac:SellersItemIdentification>
<cbc:ID></cbc:ID>
</cac:SellersItemIdentification>
</cac:Item>
</cac:SalesItem>
</cac:ForecastLine>
</Forecast>
5.1 Messaging principles
1. Determine the forecast type you are sending
Use Forecast/ForecastPurposeCode to set forecast type:
- ORDER_FORECAST for order forecasts
- DEMAND_FORECAST for demand forecasts
Based on these options, forecasts will be categorized to order and demand forecasts and can be filtered in Jakamo user interface based on the type.
2. Send one Forecast message per supplier
Forecast message should contain information and items shared with one supplier only. On the other words, do not combine Forecast message to include items ordered from different suppliers: one forecast message is shared with one supplier. Jakamo will show only the latest forecast shared with the supplier in user interface. This enables to trust that supplier will always have the latest forecast available. There is no possibility to view forecast history in Jakamo user interface.
3. Send multiple ForecastLine elements for same item to indicate demand in different time points
Jakamo user interface will combine same items (ForecastLine/Items with same BuyersItemIdentification/ID) for certain weeks or months based on the ForecastTimePeriod. Use multiple ForecastLine elements for the same item with different ForecastTimePeriods to indicate the demand in different time points. ForecastLine/ForecastPeriod/StartDate is used to set an demand for an item to a timeline in Jakamo.
6. 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. See Jakamo's general integration mappings instructions from the User Guide.
6.1 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 (Forecast/ReceiverParty/Party/PartyIdentification/ID and Forecast/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.
- Buyer customer party tags are not used with Forecast integration.
7. Requesting mapped companies to send forecasts to selected suppliers
In some cases, you might want to send your forecasts to only certain companies, and to do that, you need their Jakamo IDs. To gather the IDs, you may send a GET request to get this data. Simply send
DEMO
PRODUCTION
This will return the following JSON
[
{
"CompanyName": "Steel & Thunder Ltd",
"MappedId": "Forecast-Steelandthunder-001"
}
]
Didn't you find what you were looking for? Send email to Jakamo support (support@thejakamo.com) and we will help you.