External codes

Records can be read, matched and updated by your own codes, such as a DMS outlet code, as well as by Mikono's ID. This guide explains how codes are stored, looked up and kept unique.

The externalCodes field

Every record the API returns has an externalCodes object: one code per outside system, keyed by the system’s name.

JSON

{
  "id": "…",
  "name": "Mama Rose Bar",
  "externalCodes": { "dms": "UG2000123", "quickbooks": "143" }
}

External code systems
System	Who writes it
`dms`	You. The record’s code in the distributor management system.
A registered partner system	You. Any other system name the organisation registers for its partners.
`quickbooks`	Mikono, when the record is posted to QuickBooks. Read-only.
`efris`	Mikono, for fiscal documents (the FDN). Read-only.

DMS codes

DMS code formats
Record	DMS code	Example
Outlet	UG and 7 digits	`UG2000123`
Product	6 digits	`780123`
Route and salesman	Route code	`KBDVSM001`
Warehouse	Warehouse code	`M`
Van	V_ and the route; -G for good stock, -B for bad	`V_KBDVSM001-G`
Invoice	CS, route and number	`CS…`
Return	RT, route and number	`RT…`
Collection	PY, route and number	`PY…`
Stock adjustment	IJ and 6 digits	`IJ…`

Look up by code

Two ways to find a record by its code instead of its Mikono ID:

Read one record: GET /{resource}/by-code/{system}/{code}. It returns the record, or 404 not_found.
Filter a list: ?externalCode=dms:UG2000123 on the resource’s list endpoint.

curl

curl -s "$BASE/{resource}?externalCode=dms:UG2000123" \
  -H "Authorization: Bearer $KEY"

Create or update by code

PUT /{resource}/by-code/{system}/{code} creates the record the first time and updates it every time after. It is safe to repeat: a retry with a new Idempotency-Key still finds the same record, and no duplicate is created. Use it to keep master data in step from your system.

Rules for codes

A code is unique within an organisation, a system and a resource. Two outlets cannot share a DMS code.
Codes are case-sensitive. ug2000123 and UG2000123 are different codes.
Leading and trailing spaces are removed. A code may be up to 64 characters.
Documents from the DMS are also matched by their document number; see DMS integration.