ConnectCloud Developers

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.
  • 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) 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.

View as Markdown