API Conventions

Before diving into individual resources, it's useful to understand the patterns that are shared across the whole API.

Identifiers

• All resource identifiers are UUID v4 strings (e.g. 3f2b9a1c-4d2e-4b6e-9c1a-6f5b8e2d7c10).
• Clients never generate IDs — they are always assigned by the server on creation.
• Path parameters like {id} and {stageId} always expect a UUID.

Field casing

All JSON request and response bodies use camelCase field names:

1{
2  "orderNumber": "PO-2026-0001",
3  "supplierId": "…",
4  "reachCompliant": true,
5  "createdAt": "2026-04-21T10:00:00.000Z"
6}

Dates & times

• All timestamps use ISO 8601 format in UTC: 2026-04-21T10:00:00.000Z.
• Fields ending in At (createdAt, updatedAt, verifiedAt, changedAt) are set by the server and are read-only.
• Business dates (orderDate, expectedDelivery, actualDelivery, certificateExpiry) are client-supplied.

Monetary values

Monetary amounts (unitPrice, totalAmount, pricePerUnit) are returned as strings to preserve exact decimal precision:

{ "totalAmount": "1249.50", "currency": "EUR" }

Parse them with a decimal library on the client side — not Number / Float — whenever you need to perform arithmetic on them.

Enum fields

Enum fields are documented per endpoint. The API returns 400 Bad Request when you send a value that is not in the allowed set.

Commonly shared enums:

Country codes

Fields named country, productOriginCountry, rawMaterialOriginCountry expect ISO 3166-1 alpha-2 codes (IT, DE, CN, IN, …).

List endpoints

Collection endpoints use one of three response shapes. The reference page for each resource states the exact shape.

Plain arrays are used by simple catalog endpoints:

1[
2  { "id": "…", "name": "…" },
3  { "id": "…", "name": "…" }
4]

Some newer endpoints return items plus paging fields:

1{
2  "items": [{ "id": "..." }],
3  "total": 42,
4  "page": 1,
5  "pageSize": 20
6}

Product materials and product traceability lists return data, meta and facets:

1{
2  "data": [{ "id": "..." }],
3  "meta": {
4    "page": 1,
5    "limit": 20,
6    "total": 42,
7    "totalPages": 3,
8    "hasNextPage": true,
9    "hasPreviousPage": false
10  },
11  "facets": {}
12}

Pagination parameters are 1-based where present (page=1). limit and pageSize maximums are documented per endpoint.

Partial updates

All update endpoints use PATCH with a partial body: include only the fields you want to change. Fields omitted from the request are left untouched.

curl -X PATCH {{BASE_URL}}/api/v1/suppliers/{id} \
  -H "Content-Type: application/json" \
  -d '{ "reachCompliant": true }'

Deletion

DELETE endpoints return 204 No Content on success. Delete operations are typically cascading: deleting a supplier removes its certifications; deleting a traceability journey removes its processing stages. Cascading behavior is noted per endpoint.

Custom metadata

Most core entities expose an optional metadata object — an arbitrary JSON map you can use to attach your own keys (ERP codes, external IDs, tags) without schema changes:

1{
2  "metadata": {
3    "erpCode": "SUP-042",
4    "internalOwner": "procurement-team"
5  }
6}

Keep metadata small (avoid storing large blobs), and do not store secrets or PII in it.

Document uploads

Document endpoints use two upload patterns:

The presigned flow is always:

1. POST .../presign with file metadata.
2. PUT the bytes to the returned presignedUrl using the returned storage instructions.
3. POST .../{documentId}/complete with checksumSha256.

Document status is PENDING_UPLOAD, READY or FAILED.

Idempotency

Raw-material purchase creation requires an idempotency-key header on:

• POST /api/v1/product/materials/{kind}/{id}/purchases
• POST /api/v1/product/materials/{kind}/{id}/purchases/with-documents

Reuse the same key only when retrying the same logical request. A conflicting replay can return 409 Conflict.

Error format

Every error response uses a consistent envelope:

1{
2  "code": "VALIDATION_FAILED",
3  "message": "category is required",
4  "details": { "field": "category" },
5  "requestId": "req_01HXYZ…"
6}

Common status codes