Integration support

Connect your WMS, ERP or portal to the HerWay partner API. Four steps to a working booking, then the reference below.

Create a key Settings → API. Copy hw_live_… once and keep it on your server.
Prove the connection GET /api/v1/health (no auth), then GET /api/v1/me with Authorization: Bearer hw_live_….
Book a consignment GET /api/v1/customers, then POST /api/v1/consignments with customer, pickup, delivery and one freight line. Expect 201 with a job number.
Listen for status Optional: register an HTTPS webhook in Settings → API for consignment.status_changed.

Reference

Every request except health and OpenAPI needs a key from Settings → API.

Header	Value
`Authorization`	`Bearer hw_live_…`
`X-Api-Key`	`hw_live_…`

Scope	Used for
`customers:read`	List / get customers
`consignments:read`	List, get, status, documents, estimates
`consignments:write`	Create, update, cancel, items, POD

Never put the key in browser code. Revoke it in Settings → API if it may have been exposed. Contract: /api/v1/openapi.json.

JSON only. Responses include X-HerWay-API-Version: v1.

https://<your-herway-host>/api/v1/…

Errors return error.code, error.message and optional error.details. Quote the HTTP status and job number when you ring support.

GET /api/v1/health — no auth.

GET /api/v1/me — tenant context for a valid key.

GET /api/v1/depots — consignments:read. Use codes as sendingDepot.

Scope customers:read. Use id as customerId when booking.

Method	Path
GET	`/api/v1/customers?q=&page=&pageSize=`
GET	`/api/v1/customers/{id}`

Customer-scoped keys cannot list every customer and may only book for their bound customer.

Method	Path	Purpose
GET	`/api/v1/consignments`	List
POST	`/api/v1/consignments`	Create → 201
GET	`/api/v1/consignments/{id}`	Detail
PATCH	`/api/v1/consignments/{id}`	Notes, depot, sender ref
DELETE	`/api/v1/consignments/{id}`	Cancel — body needs `reason`

POST needs customerId, status (draft or booked), pickup, delivery and freight (1–20 lines). Send idempotencyKey so retries do not double-book.

Credit hold returns 409 conflict. Incomplete addresses or missing freight fail validation.

GET reads status. POST transitions it (include reason when cancelling). Prefer webhooks over polling.

Method	Path
POST	`/api/v1/consignments/{id}/items`
POST	`/api/v1/consignments/{id}/accessorials`
PATCH	`/api/v1/consignments/{id}/fields`

POST /pod records proof of delivery. GET /documents returns label and print links.

POST /api/v1/price-estimate is indicative, not a binding quote. POST /api/v1/suburbs checks an Australian suburb and postcode before booking.

Register HTTPS for consignment.status_changed. Verify X-HerWay-Signature as hex sha256(timestamp + "." + body + "." + secret).

{
  "id": "…",
  "type": "consignment.status_changed",
  "createdAt": "…",
  "data": { "consignmentId": "…", "jobNumber": "…", "fromStatus": "…", "toStatus": "…" }
}