# Addresses and articles (master data)

Master data is the source of truth for a tenant's business partners – the **addresses** of customers, suppliers,
prospects and partners with their postal addresses, contact persons and bank accounts – and its **articles** with
sales price and suppliers. CRM, trade and desk read these records. The API lives under `https://api.mbcom.cloud/api/masterdata`
(**no version segment**); every operation is in the [Master data reference](/reference/masterdata).

| What | Operations | Permission |
|---|---|---|
| Addresses | [`listAddresses`](/reference/masterdata/listAddresses), [`getAddress`](/reference/masterdata/getAddress), [`createAddress`](/reference/masterdata/createAddress), [`updateAddress`](/reference/masterdata/updateAddress), [`deleteAddress`](/reference/masterdata/deleteAddress) | read: `tenant:masterdata:read`, write: `tenant:masterdata:write` |
| Contact persons, postal addresses | [`createContactPerson`](/reference/masterdata/createContactPerson), [`updateContactPerson`](/reference/masterdata/updateContactPerson), [`createPostalAddress`](/reference/masterdata/createPostalAddress), [`updatePostalAddress`](/reference/masterdata/updatePostalAddress) | `tenant:masterdata:write` |
| Duplicates | [`findAddressDuplicates`](/reference/masterdata/findAddressDuplicates), [`mergeAddress`](/reference/masterdata/mergeAddress) | read / write |
| Articles | [`listProducts`](/reference/masterdata/listProducts), [`getProduct`](/reference/masterdata/getProduct), [`createProduct`](/reference/masterdata/createProduct), [`updateProduct`](/reference/masterdata/updateProduct), [`listProductGroups`](/reference/masterdata/listProductGroups) | read / write |
| Codes and fields | [`listLookupKinds`](/reference/masterdata/listLookupKinds), [`listLookupEntries`](/reference/masterdata/listLookupEntries), [`listFieldDefs`](/reference/masterdata/listFieldDefs) | `tenant:masterdata:read` |

## Codes come from the tenant

Many fields refer to the tenant's **parameter tables** (lookups) by code: `statusCode` (`address-statuses`),
`salutationCode`, `paymentTermCode`, `paymentMethodCode`, `shippingTypeCode`, an article's `unitCode` and
`taxKeyCode`. Every tenant starts with German defaults and changes them, so read the codes with
[`listLookupEntries`](/reference/masterdata/listLookupEntries) (`GET /lookups/{kind}`, e.g. `/lookups/payment-terms`)
and map your values to them once; [`listLookupKinds`](/reference/masterdata/listLookupKinds) lists the tables. An
address's `roles` (`CUSTOMER`, `SUPPLIER`, `PROSPECT`, `PARTNER`) are not sent: they follow from its status.
Tenant-defined fields are described by [`listFieldDefs`](/reference/masterdata/listFieldDefs) and stored in
`customFields`.

## Addresses

An address is one aggregate: the party (`partyType` `COMPANY` needs `companyName`, `PERSON` needs `lastName`) with its
`postalAddresses` (Anschriften), `contactPersons` (Ansprechpartner), `bankAccounts` and `sepaMandates`.

```bash
curl -X POST 'https://api.mbcom.cloud/api/masterdata/addresses' \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' \
  -d '{
    "partyType": "COMPANY",
    "companyName": "Muster GmbH",
    "statusCode": "KUNDE",
    "email": "info@muster-gmbh.example",
    "vatId": "DE123456789",
    "externalIds": { "shop": "C-4711" },
    "postalAddresses": [
      { "street": "Musterstraße 1", "postalCode": "12345", "city": "Musterstadt", "countryCode": "DE" }
    ]
  }'
```

- An empty `adrNr` (the address number) is assigned from the tenant's number range; the first postal address becomes
  the default billing and shipping address.
- `externalIds` holds the keys of other systems (up to 20, e.g. `{"shop": "C-4711"}`): store your own id there so you
  can find the address again.
- A `customerNumber` or `supplierNumber` another address already has answers **409** `customer_number_taken` /
  `supplier_number_taken`. Invalid input is **400** `invalid` with `field` and `details.fields` (nested names such as
  `postalAddresses[0].postalCode`); messages are German.
