API Quick Reference

This page is a curated index for the Operations APIs. It complements the OpenAPI by:

• grouping endpoints by persona and task
• listing allowed filters at a glance
• reminding headers, operationId conventions, and common errors
• giving copy‑paste minimal examples that chain key calls

We do not duplicate schemas here. For request/response models, use the API Reference pages.

🧾 Standard headers (recap)

Include these in all requests (no new parameters invented here):

• dj-client: OPERATOR (admin) or ACCOUNT (shop/admin context)
• dj-api-key: required
• dj-store, dj-store-view: optional, for store scoping

🧱 OperationId conventions (recap)

Follow Djust conventions:

• Admin routes: prefix ADM- + domain + code (e.g., ADM-OPERATION-100, ADM-OPERATION-LINE-200).
• Shop/Frontend routes: domain + code (e.g., OPERATION-500, OPERATION-LINE-550).

Numeric ranges (as per Djust rules):

• CREATE 100–199 (e.g., ...-100 create single, ...-150 bulk)
• UPDATE 200–299 (e.g., ...-200 update single/bulk)
• DELETE 300–399 (e.g., ...-300 delete)
• GET 500–599 (e.g., ...-500 get one, ...-550 get list)

Status changes via PATCH can use an update code within the 200–299 range (e.g., ADM-OPERATION-201).

🧩 Endpoints by task

👨‍💼 Admin — Operations

• Create: POST /v1/operations — ADM‑OPERATION‑100
• List: GET /v1/operations — ADM‑OPERATION‑550 Allowed filters: status, ids, name, type, startDateFrom, startDateTo, endDateFrom, endDateTo, ownerIds, idType, locale, sort
• Get one: GET /v1/operations/{id} — ADM‑OPERATION‑500
• Update metadata: PUT /v1/operations/{id} — ADM‑OPERATION‑200
• Change status (publish/deactivate/reactivate): PATCH /v1/operations/{id} — ADM‑OPERATION‑201
• Delete: DELETE /v1/operations/{id} — ADM‑OPERATION‑300
• 🔜 Duplicate: POST /v1/operations?fromOperationId={id} — ADM‑OPERATION‑1XX

📦 Admin — Lines

• Add: POST /v1/operations/{id}/lines — ADM‑OPERATION‑150
• List: GET /v1/operations/{id}/lines — ADM‑OPERATION‑551 Allowed filters: variantlIds, variantName
• Update (batch): PUT /v1/operations/{id}/lines — ADM‑OPERATION‑250
• Delete (batch): DELETE /v1/operations/{id}/lines — ADM‑OPERATION‑350

👥 Admin — Accounts (PRIVATE)

• Attach: POST /v1/operations/{id}/accounts — ADM‑OPERATION‑151
• List: GET /v1/operations/{id}/accounts — ADM‑OPERATION‑552 Allowed filters: accountName, accountIds
• Remove: DELETE /v1/operations/{id}/accounts — ADM‑OPERATION‑351

🛒 Frontend

• List Operations: GET /shop/operations — OPERATION‑550
• Get Operation: GET /shop/operations/{id} — OPERATION‑500
• Get Operation lines: GET /shop/operations/{id}/lines — OPERATION‑LINE‑550
• Start order (v3): POST /v2/shop/commercial-orders — ORDER‑108

Use the API Reference pages for request/response bodies and authentication details.

▶️ Minimal chained examples (copy‑paste)

Create → add lines → attach accounts (PRIVATE) → publish

# Create (DRAFT by default)
curl -X POST "$BASE/v1/operations" \
  -H "dj-client: OPERATOR" -H "dj-api-key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "BTS-2025",
    "type": "PRIVATE",
    "names": { "en": "Back-to-school 2025", "fr": "Rentrée 2025" },
    "description": { "en": "Staples and kits", "fr": "Fournitures et kits" },
    "startDate": "2025-09-01",
    "endDate": "2025-10-15"
  }'

# Add lines (array of items)
curl -X POST "$BASE/v1/operations/{operationId}/lines" \
  -H "dj-client: OPERATOR" -H "dj-api-key: $KEY" \
  -H "Content-Type: application/json" \
  -d '[
    { "variantExternalId": "VAR-001", "minQuantity": 0, "maxQuantity": 50, "recommendedQuantity": 20 },
    { "variantExternalId": "VAR-002", "minQuantity": 1, "recommendedQuantity": 5 }
  ]'

# Attach accounts (array of external IDs)
curl -X POST "$BASE/v1/operations/{operationId}/accounts" \
  -H "dj-client: OPERATOR" -H "dj-api-key: $KEY" \
  -H "Content-Type: application/json" \
  -d '[ "ACC-001", "ACC-042" ]'

# Publish (ACTIVE)
curl -X PATCH "$BASE/v1/operations/{operationId}" \
  -H "dj-client: OPERATOR" -H "dj-api-key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "ACTIVE" }'

Buyer list → detail → start order

# List visible Operations
curl -H "dj-client: ACCOUNT" -H "dj-api-key: $KEY" "$BASE/shop/operations"

# Get details and lines
curl -H "dj-client: ACCOUNT" -H "dj-api-key: $KEY" "$BASE/shop/operations/{id}"
curl -H "dj-client: ACCOUNT" -H "dj-api-key: $KEY" "$BASE/shop/operations/{id}/lines"

# Start an order
curl -X POST "$BASE/operations/{operationId}/order"   -H "dj-client: ACCOUNT" -H "dj-api-key: $KEY"

Duplicate

curl -X POST "$BASE/v1/operations?fromOperationId={id}"   -H "dj-client: OPERATOR" -H "dj-api-key: $KEY"

Replace placeholders: $BASE, $KEY, {id}, {operationId}. Do not add parameters that aren’t defined in the contracts.

🚨 Common errors (recap)

🧭 Typical sequence (illustration)

sequenceDiagram
    participant Operator
    participant AdminAPI as Admin API
    participant Buyer
    participant ShopAPI as Shop API

    Operator->>AdminAPI: POST /v1/operations (DRAFT)
    Operator->>AdminAPI: POST /v1/operations/{id}/lines
    Operator->>AdminAPI: POST /v1/operations/{id}/accounts
    Operator->>AdminAPI: PATCH /v1/operations/{id} (ACTIVE)

    Buyer->>ShopAPI: GET /shop/operations
    Buyer->>ShopAPI: GET /shop/operations/{id}
    Buyer->>ShopAPI: POST /operations/{operationId}/order

For full models and live testing, refer to the API Reference.