{ "openapi": "3.1.0", "info": { "title": "Areye Business API: deliveries", "version": "2026-10-11", "description": "Book and track Areye deliveries from your platform. Authenticate every call with the X-Business-API-Key header. Send a stable external_reference with every booking and reuse it on retries. Times are ISO-8601 with an offset. Build and test in the SANDBOX (https://sandbox.areye.app/api, sk_sandbox_ keys): the same API and webhooks, simulation endpoints to drive each trip, and nothing real is ever reached. Live (https://api.areye.app/api) takes live keys only and refuses test bookings. Every refusal carries a stable code. Full guide: https://areye.app/api-docs#sandbox" }, "servers": [ { "url": "https://sandbox.areye.app/api", "description": "Sandbox: sk_sandbox_ keys only; no real driver, phone or payment is ever reached" }, { "url": "https://api.areye.app/api", "description": "Production: live keys only; test-marked bookings are refused" } ], "security": [ { "BusinessKey": [] } ], "tags": [ { "name": "Reference data", "description": "What you may send: vehicle types, parcel sizes, zones" }, { "name": "Bookings", "description": "Estimate, book, read, mark ready and cancel" }, { "name": "Bulky delivery", "description": "Furniture, appliances and other large goods: send a goods manifest; Areye chooses the vehicle and crew and prices every line" }, { "name": "Tracking", "description": "Public tracking and the customer side of the order chat" }, { "name": "Documents", "description": "Printable PDFs from the order's own items: the pick list before packing, the packing slip that goes in the box" }, { "name": "Account", "description": "Your account, credentials, webhooks, wallet and cash on delivery. People, payouts, cards and automatic top-up are done signed in to the business portal (an integration key gets 403 signed_in_admin_only)." }, { "name": "Sandbox", "description": "Sandbox keys, simulation of every driver step, the simulated driver and the webhook inbox. The /business/sandbox/* and /sandbox/* calls exist only on the sandbox server; GET /business/sandbox and POST /business/sandbox/credentials only on live." } ], "paths": { "/business/vehicle-types": { "get": { "tags": [ "Reference data" ], "summary": "Vehicle types with live pricing", "operationId": "listVehicleTypes", "responses": { "200": { "description": "Vehicle types", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvelope" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/parcel-sizes": { "get": { "tags": [ "Reference data" ], "summary": "Parcel size bands", "operationId": "listParcelSizes", "responses": { "200": { "description": "Size bands", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvelope" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/zones": { "get": { "tags": [ "Reference data" ], "summary": "Active service zones", "operationId": "listZones", "responses": { "200": { "description": "Zones", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvelope" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/trip/fare-estimate": { "get": { "tags": [ "Bookings" ], "summary": "Price a trip before booking it", "operationId": "fareEstimate", "parameters": [ { "name": "pickup_lat", "in": "query", "required": true, "schema": { "type": "number" } }, { "name": "pickup_lng", "in": "query", "required": true, "schema": { "type": "number" } }, { "name": "dest_lat", "in": "query", "required": true, "schema": { "type": "number" } }, { "name": "dest_lng", "in": "query", "required": true, "schema": { "type": "number" } }, { "name": "vehicle_type_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Include to receive system_fare for that vehicle type" } ], "responses": { "200": { "description": "Estimate", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "distance_km": { "type": "number" }, "duration_seconds": { "type": "integer" }, "system_fare": { "type": "number" }, "currency": { "type": "string" }, "surge_multiplier": { "type": "number" }, "surge_active": { "type": "boolean" } } } } } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/book": { "post": { "tags": [ "Bookings" ], "summary": "Book a delivery (or ride)", "operationId": "book", "description": "Idempotent on external_reference: an exact retry returns 200 with replayed: true and the original delivery; the same reference with different details returns 409 external_reference_conflict; a booking still in progress returns 409 booking_in_progress with Retry-After. A reference stays tied to its first delivery for good, even once cancelled.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BookRequest" }, { "$ref": "#/components/schemas/BulkyFields" } ] } } } }, "responses": { "201": { "description": "Delivery created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookResponse" } } } }, "200": { "description": "Replay of an earlier booking with the same external_reference (replayed: true)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookResponse" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "scope_denied: a partner key used outside its scopes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "external_reference_conflict or booking_in_progress", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds, on booking_in_progress" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Bulky order booked and held for review (review_state manual_review_required); no driver is sent until it is approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookResponse" } } } }, "422": { "description": "Validation failed, outside every service zone, insufficient balance / credit, bulky_refused (no vehicle can carry it; nothing created) or bulky_not_enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests a minute", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/trips": { "get": { "tags": [ "Bookings" ], "summary": "List trips, newest first", "operationId": "listTrips", "parameters": [ { "name": "month", "in": "query", "schema": { "type": "string" }, "description": "YYYY-MM" }, { "name": "reference", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Reference, passenger, address or your external_reference" }, { "name": "test", "in": "query", "schema": { "type": "string" }, "description": "0 hides test trips, 1 shows only them" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "since", "in": "query", "schema": { "type": "string" }, "description": "Only trips updated since this time" }, { "name": "from", "in": "query", "schema": { "type": "string" }, "description": "First day, inclusive (YYYY-MM-DD)" }, { "name": "to", "in": "query", "schema": { "type": "string" }, "description": "Last day, inclusive (YYYY-MM-DD)" }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "ride", "parcel", "airport", "cargo", "all" ] } }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "One status, or several separated by commas" } ], "responses": { "200": { "description": "Trips, with meta {page, per_page, total, has_more}", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Trip" } }, "meta": { "type": "object" } } } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Bookings" ], "summary": "Book a merchant order delivery (order lines, cash on delivery, shop-and-deliver, bulky goods); retry safely with external_reference", "operationId": "createTrip", "description": "The merchant-order form of /business/book: the same route, recipient and payment fields, plus order_payload, cod_amount, shop_deliver and bulky goods. Same refusal codes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Booked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookResponse" } } } }, "200": { "description": "replayed: true" }, "409": { "description": "external_reference_conflict | booking_in_progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "validation_failed | insufficient_balance | ...", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/trips/{trip}": { "get": { "tags": [ "Bookings" ], "summary": "One trip", "operationId": "showTrip", "parameters": [ { "name": "trip", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Trip id or Areye reference" } ], "responses": { "200": { "description": "Trip", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Trip" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/trips/{trip}/cancel": { "post": { "tags": [ "Bookings" ], "summary": "Cancel before pickup", "operationId": "cancelTrip", "parameters": [ { "name": "trip", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Trip id or Areye reference" } ], "description": "Allowed while pending, scheduled, queued, accepted, enroute or arrived. A business is never charged for cancelling; anything charged to the wallet for the trip is refunded.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 255 } } } } } }, "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "not_cancellable: already collected or ended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/trip/{reference}/ready": { "post": { "tags": [ "Bookings" ], "summary": "The order is packed", "operationId": "markReady", "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Areye trip reference, e.g. ARY-8F3A21" } ], "description": "Releases a held order to drivers at once and tells an assigned driver. Calling it again is harmless.", "responses": { "200": { "description": "Marked ready (or already was)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "403": { "description": "Not your order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown reference", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/bulky/quote": { "post": { "tags": [ "Bulky delivery" ], "summary": "Price a bulky order without booking it", "operationId": "bulkyQuote", "description": "The same decision a booking freezes: send the same body to /business/book and the price, vehicle and crew are identical. Merchant-supplied totals are ignored; Areye calculates them from the lines.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkyFields" } } } }, "responses": { "200": { "description": "ok or manual_review_required", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/BulkyDecision" } } } } } }, "422": { "description": "refused (data carries the evidence per vehicle) or bulky_not_enabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": false }, "data": { "$ref": "#/components/schemas/BulkyDecision" } } } } } } } } }, "/business/checkouts": { "post": { "tags": [ "Bulky delivery" ], "summary": "In-store quote: get the customer's QR", "operationId": "createCheckout", "description": "The bulky decision priced for a customer at the counter. Returns a signed QR URL the customer opens to pay Areye directly (no account, no app); the same URL then follows the delivery. Attributed with branch_code and consultant_code. An order that needs an operations check is refused here (book it with /business/book). The merchant is not charged.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BulkyFields" }, { "type": "object", "required": [ "pickup_address", "pickup_lat", "pickup_lng", "dest_address", "dest_lat", "dest_lng", "goods" ], "properties": { "branch_code": { "type": "string" }, "consultant_code": { "type": "string" }, "customer_first_names": { "type": "string" }, "customer_surname": { "type": "string" }, "customer_phone": { "type": "string" } } } ] } } } }, "responses": { "201": { "description": "reference, url, qr_svg, total, currency, quote, vehicle, crew, commission", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "bulky_refused, needs review, or in-store checkout not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Bulky delivery" ], "summary": "Quotes, payments and deliveries", "operationId": "listCheckouts", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "branch_code", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Checkouts", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/business/checkouts/{reference}/cancel": { "post": { "tags": [ "Bulky delivery" ], "summary": "Cancel a quote, or a paid order before collection", "operationId": "cancelCheckout", "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" } } ], "description": "Before payment: the QR stops working. After payment and before collection: the delivery is cancelled and the customer refunded, once.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "Already collected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/bulky/schema": { "get": { "tags": [ "Bulky delivery" ], "summary": "The versioned goods and decision contract (for API clients and shop connectors)", "operationId": "bulkySchema", "description": "Fields are only ever added. A connector maps its product data onto goods lines and never chooses a vehicle, crew or price.", "responses": { "200": { "description": "Schema", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/business/trips/{trip}/bulky/authorise-disposal": { "post": { "tags": [ "Bulky delivery" ], "summary": "Let the driver dispose of damaged or refused lines", "operationId": "bulkyAuthoriseDisposal", "parameters": [ { "name": "trip", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Trip id or Areye reference" } ], "description": "Only lines recorded as damaged or refused. The disposal fee frozen on the order is charged once, when the driver disposes with a photo.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "lines", "reason" ], "properties": { "lines": { "type": "array", "items": { "type": "integer" } }, "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Authorised", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "Not eligible for disposal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/trips/{trip}/bulky/redeliver": { "post": { "tags": [ "Bulky delivery" ], "summary": "Another attempt for goods that came back", "operationId": "bulkyRedeliver", "parameters": [ { "name": "trip", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Trip id or Areye reference" } ], "description": "Once the goods are back at the store: a new order for the lines not delivered or disposed of, at the redelivery percentage frozen on the original. Once per return.", "responses": { "201": { "description": "The redelivery order", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "Not back yet, nothing left, or already redelivered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/trips/{trip}/bulky/accept-quote": { "post": { "tags": [ "Bulky delivery" ], "summary": "Accept a price raised by review", "operationId": "bulkyAcceptQuote", "parameters": [ { "name": "trip", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Trip id or Areye reference" } ], "description": "After trip.quote_changed. The difference is charged once and the order is released to dispatch.", "responses": { "200": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "No new price is waiting", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/trips/{trip}/bulky/decline-quote": { "post": { "tags": [ "Bulky delivery" ], "summary": "Decline a price raised by review", "operationId": "bulkyDeclineQuote", "parameters": [ { "name": "trip", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Trip id or Areye reference" } ], "description": "The order is cancelled and what you paid is refunded.", "responses": { "200": { "description": "Cancelled and refunded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "422": { "description": "No new price is waiting", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trip-track/{reference}": { "get": { "tags": [ "Tracking" ], "summary": "Live tracking (no key): position, ETA, freshness", "operationId": "trackTrip", "security": [], "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The token from tracking_url (preferred), or, during the compatibility period, the trip reference." } ], "description": "Poll every poll_after_seconds (15) while is_active; stop when it is null. Slow down or pause when your screen is in the background. A tracking_url token sees its own trip's pickup, ordered stops and destination (scope \"token\"), so you can draw the route once and then move only the driver marker. A bare reference gets the privacy-reduced view (scope \"reference\": no pickup, no stops) and stops working when Areye switches reference links off after integrators have moved. location_is_fresh uses the same age limit as dispatch; an old position is still returned for continuity but must be shown as last known, never as live. Polling supplies position and ETA only: webhooks are the authoritative delivery state. Do not keep coordinates beyond the delivery.", "responses": { "200": { "description": "Status and driver position", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Tracking" } } } } } }, "404": { "description": "Unknown token or reference", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "tracking_link_revoked or tracking_link_expired: stop polling; ask for or rotate to a new link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/trips/{trip}/tracking-link/rotate": { "post": { "tags": [ "Tracking" ], "summary": "Issue a new tracking link", "operationId": "rotateTrackingLink", "parameters": [ { "name": "trip", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Trip id or Areye reference" } ], "description": "The previous link stops working at once (404).", "responses": { "200": { "description": "The new link", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "tracking_url": { "type": "string" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/trips/{trip}/pick-list": { "get": { "tags": [ "Documents" ], "summary": "Pick list PDF (before packing)", "operationId": "downloadPickList", "parameters": [ { "name": "trip", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Trip id or Areye reference" } ], "description": "For the picker or shopper: items grouped by store, then aisle (send order_payload.items.*.aisle or category), with quantity, barcode / SKU, the substitution preference, tick boxes, the order number, the store and the pickup time. Never prices, never a delivery or pickup code. A shop order (shopping block) lists every store in its shopping sequence.", "responses": { "200": { "description": "PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Not your order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "no_items: booked without order_payload.items or a shopping block", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/trips/{trip}/packing-slip": { "get": { "tags": [ "Documents" ], "summary": "Packing slip PDF (goes in the box)", "operationId": "downloadPackingSlip", "parameters": [ { "name": "trip", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Trip id or Areye reference" }, { "name": "pieces", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50 }, "description": "Boxes in this order: one page per box, \"n of N\" (default order_payload.pieces, else 1)" } ], "description": "Order number and QR, sender and recipient (first names and surname), delivery address, items ordered against packed, substitutions made (original \u2192 substitute), items missing (refunded), piece n of N, your returns note, a signature line and the date. For a merchant order send items.*.qty_packed and items.*.substitute when packed; otherwise the packed column is left to fill in by hand. A shop order's slip carries the final outcome of every line and is ready once the basket is collected. Prices print only when show_prices is on (PUT /business/packing-slip-settings). Never a delivery or pickup code.", "responses": { "200": { "description": "PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Not your order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "not_shopped_yet: a shop order before its basket is collected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "no_items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/batches/{batch}/packing-slips": { "get": { "tags": [ "Documents" ], "summary": "Every stop's packing slip in one PDF (optionally with labels)", "operationId": "downloadBatchPackingSlips", "parameters": [ { "name": "batch", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "with_labels", "in": "query", "schema": { "type": "boolean" }, "description": "1: each slip ends in a cut-off label (QR custody code + order number); needs the scanning add-on" } ], "responses": { "200": { "description": "PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "Labels need the scanning add-on", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not your batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/packing-slip-settings": { "get": { "tags": [ "Documents" ], "summary": "Packing slip settings", "operationId": "packingSlipSettings", "responses": { "200": { "description": "show_prices (default false) and returns_note", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "show_prices": { "type": "boolean" }, "returns_note": { "type": [ "string", "null" ] } } } } } } } } } }, "put": { "tags": [ "Documents" ], "summary": "Change the packing slip settings", "operationId": "updatePackingSlipSettings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "show_prices": { "type": "boolean" }, "returns_note": { "type": [ "string", "null" ], "maxLength": 1000 } } } } } }, "responses": { "200": { "description": "The settings now", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "A portal user who is not an admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/shipments/{reference}/packing-slip": { "get": { "tags": [ "Documents" ], "summary": "Courier shipment packing slip (one page per piece)", "operationId": "downloadShipmentPackingSlip", "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Waybill" } ], "description": "Each page says what is in that piece (send parcels.*.contents when booking) and lists the whole consignment. A courier client uses GET /client/shipments/{waybill}/packing-slip for its own shipments.", "responses": { "200": { "description": "PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Not your shipment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/trips/{trip}/tracking-link/revoke": { "post": { "tags": [ "Tracking" ], "summary": "Turn the tracking link off", "operationId": "revokeTrackingLink", "parameters": [ { "name": "trip", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Trip id or Areye reference" } ], "description": "Holders of the link get 410 tracking_link_revoked. Rotate to issue a new one.", "responses": { "200": { "description": "Turned off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trip-chat/{reference}": { "get": { "tags": [ "Tracking" ], "summary": "Read the order chat (customer side)", "operationId": "readChat", "security": [], "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Areye trip reference, e.g. ARY-8F3A21" }, { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "chat_token from the booking response" } ], "responses": { "200": { "description": "Messages", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Chat not found or wrong token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Tracking" ], "summary": "Send a message as the customer", "operationId": "sendChat", "security": [], "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Areye trip reference, e.g. ARY-8F3A21" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token", "message" ], "properties": { "token": { "type": "string" }, "message": { "type": "string", "maxLength": 1000 } } } } } }, "responses": { "200": { "description": "Sent", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Chat not found or wrong token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Chat closed (cancelled, or 30 minutes after completion)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/sandbox": { "get": { "tags": [ "Sandbox" ], "summary": "LIVE: may this account have sandbox credentials, and has it?", "operationId": "sandboxStatus", "responses": { "200": { "description": "allowed, reason, provisioned_at, base_url", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "live_only: called on the sandbox", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/sandbox/credentials": { "post": { "tags": [ "Sandbox" ], "summary": "LIVE: create or rotate this account's sandbox credentials (shown once)", "operationId": "sandboxCredentials", "description": "Creates a sandbox twin of the account with its own sk_sandbox_ key, webhook secret and an enabled Storefront grant. Calling again rotates them. Portal admins and API keys only.", "responses": { "201": { "description": "base_url, business_id, api_key, webhook_secret, storefront {business_id, webhook_secret, token_audience}", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "sandbox_not_allowed or sandbox_paused (the reason is in message)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "sandbox_unavailable: try again", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sandbox/signup": { "post": { "tags": [ "Sandbox" ], "summary": "SANDBOX: sign up as a developer (emails a 6-digit code)", "operationId": "sandboxSignup", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "first_names", "surname", "email" ], "properties": { "first_names": { "type": "string" }, "surname": { "type": "string" }, "email": { "type": "string" }, "company": { "type": [ "string", "null" ] } } } } } }, "responses": { "202": { "description": "Code emailed (valid 15 minutes)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "422": { "description": "validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "too_many_codes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "signup_closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sandbox/signup/verify": { "post": { "tags": [ "Sandbox" ], "summary": "SANDBOX: exchange the code for a sandbox key (shown once)", "operationId": "sandboxSignupVerify", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "code" ], "properties": { "email": { "type": "string" }, "code": { "type": "string" } } } } } }, "responses": { "201": { "description": "base_url, business_id, api_key (sk_sandbox_\u2026), webhook_secret", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "code_invalid or code_expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/sandbox/trips/{reference}/{action}": { "post": { "tags": [ "Sandbox" ], "summary": "SANDBOX: the simulated driver takes one real step on a trip", "operationId": "sandboxStep", "description": "Each step is the driver app's own action, so it fires the real webhooks with the real payloads. assign_driver \u2192 trip.accepted; arrive_pickup (no webhook for a delivery); pick_up \u2192 trip.picked_up; arrive_dropoff; deliver (delivery code, ID check, proof photo and signature, COD) \u2192 trip.completed delivery_outcome \"delivered\"; fail_delivery {reason} \u2192 trip.delivery_failed; id_refused {reason} \u2192 trip.age_verification_failed; complete_return \u2192 trip.completed delivery_outcome \"returned\" with return_reason; cancel_by_driver {reason}. Out of order: 409 driver_not_assigned / no_return_in_progress, or the driver app's own refusal.", "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ARY-\u2026 reference, trip id, or your external_reference" }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "assign_driver", "arrive_pickup", "pick_up", "arrive_dropoff", "deliver", "fail_delivery", "id_refused", "complete_return", "cancel_by_driver" ] } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" }, "cod_collected_amount": { "type": "number" } } } } } }, "responses": { "200": { "description": "step, trip {reference, status, returning, return_reason}, webhooks [{event, event_id, status}]", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "not_found, or sandbox_only on live", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "driver_not_assigned, no_return_in_progress, refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The driver app's own refusal (e.g. awaiting_handover)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/sandbox/autopilot": { "get": { "tags": [ "Sandbox" ], "summary": "SANDBOX: the simulated driver's settings", "operationId": "sandboxAutopilot", "responses": { "200": { "description": "scenario, step_seconds, scenarios", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "put": { "tags": [ "Sandbox" ], "summary": "SANDBOX: run every new booking through a scenario on its own", "operationId": "sandboxSetAutopilot", "description": "One booking only: send \"sandbox_scenario\" on POST /business/book instead (refused on live).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "scenario" ], "properties": { "scenario": { "type": [ "string", "null" ], "enum": [ "off", null, "delivered", "failed_delivery", "id_refused", "cancel_by_driver" ] }, "step_seconds": { "type": "integer", "minimum": 1, "maximum": 60 } } } } } }, "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/sandbox/inbox": { "post": { "tags": [ "Sandbox" ], "summary": "SANDBOX: point your webhooks at the built-in inbox", "operationId": "sandboxOpenInbox", "responses": { "200": { "description": "webhook_url", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "get": { "tags": [ "Sandbox" ], "summary": "SANDBOX: read what was delivered (exact body and signed headers)", "operationId": "sandboxInbox", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "after_id", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "[{id, received_at, event, event_id, headers, body}] newest first", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "no_inbox", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/sandbox/wallet": { "put": { "tags": [ "Sandbox" ], "summary": "SANDBOX: set a test wallet balance (to try the reserve and insufficient-funds refusals)", "operationId": "sandboxSetWallet", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "currency", "balance" ], "properties": { "currency": { "type": "string", "enum": [ "BWP", "ZAR" ] }, "balance": { "type": "number" } } } } } }, "responses": { "200": { "description": "The wallet as set", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/business/profile": { "get": { "tags": [ "Account" ], "summary": "Your account: settings, services, wallet summary, portal_role and principal", "operationId": "getProfile", "responses": { "200": { "description": "Profile", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "patch": { "tags": [ "Account" ], "summary": "Update company details, webhook_url or the low-balance alert level", "operationId": "updateProfile", "description": "webhook_url must be a public HTTPS address (422 webhook_url_unsafe). A changed webhook address is recorded and emailed to the account owner. A coordinator is refused (403 portal_admin_only).", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "trading_name": { "type": "string" }, "phone": { "type": "string" }, "address": { "type": "string" }, "contact_first_names": { "type": "string" }, "contact_surname": { "type": "string" }, "webhook_url": { "type": [ "string", "null" ] }, "low_balance_threshold": { "type": [ "number", "null" ] }, "fallback_currency": { "type": [ "string", "null" ] } } } } } }, "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "webhook_url_unsafe | validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "portal_admin_only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/api-key": { "get": { "tags": [ "Account" ], "summary": "API key metadata (key_preview = last four characters of the key you hold) and your webhook secret", "operationId": "getApiKey", "responses": { "200": { "description": "Key metadata", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/business/api-key/regenerate": { "post": { "tags": [ "Account" ], "summary": "Rotate your API key (the old key stops at once; the owner is emailed)", "operationId": "regenerateApiKey", "responses": { "200": { "description": "The new key, shown once", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/business/webhook-secret/regenerate": { "post": { "tags": [ "Account" ], "summary": "Rotate the webhook signing secret (the owner is emailed)", "operationId": "regenerateWebhookSecret", "responses": { "200": { "description": "The new secret", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/business/webhook-test": { "post": { "tags": [ "Account" ], "summary": "Send a signed webhook.test event (V1 and V2 signatures) to your webhook URL", "operationId": "webhookTest", "responses": { "200": { "description": "Your receiver answered 2xx", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "webhook_url_missing | webhook_url_unsafe", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "webhook_receiver_failed: status, error and snippet in data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/webhooks/deliveries": { "get": { "tags": [ "Account" ], "summary": "Your recent webhook deliveries and their outcome (including refused ones)", "operationId": "listWebhookDeliveries", "responses": { "200": { "description": "Deliveries", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/business/webhooks/deliveries/{eventId}/replay": { "post": { "tags": [ "Account" ], "summary": "Re-send an exhausted delivery (same event id and bytes)", "operationId": "replayWebhookDelivery", "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Queued again", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/business/wallet": { "get": { "tags": [ "Account" ], "summary": "Wallet balances and billing type", "operationId": "getWallet", "responses": { "200": { "description": "Wallet", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/business/wallet/transactions": { "get": { "tags": [ "Account" ], "summary": "Wallet ledger: debits, credits and top-ups", "operationId": "walletTransactions", "responses": { "200": { "description": "Transactions", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/business/cod/ledger": { "get": { "tags": [ "Account" ], "summary": "Cash on delivery: fee, settlement cycle, netting, unsettled amount and ledger entries", "operationId": "codLedger", "responses": { "200": { "description": "{cod_enabled, cod_fee_pct, settlement_cycle, cod_netting_enabled, unsettled_amount, entries}", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/business/cod/settlements": { "get": { "tags": [ "Account" ], "summary": "Cash on delivery settlements: {id, reference, period_start, period_end, gross, fee, net, currency, status, paid_at, orders}", "operationId": "codSettlements", "responses": { "200": { "description": "Settlements", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/business/trips/export": { "get": { "tags": [ "Bookings" ], "summary": "Every trip matching from, to, type and status, as CSV", "operationId": "exportTrips", "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string" } }, { "name": "to", "in": "query", "schema": { "type": "string" } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "ride", "parcel", "airport", "cargo", "all" ] } }, { "name": "status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "text/csv" } } } }, "/business/batches": { "get": { "tags": [ "Bookings" ], "summary": "Your delivery batches", "operationId": "listBatches", "responses": { "200": { "description": "Batches", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "post": { "tags": [ "Bookings" ], "summary": "Book a batch of up to 50 deliveries; retry safely with external_reference or Idempotency-Key", "operationId": "createBatch", "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Batch booked", "content": { "application/json": { "schema": { "type": "object" } } } }, "200": { "description": "replayed: true" }, "409": { "description": "reference_conflict | request_in_progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/batches/{batch}": { "get": { "tags": [ "Bookings" ], "summary": "One batch and its stops", "operationId": "showBatch", "parameters": [ { "name": "batch", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Batch", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "webhooks": { "trip.accepted": { "post": { "operationId": "onTripAccepted", "summary": "A driver accepted", "description": "Signed: X-Areye-Signature is sha256=HMAC-SHA256(raw body, your webhook secret); X-Areye-Signature-V2 is t={X-Areye-Timestamp},sha256=HMAC-SHA256(timestamp + \".\" + raw body, secret): verify V2 and refuse a timestamp more than 5 minutes off. Retried for about 8.5 hours until you answer 2xx. Order is not guaranteed.", "parameters": [ { "name": "X-Areye-Event", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Signature-V2", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Timestamp", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "trip_id", "reference", "status" ], "properties": { "trip_id": { "type": "integer" }, "reference": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/TripStatus" }, "driver_name": { "type": [ "string", "null" ] } } } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery" } } } }, "trip.picked_up": { "post": { "operationId": "onTripPickedUp", "summary": "Collected; status is now active", "description": "Signed: X-Areye-Signature is sha256=HMAC-SHA256(raw body, your webhook secret); X-Areye-Signature-V2 is t={X-Areye-Timestamp},sha256=HMAC-SHA256(timestamp + \".\" + raw body, secret): verify V2 and refuse a timestamp more than 5 minutes off. Retried for about 8.5 hours until you answer 2xx. Order is not guaranteed.", "parameters": [ { "name": "X-Areye-Event", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Signature-V2", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Timestamp", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "trip_id", "reference", "status" ], "properties": { "trip_id": { "type": "integer" }, "reference": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/TripStatus" } } } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery" } } } }, "trip.completed": { "post": { "operationId": "onTripCompleted", "summary": "Delivered", "description": "Signed: X-Areye-Signature is sha256=HMAC-SHA256(raw body, your webhook secret); X-Areye-Signature-V2 is t={X-Areye-Timestamp},sha256=HMAC-SHA256(timestamp + \".\" + raw body, secret): verify V2 and refuse a timestamp more than 5 minutes off. Retried for about 8.5 hours until you answer 2xx. Order is not guaranteed.", "parameters": [ { "name": "X-Areye-Event", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Signature-V2", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Timestamp", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "trip_id", "reference", "status" ], "properties": { "trip_id": { "type": "integer" }, "reference": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/TripStatus" }, "amount": { "type": "number" }, "picked_up_at": { "type": [ "string", "null" ] }, "completed_at": { "type": "string" }, "pod_photo_url": { "type": [ "string", "null" ] }, "pod_signature_url": { "type": [ "string", "null" ] }, "pod_at": { "type": [ "string", "null" ] }, "age_verification_outcome": { "type": [ "string", "null" ] }, "cod_status": { "type": [ "string", "null" ] }, "cod_collected_amount": { "type": [ "number", "null" ] }, "delivery_outcome": { "type": "string", "enum": [ "delivered", "returned" ] }, "returned": { "type": "boolean" }, "return_reason": { "type": [ "string", "null" ], "description": "The driver's reason, or age_verification_refused" } } } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery" } } } }, "trip.delivery_failed": { "post": { "operationId": "onTripDeliveryFailed", "summary": "Could not deliver; the goods are coming back (then trip.completed, delivery_outcome \"returned\")", "description": "Signed: X-Areye-Signature is sha256=HMAC-SHA256(raw body, your webhook secret); X-Areye-Signature-V2 is t={X-Areye-Timestamp},sha256=HMAC-SHA256(timestamp + \".\" + raw body, secret): verify V2 and refuse a timestamp more than 5 minutes off. Retried for about 8.5 hours until you answer 2xx. Order is not guaranteed.", "parameters": [ { "name": "X-Areye-Event", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Signature-V2", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Timestamp", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "trip_id", "reference", "status" ], "properties": { "trip_id": { "type": "integer" }, "reference": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/TripStatus" }, "reason": { "type": "string" }, "return_reason": { "type": "string" }, "returning": { "type": "boolean" }, "return_due_at": { "type": "string" } } } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery" } } } }, "trip.return_overdue": { "post": { "operationId": "onTripReturnOverdue", "summary": "A failed delivery coming back to you is past its return deadline; Areye operations are chasing the driver (sent once)", "description": "Signed: X-Areye-Signature is sha256=HMAC-SHA256(raw body, your webhook secret); X-Areye-Signature-V2 is t={X-Areye-Timestamp},sha256=HMAC-SHA256(timestamp + \".\" + raw body, secret): verify V2 and refuse a timestamp more than 5 minutes off. Retried for about 8.5 hours until you answer 2xx. Order is not guaranteed.", "parameters": [ { "name": "X-Areye-Event", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Signature-V2", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Timestamp", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "trip_id", "reference", "status" ], "properties": { "trip_id": { "type": "integer" }, "reference": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/TripStatus" }, "return_due_at": { "type": "string" }, "return_reason": { "type": [ "string", "null" ] } } } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery" } } } }, "trip.age_verified": { "post": { "operationId": "onTripAgeVerified", "summary": "Age-restricted order: the buyer passed the ID check", "description": "Signed: X-Areye-Signature is sha256=HMAC-SHA256(raw body, your webhook secret); X-Areye-Signature-V2 is t={X-Areye-Timestamp},sha256=HMAC-SHA256(timestamp + \".\" + raw body, secret): verify V2 and refuse a timestamp more than 5 minutes off. Retried for about 8.5 hours until you answer 2xx. Order is not guaranteed.", "parameters": [ { "name": "X-Areye-Event", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Signature-V2", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Timestamp", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "trip_id", "reference", "status" ], "properties": { "trip_id": { "type": "integer" }, "reference": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/TripStatus" }, "age_verification_outcome": { "type": "string" } } } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery" } } } }, "trip.age_verification_failed": { "post": { "operationId": "onTripAgeVerificationFailed", "summary": "Age-restricted order: the buyer failed the ID check; the goods return", "description": "Signed: X-Areye-Signature is sha256=HMAC-SHA256(raw body, your webhook secret); X-Areye-Signature-V2 is t={X-Areye-Timestamp},sha256=HMAC-SHA256(timestamp + \".\" + raw body, secret): verify V2 and refuse a timestamp more than 5 minutes off. Retried for about 8.5 hours until you answer 2xx. Order is not guaranteed.", "parameters": [ { "name": "X-Areye-Event", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Signature-V2", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Timestamp", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "trip_id", "reference", "status" ], "properties": { "trip_id": { "type": "integer" }, "reference": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/TripStatus" }, "age_verification_outcome": { "type": "string" }, "reason": { "type": [ "string", "null" ] } } } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery" } } } }, "trip.cancelled": { "post": { "operationId": "onTripCancelled", "summary": "Cancelled", "description": "Signed: X-Areye-Signature is sha256=HMAC-SHA256(raw body, your webhook secret); X-Areye-Signature-V2 is t={X-Areye-Timestamp},sha256=HMAC-SHA256(timestamp + \".\" + raw body, secret): verify V2 and refuse a timestamp more than 5 minutes off. Retried for about 8.5 hours until you answer 2xx. Order is not guaranteed.", "parameters": [ { "name": "X-Areye-Event", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Signature-V2", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Timestamp", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "trip_id", "reference", "status" ], "properties": { "trip_id": { "type": "integer" }, "reference": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/TripStatus" }, "cancelled_by": { "type": "string" }, "reason": { "type": [ "string", "null" ] } } } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery" } } } }, "trip.driver_released": { "post": { "operationId": "onTripDriverReleased", "summary": "The driver dropped the job and Areye has put it back on the market (not terminal: trip.accepted follows)", "description": "Signed: X-Areye-Signature is sha256=HMAC-SHA256(raw body, your webhook secret); X-Areye-Signature-V2 is t={X-Areye-Timestamp},sha256=HMAC-SHA256(timestamp + \".\" + raw body, secret): verify V2 and refuse a timestamp more than 5 minutes off. Retried for about 8.5 hours until you answer 2xx. Order is not guaranteed.", "parameters": [ { "name": "X-Areye-Event", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Signature-V2", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Timestamp", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "trip_id", "reference", "status" ], "properties": { "trip_id": { "type": "integer" }, "reference": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/TripStatus" }, "cancelled_by": { "type": "string" }, "requeued": { "type": "boolean" }, "reason": { "type": [ "string", "null" ] } } } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery" } } } }, "trip.review_required": { "post": { "operationId": "onTripReviewRequired", "summary": "Bulky order held for review before dispatch", "description": "Signed: X-Areye-Signature is sha256=HMAC-SHA256(raw body, your webhook secret); X-Areye-Signature-V2 is t={X-Areye-Timestamp},sha256=HMAC-SHA256(timestamp + \".\" + raw body, secret): verify V2 and refuse a timestamp more than 5 minutes off. Retried for about 8.5 hours until you answer 2xx. Order is not guaranteed.", "parameters": [ { "name": "X-Areye-Event", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Signature-V2", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Timestamp", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "trip_id", "reference", "status" ], "properties": { "trip_id": { "type": "integer" }, "reference": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/TripStatus" }, "reasons": { "type": "array", "items": { "type": "string" } } } } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery" } } } }, "trip.quote_changed": { "post": { "operationId": "onTripQuoteChanged", "summary": "Review raised the price: accept or decline it", "description": "Signed: X-Areye-Signature is sha256=HMAC-SHA256(raw body, your webhook secret); X-Areye-Signature-V2 is t={X-Areye-Timestamp},sha256=HMAC-SHA256(timestamp + \".\" + raw body, secret): verify V2 and refuse a timestamp more than 5 minutes off. Retried for about 8.5 hours until you answer 2xx. Order is not guaranteed.", "parameters": [ { "name": "X-Areye-Event", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Signature-V2", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Timestamp", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "trip_id", "reference", "status" ], "properties": { "trip_id": { "type": "integer" }, "reference": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/TripStatus" }, "previous_total": { "type": "number" }, "new_total": { "type": "number" }, "currency": { "type": "string" } } } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery" } } } }, "trip.review_approved": { "post": { "operationId": "onTripReviewApproved", "summary": "Review approved; released to dispatch", "description": "Signed: X-Areye-Signature is sha256=HMAC-SHA256(raw body, your webhook secret); X-Areye-Signature-V2 is t={X-Areye-Timestamp},sha256=HMAC-SHA256(timestamp + \".\" + raw body, secret): verify V2 and refuse a timestamp more than 5 minutes off. Retried for about 8.5 hours until you answer 2xx. Order is not guaranteed.", "parameters": [ { "name": "X-Areye-Event", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Signature-V2", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Timestamp", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "trip_id", "reference", "status" ], "properties": { "trip_id": { "type": "integer" }, "reference": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/TripStatus" }, "total": { "type": "number" } } } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery" } } } }, "trip.delivery_outcome": { "post": { "operationId": "onTripDeliveryOutcome", "summary": "What happened to each line at the door", "description": "Signed: X-Areye-Signature is sha256=HMAC-SHA256(raw body, your webhook secret); X-Areye-Signature-V2 is t={X-Areye-Timestamp},sha256=HMAC-SHA256(timestamp + \".\" + raw body, secret): verify V2 and refuse a timestamp more than 5 minutes off. Retried for about 8.5 hours until you answer 2xx. Order is not guaranteed.", "parameters": [ { "name": "X-Areye-Event", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Signature-V2", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Timestamp", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "trip_id", "reference", "status" ], "properties": { "trip_id": { "type": "integer" }, "reference": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/TripStatus" }, "lines": { "type": "object", "description": "line_no \u2192 delivered | damaged | refused | short" }, "returning_lines": { "type": "array", "items": { "type": "integer" } }, "note": { "type": [ "string", "null" ] } } } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery" } } } }, "trip.exception": { "post": { "operationId": "onTripException", "summary": "The driver reported a structured problem", "description": "Signed: X-Areye-Signature is sha256=HMAC-SHA256(raw body, your webhook secret); X-Areye-Signature-V2 is t={X-Areye-Timestamp},sha256=HMAC-SHA256(timestamp + \".\" + raw body, secret): verify V2 and refuse a timestamp more than 5 minutes off. Retried for about 8.5 hours until you answer 2xx. Order is not guaranteed.", "parameters": [ { "name": "X-Areye-Event", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Signature-V2", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Timestamp", "in": "header", "schema": { "type": "string" } }, { "name": "X-Areye-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "trip_id", "reference", "status" ], "properties": { "trip_id": { "type": "integer" }, "reference": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/TripStatus" }, "exception": { "type": "string", "enum": [ "merchant_not_ready", "manifest_mismatch", "serial_mismatch", "damaged_at_collection", "unsafe_load", "vehicle_unsuitable", "crew_unavailable", "damaged_in_transit", "access_blocked", "no_working_lift", "does_not_fit_access", "recipient_unavailable", "recipient_refused", "other" ] }, "note": { "type": [ "string", "null" ] }, "before_collection": { "type": "boolean" }, "returned_to_review": { "type": "boolean", "description": "True when, before collection, the order went back to operations" } } } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery" } } } } }, "components": { "securitySchemes": { "BusinessKey": { "type": "apiKey", "in": "header", "name": "X-Business-API-Key" } }, "schemas": { "Error": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "const": false }, "message": { "type": "string" }, "code": { "type": "string", "description": "Stable machine code, on every booking refusal. Among them: validation_failed, insufficient_balance, credit_limit_exceeded, OUT_OF_SERVICE_AREA, zone_service_unavailable, vehicle_fit_refused, cod_refused, service_not_enabled, service_paused, booking_refused, scope_denied, external_reference_conflict, booking_in_progress, not_cancellable, test_booking_refused, test_mode_moved_to_sandbox, sandbox_key_on_live, live_key_on_sandbox, sandbox_only, live_only; otherwise the code for the status (conflict, unprocessable, forbidden, \u2026)" }, "environment": { "type": "string", "enum": [ "sandbox" ], "description": "Present on every sandbox response" }, "reference": { "type": [ "string", "null" ] } } }, "Ok": { "type": "object", "properties": { "success": { "const": true }, "message": { "type": "string" } } }, "ListEnvelope": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object" } } } }, "TripStatus": { "type": "string", "enum": [ "pending", "scheduled", "queued", "accepted", "enroute", "arrived", "active", "completed", "cancelled", "rider_no_show" ], "description": "Final: completed, cancelled, rider_no_show (the driver waited at the pickup and nobody came; a trip.cancelled webhook with reason rider_no_show is sent). Cancellable: pending, scheduled, queued, accepted, enroute, arrived. Treat unknown values as in progress." }, "Point": { "type": "object", "required": [ "lat", "lng" ], "properties": { "address": { "type": "string" }, "lat": { "type": "number" }, "lng": { "type": "number" } } }, "BookRequest": { "type": "object", "required": [ "passenger_name", "passenger_phone", "pickup_address", "pickup_lat", "pickup_lng", "dest_address", "dest_lat", "dest_lng" ], "properties": { "external_reference": { "type": "string", "maxLength": 80, "description": "Your stable order id. Required in practice: it is what makes retries safe." }, "type": { "type": "string", "enum": [ "ride", "parcel", "airport" ], "description": "Cargo is type parcel with segment cargo" }, "segment": { "type": "string", "enum": [ "parcel", "cargo" ] }, "test": { "type": "boolean", "description": "Retired: on live, true is refused with test_mode_moved_to_sandbox; in the sandbox it is ignored. Test in the sandbox." }, "passenger_name": { "type": "string" }, "passenger_phone": { "type": "string" }, "recipient_name": { "type": "string", "maxLength": 100 }, "recipient_phone": { "type": "string", "maxLength": 20 }, "pickup_address": { "type": "string" }, "pickup_lat": { "type": "number" }, "pickup_lng": { "type": "number" }, "dest_address": { "type": "string" }, "dest_lat": { "type": "number" }, "dest_lng": { "type": "number" }, "stops": { "type": "array", "maxItems": 3, "items": { "$ref": "#/components/schemas/Point" } }, "scheduled_at": { "type": "string", "format": "date-time", "description": "With an offset. Within 10 minutes means now; no offset means Africa/Gaborone." }, "vehicle_type_id": { "type": "integer" }, "parcel_size": { "type": "string", "enum": [ "small", "medium", "large", "oversized" ] }, "parcel_weight_kg": { "type": "number" }, "parcel_length_cm": { "type": "number" }, "parcel_width_cm": { "type": "number" }, "parcel_height_cm": { "type": "number" }, "fragile": { "type": "boolean" }, "declared_value": { "type": "number" }, "contents_category": { "type": "string", "maxLength": 40 }, "contents_description": { "type": "string", "maxLength": 255 }, "notes": { "type": "string" }, "payment_method": { "type": "string", "enum": [ "business_wallet", "cash", "duela_easy" ] }, "customer_payment": { "type": "string", "enum": [ "cod", "prepaid" ] }, "cod_amount": { "type": "number" }, "bring_change_amount": { "type": "number" }, "shop_deliver": { "type": "boolean" }, "purchase_amount": { "type": "number", "description": "Required when shop_deliver is true" }, "prep_minutes": { "type": "integer", "minimum": 0, "maximum": 600, "description": "Drivers are offered the order about 12 minutes before it is ready" }, "handover_required": { "type": "boolean", "description": "Driver waits at the counter until you call /ready" }, "delivery_speed": { "type": "string", "enum": [ "standard", "priority" ], "default": "standard", "description": "priority (express): offered to drivers at once at the widest radius, never batched or combined with another delivery. A priority fee is charged with the delivery (priority_fee in the response); part of it goes to the driver on completion. Refunded with the delivery if it is cancelled. Deliveries only (type parcel), not scheduled or bulky; when priority cannot apply the booking goes ahead as standard and the response says why (delivery_speed_applied, delivery_speed_reason). Refused on /business/batches." }, "age_verification_required": { "type": "boolean" }, "delivery_code": { "type": "string", "minLength": 4, "maxLength": 4, "pattern": "^[0-9]{4}$", "description": "Your customer's code, exactly 4 digits; the driver enters it at the door. Any other value is refused with 422 invalid_delivery_code." }, "order_payload": { "type": "object", "properties": { "store_name": { "type": "string" }, "store_phone": { "type": "string" }, "order_note": { "type": "string" }, "module_type": { "type": "string" }, "order_amount": { "type": "number" }, "pieces": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Boxes this order is packed in (packing slip \"n of N\")" }, "items": { "type": "array", "maxItems": 100, "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "qty": { "type": "number" }, "price": { "type": "number" }, "options": { "type": "string" }, "image": { "type": "string" }, "sku": { "type": "string" }, "barcode": { "type": "string" }, "aisle": { "type": "string" }, "category": { "type": "string" }, "substitution": { "type": "string", "enum": [ "refund", "match", "ask", "none" ] }, "qty_packed": { "type": "number" }, "substitute": { "type": "string", "description": "What was packed instead, when it was substituted" } } } } } }, "expense_code": { "type": "string", "maxLength": 50 }, "airport_terminal_id": { "type": "integer" }, "booking_type": { "type": "string", "enum": [ "arrival", "departure" ] }, "flight_number": { "type": "string" }, "flight_date": { "type": "string", "format": "date" } } }, "Tracking": { "type": "object", "description": "Fields may be added; ignore unknown ones.", "properties": { "reference": { "type": "string" }, "type": { "type": "string" }, "status": { "$ref": "#/components/schemas/TripStatus" }, "is_active": { "type": "boolean" }, "is_complete": { "type": "boolean" }, "dest_address": { "type": [ "string", "null" ] }, "dest_lat": { "type": "number" }, "dest_lng": { "type": "number" }, "driver_name": { "type": [ "string", "null" ] }, "driver_phone": { "type": [ "string", "null" ], "description": "Always null: drivers' numbers are not public" }, "driver_plate": { "type": [ "string", "null" ] }, "driver_color": { "type": [ "string", "null" ] }, "driver_lat": { "type": [ "number", "null" ], "description": "Null unless a driver is on this job" }, "driver_lng": { "type": [ "number", "null" ] }, "eta_minutes": { "type": [ "integer", "null" ] }, "accepted_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "location_observed_at": { "type": [ "string", "null" ], "description": "When the driver's device last fixed this position" }, "location_age_seconds": { "type": [ "integer", "null" ] }, "location_is_fresh": { "type": "boolean", "description": "False = show as last known position, not live" }, "scope": { "type": "string", "enum": [ "token", "reference" ] }, "poll_after_seconds": { "type": [ "integer", "null" ], "description": "Null once the trip has ended: stop polling" }, "pickup_address": { "type": [ "string", "null" ], "description": "Token scope only" }, "pickup_lat": { "type": [ "number", "null" ] }, "pickup_lng": { "type": [ "number", "null" ] }, "stops": { "type": "array", "description": "Token scope only, in route order", "items": { "type": "object", "properties": { "address": { "type": [ "string", "null" ] }, "lat": { "type": [ "number", "null" ] }, "lng": { "type": [ "number", "null" ] }, "reached": { "type": "boolean" } } } }, "route_polyline": { "type": [ "string", "null" ], "description": "Token scope only; null until stored geometry exists. Draw the route once from pickup, stops and destination." }, "link_expires_at": { "type": [ "string", "null" ], "description": "Token scope only" } } }, "BulkyLine": { "type": "object", "required": [ "description", "weight_kg", "length_cm", "width_cm", "height_cm" ], "properties": { "sku": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string", "description": "e.g. bed, mattress, sofa, furniture, refrigerator, washing_machine, television, appliance, general_cargo" }, "quantity": { "type": "integer" }, "weight_kg": { "type": "number", "description": "Per item" }, "length_cm": { "type": "integer" }, "width_cm": { "type": "integer" }, "height_cm": { "type": "integer" }, "fragile": { "type": "boolean" }, "upright": { "type": "boolean", "description": "Must travel with its height vertical" }, "stackable": { "type": "boolean" }, "declared_value": { "type": "number" }, "serial": { "type": "string", "description": "Checked at collection and delivery" }, "collection_photo_required": { "type": "boolean" }, "delivery_photo_required": { "type": "boolean" } } }, "BulkyFields": { "type": "object", "description": "Add these to a booking (with the usual route and recipient fields) to make it a bulky order. Omit goods and the booking is exactly as before.", "properties": { "goods": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/components/schemas/BulkyLine" } }, "service_level": { "type": "string", "enum": [ "curbside", "doorstep", "room_of_choice" ] }, "extras": { "type": "array", "items": { "type": "string", "enum": [ "assembly", "installation", "old_item_removal", "packaging_removal" ] }, "description": "Only where the merchant is authorised; otherwise the order is reviewed" }, "crew_required": { "type": "integer", "description": "Optional; derived when omitted" }, "needs": { "type": "object", "properties": { "body": { "type": "string", "enum": [ "open", "closed", "refrigerated" ] }, "tail_lift": { "type": "boolean" } } }, "access": { "type": "object", "properties": { "floor": { "type": "integer" }, "stairs": { "type": "boolean" }, "lift": { "type": "boolean", "description": "Omitted on an upper floor = review" }, "lift_dimensions_cm": { "type": "string" }, "merchant_loads": { "type": "boolean" }, "recipient_unloads": { "type": "boolean" }, "estate_instructions": { "type": "string" }, "parking": { "type": "string" }, "restricted_hours": { "type": "string" } } }, "handling": { "type": "string" }, "contacts": { "type": "object", "properties": { "collection_first_names": { "type": "string" }, "collection_surname": { "type": "string" }, "collection_phone": { "type": "string" }, "delivery_first_names": { "type": "string" }, "delivery_surname": { "type": "string" }, "delivery_phone": { "type": "string" } } }, "delivery_window": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } } }, "pickup_lat": { "type": "number" }, "pickup_lng": { "type": "number" }, "dest_lat": { "type": "number" }, "dest_lng": { "type": "number" } } }, "BulkyDecision": { "type": "object", "description": "Frozen on the order at booking; later settings never change it.", "properties": { "status": { "type": "string", "enum": [ "ok", "manual_review_required", "refused" ] }, "declared": { "type": "object" }, "totals": { "type": "object", "properties": { "item_count": { "type": "integer" }, "actual_weight_kg": { "type": "number" }, "volumetric_weight_kg": { "type": "number" }, "chargeable_weight_kg": { "type": "number" }, "cargo_volume_m3": { "type": "number" }, "longest_item_cm": { "type": "array", "items": { "type": "integer" } } } }, "fit": { "type": "object", "properties": { "vehicle_name": { "type": [ "string", "null" ] }, "packing_confidence": { "type": [ "string", "null" ], "enum": [ "proven", "manual_review", null ], "description": "proven = an arrangement of the whole load was demonstrated; manual_review = a person checks it" }, "evidence": { "type": "object", "description": "Per vehicle class: qualifies, and why not" } } }, "crew": { "type": "object", "properties": { "required": { "type": "integer" } } }, "review": { "type": "object", "properties": { "reasons": { "type": "array", "items": { "type": "string" } } } }, "window": { "type": [ "object", "null" ], "description": "From delivery_window and access.restricted_hours: earliest/latest arrival and dispatch. Not offered before, refused after." }, "rules": { "type": "object", "description": "Commercial rules frozen with the order: cancel_after_commit_fee, waiting, return_fee_pct, redelivery_fee_pct, disposal_fee" }, "proof": { "type": "object", "description": "What the driver must capture at collection and at delivery" }, "quote": { "type": [ "object", "null" ], "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "number" } } } }, "merchant_total": { "type": "number" }, "driver_earning": { "type": "number" }, "crew_earning": { "type": "number" }, "currency": { "type": "string" }, "terms": { "type": "object", "properties": { "waiting": { "type": "string" }, "return": { "type": "string" } } } } } } }, "Trip": { "type": "object", "description": "Fields may be added; ignore unknown ones.", "properties": { "id": { "type": "integer" }, "reference": { "type": "string" }, "tracking_url": { "type": [ "string", "null" ], "description": "Open or embed this. For your deliveries it carries a trip-scoped token; build nothing from the reference. Null once the link is revoked (rotate for a new one)." }, "tracking_link_status": { "type": "string", "enum": [ "active", "revoked", "reference" ], "description": "reference = a trip from before tokenised links" }, "status": { "$ref": "#/components/schemas/TripStatus" }, "type": { "type": "string" }, "pickup_address": { "type": "string" }, "dest_address": { "type": "string" }, "billing_amount": { "type": [ "number", "null" ] }, "billing_currency": { "type": [ "string", "null" ] }, "eta_minutes": { "type": [ "integer", "null" ] }, "prep_minutes": { "type": [ "integer", "null" ] }, "ready_estimate_at": { "type": [ "string", "null" ] }, "ready_confirmed_at": { "type": [ "string", "null" ] }, "handover_required": { "type": "boolean" }, "cod_amount": { "type": [ "number", "null" ] }, "cod_status": { "type": [ "string", "null" ] }, "order_payload": { "type": [ "object", "null" ] }, "payment_method": { "type": [ "string", "null" ] }, "delivery_speed": { "type": "string", "enum": [ "standard", "priority" ], "description": "The speed applied to this delivery" }, "priority_fee": { "type": "number", "description": "Priority deliveries only: the fee charged with the delivery, in billing_currency" } } }, "BookResponse": { "type": "object", "properties": { "success": { "const": true }, "replayed": { "type": "boolean", "description": "Present and true on a 200 replay" }, "data": { "allOf": [ { "$ref": "#/components/schemas/Trip" }, { "type": "object", "properties": { "chat_token": { "type": "string" }, "is_test": { "type": "boolean" }, "delivery_speed_applied": { "type": "string", "enum": [ "standard", "priority" ] }, "delivery_speed_reason": { "type": "string", "description": "Present when priority was asked for and the delivery was booked as standard" } } } ] } } }, "WebhookEnvelope": { "type": "object", "required": [ "id", "event", "business_id", "timestamp", "data" ], "properties": { "id": { "type": "string", "description": "Delivery id; dedupe on this. Also sent as X-Areye-Delivery" }, "event_id": { "type": "string" }, "event": { "type": "string" }, "business_id": { "type": "integer" }, "timestamp": { "type": "string" }, "data": { "type": "object", "description": "trip_id, reference, external_reference, status, tracking_url (added), delivery_speed (standard | priority, on trip.* events), plus event fields. Webhooks are the authoritative delivery state; they may arrive more than once (dedupe on id) or out of order (compare timestamp; never move a delivery backwards)." } } } } } }