Claim API

1. Overview

The Jakamo Claim API is an XML-based API over HTTPS/REST.

With the Jakamo Claim API, it is possible to push claims data from external systems (for example ERP systems) to Jakamo. It is also possible to retrieve claims information from Jakamo (for example supplier's replies to claims). This document is intended to help build Jakamo connectors for external systems.

Claim App guide for the users!

See user instructions of the Claim application from the Claims User Guide page.

1.1 Requirements how to get started

Request demo accounts from Jakamo Support Team (support@thejakamo.com) to create a Claim integration from your system.

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. Claim integration activation

First, ask for Claim integration activation for your Jakamo production account. Ask Jakamo Support Team (support@thejakamo.com) to activate the 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 authentication

Register OAuth2.0 application or create integration credentials in the Jakamo production account on the Integrations settings page under Integration Credentials. It is recommended to use OAuth2.0.

3. Company and user mappings configuration in Jakamo

Define user and company mappings on the Jakamo Integrations page.

4. Message endpoint configuration

Change messages’ endpoint configurations from the test environment to the production environment. Check Claim API endpoints here.

5. Everything is ready!

You can send Claim, ClaimChange, and StatusMessages to Jakamo, and receive Claim responses and StatusMessages from Jakamo!

2. Authorization

Jakamo Claim 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. Please ensure using different usernames and passwords in each enabled integration in use.

3. Claim API endpoints

Jakamo environment	HTTP request	Jakamo API endpoint
Test environment	POST	https://demo.thejakamo.com/api/claim
Test environment	GET	https://demo.thejakamo.com/api/claim/response
Test environment	PUT	https://demo.thejakamo.com/api/claim/{claim_id}
Production environment	POST	https://www.thejakamo.com/api/claim
Production environment	GET	https://www.thejakamo.com/api/claim/response
Production environment	PUT	https://www.thejakamo.com/api/claim/{claim_id}

4. Claim API request response messages

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

HTTP response status code	Response body	Additional information
200 OK		Claim, ClaimChange, or StatusMessage successfully posted to Jakamo Claim API.
400 Bad Request	A claim with the provided claim id already exists	Claim with Claim/ID already existing in Jakamo. If you are trying to update an existing claim, use the ClaimChange message.
400 Bad Request	Authentication failed.	Check that the authentication method is basic authentication and that you have the correct integration credentials in use. If needed, create new integration credentials on Jakamo's Integrations page.
400 Bad Request	Cannot find claiming party with given ClaimingParty\ID	Check that identifier in Claim/ClaimingParty/ID is mapped in Jakamo Integrations page to your Jakamo company account.
400 Bad Request	No claiming user id found or cannot find user mapping.	Check that identifier in Claim/ClaimingParty/ClaimingUser/ID is mapped in Jakamo Integrations page to your user's Jakamo user account.
400 Bad Request	No vendor mapping found.	Check that identifier in Claim/ClaimedParty/ID is mapped in Jakamo Integrations page to your supplier's Jakamo account.
400 Bad Request	Error in Defect\DefectType	Check that there is information in Claim/DefectType (see all options from here). This element cannot be left empty. If no information provided, Claim/DefectType should be leave out of the Claim message.
400 Bad Request	Error in Defect\DefectClassification	Check that there is information in Claim/DefectClassification (see all options from here). This element cannot be left empty. If no information provided, Claim/DefectClassification should be leave out of the Claim message.

5. Handling incoming message queue

See the general Jakamo API queue handling instructions from incoming message queue handling page. Jakamo stores all outgoing messages in an API queue. By making an HTTP GET request to the response endpoint Jakamo delivers the first message from the queue.

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 that message from the queue. After that, the next message from the queue will be returned.

DEMO

1. GET Claim https://demo.thejakamo.com/api/claim/response
2. Open headers and look for header x-acknowledge-uri
3. POST: https://demo.thejakamo.com/api/claim/response/claim_ID

PRODUCTION

1. GET Claim https://www.thejakamo.com/api/claim/response
2. Open headers and look for header x-acknowledge-uri
3. POST: https://www.thejakamo.com/api/claim/response/claim_ID

6. Claim handling process in Jakamo

See a detailed description of the Claim process in Jakamo from the Claims User Guide page.

6.1 Creating a new claim to Jakamo (A)

Push new claim from external system (e.g. from the ERP) to Jakamo.

Example A: Send a new claim (HTTP POST)

<Claim>
<ApiVersion>1</ApiVersion>
 <ClaimID>123</ClaimID>
 <Title>This is a title</Title> <!-- If Title is not set here, claimID will be set to title -->
 <!-- ISO 4217 currency code which applies to all the costs in the document -->
 <DocumentCurrencyCode>EUR</DocumentCurrencyCode>
 <!-- Company creating the claim, including the user -->
 <ClaimingParty>
    <ID>12345</ID>
    <ClaimingUser>
       <ID>user12345</ID>
    </ClaimingUser>
 </ClaimingParty>
 <!-- Company receiving the claim -->
 <ClaimedParty>
    <ID>67890</ID>
 </ClaimedParty>
 <!-- Reference to purchase order, including the confirmation number from supplier side -->
 <PurchaseOrder>
    <OrderNumber>PO12345</OrderNumber>
    <ConfirmationNumber>confirmation12345</ConfirmationNumber>
 </PurchaseOrder>
 <ProductNumber>PN12345</ProductNumber>
 <ProjectReference>PR12345</ProjectReference>
 <Defect>
    <!-- ISO 8601 standard format of "YYYY-MM-DD"-->
    <DefectDate>2018-01-01</DefectDate>
    <!-- ISO 8601 standard format "hh:mm:ss".-->
    <DefectTime>00:00:00</DefectTime>
    <!-- Possible defect types: one of the following:
         Assembly defect
         Component defect
         Design / Planning defect
         Documentation defect
         Equipment defect
         Handling or transportation defect
         Incomplete delivery
         Instruction defect
         Late delivery
         Machine defect
         Manufacturing defect
         Material defect
         Phase planning defect
         Safety
         Surface treatment
         System defect
         Work defect
         Wrong product
         Other defect-->
    <DefectType>Work defect</DefectType>
    <!-- One of "Comment / Improvement initiative", "Minor deviation", "Serious deviation" -->
    <DefectClassification>Minor deviation</DefectClassification>
    <DefectDescription>This is the description of the defect.</DefectDescription>
    <!-- Compensation or proposed actions for compensation -->
    <OtherCompensation>Repair of the surface.</OtherCompensation>
    <!-- Amount of claimed costs, the currency used is defined in the DocumentCurrencyCode element -->
    <ClaimedCosts>1200.00</ClaimedCosts>
    <!-- Amount of total costs (including internal costs), the currency used is defined in the DocumentCurrencyCode element -->
    <ClaimTotalCost>1200.00</ClaimTotalCost>
    <!-- Amount of items claimed -->
    <ClaimedItemCount>12</ClaimedItemCount>
    <!--  Unit of claimed items  -->
    <ClaimedItemUnit>PCS</ClaimedItemUnit>
    <!-- Hours used for inspecting the defect -->
    <InspectionHours>130</InspectionHours>
    <!-- Total loss hours -->
    <LossHours>330</LossHours>
 </Defect>
</Claim>

Defect type options

Please use only following defect types or leave the Claim/DefectType out of the Claim message. If defect type information is not provided in the message, Jakamo will show only "-" on the Jakamo UI.

Defect type options:

• Assembly defect
• Component defect
• Design / Planning defect
• Documentation defect
• Equipment defect
• Handling or transportation defect
• Incomplete delivery
• Instruction defect
• Late delivery
• Machine delivery
• Manufacturing defect
• Material defect
• Phase planning defect
• Safety
• Surface treatment
• System defect
• Work defect
• Wrong product
• Other defect

Defect classification options

Please use only following defect classifications or leave the Claim/DefectClassification out of the Claim message. If defect classification information is not provided in the message, Jakamo will show only "-" on the Jakamo UI.

Defect classification options:

• Comment / Improve initiative
• Serious deviation
• Minor deviation

6.2 Updating an existing Claim in Jakamo (B)

Push revised claim from external system (e.g. from the ERP) to Jakamo. This is used for sending the revised claim to Jakamo. This is used when it is necessary to correct an error in the claim data.

Example B: Updating a claim (HTTP PUT)

<ClaimChange>
<ApiVersion>1</ApiVersion>
 <ClaimID>123</ClaimID>
 <Title>This is a title</Title> <!-- If Title is not set here, claimID will be set to title -->
 <!-- ISO 4217 currency code which applies to all the costs in the document -->
 <DocumentCurrencyCode>EUR</DocumentCurrencyCode>
 <!-- Company creating the claim, including the user -->
 <ClaimingParty>
    <ID>12345</ID>
    <ClaimingUser>
       <ID>user12345</ID>
    </ClaimingUser>
 </ClaimingParty>
 <!-- Company receiving the claim -->
 <ClaimedParty>
    <ID>67890</ID>
 </ClaimedParty>
 <!-- Reference to purchase order, including the confirmation number from supplier side -->
 <PurchaseOrder>
    <OrderNumber>PO12345</OrderNumber>
    <ConfirmationNumber>confirmation12345</ConfirmationNumber>
 </PurchaseOrder>
 <ProductNumber>PN12345</ProductNumber>
 <ProjectReference>PR12345</ProjectReference>
 <Defect>
    <!-- ISO 8601 standard format of "YYYY-MM-DD"-->
    <DefectDate>2018-01-01</DefectDate>
    <!-- ISO 8601 standard format "hh:mm:ss".-->
    <DefectTime>00:00:00</DefectTime>
    <!-- Possible defect types: one of the following:
         Assembly
         Component defect
         Design / Planning defect
         Documentation defect
         Equipment defect
         Handling or transportation defect
         Incomplete delivery
         Instruction defect
         Late delivery
         Machine defect
         Manufacturing defect
         Material defect
         Phase planning defect
         Safety
         Surface treatment
         System defect
         Work defect
         Wrong product
         Other defect-->
    <DefectType>Work defect</DefectType>
        <!-- Possible defect classification types: one of following: Comment / Improvement initiative, Minor deviation, Serious deviation -->
    <DefectClassification>Minor deviation</DefectClassification>
    <DefectDescription>This is the description of the defect.</DefectDescription>
    <!-- Compensation or proposed actions for compensation -->
    <OtherCompensation>Repair of the surface.</OtherCompensation>
    <!-- Amount of claimed costs, currency used is defined in the DocumentCurrencyCode element -->
    <ClaimedCosts>1200.00</ClaimedCosts>
    <!-- Amount of total costs (including internal costs), currency used is defined in the DocumentCurrencyCode element -->
    <ClaimTotalCost>1200.00</ClaimTotalCost>
    <!-- Amount of items claimed -->
    <ClaimedItemCount>12</ClaimedItemCount>
    <!--  Unit of claimed items  -->
    <ClaimedItemUnit>PCS</ClaimedItemUnit>
    <!-- Hours used for inspecting the defect -->
    <InspectionHours>130</InspectionHours>
    <!-- Total loss hours -->
    <LossHours>330</LossHours>   
 </Defect>
</ClaimChange>

6.3 Updating a status of the claim in Jakamo (C)

Send a status message from external system to Jakamo. A claim status can be set with status messages. Statuses Cancelled, Accepted and Follow-up done can be set with StatusMessage. When setting Cancelled status, an entire claim will be cancelled. Status must be set also when defect response is accepted.

Example C: Updating a claim status (HTTP PUT)

<StatusMessage>
  <ClaimID>123</ClaimID>
      <!-- Possible claim statuses - One of the following:
          Cancelled
          Accepted
          Follow-up done -->
  <Status>Cancelled</Status>
</StatusMessage>

6.4 Retrieving "In progress" status update information from Jakamo (D)

Retrieve status message from Jakamo. When claimed company is start to process a claim in Jakamo, a claim will have status In progress. This status data is available in Claim API. Information might be useful, because it shows that something is happening to a claim.

Example D: Retrieving In progress status from Jakamo (HTTP GET)

<StatusMessage>
      <ApiVersion>1</ApiVersion>
        <ClaimID>123</ClaimID>
        <Status>In progress</Status>
</StatusMessage>

6.5 Retrieving a claim response information from Jakamo (E)

Retrieve a claim response from Jakamo. Claim responses are Claim messages with supplier response information (Defect Response).

Example E: Retrieved claim response from Jakamo (HTTP GET)

<Claim>
<ApiVersion>1</ApiVersion>
 <ClaimID>123</ClaimID>
 <!-- ISO 4217 currency code which applies to all the costs in the document -->
 <DocumentCurrencyCode>EUR</DocumentCurrencyCode>
 <!-- Claim status -->
 <Status>Completed</Status>
 <!-- Company creating the claim, including the user -->
 <ClaimingParty>
    <ID>12345</ID>
    <ClaimingUser>
       <ID>user12345</ID>
    </ClaimingUser>
 </ClaimingParty>
 <!-- Company receiving the claim -->
 <ClaimedParty>
    <ID>67890</ID>
 </ClaimedParty>
 <!-- Reference to purchase order, including the confirmation number from supplier side -->
 <PurchaseOrder>
    <OrderNumber>PO12345</OrderNumber>
    <ConfirmationNumber>confirmation12345</ConfirmationNumber>
 </PurchaseOrder>
 <ProductNumber>PN12345</ProductNumber>
 <ProjectReference>PR12345</ProjectReference>
 <Defect>
    <!-- ISO 8601 standard format of "YYYY-MM-DD"-->
    <DefectDate>2023-01-01</DefectDate>
    <!-- ISO 8601 standard format "hh:mm:ss".-->
    <DefectTime>00:00:00</DefectTime>
    <!-- One of the following:
       Work defect
       Material defect
       .... -->
    <DefectClassification>Minor deviation</DefectClassification>
    <DefectDescription>This is the description of the defect.</DefectDescription>
    <!-- Compensation or proposed actions for compensation -->
    <OtherCompensation>Repair of the surface.</OtherCompensation>
    <!-- Amount of claimed costs, currency used is defined in the DocumentCurrencyCode element -->
    <ClaimedCosts>1200.00</ClaimedCosts>
    <!-- Amount of total costs (including internal costs), currency used is defined in the DocumentCurrencyCode element -->
    <ClaimTotalCost>1200.00</ClaimTotalCost>
    <!-- Amount of items claimed -->
    <ClaimedItemCount>12</ClaimedItemCount>
    <!--  Unit of claimed items  -->
    <ClaimedItemUnit>PCS</ClaimedItemUnit>
    <!-- Hours used for inspecting the defect -->
    <InspectionHours>130</InspectionHours>
    <!-- Total loss hours -->
    <LossHours>330</LossHours>  
 </Defect>
 <!-- Claim response created by the claimed party -->
 <DefectResponse>
    <!-- Process phase, needs to be one of the following:
          Assembly
          Component manufacturing
          Delivery
          ...... -->
    <ProcessPhase>Component manufacturing</ProcessPhase>
    <!-- Agreed compensation in the currency defined by DocumentCurrencyCode -->
    <AgreedCompensation>1000.00</AgreedCompensation>
    <CauseAnalysis>This is a free-text field for the cause analysis of this defect.</CauseAnalysis>
    <CorrectiveActions>This is a free-text field for listing the corrective actions.</CorrectiveActions>
    <PrecautionaryActions>This is a free-text field for listing the precautionary actions.</PrecautionaryActions>
    <FollowupActions>This is a free-text field for listing the followup actions.</FollowupActions>
    <!-- ISO 8601 standard format of "YYYY-MM-DD"-->
    <FollowupDate>2018-06-01</FollowupDate>
    <!-- Reference added for this claim by the claimed party -->
    <VendorReference>CLAIM1234</VendorReference>
    <!-- Referenced material of the claimed party -->
    <VendorMaterialID>MAT123</VendorMaterialID>
 </DefectResponse>
</Claim>

7. User and company mappings in the Jakamo integration settings

Mapping configurations to identify customer (ClaimingParty) and supplier (ClaimedParty) 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 in the User Guide.

7.1 User mapping – Map your ERP users to your Jakamo users

ERP users (buyers, purchasers, supplier responsibles) who will create claims via Jakamo must have their personal user accounts in Jakamo. User has to have some identifier (string, email address, username, buyer number…) in the ERP, and that identifier will be transferred in the Claim XML data (Claim/ClaimingParty/ClaimingUser/ID). This ERP identifier must be linked to the Jakamo user so that Jakamo can identify the message sender. The Claim integration requires passing this user information in the Claim message when making new claim or claim change.

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 that you send in Claim/ClaimingParty/ClaimingUser/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. It is not used in claim integration.

7.2. 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 Claim XML data (Claim/ClaimedParty/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 Claim/ClaimedParty/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 can be determined to separate customer company's different sites while creating the company mapping. See more information on the integrations instruction page on Jakamo User Guide.

Help & Support

Didn't you find what you were looking for? Send email to Jakamo support (support@thejakamo.com) and we will help you.