CargoWise field mapping
Every UniversalTransaction element Alya Books reads, the API field and PINT AE term it fills, whether it is required, and the rule that checks it.
Alya Books reads the Universal XML that eAdaptor sends for an AR transaction. WiseTech publishes the schema to licensees only, so the reader is deliberately tolerant: namespaces and envelopes are ignored, several spellings are read for each element (in brackets), and anything not listed here is ignored. Download the table as CSV.
The seller (name, TRN, address, Peppol ID, bank details) always comes from the organisation's profile in Alya Books, never from the message. Lines get their VAT treatment from the connector's charge map; see the charge-code template.
Check a message without creating anything: POST {BASE}/invoices/validate?connector=cargowise with the message as the body returns the mapped invoice, the notes and every failed rule.
Document
| CargoWise element | Required | Alya Books field | PINT AE | Rule or behaviour |
|---|---|---|---|---|
| TransactionInfo/Number (TransactionNumber; InvoiceNumber) | Yes | invoiceNumber | BT-1 Invoice number | Unique per seller. With the branch and type it forms the message key cargowise: |
| TransactionInfo/TransactionType (TransactionType/Code; Type) | No (default INV) | invoiceTypeCode | BT-3 Invoice type code | INV, ARI, AR → 380 tax invoice; CRD, CRN, ARC → 381 credit note; DBN, DEB → 383 debit note; or a 3-digit code. Anything else is refused. |
| TransactionInfo/TransactionDate (PostDate; InvoiceDate) | Yes | issueDate | BT-2 Issue date | YYYY-MM-DD or DD/MM/YYYY. |
| TransactionInfo/DueDate (PaymentDueDate) | Yes for invoices with a payment due | dueDate | BT-9 Payment due date | Missing due date fails IBR-127-AE unless payment terms are given. |
| TransactionInfo/Currency/Code (Currency; LocalCurrency/Code) | No (default AED) | currency | BT-5 Invoice currency code | ISO 4217. |
| TransactionInfo/ExchangeRate (LocalExchangeRate) | For non-AED invoices | exchangeRate | BT-111 / AED tax totals | When absent, Alya Books uses the UAE Central Bank rate for the date of supply (the issue date when no supply date is given). |
| TransactionInfo/Branch/Code (Branch; BranchCode) | No | metadata.branch | — | Part of the message key; printed in the logistics Shipment panel. |
| TransactionInfo/JobNumber (Job/Key; Job/JobNumber; JobKey) | No | metadata.job | — | Kept as a custom field and in the invoice note; printed in the logistics Shipment panel. |
| TransactionInfo/HouseBill (HouseBillNumber; Shipment/HouseBill) | No | metadata.house_bill | — | Kept as a custom field and in the invoice note; printed in the logistics Shipment panel. |
| TransactionInfo/ShipmentIncoTerm/Code (IncoTerm/Code; Incoterms; or Shipment/ShipmentIncoTerm/Code) | No | incoterms | Delivery terms (cac:DeliveryTerms) | EXW, FCA, CPT, CIP, DAP, DPU, DDP, FAS, FOB, CFR, CIF. An unknown code is left out with a note. |
| TransactionInfo/OriginalTransactionNumber (ReferenceTransactionNumber; AppliedInvoiceNumber) | Yes for credit and debit notes | precedingInvoice.number | BT-25 Preceding invoice reference | |
| TransactionInfo/OriginalTransactionDate (ReferenceTransactionDate) | Yes for credit and debit notes | precedingInvoice.issueDate | BT-26 Preceding invoice issue date | |
| TransactionInfo/CreditNoteReason (CreditNoteReason/Code; ReasonCode; CreditReason) | Yes for credit notes | creditNoteReasonCode | BTAE-03 Credit note reason | Alya Books never guesses a tax reason; a credit note without one fails validation. |
| TransactionInfo/PK (Key; TransactionKey) | No | — | — | Kept as a note on the message for tracing. |
Buyer
| CargoWise element | Required | Alya Books field | PINT AE | Rule or behaviour |
|---|---|---|---|---|
| Organization/FullName (Name; CompanyName; OrganizationName) | Yes | buyer.name | BT-44 Buyer name | The Organization block is the customer of the AR transaction. |
| Organization/RegistrationNumber with Type TRN|VAT|TAXREG (or TRN; TaxRegistrationNumber; VATNumber) | Yes for VAT-registered UAE buyers | buyer.trn | BT-48 Buyer VAT identifier | 15 digits. A UAE buyer needs a TRN or a legal registration (IBR-135-AE). |
| Organization/Code (OrganizationCode) | No | buyer.externalId | — | Matches the Alya Books customer created for this CargoWise organisation. |
| Organization/Email (Contact/Email) | No | buyer.email | — | Used to send the invoice when sending is on. |
| Address/Address1 (AddressLine1; Street) | Yes for UAE buyers | buyer.address.street | BT-50 Buyer address line 1 | IBR-144-AE needs street; city and emirate. |
| Address/Address2 (AddressLine2) | No | buyer.address.additional | BT-51 Buyer address line 2 | |
| Address/City (CityOrSuburb) | Yes for UAE buyers | buyer.address.city | BT-52 Buyer city | |
| Address/State/Code (State; Emirate) | Yes for UAE buyers | buyer.address.emirate | BT-54 Buyer country subdivision | Emirate code or name, e.g. DXB or Dubai. |
| Address/Postcode (PostCode; PostalCode) | No | buyer.address.postalCode | BT-53 Buyer post code | |
| Address/Country/Code (CountryCode; Country) | Yes | buyer.address.country | BT-55 Buyer country code | AE is assumed when a TRN is present. |
Lines
| CargoWise element | Required | Alya Books field | PINT AE | Rule or behaviour |
|---|---|---|---|---|
| PostingJournalCollection/PostingJournal (TransactionLineCollection/TransactionLine; InvoiceLineCollection/InvoiceLine; ChargeLineCollection/ChargeLine) | At least one | items[] | BG-25 Invoice line | |
| ChargeCode (ChargeCode/Code; ChargeLine/ChargeCode; Code) | Yes | charge map key | BT-151 VAT category; item type (G, S, B); service or HS code | Looked up in the connector's charge map (VAT category, item type, service accounting code, HS code, exemption reason, transaction type). |
| VATCode (VATCode/Code; TaxCode; Tax/Code; VAT/Code) | Fallback | items[].taxCategory | BT-151 Invoiced item VAT category | Used only when the charge code is not mapped: the connector's VAT-code map, then S/STD/5/VAT5 standard, Z/ZR/ZERO zero rated, E/EX/EXEMPT exempt, O/OS/OOS/NA/DISB out of scope, RC/RCM/AE reverse charge, then the connector's default category. Otherwise the message fails and names the code. |
| Quantity (ChargeLine/Quantity) | No (default 1) | items[].quantity | BT-129 Invoiced quantity | |
| Amount (NetAmount; OSAmount; LocalAmount; ChargeLine/SellOSAmount; ChargeLine/SellLocalAmount) | Yes | line net amount | BT-131 Invoice line net amount | Net of VAT, in the invoice currency. |
| UnitPrice (SellRate; ChargeLine/SellRate) | No (amount ÷ quantity) | items[].unitPrice | BT-146 Item net price | Rounded to 2 decimals. |
| Description (ChargeLine/Description; ChargeCode/Description) | No (charge code) | items[].description | BT-153 Item name | |
| PK (Key; LineNumber) | No | items[].externalId | — | Kept for tracing. |
Seller
| CargoWise element | Required | Alya Books field | PINT AE | Rule or behaviour |
|---|---|---|---|---|
| — (not read from the message) | — | Organisation profile in Alya Books | BG-4 Seller | Seller name, TRN, address, Peppol ID and bank details come from Settings → Company, never from the message. |
Message key and duplicates
Each message gets the key cargowise:<branch>:<type>:<number> (for example cargowise:DXB:INV:INV-2027-00412). It is the invoice's externalId, it appears in webhook payloads, and a second message with the same key answers duplicate without creating anything. To correct an invoice after it was reported, post a credit note; to fix a mapping before it was processed, replay the stored message from the log.