ymorder integration API v1.0.0

GET /api/v1/openapi.json

This OpenAPI 3.1 document

Public: no key needed

GET /api/v1/docs

Human-readable rendering of this spec (HTML)

Public: no key needed

GET /api/v1/ping

Check a key: returns its id, name, scopes and the server time

Any valid API key

GET /api/v1/events

Pull feed of integration events (for systems that cannot receive webhooks)

Scope (any of): orders:read

Ordered by id. Keep the largest returned id and pass it back as since_id. Same event types as the webhooks.

GET /api/v1/orders

List orders (whitelisted fields only)

Scope (any of): orders:read

GET /api/v1/orders/{no}

One order

Scope (any of): orders:read

GET /api/v1/webhooks

List the webhook subscriptions THIS key created (never other keys' or the planner's)

Scope (any of): webhooks:manage

POST /api/v1/webhooks

Subscribe a URL to events; the signing secret is returned ONCE

Scope (any of): webhooks:manage

The URL must be https (or http) to a public host; private / loopback / link-local addresses are refused (SSRF guard) and re-checked at delivery time.

Body (JSON, required)

{
  "name": "Accounting bridge",
  "url": "https://example.com/hooks/ymorder",
  "events": [
    "invoice.exported",
    "order.status_changed"
  ]
}

DELETE /api/v1/webhooks/{id}

Delete a subscription this key created

Scope (any of): webhooks:manage

GET /api/v1/billing/profiles

Accounting layouts available (columns, formats, unverified flag)

Scope (any of): billing:read

GET /api/v1/billing/invoices

PREVIEW an invoice export. Read-only: never marks anything exported

Scope (any of): billing:read

POST /api/v1/billing/batches

Build an export AND mark its orders exported (never exported twice); returns the file

Scope (any of): billing:write

Only Delivered orders that classify as ready are exported. Response headers X-Billing-Batch (batch id) and X-Billing-Skipped. Emits invoice.exported (one per order from the audit bridge, plus one batch-level event carrying batch_id).

Body (JSON)

{
  "profile": "xero",
  "format": "csv",
  "group": "customer"
}

POST /api/v1/billing/batches/{id}/ack

Store the accounting system's own document number per DO

Scope (any of): billing:write

Idempotent: the same number again = "unchanged". A different number than the one already stored is refused.

Body (JSON, required)

{
  "documents": [
    {
      "tempdo_no": "TEMPDO-0001",
      "external_doc_no": "IV-000123"
    }
  ]
}

POST /api/v1/billing/batches/{id}/unmark

Re-open a batch the accounting system rejected (so its DOs can be exported again)

Scope (any of): billing:write

DOs that already have a payment recorded are skipped and listed under "blocked". Emits invoice.unmarked per order.

Body (JSON)

{
  "type": "object",
  "properties": {
    "tempdo_nos": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "Temp DO no"
      },
      "description": "only these (default: whole batch)"
    }
  }
}

POST /api/v1/billing/payments

Import payments received (send dry_run:true first). Idempotent on (order, reference)

Scope (any of): billing:write

A payment can only be applied to a DO that was exported. Same reference + same amount = "duplicate", same reference + different amount = "conflict". external_doc_no works only when it maps to exactly one DO; otherwise send tempdo_no.

Body (JSON, required)

{
  "dry_run": true,
  "payments": [
    {
      "tempdo_no": "TEMPDO-0001",
      "reference": "BANK-8841",
      "amount": 1200.5,
      "paid_at": "2026-10-10"
    }
  ]
}

GET /api/v1/billing/payments

Exported DOs with their payment status

Scope (any of): billing:read

POST /api/v1/tms/positions

PUSH GPS positions (one object, an array, {positions:[]}, a vendor payload via the field map, or Traccar forwarding)

Scope (any of): tms:write

Batch max 500 per request. Only plates that already exist are accepted. (plate, ts) is the dedupe key. HTTP 200 if anything was accepted or was a duplicate, 422 if every record was rejected, 413 over 500, 400 for an empty/malformed body. Per-record reasons are in rejected[].

Body (JSON, required)

{
  "positions": [
    {
      "plate": "JKL 9999",
      "lat": 1.4927,
      "lng": 103.7414,
      "speed_kmh": 62,
      "heading_deg": 90,
      "ts": "2026-10-12T08:00:00Z"
    }
  ]
}

GET /api/v1/tms/positions

Latest position per lorry from the configured TMS provider

Scope (any of): tms:read

GET /api/v1/tms/osmand

OsmAnd / Traccar-client style position push by query string (key may be sent as ?key= on THIS route only)

Scope (any of): tms:write

POST /api/v1/tms/events

Trip event from the tracking system: arrived / departed / geofence

Scope (any of): tms:write

Audited and emitted as order.checkpoint when it resolves to an order. It does NOT change order status (see wiki/integrations.md, TMS_AUTO_STATUS).

Body (JSON, required)

{
  "type": "object",
  "properties": {
    "plate": {
      "type": "string",
      "description": ""
    },
    "type": {
      "type": "string",
      "enum": [
        "arrived",
        "departed",
        "geofence"
      ]
    },
    "ts": {
      "type": "string",
      "description": "ISO 8601"
    },
    "tempdo_no": {
      "type": "string",
      "description": "optional; must be assigned to that plate"
    },
    "note": {
      "type": "string",
      "description": "max 300 chars"
    }
  },
  "required": [
    "plate",
    "type",
    "ts"
  ]
}

PUT /api/v1/tms/field-map

Store THIS key's vendor-field -> canonical-field map (dotted paths)

Scope (any of): tms:write

Body (JSON, required)

{
  "map": {
    "plate": "vehicleNo",
    "lat": "gps.latitude",
    "lng": "gps.longitude",
    "ts": "gpsTime"
  }
}

GET /api/v1/tms/field-map

Read this key's field map

Scope (any of): tms:read tms:write

DELETE /api/v1/tms/field-map

Delete this key's field map

Scope (any of): tms:write

GET /api/v1/tms/lorries/{plate}/track

Track points for one lorry

Scope (any of): tms:read

GET /api/v1/tms/jobs

Active assigned trips for the TMS to poll (plate, driver, from/to with coordinates, status)

Scope (any of): tms:read

GET /api/v1/datasets

Datasets, columns, aliases, limits

Scope (any of): master:read orders:read

GET /api/v1/export/{dataset}

Export a dataset as csv / xlsx / json

Scope (any of): orders:read master:read

The orders dataset needs orders:read; customers, lorries, drivers and charges need master:read.

POST /api/v1/import/{dataset}

Import customers or lorries. Dry run unless dry_run is exactly false; atomic unless partial

Scope (any of): master:write

Body is JSON {format, content, dry_run, mode, partial, strict} (JSON is capped at 1 MB by the server) OR a RAW body (Content-Type text/csv for CSV, application/octet-stream for .xlsx bytes) with the options as query parameters, up to 5 MB. Max 5000 rows. Blank cells never clear a field.

Body (JSON, required)

{
  "type": "object",
  "properties": {
    "format": {
      "type": "string",
      "enum": [
        "csv",
        "xlsx",
        "json"
      ]
    },
    "content": {
      "type": "string",
      "description": "CSV text, base64 for xlsx, or JSON rows"
    },
    "dry_run": {
      "type": "boolean",
      "description": "default true"
    },
    "mode": {
      "type": "string",
      "enum": [
        "upsert",
        "create_only",
        "update_only"
      ]
    },
    "partial": {
      "type": "boolean",
      "description": ""
    },
    "strict": {
      "type": "boolean",
      "description": ""
    }
  },
  "required": [
    "content"
  ]
}