{ "openapi": "3.0.3", "info": { "title": "DropOff Couriers Integration API", "version": "1.0.0", "description": "Stateless, API-key-authenticated integration API for creating and tracking shipments.\n\nAll endpoints are under `/api/v1/business`. Authenticate with a Bearer API key issued from the business dashboard (API / Integrations). Keys are prefixed `dk_live_` or `dk_test_`; the prefix is cosmetic and the authoritative mode is the key itself. A test key creates persisted TEST shipments that are visible only to test keys and are excluded from live operations, invoices, COD, settlements and SMS.\n\nEvery response carries an `X-Request-Id` header; every error body repeats it as `request_id`. Successful single-resource and list responses use a `data` envelope; errors use an `error` envelope.\n\nWebhooks are delivered out of band (see the `WebhookEvent` schema and the createShipment callback). Webhook delivery is at-least-once and unordered: dedupe on the event `id` and order by `created_at`.", "contact": { "name": "DropOff Couriers API support", "url": "https://app.dropoffcouriers.com" }, "license": { "name": "Proprietary", "url": "https://app.dropoffcouriers.com" } }, "servers": [ { "url": "https://app.dropoffcouriers.com/api/v1/business", "description": "Production" } ], "security": [ { "bearerKey": [] } ], "tags": [ { "name": "Shipments", "description": "Create, read, cancel and track shipments." }, { "name": "Pricing", "description": "Quote a delivery fee before booking." }, { "name": "Zones", "description": "Pricing zones, their areas and prices." }, { "name": "COD", "description": "Cash-on-delivery ledger and payouts." }, { "name": "Settlements", "description": "Settlement summaries per period." }, { "name": "Returns", "description": "Returns raised against your parcels." }, { "name": "Test mode", "description": "Test-key-only helpers for building and testing an integration." } ], "paths": { "/shipments": { "post": { "operationId": "createShipment", "tags": [ "Shipments" ], "summary": "Create a shipment", "description": "Books a parcel. It is priced automatically; a live key raises an invoice per the payment type and notifies the receiver by SMS after the response. Send an optional `Idempotency-Key` header to make retries safe. A test key persists a TEST parcel (no invoice, no live SMS) and the response includes `meta.test: true`.", "security": [ { "bearerKey": [ "shipments:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShipmentRequest" }, "example": { "receiver_name": "Jane Receiver", "receiver_phone_number": "0772123456", "receiver_address": "Plot 5, Ntinda, Kampala", "service_type": "standard", "payment_type": "sender_pays", "item_name": "Phone case", "external_reference": "ORD-5001" } } } }, "responses": { "201": { "description": "Created. Example is a real LIVE create (no `meta` block; `invoice_id` set). A TEST key returns the same `data` shape plus `\"meta\":{\"test\":true}` and `invoice_id` 0.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentEnvelope" }, "example": { "data": { "id": 28, "tracking_number": "#DOC-0004047565693", "tracking_url": "https://app.dropoffcouriers.com/tracking/%23DOC-0004047565693", "external_reference": "ORD-5001", "status": "created", "service_type": "standard", "payment_type": "sender_pays", "currency": "UGX", "delivery_fee": 4900, "cod_amount": null, "receiver": { "name": "Jane Receiver", "phone": "+256772123456", "email": null, "address": "Plot 5, Ntinda, Kampala", "city": null, "state": null, "country": null }, "pickup": { "address": "Kampala, Uganda", "contact_name": "Test Business", "contact_phone": "+256700000000" }, "invoice_id": 12, "registration_date": "2026-10-16", "delivery_date": "2026-10-17", "estimated_delivery": null, "created_at": "2026-10-16T13:56:56+00:00" } } } } }, "200": { "description": "Idempotent replay: a retry with the same `Idempotency-Key` and body returns the original shipment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientAbility" }, "409": { "description": "Idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "in_progress": { "value": { "error": { "code": "idempotency_in_progress", "message": "A shipment with this Idempotency-Key is still being created. Please retry shortly.", "request_id": "..." } } }, "reused": { "value": { "error": { "code": "idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "request_id": "ccbf98b5-fa64-40fd-aff1-166d5af40d18" } } } } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "callbacks": { "shipmentStatusEvent": { "{$request.header.X-Configured-Webhook-Url}": { "post": { "summary": "Shipment status event delivered to your configured webhook endpoint", "description": "DropOff POSTs this to the URL you register on the Webhooks screen whenever a shipment hits a milestone. Respond 2xx within 10s. See the Webhooks section for signature verification.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Your endpoint rejected the event; DropOff retries with backoff." } } } } } } }, "get": { "operationId": "listShipments", "tags": [ "Shipments" ], "summary": "List shipments", "description": "Paginated (25 per page, `?page=N`). Filter by `status`, `service_type`, `external_reference`.", "security": [ { "bearerKey": [ "shipments:read" ] } ], "parameters": [ { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/FlowStatus" } }, { "name": "service_type", "in": "query", "schema": { "type": "string", "enum": [ "standard", "express" ] } }, { "name": "external_reference", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "A page of shipments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentListEnvelope" }, "example": { "data": [ { "id": 18, "tracking_number": "#DOC-0002807921284", "tracking_url": "https://app.dropoffcouriers.com/tracking/%23DOC-0002807921284", "external_reference": "ORD-5001", "status": "created", "service_type": "standard", "payment_type": "sender_pays", "currency": "UGX", "delivery_fee": 4900, "cod_amount": null, "receiver": { "name": "Jane Receiver", "phone": "+256772123456", "email": null, "address": "Plot 5, Ntinda, Kampala", "city": null, "state": null, "country": null }, "pickup": { "address": "Kampala, Uganda", "contact_name": "Test Business", "contact_phone": "+256700000000" }, "invoice_id": 0, "registration_date": "2026-10-16", "delivery_date": "2026-10-17", "estimated_delivery": null, "created_at": "2026-10-16T10:08:11+00:00" } ], "meta": { "current_page": 1, "per_page": 25, "total": 1, "last_page": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientAbility" } } } }, "/shipments/quote": { "post": { "operationId": "quoteShipment", "tags": [ "Pricing" ], "summary": "Quote a delivery fee", "description": "Prices a combination without persisting anything.", "security": [ { "bearerKey": [ "shipments:read" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" }, "example": { "service_type": "express" } } } }, "responses": { "200": { "description": "A price", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteEnvelope" }, "example": { "data": { "delivery_fee": 9900, "currency": "UGX", "service_type": "express", "pricing_mode": "zone" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/shipments/lookup": { "get": { "operationId": "lookupShipment", "tags": [ "Shipments" ], "summary": "Look up one shipment", "description": "Fetch a single shipment by `tracking_number` or `external_reference`. Provide at least one.", "security": [ { "bearerKey": [ "shipments:read" ] } ], "parameters": [ { "name": "tracking_number", "in": "query", "schema": { "type": "string" }, "example": "#DOC-0002807921284" }, { "name": "external_reference", "in": "query", "schema": { "type": "string" }, "example": "ORD-5001" } ], "responses": { "200": { "description": "The shipment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/shipments/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "get": { "operationId": "getShipment", "tags": [ "Shipments" ], "summary": "Get a shipment", "security": [ { "bearerKey": [ "shipments:read" ] } ], "responses": { "200": { "description": "The shipment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/shipments/{id}/cancel": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "post": { "operationId": "cancelShipment", "tags": [ "Shipments" ], "summary": "Cancel a shipment", "description": "Only while `status` is `created`. Once collected or further, it is refused with `409 cannot_cancel`.", "security": [ { "bearerKey": [ "shipments:write" ] } ], "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentEnvelope" } } } }, "409": { "description": "Cannot cancel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "cannot_cancel", "message": "Only a parcel still in the \"created\" stage can be cancelled; this one is \"collected\".", "request_id": "618cb511-913e-40d4-b90a-25bcbda01d7e" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/shipments/{id}/tracking": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "get": { "operationId": "getShipmentTracking", "tags": [ "Shipments" ], "summary": "Tracking timeline", "security": [ { "bearerKey": [ "tracking:read" ] } ], "responses": { "200": { "description": "Current status + events (event times are UTC ISO-8601)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackingEnvelope" }, "example": { "data": { "tracking_number": "#DOC-0002807921284", "current_status": "created", "events": [ { "status": "Created", "notes": "Shipment created by business.", "at": "2026-10-16T07:08:00+00:00" } ] } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/shipments/{id}/waybill": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "get": { "operationId": "getShipmentWaybill", "tags": [ "Shipments" ], "summary": "Waybill PDF", "description": "Streams the A6 label as `application/pdf`. Errors still use the JSON error envelope.", "security": [ { "bearerKey": [ "shipments:read" ] } ], "responses": { "200": { "description": "PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/shipments/{id}/test/advance": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "post": { "operationId": "advanceTestShipment", "tags": [ "Test mode" ], "summary": "Advance a test shipment (test key only)", "description": "TEST KEY ONLY. Moves a test shipment forward one step (or to an explicit `to` status) so you can exercise webhooks. Rejects a live key with `403 test_only`.", "security": [ { "bearerKey": [ "shipments:write" ] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "$ref": "#/components/schemas/FlowStatus" } } }, "example": { "to": "collected" } } } }, "responses": { "200": { "description": "Advanced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentEnvelope" }, "example": { "data": { "id": 18, "status": "collected", "tracking_number": "#DOC-0002807921284" }, "meta": { "test": true } } } } }, "403": { "description": "Live key refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "test_only", "message": "This endpoint requires a test API key.", "request_id": "..." } } } } }, "409": { "description": "Already terminal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/zones": { "get": { "operationId": "listZones", "tags": [ "Zones" ], "summary": "List pricing zones", "security": [ { "bearerKey": [ "shipments:read" ] } ], "responses": { "200": { "description": "Zones with areas and prices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZoneListEnvelope" }, "example": { "data": [ { "id": 37, "code": "A", "name": "Zone A - Kampala (City)", "transit_time": "Same day", "currency": "UGX", "areas": [ "Bugolobi", "Kololo / Kisementi", "Ntinda" ], "prices": { "small": { "standard": 4900, "express": 9900 } } } ] } } } }, "403": { "$ref": "#/components/responses/InsufficientAbility" } } } }, "/cod-ledger": { "get": { "operationId": "listCodLedger", "tags": [ "COD" ], "summary": "COD ledger", "description": "Paginated. Filter by `status`, `from`, `to`. A test key returns an empty page with `meta.test: true`.", "security": [ { "bearerKey": [ "cod:read" ] } ], "responses": { "200": { "description": "A page of COD rows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvelope" }, "example": { "data": [], "meta": { "current_page": 1, "per_page": 25, "total": 0, "last_page": 1, "test": true } } } } }, "403": { "$ref": "#/components/responses/InsufficientAbility" } } } }, "/settlements": { "get": { "operationId": "listSettlements", "tags": [ "Settlements" ], "summary": "Settlement summaries", "description": "Paginated. `statement_available` is a boolean; the statement PDF is NOT served over the API — it downloads from the dashboard (Settlements), which needs a browser session. A test key returns an empty page with `meta.test: true`.", "security": [ { "bearerKey": [ "settlements:read" ] } ], "responses": { "200": { "description": "A page of settlements", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvelope" }, "example": { "data": [], "meta": { "current_page": 1, "per_page": 25, "total": 0, "last_page": 1, "test": true } } } } }, "403": { "$ref": "#/components/responses/InsufficientAbility" } } } }, "/returns": { "get": { "operationId": "listReturns", "tags": [ "Returns" ], "summary": "List returns", "description": "Paginated. Filter by `status`. A test key returns an empty page with `meta.test: true`.", "security": [ { "bearerKey": [ "returns:read" ] } ], "responses": { "200": { "description": "A page of returns", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvelope" } } } }, "403": { "$ref": "#/components/responses/InsufficientAbility" } } } }, "/returns/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "get": { "operationId": "getReturn", "tags": [ "Returns" ], "summary": "Get a return", "security": [ { "bearerKey": [ "returns:read" ] } ], "responses": { "200": { "description": "The return", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ReturnResource" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "components": { "securitySchemes": { "bearerKey": { "type": "http", "scheme": "bearer", "description": "Business API key, e.g. `dk_live_` or `dk_test_`. Scopes (abilities): shipments:write, shipments:read, tracking:read, cod:read, settlements:read, returns:read." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "A unique value per order (a UUID is ideal). A retry with the same key and body returns the original shipment (200); a different body returns 409 idempotency_key_reused. Keys are kept 24 hours." } }, "headers": { "XRequestId": { "schema": { "type": "string", "format": "uuid" }, "description": "Server-generated request id, echoed in every error body as request_id." }, "RateLimitLimit": { "schema": { "type": "integer" }, "description": "Per-key requests/minute (120)." }, "RateLimitRemaining": { "schema": { "type": "integer" } }, "RetryAfter": { "schema": { "type": "integer" }, "description": "Seconds to wait (on 429)." } }, "responses": { "Unauthenticated": { "description": "Missing/invalid key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "A valid API key is required.", "request_id": "ff55abf6-402c-4f54-b700-39cbd6ab3349" } } } } }, "InsufficientAbility": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_ability", "message": "This API key lacks the required ability for this action.", "request_id": "..." } } } } }, "NotFound": { "description": "Not found (or not visible to this key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "The requested resource was not found.", "request_id": "4f0a2269-0e0f-487c-9dd7-eed1873246fa" } } } } }, "ValidationFailed": { "description": "Invalid input (code `validation_failed`), or the shipment could not be priced (code `pricing_unavailable` — no zone/size resolved, or the business's rates are unset).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_failed": { "value": { "error": { "code": "validation_failed", "message": "The receiver name field is required. (and 4 more errors)", "details": { "receiver_name": ["The receiver name field is required."], "payment_type": ["The payment type field is required."] }, "request_id": "532debd1-eba9-421e-acfb-b453dfe1302a" } } }, "pricing_unavailable": { "value": { "error": { "code": "pricing_unavailable", "message": "This shipment could not be priced. Check the destination zone and parcel size, or the business's rates.", "request_id": "7b3f1a2c-0e0f-487c-9dd7-eed1873246fa" } } } } } } }, "RateLimited": { "description": "Too many requests", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Too many requests. Please slow down.", "request_id": "..." } } } } }, "InternalError": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred.", "request_id": "..." } } } } } }, "schemas": { "FlowStatus": { "type": "string", "enum": [ "created", "collected", "received_at_hub", "sorted", "dispatched", "handed_to_partner", "received_from_partner", "out_for_delivery", "delivered", "failed", "returned", "cancelled" ] }, "CreateShipmentRequest": { "type": "object", "required": [ "receiver_name", "receiver_phone_number", "receiver_address", "service_type", "payment_type", "item_name" ], "properties": { "receiver_name": { "type": "string", "maxLength": 191 }, "receiver_email": { "type": "string", "format": "email", "nullable": true, "maxLength": 191 }, "receiver_phone_number": { "type": "string", "maxLength": 30 }, "receiver_address": { "type": "string" }, "receiver_city": { "type": "string", "nullable": true }, "receiver_state": { "type": "string", "nullable": true }, "receiver_country": { "type": "string", "nullable": true }, "receiver_zip_code": { "type": "string", "nullable": true }, "service_type": { "type": "string", "enum": [ "standard", "express" ] }, "payment_type": { "type": "string", "enum": [ "sender_pays", "receiver_pays", "cod", "business_credit" ] }, "cod_amount": { "type": "integer", "minimum": 0, "nullable": true, "description": "Required when payment_type is cod." }, "item_name": { "type": "string", "maxLength": 191 }, "description": { "type": "string", "nullable": true }, "external_reference": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z0-9._-]+$", "nullable": true, "description": "Your own order id. Unique per business + mode." }, "zone_id": { "type": "integer", "nullable": true }, "size_category": { "type": "string", "enum": [ "small", "medium", "large" ], "nullable": true }, "actual_weight": { "type": "number", "nullable": true }, "length_cm": { "type": "number", "nullable": true }, "width_cm": { "type": "number", "nullable": true }, "height_cm": { "type": "number", "nullable": true }, "custom_pickup": { "type": "boolean", "nullable": true, "description": "Use the pickup_* fields for a non-default pickup point (e.g. a supplier)." }, "pickup_address": { "type": "string", "nullable": true }, "pickup_contact_name": { "type": "string", "nullable": true }, "pickup_contact_phone": { "type": "string", "nullable": true } } }, "QuoteRequest": { "type": "object", "required": [ "service_type" ], "properties": { "service_type": { "type": "string", "enum": [ "standard", "express" ] }, "zone_id": { "type": "integer", "nullable": true }, "size_category": { "type": "string", "enum": [ "small", "medium", "large" ], "nullable": true }, "actual_weight": { "type": "number", "nullable": true }, "length_cm": { "type": "number", "nullable": true }, "width_cm": { "type": "number", "nullable": true }, "height_cm": { "type": "number", "nullable": true } } }, "Shipment": { "type": "object", "properties": { "id": { "type": "integer" }, "tracking_number": { "type": "string" }, "tracking_url": { "type": "string", "nullable": true }, "external_reference": { "type": "string", "nullable": true }, "status": { "$ref": "#/components/schemas/FlowStatus" }, "service_type": { "type": "string" }, "payment_type": { "type": "string" }, "currency": { "type": "string" }, "delivery_fee": { "type": "integer" }, "cod_amount": { "type": "integer", "nullable": true }, "receiver": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string", "nullable": true }, "address": { "type": "string" }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true } } }, "pickup": { "type": "object", "properties": { "address": { "type": "string", "nullable": true }, "contact_name": { "type": "string", "nullable": true }, "contact_phone": { "type": "string", "nullable": true } } }, "invoice_id": { "type": "integer", "description": "0 when no invoice was raised (e.g. test parcels, business_credit)." }, "registration_date": { "type": "string", "format": "date" }, "delivery_date": { "type": "string", "format": "date" }, "estimated_delivery": { "type": "string", "nullable": true, "description": "The zone's stated transit time when the parcel is zone-resolved; null otherwise." }, "created_at": { "type": "string", "format": "date-time" } } }, "ShipmentEnvelope": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Shipment" }, "meta": { "type": "object", "properties": { "test": { "type": "boolean" } } } } }, "ShipmentListEnvelope": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Shipment" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "QuoteEnvelope": { "type": "object", "properties": { "data": { "type": "object", "properties": { "delivery_fee": { "type": "integer" }, "currency": { "type": "string" }, "service_type": { "type": "string" }, "pricing_mode": { "type": "string", "enum": [ "zone", "weight" ] } } } } }, "TrackingEnvelope": { "type": "object", "properties": { "data": { "type": "object", "properties": { "tracking_number": { "type": "string" }, "current_status": { "$ref": "#/components/schemas/FlowStatus" }, "events": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "at": { "type": "string", "format": "date-time", "nullable": true } } } } } } } }, "ZoneListEnvelope": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "code": { "type": "string" }, "name": { "type": "string" }, "transit_time": { "type": "string", "nullable": true }, "currency": { "type": "string" }, "areas": { "type": "array", "items": { "type": "string" } }, "prices": { "type": "object", "additionalProperties": { "type": "object", "properties": { "standard": { "type": "integer", "nullable": true }, "express": { "type": "integer", "nullable": true } } } } } } } } }, "ReturnResource": { "type": "object", "properties": { "id": { "type": "integer" }, "tracking_number": { "type": "string", "nullable": true }, "courier_id": { "type": "integer" }, "type": { "type": "string", "nullable": true }, "status": { "type": "string" }, "reason": { "type": "string", "nullable": true }, "requested_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true } } }, "ListEnvelope": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "PageMeta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" }, "test": { "type": "boolean" } } }, "ErrorEnvelope": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "request_id": { "type": "string" } } } } }, "WebhookEvent": { "type": "object", "description": "Outbound webhook body. POSTed to your endpoint with headers X-DropOff-Event, X-DropOff-Event-Id, X-DropOff-Timestamp, X-DropOff-Signature (sha256= of `{timestamp}.{raw body}`), and, during a 24h secret-rotation grace, X-DropOff-Signature-Previous. Verify by recomputing the HMAC-SHA256; reject if the timestamp is older than 5 minutes. Delivery is at-least-once and unordered — dedupe on id, order by created_at. An endpoint auto-disables after 5 consecutive failed deliveries.", "properties": { "id": { "type": "string", "example": "evt_6f1c..." }, "type": { "type": "string", "enum": [ "shipment.created", "shipment.picked_up", "shipment.out_for_delivery", "shipment.delivered", "shipment.failed", "shipment.returned", "shipment.cancelled" ] }, "livemode": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Shipment" } } } } } }