Building the payload

The integration API does not have its own description of each data type. A payload has the same structure as in the regular API of the WMS, the one the WMS apps use. What differs is how identifiers are written: your system uses its own codes, and the WMS translates them.

Where to find the structure

1. Find the data type on the Integration data types page.
2. Its section links to two operations of the regular API in Swagger:
   • What you send — the create operation; its request body is the structure of an import payload. For a receipt: POST /api/v1/inbound/receipts (ReceiptIncomeDto).
   • What you read — the read operation; its response is the structure of a change feed payload. For a receipt: GET /api/v1/inbound/receipts/{id} (ReceiptFullResponseDto).
3. Take the fields from that schema and apply the rules below to every identifier field.

Fields the server fills itself, such as the document number or the creation date, can be left out. Fields the schema does not know are ignored.

Identifiers in what you send

The record's own identifier

id is your identifier of the record: the code, GUID or key it has in your system. The WMS remembers which of its records belongs to it, so you never need to store WMS identifiers.

{
  "id": "erp-prod-cement-m400",
  "name": "Cement M400",
  "categoryId": "erp-cat-cement",
  "uomId": "erp-uom-kg"
}

• Identifiers are not case-sensitive: ABC-1 and abc-1 are the same record. The WMS stores them in lower case.
• Reference data (products, counterparties…) is matched per external system: two systems may use the same code for different records.
• Documents are matched across the company: the document's id is its identifier for every system.

Links to other records

Every field that points at another record (categoryId, warehouseId, lines[].productId and so on) takes one of two forms:

• your identifier of that record, as a string — "productId": "erp-prod-cement-m400";
• the WMS identifier, wrapped in an object — "warehouseId": {"wmsId": "0199a7c4-…"}. Use it for records your system never sent, for example warehouses set up in the WMS.

The two forms can be mixed within one payload and work inside nested lists such as lines and containers. A record referenced by your identifier must already be known to the WMS — sent earlier, or earlier in the same import request. Otherwise the item fails with an error on that field.

Service fields

These fields sit at the top level of a payload next to the data. They are never stored as data.

Field	Data types	What it does
_representation	reference data	The name shown for the record in the WMS. Defaults to name; required when the payload has no name.
_key	reference data	The fields that find an existing WMS record when your id is not linked to anything yet, for example "code" or ["code", "type"]. Used by Match only and Enrich.
_updateFields	all	The fields to change in an existing record; the rest stay as they are. Required by Enrich.
_wmsId	all	The WMS identifier of this record, when you know it. It takes priority over id and links the two.
deleted	reference data	true deletes the record, false restores it (in a Create or update item).

Identifiers in what you read

In payloads the WMS sends you (the change feed, a resync, stock balances) every identifier field is a pair:

{
  "id": {"int": "0199a7c4-1f2e-7a10-9b3c-5d6e7f8091a2", "ext": "erp-prod-cement-m400"},
  "uomId": {"int": "0199a7c4-2a3b-7c4d-8e5f-6a7b8c9d0e1f", "ext": "erp-uom-kg"},
  "categoryId": {"int": "0199a7c4-3b4c-7d5e-9f60-7b8c9d0e1f2a", "ext": null}
}

• int — the WMS identifier.
• ext — your identifier of that record, in lower case, or null when your system has none: the record was created in the WMS, or it is something internal to the WMS such as a user.

Find the record in your system by ext. When ext is null, keep a link between int and your record, and send int back as {"wmsId": …} or _wmsId when you refer to it.

Numeric identifiers — a barcode, a line number — stay plain numbers.

See all of this on one document in Example: identifiers in a receipt.