Field mapping cookbook

Receiving orders

How the hand-off payload usually maps onto a sales order. Column names are illustrative; the decisions are what matter.

Header

AIOTIC	Sales order	Notes
request_id	external reference / your-ref field	Index it. Used for idempotency and support.
purchase_order.order_number	customer PO number ("Your reference")	Already /-free. Truncate to your field length — many ERPs allow 20–35 characters.
order_date	order date	ISO string → date.
delivery_date	requested delivery date	May be null → your default lead time.
currency	currency code	Validate against your allowed set; default to the customer's currency when null.
total_price	do not book	Informational. It is the printed total and may include VAT. Your ERP computes totals.
additional_information	internal note / order remark	Free text; can be long.
supplier	ignore	It is you.

Customer

AIOTIC	Sales order	Notes
customer.customer_id	sell-to customer number	Your debtor number as synced. null → reject (or your fallback).
customer.company, address, vat_id, email, phone	compare, do not overwrite	On confident matches these already equal your master record. A difference means the customer printed something new — worth a review, not an automatic master-data update.
customer.contact_person	contact / attention	Document-authoritative: the person who signed this PO.
customer.iban, bic	usually ignore	Purchase orders rarely carry bank data.

Ship-to

AIOTIC	Sales order	Notes
shipping_details.recipient.company + address	ship-to address	Match against the customer's known ship-to addresses if you keep them; create a one-off address otherwise.
recipient.contact_person, phone, email	ship-to contact	For the carrier.
recipient.department	address line 2
special_instructions	shipment note	"Deliver before noon", dock numbers, etc.

Lines

AIOTIC	Sales order line	Notes
items[].article_number	item number	Your SKU. null only on override sends → reject or route to a person.
items[].quantity	quantity	Whole units in the base unit unless unit says otherwise. null only on override sends.
items[].unit	unit of measure	As printed: ST, PCS, Stk, stuks, m, KG, rol… Map to your codes; unknown → base unit or reject.
items[].price	unit price	Customer-stated price. Most suppliers book their own price list and keep the customer's price as reference; some honour it. Decide explicitly.
items[].line_total	check only	quantity × price; useful to detect a mis-read quantity.
items[].description	description	The customer's wording; keep in a note if you use your own catalog text.
items[].currency	line currency	Normally equals the header's.

Business Central flavour

If you target Microsoft Dynamics 365 Business Central through its API:

• Sales Order header: customerNumber ← customer_id, externalDocumentNumber ← order_number (35 chars), requestedDeliveryDate ← delivery_date, currencyCode ← currency.
• Ship-to fields: shipToName, shipToAddressLine1, shipToPostCode, shipToCity, shipToCountry.
• Lines: lineType: Item, lineObjectNumber ← article_number, quantity, unitOfMeasureCode ← mapped unit. Omit unitPrice to take the price list.
• Business Central returns number — that is your order_number in the response.
• BC rejects unknown items with a 400 whose error.message reads "The Item does not exist. Identification fields and values: No.='…'" — pass it through as error.

Data-API ERPs (writing to tables)

Everything above still applies, plus: nobody validates for you. Use the SDK pipeline with at least catalog membership, customer exists / not blocked, positive quantities and duplicate PO before writing. See Validation when your ERP has no functional API.