# 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.

Source: /docs/guides/cargowise-integration

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

1. An AR invoice, credit note or debit note is posted in CargoWise.
2. eAdaptor (SOAP) or eAdaptor Next (REST) pushes the Universal XML to Alya Books's endpoint.
3. 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.
4. A processed invoice is submitted to the service provider; the FTA status arrives within minutes.
5. Alya Books reports each status change by webhook (or your side polls), with the XML and PDF available by download link.
6. Later phase: Alya Books writes the status and documents back into the CargoWise job (see [What comes later](#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](/docs/guides/erp-intake#what-the-cargowise-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](/docs/reference/erp-replies). 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](/docs/guides/erp-intake) | The endpoint, the connector settings, the message log, replays and the dry run |
| [CargoWise field mapping](/docs/reference/cargowise-field-mapping) | Every element Alya Books reads, the PINT AE term it fills and the rule that checks it ([CSV](/docs/downloads/cargowise-field-mapping.csv)) |
| [Charge-code template](/docs/downloads/cargowise-charge-map-template.csv) | 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](/docs/reference/erp-replies) | Status codes, reply bodies, duplicates, retries and the error format |
| [Status updates back to the ERP](/docs/guides/erp-status-updates) | Webhooks or polling for submitted, reported and rejected, with the XML and PDF |
| [Testing a CargoWise integration](/docs/guides/cargowise-testing) | Set-up, the smoke test, the test console and the sign-off checklist |
| [API reference](/docs/api-reference/introduction) | Every endpoint; the OpenAPI file is at `{BASE}/openapi.json` and a Postman collection at [/docs/api.postman_collection.json](/docs/api.postman_collection.json) |
| [Errors](/docs/reference/errors) and [PINT AE fields](/docs/reference/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](/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:

1. The forwarder's finance team fills the [charge-code template](/docs/downloads/cargowise-charge-map-template.csv): 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` …).
2. The audit firm reviews it against the forwarder's transaction types.
3. 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

1. 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.
2. Which outbound authentication you will configure: Basic with our key, OAuth client credentials, or none plus an IP allowlist.
3. The header or field carrying your message id, the reply eAdaptor Next expects on success, and its retry behaviour.
4. Anonymised sample messages: a standard AR invoice, a credit note against it, a foreign-currency invoice, and one with shipment details and Incoterms.
5. 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.