- Creates are **not idempotent** (no `Idempotency-Key`): after a timeout, look the address up (`q` with its name, e-mail or VAT ID, or
  [`findAddressDuplicates`](/reference/masterdata/findAddressDuplicates)) before creating it again.

[`updateAddress`](/reference/masterdata/updateAddress) is a `PUT` that **replaces the whole aggregate**: read the
address with [`getAddress`](/reference/masterdata/getAddress), change it and send it back complete, children
included (children keep their `id`), with the `version` you read – a stale version is **409** `version_conflict`.
To change one contact person or postal address without sending the rest, use the child routes
([`updateContactPerson`](/reference/masterdata/updateContactPerson),
[`updatePostalAddress`](/reference/masterdata/updatePostalAddress)); they bump the version of the address and return
it as `addressVersion`.

Addresses can be **merged**: a merged address answers [`getAddress`](/reference/masterdata/getAddress) with **404**,
code `merged` and `details.mergedInto` – the id of the address that was kept. Follow it and update your mapping.

## Articles

```bash
curl -X POST 'https://api.mbcom.cloud/api/masterdata/products' \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' \
  -d '{
    "shortName": "Monitor 24\" Full HD",
    "articleType": "GOODS",
    "productGroupId": "<id from listProductGroups>",
    "unitCode": "STK",
    "taxKeyCode": "STANDARD",
    "salesPrice": 189.00
  }'
```

`shortName` is always required; `GOODS`, `SERVICE` and `FEE` also need a product group, `unitCode`, `taxKeyCode` and
`salesPrice` (unit and tax key may come from the product group), `SUBSCRIPTION` in addition its billing fields;
`TEXT` articles need nothing else. A missing field is **400** naming it. An empty `articleNumber` is assigned from
the tenant's number range. [`updateProduct`](/reference/masterdata/updateProduct) replaces the article including its
price and `suppliers`, at its `version`.

## Keep an external system in sync

[`listAddresses`](/reference/masterdata/listAddresses) and [`listProducts`](/reference/masterdata/listProducts) page by
cursor: `limit` (1–200, default 50) and `cursor` = the `nextCursor` of the previous page, with `sort` and the filters
unchanged, until `nextCursor` is missing. They answer compact rows `{items, total, nextCursor}` – each with `id`,
`version` and `updatedAt` – not the full aggregate. See [Pagination](/guides/pagination).

**Initial load:** page through the whole list, then read each record you need in full with
[`getAddress`](/reference/masterdata/getAddress) / [`getProduct`](/reference/masterdata/getProduct). Remember the
time your run **started**.

**Changes since the last run:** there is no `updatedSince` filter; sort by `-updatedAt` and stop paging at the first
row whose `updatedAt` is older than the start of your last run:

```bash
curl 'https://api.mbcom.cloud/api/masterdata/addresses?sort=-updatedAt&limit=200' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

For each row compare `version` with the version you stored: equal means you have it already (for example your own
write), higher means read the record again. A record changed while you were paging moves to the top of the list –
because you start the next run from the start time of this one, it is picked up then.

**Deletions and merges** do not appear in the lists (a deleted address is gone from them, a merged one answers
`404 merged`). Subscribe to the events below, or check the ids you hold now and then: `404` means deleted, `404`
with `merged` points to the kept address.

**Events instead of polling:** master data announces `masterdata.address.created`, `…updated`, `…deleted`,
`…merged` and `masterdata.product.created`, `…updated`, `…deleted`; deliver them to your system with a
[webhook](/guides/webhooks) channel and a [flow](/guides/flows). Events carry ids, not the record: read it after the
event. Keep a slow periodic sync as well – a webhook can fail, the list cannot.

**Writing back:** send the `version` you read on every `PUT`; on **409** `version_conflict` someone changed the
record in ConnectCloud in the meantime – read it again, merge, retry. Identifiers (VAT ID, IBAN, codes) are trimmed
and upper-cased on write, so compare them normalised, or your sync sees a change that is none.
