Getting Started

This page describes the conventions shared by every DSOrder integration endpoint. Read it before the individual interface pages.

Base URL

All endpoints are served over HTTPS from the DSOrder integration service:

https://{url}

The host for each environment (test and production) is provided by DSOrder during onboarding. Every URL in this documentation is relative to it, for example https://{url}/orders/submitted.

All calls are initiated by the ERP. DSOrder never calls the ERP; data that flows from DSOrder to the ERP is fetched by the ERP with GET requests.

Authentication

Every request must be authenticated with HTTP Basic authentication.

Credential	Value
Username	Numeric client ID issued by DSOrder, for example 42
Password	API key issued by DSOrder together with the client ID

GET /orders/submitted HTTP/1.1
Host: {url}
Authorization: Basic NDI6eW91ci1hcGkta2V5

The client determines the organization the data belongs to. Store, article, supplier, promotion and placement type identifiers are always resolved within that organization, so the same external identifier can safely exist in other organizations.

Requests without credentials, or with an unknown client ID or a wrong API key, are rejected with 401 Unauthorized and an empty body. Keep the API key secret; request a new one from DSOrder if it may have been exposed.

Requests

• Request bodies are JSON and must be sent as UTF-8 with Content-Type: application/json.
• Every endpoint that accepts a body expects a JSON array of objects, even for a single record.
• Field names are snake_case, exactly as listed on each page.
• Do not send fields that are not documented. Unknown fields make the whole request fail with "success": false.
• Path parameters that contain characters outside A-Z a-z 0-9 - _ . must be URL-encoded.

Identifiers

Unless stated otherwise, identifiers are the ERP's own identifiers ("external IDs"): store_id, article_id, supplier_id, promotion_id and type_id. Stores, articles, suppliers, promotion types and placement types must already be known to DSOrder (they are set up during onboarding or by master data interfaces); records that reference unknown identifiers are rejected or skipped, as described on each page.

order_id is the exception: it is the identifier DSOrder assigns to a purchase order, returned by Get Submitted Orders.

Data types

Type	Format	Example
date	yyyy-mm-dd string, no time and no time zone	"2026-09-17"
timestamp	Unix epoch time in milliseconds, JSON number	1758067200000
number	JSON number, decimals allowed	12.250
boolean	true or false	true

Stock and sales quantities are stored with three decimal places and rounded half-up.

Timestamps are only used in responses. Where a timestamp represents a calendar date (such as a delivery date), it points to midnight UTC of that date.

Responses

Response envelope

Write operations (POST, PATCH, DELETE) and Get Submitted Orders return a JSON envelope:

Name	Type	Description
success	boolean	true if the request was processed, false if it failed
message	string or null	Reason of the failure; null on success
data	any or null	Response payload, if the endpoint returns one; otherwise null
warnings	array of strings	Non-fatal issues found while processing; usually empty

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

The other GET endpoints return a plain JSON array on success, and the same envelope with "success": false if the request fails (for example, when the store is unknown).

Business errors are returned with HTTP 200

A request that DSOrder understood but could not process is answered with 200 OK and "success": false. Always check the success field; the HTTP status alone does not tell whether the data was saved.

{
    "success": false,
    "message": "Store with external ID 'STORE-9999' was not found for organization '42'",
    "data": null,
    "warnings": []
}

The message text is meant for logs and troubleshooting. Its wording may change, so do not parse it.

HTTP status codes

Status	Meaning
200 OK	The request was handled. Check success in the body.
401 Unauthorized	Credentials are missing or invalid. Empty body.
409 Conflict	The request could not be handled at all, for example a path date that is not in yyyy-mm-dd format or a missing request body. Empty body.

Network errors and 5xx responses from the hosting infrastructure are possible as with any HTTP service; retry them with a back-off.

Partial processing

Records in a request are processed one by one, in the order they are sent. Unless an endpoint states otherwise, a failure stops processing at the failing record, records before it stay saved, and the response reports "success": false. All import endpoints are safe to retry, so the recommended recovery is to fix the cause and resend the whole request.