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.
| What | Operations | Permission |
|---|---|---|
| Addresses | listAddresses, getAddress, createAddress, updateAddress, deleteAddress |
read: tenant:masterdata:read, write: tenant:masterdata:write |
| Contact persons, postal addresses | createContactPerson, updateContactPerson, createPostalAddress, updatePostalAddress |
tenant:masterdata:write |
| Duplicates | findAddressDuplicates, mergeAddress |
read / write |
| Articles | listProducts, getProduct, createProduct, updateProduct, listProductGroups |
read / write |
| Codes and fields | listLookupKinds, listLookupEntries, 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 (GET /lookups/{kind}, e.g. /lookups/payment-terms)
and map your values to them once; 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 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.
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. externalIdsholds 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
customerNumberorsupplierNumberanother address already has answers 409customer_number_taken/supplier_number_taken. Invalid input is 400invalidwithfieldanddetails.fields(nested names such aspostalAddresses[0].postalCode); messages are German. - Creates are not idempotent (no
Idempotency-Key): after a timeout, look the address up (qwith its name, e-mail or VAT ID, orfindAddressDuplicates) before creating it again.
updateAddress is a PUT that replaces the whole aggregate: read the
address with 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,
updatePostalAddress); they bump the version of the address and return
it as addressVersion.
Addresses can be merged: a merged address answers getAddress with 404,
code merged and details.mergedInto – the id of the address that was kept. Follow it and update your mapping.
Articles
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 replaces the article including its
price and suppliers, at its version.
Keep an external system in sync
listAddresses and 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.
Initial load: page through the whole list, then read each record you need in full with
getAddress / 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:
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 channel and a flow. 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.