CargoWise

CargoWise Invoice Intake

Copy page

CargoWise Plugin — Invoice Intake

The CargoWise Invoice Intake endpoint receives invoice documents from CargoWise-integrated logistics systems and processes them through the eTIMS compliance pipeline. Documents are converted to the VSCU format required by KRA, submitted for validation, and a stamped output document is returned to the originating system.

What is CargoWise?

CargoWise is a global logistics execution platform used for freight forwarding, customs brokerage, and supply chain management. For each invoice transaction it generates two independent XML documents:

Document	Role
XUT	Invoice trigger — contains the shipment and invoice data (transaction XML)
XUD	Invoice document — the document XML accompanying the transaction

These two files are transmitted separately and independently from CargoWise. Either one may arrive before the other. The intake API handles this out-of-sequence delivery automatically.

---

Overview

The end-to-end flow for a CargoWise invoice submission:

1. CargoWise exports the XUT (and/or XUD) for an invoice transaction.
2. Each document is submitted to the Intake API as it becomes available.
3. The platform authenticates the request (OAuth 2.0), stores the document, and waits for its pair.
4. Once both documents are received and paired, the job status advances to READY and processing begins.
5. The platform converts the XUT data into VSCU format — the KRA-compatible tax data structure.
6. The converted data is submitted to KRA for validation and signing.
7. KRA returns a signed response; the platform stamps the invoice and produces the final XUD output.
8. The stamped XUD is returned to the originating system.

---

Document Sequencing

XUT and XUD are independent files that will transmit separately from CargoWise. Either document may arrive before the other. The API is designed to handle this gracefully:

Scenario	Behaviour	Job Status
XUT arrives, XUD not yet received	Document stored; waiting for pair	WAITING_FOR_XUD
XUD arrives, XUT not yet received	Document stored; waiting for pair	WAITING_FOR_XUT
Second document arrives	Documents paired; processing triggered	READY
Both submitted in a single request	Paired immediately; processing triggered	READY

Important: While out-of-sequence arrival is handled automatically, a scenario where one document arrives and its pair never follows is not expected behaviour. If a job remains in WAITING_FOR_XUT or WAITING_FOR_XUD for an extended period, an investigation should be opened with the sending system.

Duplicate XUT Submissions

CargoWise may send the same XUT document more than once. The platform validates the invoice number on every submission to prevent duplicate processing. Always ensure your XUT contains a consistent, unique invoice number per transaction.

---

Invoice Intake Endpoint

Endpoint Details

Property	Value
Method	POST
URL	{{base_url}}/api/invoice/intake/
Base URL	https://adapters.erp.release.slade360edi.com
Content-Type	multipart/form-data
Authentication	Bearer Token (OAuth 2.0)

---

Headers

Header	Value	Required	Description
Authorization	Bearer <access_token>	Yes	OAuth 2.0 Bearer token
Idempotency-Key	{{$guid}}	Recommended	A unique UUID per request to prevent duplicate processing

Idempotency Keys

Always supply a unique Idempotency-Key (e.g., a UUID v4) for each intake request. If the same key is used on a retry, the server returns the original response without reprocessing. This prevents duplicate submissions in the event of network errors or timeouts.

---

Request Body

The request body must be sent as multipart/form-data with the following fields:

Field	Type	Required	Description
xut	File	Conditional	The XUT invoice trigger XML from CargoWise (shipment and invoice data)
xud	File	Conditional	The XUD invoice document XML from CargoWise
source	Text	Yes	Identifier for the originating system (e.g., CARGOWISE, POSTMAN_TEST)

Note: At least one of xut or xud must be provided. Both can be submitted in the same request, or each can be submitted independently as they become available.

Example File Naming Convention

CargoWise-generated files follow the pattern:

Code
 
UDM_TRX_XDC_<sequence_number>_<document_identifier>

For example:

• UDM_TRX_XDC_000000000001343490_0000000000001... (XUT file)
• UDM_TRX_XDC_000000000001111911_0000000000001... (XUD file)

Example Request — Submitting Both Documents

Code
 
curl --request POST \
  --url https://adapters.erp.release.slade360edi.com/api/invoice/intake/ \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  --form 'xut=@/path/to/UDM_TRX_XDC_0000000000015826490.xml' \
  --form 'xud=@/path/to/UDM_TRX_XDC_0000000000015826491.xml' \
  --form 'source=CARGOWISE'

Example Request — Submitting XUT Only (XUD to follow)

Code
 
curl --request POST \
  --url https://adapters.erp.release.slade360edi.com/api/invoice/intake/ \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001' \
  --form 'xut=@/path/to/UDM_TRX_XDC_0000000000015826490.xml' \
  --form 'source=CARGOWISE'

---

Responses

202 Accepted — Document Received

The API responds with 202 Accepted as soon as a document is stored. The status field indicates whether both documents have been paired or whether the job is waiting for its counterpart:

Code
 
{
    "job_id": "31fdf049-1b29-40fa-be16-9dc5eb164d66",
    "correlation_id": "sha256:e6d792462237ec5f7d03e96b9b039b512546efdb95bb98d744007696014b5c5d",
    "status": "READY"
}

Field	Type	Description
job_id	UUID	Unique identifier for this document pair's processing job. Use this to track progress.
correlation_id	String	SHA-256 hash for tracing the request through the system. Include this when contacting support.
status	String	Current state of the job. See status values below.

Job Status Values

Status	Meaning
WAITING_FOR_XUD	XUT received and stored; waiting for the XUD document to arrive.
WAITING_FOR_XUT	XUD received and stored; waiting for the XUT document to arrive.
READY	Both documents received and paired; processing has been triggered.

Asynchronous Processing

202 Accepted means the document has been received — not that processing is complete. A status of READY means both documents are paired and the pipeline has started. Use the job_id to monitor progress until KRA submission is confirmed.

---

400 Bad Request — Missing Document

If neither xut nor xud is provided, the API returns:

Code
 
{
    "non_field_errors": [
        "Provide at least one of xut or xud."
    ]
}

Resolution: Include at least one of xut or xud in the request.

---

Common Error Codes

Status Code	Error	Resolution
400	Provide at least one of xut or xud.	Include at least one file (xut or xud) in the request.
401	Unauthorized	Your Bearer token is invalid or expired. Obtain a new token.
409	Conflict (duplicate Idempotency-Key)	The key was already used; the original response is returned.
422	Unprocessable Entity	The file is malformed or does not conform to the expected XUT/XUD schema.
500	Internal Server Error	Contact Slade360 support with your correlation_id.

---