Integration API

oneGRID Cloud integrates with external systems — ERP, WMS, or custom software — through an adapter: a small REST service that implements the Adapter API contract described in this section. The adapter translates between oneGRID Cloud and the external system.

hinweis

This API reference is available in English only. — Diese API-Referenz ist nur auf Englisch verfügbar.

Architecture

oneGRID Cloud is the HTTP client; the adapter is the server. oneGRID Cloud calls the adapter's endpoints to fetch work orders and item data from the external system and to notify it about picking progress, cancellations, and container events. Each customer integration runs its own adapter deployment, configured in oneGRID Cloud with the adapter's base address.

Integrations work in both directions: pull — oneGRID Cloud fetches data through the standardized endpoints in this reference — and push — the external system delivers work orders, stock, or item data through inbound adapter endpoints that are defined per deployment (see Pushing work orders).

An adapter implements some or all of these endpoint groups:

• Integration lifecycle — start here: sequence diagrams showing when oneGRID Cloud calls which endpoint.
• Work order endpoints — deliver work orders to oneGRID Cloud and receive completion, cancellation, and container events.
• Processing callbacks — step-by-step confirmation handshake during picking and placing.
• Item endpoints — deliver item master data and product images.
• File formats — the JSON and CSV formats accepted by the file-based work order and item imports.

Endpoints an adapter does not need can return an empty or non-success result — oneGRID Cloud treats every group as optional capability.

Conventions

• Content type: all request and response bodies are JSON (application/json; charset=utf-8). File uploads are not multipart — file bytes travel Base64-encoded inside a JSON body (see File formats).
• Language: oneGRID Cloud sends an Accept-Language header with the current user's ISO language code (default en), so the adapter can localize messages it returns.
• No versioning: the contract carries no API-version header or route segment.
• Security: the HTTP contract itself does not prescribe an authentication scheme. Adapter deployments are secured at the infrastructure level — private networking between oneGRID Cloud and the adapter, or gateway-level authentication configured per deployment.

Response envelope

Every endpoint except GET /Status responds with HTTP 200 OK and a JSON envelope. Operation outcomes — including failures — are reported in-band through the result field, not through HTTP status codes.

Property	Type	Meaning
isResultSuccess	boolean	Whether the operation succeeded.
result	number (enum)	Operation outcome. Enums serialize as numbers, and the numeric values differ per endpoint — every endpoint lists its values, with the success value in bold.
validationStatus	object | null	Set only when validation failed: { errorMessages: string[], isValid: boolean, errorCount: number }.
externalMessage	string | null	Optional free-text message from the external system, shown to the operator where applicable.
data	object | array | null	The payload, on endpoints that return data.

Depending on the adapter host's configuration, a request that fails model validation returns either HTTP 400 with standard ASP.NET Core validation problem details, or the 200 envelope with an InvalidInput result.

Health and version

GET /Status

Returns the adapter's version information — the only endpoint not wrapped in the response envelope.

Property	Type	Meaning
version	string | null	Adapter application version, normalized to Major.Minor.Patch.
title	string | null	Adapter application title.
buildDateTime	string (date-time)	Build timestamp of the deployed adapter.