ERP push connectors (CargoWise and JSON)
Let your ERP post invoices straight to Alya Books: set the charge map, have it signed off, and follow every message in the log.
An ERP push connector gives your ERP one address to post invoices to. Alya Books stores each message, maps it to an e-invoice, validates it against the UAE rules, creates and submits the invoice, and keeps the message so it can be replayed after a fix. Two connectors exist:
- CargoWise: reads the UniversalTransaction XML that CargoWise's eAdaptor sends when an AR invoice or credit note is posted.
- JSON: for middleware that already speaks Alya Books's invoice JSON and wants the same log, duplicate detection and replay.
You find them under Connectors → ERP push connectors. Owners and admins can change settings and replay messages; everyone else can view.
Give the ERP its address
Each card shows the endpoint to configure in the ERP. Copy it with the button next to it. The ERP authenticates with a Alya Books API key (API access in the menu): either the X-API-KEY header, or HTTP Basic authentication with any user name and the key as the password, which is what CargoWise's outbound tab offers. Use a test key while integrating; the invoices it creates are test documents and never reach the live service provider.
Set the charge map
Click Configure on the card. The Charge map tab has one row per charge code as the ERP posts it:
| Column | What to enter |
|---|---|
| Charge code | The code exactly as the ERP sends it (FRT, THC, DUTY). Case does not matter. |
| VAT category | Standard rated, zero rated, exempt, reverse charge, out of scope or profit margin. |
| Item type | S for a service, G for goods, B for both, or not stated. |
| Service / HS code | The service accounting code for services, the HS code for goods. The e-invoice needs one when the item type is stated. |
| Exemption code | For exempt charges only: DL8.46.1 to DL8.46.4. |
| Transaction type | A transaction type the charge implies for the whole invoice, for example Exports. |
| Label | A name for your own reference. |
A charge code that is not in the map is resolved by the VAT codes tab (the ERP's own VAT code, for example Z or S), then by Alya Books's built-in list of common VAT codes, then by the default category. When nothing decides, the message fails and names the charge code, so a new charge code in the ERP never slips through as the wrong VAT treatment. We recommend leaving the default category on "None".
Duplicate charge codes are flagged in red and cannot be saved.
Choose what happens on receipt
The On receipt tab:
- Submit on receipt: on, the invoice is created and submitted to the service provider in one step. Off, it is created as a validated draft for someone to submit from Alya Books.
- Always acknowledge: on, the endpoint answers success even when a message cannot be processed, so a push transport that retries on any error does not loop. The failure stays in the log.
- Refuse live messages until signed off: on, messages from a live key are refused while the mapping is not signed off. Test documents are always accepted.
- Message fields kept as custom fields: the job, house bill and branch from the message are stored on the invoice as custom fields. Define the same keys under Settings → Custom fields so they are validated and shown.
- PDF design for these invoices: the design the connector's invoices use; choose one with the Logistics layout to print the job number and house bill in a Shipment panel. Without a choice, the organisation's default design applies.
How messages may arrive
The CargoWise address accepts the Universal XML however the integrator configures eAdaptor or eAdaptor Next: as plain XML, in a SOAP envelope, inside JSON, base64-encoded or compressed. Open a message in the log to see Received as and the Sender's message id.
Sign the mapping off
The charge map decides VAT treatment, so it is a tax decision. On the Sign-off tab the adviser who reviewed the map clicks Sign off this mapping as me; the card then shows who signed and when. Withdraw sign-off clears it when the map should be reviewed again, for example after new charge codes were added.
Follow the message log
Messages on a card, or Message log above the cards, lists every message with its outcome:
| Status | Meaning |
|---|---|
| Processed | The invoice was created (and submitted when that is on). The invoice number links to it. |
| Duplicate | The same document was received before. Nothing was created; the earlier invoice is referenced. |
| Failed | The message could not be mapped (unknown charge code, missing customer) or the invoice failed a rule. The reason, the rule, the fix and a link to the rule's explanation are shown. |
| Received | Being processed. |
Open a message to see the reason, the mapping notes, the raw message as the ERP sent it, and the invoice it created. After you fix the charge map or the customer master, open the failed message and click Replay now. A message whose document was processed since cannot be replayed, so a replay never creates a duplicate.
Every outcome is written to the audit log, and the usual invoice notifications and webhooks fire as for any invoice.
Check a message before the ERP sends it
Developers can dry-run a message with the API (POST /invoices/validate?connector=cargowise): it maps and validates without creating anything and returns the report with a preview of the mapped invoice. See the developer guide "ERP intake".