CargoWise integration kit

Everything a CargoWise integrator needs to connect eAdaptor or eAdaptor Next to Alya Books: the endpoint, authentication, environments, the documents to read, what Alya Books needs from you, and what comes later.

View as Markdown Open in Claude Open in ChatGPT

This kit is for the team configuring a freight forwarder's CargoWise to report its UAE e-invoices through Alya Books. CargoWise keeps posting AR invoices as it does today. eAdaptor or eAdaptor Next pushes each one to Alya Books, which validates it against PINT AE, submits it to the accredited service provider for reporting to the FTA, renders the PDF and tells your side the outcome.

How it fits together

An AR invoice, credit note or debit note is posted in CargoWise.
eAdaptor (SOAP) or eAdaptor Next (REST) pushes the Universal XML to Alya Books's endpoint.
Alya Books stores the message, maps it through the organisation's charge map, validates it and answers at once: processed, duplicate or failed with the reasons.
A processed invoice is submitted to the service provider; the FTA status arrives within minutes.
Alya Books reports each status change by webhook (or your side polls), with the XML and PDF available by download link.
Later phase: Alya Books writes the status and documents back into the CargoWise job (see What comes later).

The endpoint

POST {BASE}/erp/cargowise/messages

{BASE} is the API address we send you with your test key. The same endpoint serves every environment; the key decides which one.

Body: the Universal XML in whatever shape your transport delivers: bare UniversalInterchange or UniversalTransaction, a SOAP envelope, a JSON wrapper, base64, gzip or a form post. Any Content-Type is accepted. See What the endpoint accepts.
Authentication: HTTP Basic with any user name and the API key as the password, or the header X-API-KEY. OAuth client credentials can be added if your outbound configuration requires it; tell us.
Message id: send yours in X-Message-Id (or MessageId in a JSON wrapper, or the SOAP header). Alya Books stores it and returns it, so both sides can trace a document.
Replies: see Replies to the ERP. With ?ack=always every message is acknowledged with 2xx and failures stay in the log, for transports that retry on any error.

Environments

Environment	Key	What happens on submit
Simulated	`sk_test_…`	Alya Books plays the service provider and the FTA. Statuses and webhooks are real; nothing leaves Alya Books.
Provider test (UAT)	`sk_test_…`	The invoice goes to the service provider's test system. Nothing reaches the live FTA.
Live	`sk_live_…`	Real reporting to the FTA. Issued by the organisation owner when go-live is signed off.

A test key only ever creates test documents, which are excluded from VAT reports and cannot be submitted live.

Read these

Document	What it gives you
ERP intake guide	The endpoint, the connector settings, the message log, replays and the dry run
CargoWise field mapping	Every element Alya Books reads, the PINT AE term it fills and the rule that checks it (CSV)
Charge-code template	The sheet the forwarder's finance team fills: charge code → VAT treatment. It becomes the connector's charge map, signed off by the tax adviser
Replies to the ERP	Status codes, reply bodies, duplicates, retries and the error format
Status updates back to the ERP	Webhooks or polling for submitted, reported and rejected, with the XML and PDF
Testing a CargoWise integration	Set-up, the smoke test, the test console and the sign-off checklist
API reference	Every endpoint; the OpenAPI file is at `{BASE}/openapi.json` and a Postman collection at /docs/api.postman_collection.json
Errors and PINT AE fields	What each rule means and how to fix it

Every page is also plain Markdown at its address plus .md, and the whole site is in /docs/llms-full.txt for your developers' AI tools.

The charge map

CargoWise charge codes decide each line's VAT treatment, so they are mapped once per organisation, before the first live message:

The forwarder's finance team fills the charge-code template: VAT category (standard, zero_rated, exempt, reverse_charge, out_of_scope, margin), item type (S service, G goods, B both), the service accounting code or HS code, an exemption reason code where needed, and a UAE transaction type where one applies (exports, free_trade_zone, disclosed_agent …).
The audit firm reviews it against the forwarder's transaction types.
It is loaded in Alya Books (Connectors → CargoWise → Configure, or PUT {BASE}/erp/connectors/cargowise) and signed off. Live messages can be refused until the sign-off exists.

An unmapped charge falls back to the line's VAT code; when nothing decides, the message fails and names the code, so no invoice is reported with a guessed treatment.

What we need from you

How eAdaptor Next delivers the outbound message: bare XML, JSON wrapper or SOAP, and the Content-Type. Alya Books accepts all of them; we want to test the one you will use.
Which outbound authentication you will configure: Basic with our key, OAuth client credentials, or none plus an IP allowlist.
The header or field carrying your message id, the reply eAdaptor Next expects on success, and its retry behaviour.
Anonymised sample messages: a standard AR invoice, a credit note against it, a foreign-currency invoice, and one with shipment details and Incoterms.
For the write-back phase: the EDI client registration Alya Books needs in CargoWise (token address, certificate, message type for status and eDocs), and access to a test CargoWise instance.

What comes later

Write-back into CargoWise. Alya Books posts the FTA status, the PINT AE XML and the PDF back to the job through eAdaptor's inbound interface. It needs the registration in point 5 above.
The forwarder's approved PDF layout. Today invoices use Alya Books's standard or logistics layout (job number, house bill and Incoterms in a Shipment panel); the forwarder's approved layout can be rebuilt as a Alya Books design.
OAuth client credentials for the endpoint, if your configuration needs them.

Support

Send questions, sample messages and test results to your Alya Books contact. Include the message id or the Alya Books message id from the reply; every message is kept in the log with its raw body, so we can see exactly what arrived.