EDI: DSMDS and ERP

The DSMDS integration API receives master data from the external system (ERP). All interfaces are inbound: the external system sends data to DSMDS, and DSMDS does not call the external system.

EDI Schematic

+─────────────+                                                        +─────────────+
|             |                                                        |             |
|             |  ── POST /articles/v1 ──────────────────────────────>  |             |
|             |     Articles (near real-time)                          |             |
|             |                                                        |             |
|             |  ── POST /articles/external-id/v1 ──────────────────>  |             |
|             |     Article ID change (near real-time)                 |             |
|             |                                                        |             |
|             |  ── POST /articles/units/v1 ────────────────────────>  |             |
|             |     Article units (near real-time)                     |             |
|             |                                                        |             |
|             |  ── POST /articles/units/barcodes/v1 ───────────────>  |             |
|             |     Article unit barcodes (near real-time)             |             |
|             |                                                        |             |
|             |  ── POST /articles/suppliers/v1 ────────────────────>  |             |
|             |     Article suppliers (near real-time)                 |             |
|             |                                                        |             |
|             |  ── POST /articles/purchasing/v1 ───────────────────>  |             |
|             |  ── DELETE /articles/purchasing/v1 ─────────────────>  |             |
|     ERP     |     Article purchasing (near real-time)                |    DSMDS    |
|             |                                                        |             |
|             |  ── POST /articles/assortment/v1 ───────────────────>  |             |
|             |  ── DELETE /articles/assortment/v1 ─────────────────>  |             |
|             |     Article assortments (near real-time)               |             |
|             |                                                        |             |
|             |  ── POST /article/sources/v1 ───────────────────────>  |             |
|             |     Article sources & rounding (near real-time)        |             |
|             |                                                        |             |
|             |  ── POST /stores/v1 ────────────────────────────────>  |             |
|             |     Stores / customers (near real-time)                |             |
|             |                                                        |             |
|             |  ── POST /stores/assortments/v1 ────────────────────>  |             |
|             |  ── DELETE /stores/assortments/v1 ──────────────────>  |             |
|             |     Store assortments (near real-time)                 |             |
|             |                                                        |             |
|             |  ── POST /suppliers/v1 ─────────────────────────────>  |             |
|             |     Suppliers (near real-time)                         |             |
|             |                                                        |             |
+─────────────+                                                        +─────────────+

Data Flow Summary

Direction	Interface	Endpoint	Frequency
ERP -> DSMDS	Articles	`POST /articles/v1`	Near real-time
ERP -> DSMDS	Article External ID	`POST /articles/external-id/v1`	Near real-time
ERP -> DSMDS	Article Units	`POST /articles/units/v1`	Near real-time
ERP -> DSMDS	Article Unit Barcodes	`POST /articles/units/barcodes/v1`	Near real-time
ERP -> DSMDS	Article Suppliers	`POST /articles/suppliers/v1`	Near real-time
ERP -> DSMDS	Article Purchasing	`POST /articles/purchasing/v1`, `DELETE /articles/purchasing/v1`	Near real-time
ERP -> DSMDS	Article Assortments	`POST /articles/assortment/v1`, `DELETE /articles/assortment/v1`	Near real-time
ERP -> DSMDS	Article Sources	`POST /article/sources/v1`	Near real-time
ERP -> DSMDS	Stores	`POST /stores/v1` (alias `POST /customers/v1`)	Near real-time
ERP -> DSMDS	Store Assortments	`POST /stores/assortments/v1`, `DELETE /stores/assortments/v1`	Near real-time
ERP -> DSMDS	Suppliers	`POST /suppliers/v1`	Near real-time

Authentication

All endpoints require HTTP Basic authentication.

Credential	Value
Username	Client integration ID (numeric) issued by DSMDS
Password	API key issued by DSMDS for that client integration

Authorization: Basic base64(<client_integration_id>:<api_key>)

The API is stateless: no session is created, and the credentials must be sent with every request.

The client integration determines the client and organization the data is imported for.

Status	Meaning
401 Unauthorized	Credentials are missing or invalid

Requests

Request bodies are JSON, sent with Content-Type: application/json.
For every endpoint, the top-level request body is a JSON array.
Unknown fields are ignored.
The maximum request body size is 2 MB (2097152 bytes). The limit is checked against the Content-Length header before authentication; requests whose Content-Length exceeds it are rejected with 413 Payload Too Large. Always send the Content-Length header.

Processing behaviour

Updates replace all fields. When an existing record is updated, every field is overwritten with the values from the request. Optional fields that are omitted are cleared, and omitted boolean fields become false. Always send the full record, not only the changed fields.

Failure handling differs per endpoint. Some endpoints process a request all-or-nothing: if any record fails, nothing from the request is saved. Others process records one by one: records processed before a failure stay saved. See the Technical section of each interface page for its behaviour.

Response format

Every processed request returns HTTP 200 OK with the following JSON envelope, including when processing fails.

Name	Type	Description
success	boolean	`true` if the request was processed, `false` if it was rejected
message	string	Error message when `success` is `false`
data	null	Not used by the import endpoints, always `null`
warnings	string[]	Records that were skipped or partially processed. Always present; an empty list when nothing was skipped, and also when `success` is `false`

Always check success and warnings, not only the HTTP status code: a 200 OK response can report a failure, and a successful response can contain warnings about records that were not imported.

The Article Suppliers and Article Sources endpoints return at most 50 warnings. Any further warnings are replaced by a final N additional warnings omitted entry. The other endpoints return all warnings.

200: OK — Success

{
    "success": true,
    "message": "",
    "data": null,
    "warnings": []
}

200: OK — Success with warnings

{
    "success": true,
    "message": null,
    "data": null,
    "warnings": [
        "Article not found by external ID '0001' for client '20'"
    ]
}

200: OK — Error

{
    "success": false,
    "message": "Failed to map JSON",
    "data": null,
    "warnings": []
}

Error messages

Status	`message`	Cause
200	`Failed to process JSON`	The request body is not valid JSON
200	`Failed to map JSON`	The JSON does not match the expected structure (e.g., an object instead of an array, or a value of the wrong type)
200	`general.errors.optimistic_locking_failed`	The data was modified concurrently; the request can be retried
413	`Request payload is too large. Maximum allowed size is 2097152 bytes`	The `Content-Length` of the request exceeds the size limit
409	(empty body)	Any other error, e.g., a missing required field or `null` identifier, a value too long for its field, an unknown `picking_method`, a wrong HTTP method or path, or an empty request body

EDI Schematic​

Data Flow Summary​

Authentication​

Requests​

Processing behaviour​

Response format​

200: OK — Success​

200: OK — Success with warnings​

200: OK — Error​

Error messages​