Testing a CargoWise integration

For the Alya Books team and the integrator. It says which environment to use, how to set it up, and how to prove that the endpoint, the mapping, the submission, the webhooks and the documents work before anything goes live.

Environments

The same API and organisation serve all three; the API key and the organisation's e-invoicing connection decide what happens.

• A test key only creates test documents (isTest: true), excluded from reports and the VAT return.
• A test document cannot be submitted while the connection is live (400), so a test key is safe to hand to an integrator.
• Live keys are issued by the organisation owner when go-live is signed off.

Set-up

1. Organisation. A test organisation with a complete company profile: name, TRN, trade licence, address with emirate, Peppol ID, bank IBAN and account name. The seller side of every invoice comes from here.
2. Connection. Admin → E-invoicing → Connection: Test (simulated), scenario accept.
3. API key. API access → API keys → New key, type Test, scopes invoices:read, invoices:write, settings:read, settings:write, webhooks:manage. The key is shown once.
4. CargoWise connector. Connectors → CargoWise → Configure:
   • the charge map (load the sample codes from the test console (/console on the Alya Books site) with Add the sample charge codes, or from the forwarder's filled template);
   • Submit on receipt on, so a processed message is submitted at once;
   • PDF design: a design with the Logistics layout, so the job number, house bill and Incoterms print in a Shipment panel.
5. Custom fields. Settings → Custom fields: job, house_bill, branch as text fields in the invoice template, so the references from the message are validated and shown.
6. Webhook receiver. For a first run, a public https inbox such as webhook.site. Private addresses and plain http are refused.

The smoke test

scripts/sandbox/cargowise-smoke.sh (from the Alya Books repository, or ask us for it) runs the flow against a test key and reports PASS, FAIL or SKIP per check. It refuses live keys.

API_BASE={BASE} \
API_KEY=sk_test_… \
WEBHOOK_URL=https://webhook.site/<your-id> \
scripts/sandbox/cargowise-smoke.sh

Outputs (replies, status, XML, PDF) are written to scripts/sandbox/out/. On level 1 the run takes under a minute. On level 2 step 4 waits for the provider's test system; rerun the status call if the script times out.

Then switch the connection's scenario to reject_taxilla, reject_buyer and reject_fta in turn and confirm the invoice ends rejected, the status carries the reason, and an invoice.rejected webhook arrives. That is what the write-back must handle.

The test console

The test console (/console on the Alya Books site) covers the same ground by clicking:

• In the browser, without a key: each sample through the same reader, mapper and rules as the API.
• Your sandbox, with the test key: check the connection, add the sample charge codes (only missing codes are added), and send single requests (dry run, ERP intake, POST /invoices) with every failed rule explained.
• Dummy data feed: up to 200 freight documents in CargoWise XML or JSON, a chosen share with planted mistakes (mistyped TRN, unmapped charge code, 5 % on zero-rated freight, credit note without a reason), each checked against what it must produce; with send each twice, every resend must answer duplicate.
• Status and webhooks: follow an invoice to accepted or rejected and read the webhook deliveries.

The key stays in the page's memory and is never shown in the log; live keys are refused.

What the integration team tests

1. Your transport. Configure eAdaptor or eAdaptor Next exactly as for production and post a real AR invoice in CargoWise UAT. It must arrive as one Alya Books invoice with the right lines, VAT categories, references and currency. The reply and the message log show how it arrived (envelope) and your message id.
2. Failures. Post an invoice with a charge code missing from the map. The reply is 400 (or 202 failed with always-acknowledge) naming the code. Map it, then resend or replay: it is processed.
3. Duplicates. Send the same invoice twice: one invoice, the second reply duplicate.
4. Credit notes. Post a credit note with its reason against the test invoice: the preceding reference is carried and it is accepted.
5. Foreign currency. Bill in USD with the AED rate and check the AED tax amounts in the XML.
6. Status back. Handle invoice.reported and invoice.rejected (or poll the status): attach the XML and PDF to the job and set its e-invoice status; on a rejection, show the rule and message to the person who posted it.
7. Webhook signature. Verify X-Webhook-Signature on a delivery and reject timestamps older than five minutes.

Sign-off checklist

• Smoke test passes on level 1 with scenario accept, and ends rejected for each rejection scenario.
• Smoke test passes on level 2 (provider UAT): status accepted with the acknowledgements on the invoice timeline.
• Every transaction type in the forwarder's signed readiness matrix has been posted from CargoWise UAT and accepted.
• The charge map is complete and signed off by the audit firm.
• Failures, duplicates, credit notes and foreign currency behave as above.
• Status back (webhooks or polling) handled for accepted and rejected invoices; signatures verified; the receiver answers 2xx within 10 seconds.
• The PDF design approved by the forwarder.