File Callback API

1. Overview

File Callback API provides suppliers access to order documents without having to upload them as attachments in Jakamo. To utilize this functionality, provide an API that can respond to queries with the following format:

GET [base_url]/materials/documents?materialId=[item_id]&revision=[revision]

File Callback API Usage

The usage of the File Callback API depends on the capabilities of the client's system and the integration developer.

Case 1:

1. Jakamo authenticates itself with the PDM system.
2. The PDM system returns all data related to the specified item to Jakamo.
   • Jakamo does not verify the accuracy of the drawings. It is the client's responsibility to ensure that the PDM system's data is correct.
   • All supplier users can view the specified document information related to the items in the orders within the customer relationship.

Authentication occurs through the order via Jakamo. External parties cannot view the information behind the PDM link; only the buyer and seller involved in the order have access.

Example:

https://www.example.com/api/v1/materials/documents?materialId=55-554354&revision=120 would fetch files for item number 55-554354 revision 120.

The revision parameter is optional. If a revision parameter is not provided, the latest revision should be returned.

Expected data format:

{
   "data":[
   {
      "fileName": "File1.pdf",
      "description":"File1",
      "type":"Drawing",
      "link": "https://www.example.com/api/item/55-554354/file1.pdf"
   },
   {
      "fileName": "File2.xml",
      "description":"File2",
      "type": "Specification",
      "link": "https://www.example.com/api/item/55-554354/file2.xml"
   }
   ]
}

Links should point to the same base domain as the initial query and have the same authentication method.

2. How Jakamo Determines What to Query

When a user opens an order line and fetches documents, Jakamo sends the query to your API automatically. The values used in the query come from the order line fields in Jakamo:

Query parameter	Source in Jakamo
materialId	Item number field on the order line
revision	Revision field on the order line

The revision is always read from the dedicated Revision field — not from the description or any other free-text field.

If the Revision field on the order line is empty, Jakamo sends the query without a revision parameter. Whether your PLM returns results in that case depends on how your API is implemented (see recommendation in Section 1: return the latest revision when no revision is provided).

Documents not appearing?

If documents are not showing up for an order line, check that the Revision field is populated on that line — not just the description or info text. Text entered in description fields is not passed to the file query.

3. Authentication

API key authentication in a header is currently supported. Both the file listing query and the actual file fetching should use the same authentication method.

The header name and API key value are configured in the Jakamo integration settings (api_key_header and api_key). Jakamo sends the same header on:

• GET {base_url}/materials/documents?... (file listing)
• GET {link} (file download — the URL from each item in the data array)

Your API is responsible for validating the key and, if needed, authenticating to your PDM backend (for example Sensei) before returning files.

4. Error handling and HTTP status codes

Use normal HTTP status codes. You do not need to return HTTP 200 for every response.

Recommended responses

Situation	HTTP status	Response body	What the user sees in Jakamo
Request OK, files found	200	{ "data": [ ... ] }	File list with download links
Request OK, no documents for this material/revision	200	{ "data": [] }	No files found for this item number!
Invalid or missing API key	401 or 403	Optional error body	Unable to display files at this time. Try again later.
Your server or PDM backend unavailable	500 or 502	Optional error body	Unable to display files at this time. Try again later.
Material/revision not found	200 + "data": [] recommended	See note below	No files found for this item number!

Do not use HTTP 200 with an empty list for authentication failures

If authentication fails, return 401 or 403. Returning 200 with { "data": [] } will look like “no files” in Jakamo, which is misleading.

Material or revision not found

If you return 404 Not Found, Jakamo currently treats it as a technical error (same generic message as 500), not as “no files found”.

For “valid request, but no documents exist”, return HTTP 200 with an empty data array.

Response body for a successful listing (200)

Each object in data must include:

Field	Required	Notes
fileName	Yes
link	Yes	URL Jakamo calls to download the file (same auth header as the listing)
description	Yes	May be an empty string ""
type	No	Optional, shown in the file list when provided

Example with no files:

{
  "data": []
}

If the body is not valid JSON, or required fields are missing, Jakamo shows the same generic error as for server failures.

File download errors

When the user downloads a file, Jakamo calls the link URL with the same API key header. If that request fails, the user sees: Could not download file.

What Jakamo does not do today

• Jakamo does not show different messages for 401, 404, and 500 on the listing request — non-success responses all use the same generic text.
• Jakamo does not expose your HTTP status code or error body to end users.

Clear status codes are still recommended for your own logging and for troubleshooting during integration setup.

5. API reference

Full API reference in OpenAPI 3.0 format: File callback API reference

Help & Support

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