{ "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": "Fleet partner", "description": "Run a ride-hailing fleet on Areye: your vehicles and drivers, live oversight, every trip's split, statements and payouts. Enabled per account by Areye (403 fleet_not_enabled until then). Payment methods are shown as the customer paid (Card, Wallet, Cash, Orange Money, DuelaEasy, Business account), never a provider. Rent arrears and collections, pausing a vehicle, downtime, operating costs and utilisation are covered too. Bank details and payout requests need a signed-in owner or portal admin." }, { "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." }, { "name": "Breakdown towing", "description": "Book and follow breakdown tows for your policyholders or fleet. Every job carries the policy number and claim reference; a monthly statement lists both per line. Prices are upfront: call-out + per km to the pickup (after free km) + per km towed, times the class multiplier, plus a night or weekend surcharge, never below the zone minimum; the final price can only grow by capped waiting time and capped extra distance, and never falls below the quote. Errors: 401 unauthenticated \u00b7 403 forbidden (permission) \u00b7 404 not_found (also for another account's job) \u00b7 409 invalid_transition | already_loaded | not_finished | quote_expired \u00b7 422 validation \u00b7 423 tow_disabled \u00b7 429 throttled. Webhooks: tow.requested, tow.assigned, tow.en_route, tow.arrived, tow.loaded, tow.in_transit, tow.delivered, tow.cancelled, tow.price_finalised, tow.evidence_added \u2014 the standard envelope with data = {job: TowJob, previous_stage, sandbox}, signed with X-Areye-Signature (sha256=HMAC(body)) and X-Areye-Signature-V2 (t=,sha256=HMAC(ts.body)); verify: expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret); compare in constant time and reject t older than 5 minutes. Retried with backoff up to the attempt limit; see GET /business/webhooks/deliveries and replay. SANDBOX: with sk_sandbox_ keys a booked tow goes to a simulated operator, never real dispatch. It advances one stage every 20 s on autopilot (PUT /business/sandbox/autopilot {\"tow\": false} to stop), or step it with POST /business/sandbox/tow/{reference}/{action}. Policy number SANDBOX-DECLINE: the operator declines once and is re-assigned; SANDBOX-NOOP: nobody is found and the job is cancelled with no fee. Guide: docs/TOW_SANDBOX.md." } ], "paths": { "/business/bus/departures/{schedule}/seat-map": { "get": { "tags": [ "Bus seats" ], "summary": "Seat map for one departure over one stretch of the route", "operationId": "busSeatMap", "parameters": [ { "name": "schedule", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "date", "in": "query", "required": true, "schema": { "type": "string" }, "description": "YYYY-MM-DD" }, { "name": "board_stop_id", "in": "query", "required": true, "schema": { "type": "integer" } }, { "name": "alight_stop_id", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "layout, seats[{no,pos,state,label}], available_count" }, "404": { "description": "not_found: not your departure (retailers see any active bus)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_segment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/bus/sell": { "post": { "tags": [ "Bus seats" ], "summary": "Sell seats at the door (operator) or at a till (retailer, float debited)", "operationId": "busSell", "description": "Body: schedule_id, date, board_stop_id, alight_stop_id, seats[{seat_no, first_name, last_name, phone}], payment_method cash. Sold at once; each passenger gets an SMS ticket.", "responses": { "201": { "description": "Sold booking with ticket codes" }, "402": { "description": "float_insufficient", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "not_a_seller, bus_sales_off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "seat_taken", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_segment, seat_unknown, passenger_details_required, departure_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/bus/checkin": { "post": { "tags": [ "Bus seats" ], "summary": "Board a passenger by ticket code or phone", "operationId": "busCheckin", "responses": { "200": { "description": "Checked in" }, "404": { "description": "ticket_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "already_checked_in, ticket_wrong_departure, ticket_not_paid, phone_ambiguous", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/bus/manifest": { "get": { "tags": [ "Bus seats" ], "summary": "Manifest by boarding stop in seat order (format=csv for a file)", "operationId": "busManifest", "parameters": [ { "name": "schedule_id", "in": "query", "required": true, "schema": { "type": "integer" } }, { "name": "date", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "stop_id", "in": "query", "schema": { "type": "integer" } }, { "name": "format", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "departure, stops[{stop, seq, time, passengers}], totals" }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/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": "Stage a new API key (shown once; traffic is unchanged)", "operationId": "stageApiKey", "responses": { "200": { "description": "The staged key, shown once", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "signed_in_admin_only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/webhook-secret/regenerate": { "post": { "tags": [ "Account" ], "summary": "Stage a new webhook secret (traffic is unchanged)", "operationId": "stageWebhookSecret", "responses": { "200": { "description": "The staged secret", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "signed_in_admin_only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/credentials/{kind}/activate": { "post": { "tags": [ "Account" ], "summary": "Activate a staged api or webhook credential; old stays valid for 24 hours", "operationId": "activateCredential", "responses": { "200": { "description": "Activated" } } } }, "/business/credentials/{kind}/discard-staged": { "post": { "tags": [ "Account" ], "summary": "Discard a staged api or webhook credential with an audit reason", "operationId": "discardStagedCredential", "responses": { "200": { "description": "Discarded" }, "409": { "description": "Nothing staged" } } } }, "/business/credentials/{kind}/retire-previous": { "post": { "tags": [ "Account" ], "summary": "Emergency-retire the previous credential before its 24-hour expiry (reason required)", "operationId": "retirePreviousCredential", "responses": { "200": { "description": "Retired" } } } }, "/business/credentials/{kind}/rollback": { "post": { "tags": [ "Account" ], "summary": "Restore the unexpired previous credential (reason required)", "operationId": "rollbackCredential", "responses": { "200": { "description": "Restored" } } } }, "/business/webhook-test": { "post": { "tags": [ "Account" ], "summary": "Send a signed webhook.test event (V1, V2 and V3/key-id 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/fleet/arrears": { "get": { "tags": [ "Fleet partner" ], "summary": "Fixed-rent vehicles behind or paused: fee_status, arrears_amount, arrears_periods, arrears_since, last_collection, next_due_on, driver", "operationId": "fleetArrears", "responses": { "200": { "description": "{currency, settings{suspend_periods, auto_suspend}, summary{vehicles, amount, suspended}, vehicles[]}", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/business/fleet/utilisation": { "get": { "tags": [ "Fleet partner" ], "summary": "Per vehicle: days_in_period, days_in_service, days_down (by reason), days_with_trips, trips, km, online_hours, utilisation_pct, earnings, fixed_fees, rto, costs, profit; totals", "operationId": "fleetUtilisation", "parameters": [ { "name": "period", "in": "query", "schema": { "type": "string" }, "description": "YYYY-MM" }, { "name": "from", "in": "query", "schema": { "type": "string" } }, { "name": "to", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "{vehicles[], totals, from, to, currency}", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/business/fleet/vehicles/{vehicle}/collections": { "get": { "tags": [ "Fleet partner" ], "summary": "The rent ledger for one vehicle: every collection attempt (collected | partial | failed) with collected_amount and wallet_balance_after", "operationId": "fleetVehicleCollections", "parameters": [ { "name": "vehicle", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "{vehicle, next_due_on, collections[], totals{billed, collected, uncollected}}", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/business/fleet/vehicles/{vehicle}/rent": { "get": { "tags": [ "Fleet partner" ], "summary": "The vehicle's rent book when the owner collects: rent_collection (areye | owner), periods (due | part_paid | paid | waived, or collected | partial | failed when Areye collects), payments with receipt numbers and where each was applied, credit, totals, and the audit trail", "operationId": "fleetVehicleRent", "parameters": [ { "name": "vehicle", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "{vehicle, rent_collection, rent_collection_override, fleet_rent_collection, next_due_on, credit, methods[], periods[], payments[], totals{due, paid, waived, outstanding}, events[]}", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/business/fleet/vehicles/{vehicle}/rent/payments": { "post": { "tags": [ "Fleet partner" ], "summary": "Record rent the owner received (owner or portal admin). Applied to the oldest open periods first; any surplus is credit for the next period. The driver is notified with the receipt number. Send idempotency_key (or an Idempotency-Key header): the same key again returns the first payment with duplicate=true.", "operationId": "fleetRentRecordPayment", "parameters": [ { "name": "vehicle", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "method" ], "properties": { "amount": { "type": "number", "description": "Up to 2 decimals" }, "method": { "type": "string", "enum": [ "cash", "eft", "orange_money", "other" ] }, "paid_on": { "type": "string", "format": "date" }, "reference": { "type": "string" }, "note": { "type": "string" }, "idempotency_key": { "type": "string" }, "driver_id": { "type": "string" } } } } } }, "responses": { "201": { "description": "{payment, duplicate:false, vehicle, credit, message}", "content": { "application/json": { "schema": { "type": "object" } } } }, "200": { "description": "duplicate:true \u2014 already recorded under this key" }, "422": { "description": "payment_not_recorded with a reason" } } } }, "/business/fleet/vehicles/{vehicle}/rent/payments/{payment}/void": { "post": { "tags": [ "Fleet partner" ], "summary": "Void a recorded payment with a reason; it is kept, marked voided, and the rent it covered is owed again", "operationId": "fleetRentVoidPayment", "parameters": [ { "name": "vehicle", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "payment", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "{payment, vehicle, message}", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "payment_not_voided" } } } }, "/business/fleet/vehicles/{vehicle}/rent/periods/{collection}/waive": { "post": { "tags": [ "Fleet partner" ], "summary": "Waive what is still owed on one owner-collected rent period, with a reason", "operationId": "fleetRentWaivePeriod", "parameters": [ { "name": "vehicle", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "collection", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "{period, vehicle, message}", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "period_not_waived" } } } }, "/business/fleet/vehicles/{vehicle}/rent-collection": { "post": { "tags": [ "Fleet partner" ], "summary": "Who collects this vehicle's rent: areye, owner, or fleet (follow the fleet setting). Applies from the next due date.", "operationId": "fleetVehicleRentCollection", "parameters": [ { "name": "vehicle", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "areye", "owner", "fleet" ] } } } } } }, "responses": { "200": { "description": "{vehicle_id, rent_collection, rent_collection_override, applies_from, message}", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/business/fleet/rent-payments/{payment}/receipt": { "get": { "tags": [ "Fleet partner" ], "summary": "The rent receipt as a PDF", "operationId": "fleetRentReceipt", "parameters": [ { "name": "payment", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "application/pdf" } } } }, "/business/fleet/vehicles/{vehicle}/suspend": { "post": { "tags": [ "Fleet partner" ], "summary": "Pause a vehicle for rent: the driver is taken offline, told, and refused new ride offers", "operationId": "fleetVehicleSuspend", "parameters": [ { "name": "vehicle", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "{vehicle, message}", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "already_suspended" } } } }, "/business/fleet/vehicles/{vehicle}/reinstate": { "post": { "tags": [ "Fleet partner" ], "summary": "Lift a pause; the arrears still stand", "operationId": "fleetVehicleReinstate", "parameters": [ { "name": "vehicle", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "{vehicle, message}", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "not_suspended" } } } }, "/business/fleet/vehicles/{vehicle}/status": { "post": { "tags": [ "Fleet partner" ], "summary": "Open a status span: in_service (needs a driver), maintenance, off_road or available; the previous span closes", "operationId": "fleetVehicleStatus", "parameters": [ { "name": "vehicle", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "in_service", "maintenance", "off_road", "available" ] }, "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "{vehicle, span}", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "status_not_set with a reason" } } } }, "/business/fleet/vehicles/{vehicle}/status-log": { "get": { "tags": [ "Fleet partner" ], "summary": "The vehicle's status spans, newest first", "operationId": "fleetVehicleStatusLog", "parameters": [ { "name": "vehicle", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "{vehicle, spans[]}", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/business/fleet/vehicles/{vehicle}/costs": { "get": { "tags": [ "Fleet partner" ], "summary": "Operating costs on a vehicle; ?period=YYYY-MM or from&to, else all", "operationId": "fleetVehicleCosts", "parameters": [ { "name": "vehicle", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "period", "in": "query", "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string" } }, { "name": "to", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "{vehicle, types[], costs[], total, by_type}", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "post": { "tags": [ "Fleet partner" ], "summary": "Log a cost (service and repair rows are the maintenance log and move the odometer forward)", "operationId": "fleetVehicleAddCost", "parameters": [ { "name": "vehicle", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "amount" ], "properties": { "type": { "type": "string", "enum": [ "fuel", "insurance", "licence", "service", "repair", "tracker", "other" ] }, "amount": { "type": "number" }, "currency": { "type": "string" }, "incurred_on": { "type": "string", "format": "date" }, "odometer_km": { "type": "integer" }, "note": { "type": "string" } } } } } }, "responses": { "201": { "description": "{cost}", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/business/fleet/vehicles/{vehicle}/costs/{cost}": { "delete": { "tags": [ "Fleet partner" ], "summary": "Remove a cost line (kept on file, marked deleted)", "operationId": "fleetVehicleDeleteCost", "parameters": [ { "name": "vehicle", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "cost", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "{deleted, id}", "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 latest 50 delivery batches, each with its stops", "operationId": "listBatches", "responses": { "200": { "description": "Batches", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Batch" } } } } } } } } }, "post": { "tags": [ "Bookings" ], "summary": "Book a batch of up to 50 deliveries on one driver; retry safely with external_reference or Idempotency-Key", "operationId": "createBatch", "description": "One driver, one vehicle, for any retail merchant (restaurants, grocers, liquor stores, pharmacies, shops). Each stop takes the same goods fields and door rules as a single delivery (order lines, contents, declared value, 18+ ID check, delivery code, tip, COD). For orders collected now send dispatch_mode \"immediate\": Areye chooses the stop order, returns each stop's time at the door, refuses the batch when it adds more than max_added_minutes to any order (batch_adds_too_much_time), holds it off the market until shortly before the last ready_at (or until every order is marked ready with POST /business/trip/{reference}/ready), and freezes the driver's guaranteed pay. A priority (express) stop is never batched. With no dispatch_mode the legacy path is unchanged.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRequest" } } } }, "responses": { "201": { "description": "Batch booked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchBooked" } } } }, "202": { "description": "Bulky batch booked and held for review", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchBooked" } } } }, "200": { "description": "replayed: true \u2014 the first batch, nothing charged again", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchBooked" } } } }, "403": { "description": "reserved_routes_not_enabled | service_not_enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "reference_conflict | request_in_progress | prices_changed | no_longer_served", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "validation_failed | priority_not_batchable | batch_adds_too_much_time (with max_added_minutes and stops[]: stop, added_minutes, eta_minutes, alone_minutes) | ready_at_too_far | immediate_is_now | OUT_OF_SERVICE_AREA | insufficient balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/batches/estimate": { "post": { "tags": [ "Bookings" ], "summary": "Price a batch without booking it: per-stop fee, the alone price, the batch total and (immediate) times at the door", "operationId": "estimateBatch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRequest" } } } }, "responses": { "200": { "description": "Estimate; nothing booked or charged", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/BatchEstimate" } } } } } }, "422": { "description": "The same refusals as POST /business/batches, with the same codes", "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": "integer" }, "description": "batch_id" } ], "responses": { "200": { "description": "Batch", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Batch" } } } } } }, "404": { "description": "Not your batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/batches/{batch}/stops/{stop}/cancel": { "post": { "tags": [ "Bookings" ], "summary": "Cancel one order of a batch; the rest go on", "operationId": "cancelBatchStop", "description": "Only before that order is collected. Its fee and driver tip are refunded through its own trip (trip.cancelled), batch.stop_cancelled is sent, and the driver keeps the batch's guaranteed pay. Cancelling the last open order ends the batch (batch.cancelled). Stops cannot be added to a batch.", "parameters": [ { "name": "batch", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "batch_id" }, { "name": "stop", "in": "path", "required": true, "schema": { "type": "string" }, "description": "stop_id, the stop's Areye reference, or your external_reference for it" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 255 } } } } } }, "responses": { "200": { "description": "The batch after the cancel (already_cancelled: true on a repeat)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "already_cancelled": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Batch" } } } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "not_cancellable: collected or ended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/fleet": { "get": { "tags": [ "Fleet partner" ], "summary": "Fleet overview: defaults, settlement terms, counts, today and this month, outstanding fees, paperwork alerts", "operationId": "fleetOverview", "responses": { "200": { "description": "Overview", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/FleetOverview" } } } } } }, "403": { "description": "fleet_not_enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/fleet/settings": { "patch": { "tags": [ "Fleet partner" ], "summary": "Payment defaults for new vehicles, settlement cadence and day, automatic payout, bank on file, work categories", "operationId": "fleetUpdateSettings", "description": "Any subset of the fields. Owner, portal admin or integration key; the bank fields (fleet_bank_name, fleet_account_name, fleet_account_number, fleet_branch_code) need a signed-in owner or portal admin (403 signed_in_admin_only for a key).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FleetSettings" } } } }, "responses": { "200": { "description": "The settings as saved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/FleetSettings" } } } } } }, "403": { "description": "fleet_not_enabled | signed_in_admin_only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/fleet/live": { "get": { "tags": [ "Fleet partner" ], "summary": "Live board: every vehicle with its driver, the trip under way, tracker status and paperwork dates", "operationId": "fleetLive", "description": "A snapshot; poll every 30\u201360 seconds. online = on duty and the phone spoke to Areye in the last minutes; ready = can be given work now; lat/lng = last known position or null when stale.", "responses": { "200": { "description": "Vehicles", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "vehicles": { "type": "array", "items": { "$ref": "#/components/schemas/FleetLiveVehicle" } }, "tracker_enabled": { "type": "boolean" }, "as_at": { "type": "string" } } } } } } } }, "403": { "description": "fleet_not_enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/fleet/vehicles/{vehicle}/trips": { "get": { "tags": [ "Fleet partner" ], "summary": "Completed trips on one vehicle, newest first, with the settled split per trip", "operationId": "fleetVehicleTrips", "parameters": [ { "name": "vehicle", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "maximum": 200 } } ], "responses": { "200": { "description": "Trips, totals and paging", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/FleetTripsPage" } } } } } }, "404": { "description": "Not your vehicle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "fleet_not_enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/fleet/drivers": { "get": { "tags": [ "Fleet partner" ], "summary": "Your fleet drivers: documents, vehicle, online, today, wallet balance", "operationId": "fleetDrivers", "responses": { "200": { "description": "Drivers", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "drivers": { "type": "array", "items": { "$ref": "#/components/schemas/FleetDriver" } }, "required_documents": { "type": "array", "items": { "type": "string" } } } } } } } } }, "403": { "description": "fleet_not_enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/fleet/drivers/{driver}/trips": { "get": { "tags": [ "Fleet partner" ], "summary": "Completed trips by one of your drivers (same shape as a vehicle's trips)", "operationId": "fleetDriverTrips", "parameters": [ { "name": "driver", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Driver id" }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "page", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Trips, totals and paging", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/FleetTripsPage" } } } } } }, "404": { "description": "Not one of your fleet drivers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "fleet_not_enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/fleet/drivers/invite": { "post": { "tags": [ "Fleet partner" ], "summary": "Invite a driver by phone (SMS with the accept link; 14 days)", "operationId": "fleetInviteDriver", "description": "An existing Areye driver joins with one tap; a new one downloads the app and signs up with that phone, which attaches them automatically. With rental_vehicle_id the vehicle is assigned on acceptance.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone", "first_name", "last_name" ], "properties": { "phone": { "type": "string" }, "first_name": { "type": "string", "maxLength": 80 }, "last_name": { "type": "string", "maxLength": 80 }, "rental_vehicle_id": { "type": [ "integer", "null" ] } } } } } }, "responses": { "201": { "description": "The invitation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/FleetInvitation" } } } } } }, "422": { "description": "validation_failed | already in your fleet | open invitation exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "fleet_not_enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/fleet/invitations": { "get": { "tags": [ "Fleet partner" ], "summary": "Open and past invitations with their accept links", "operationId": "fleetInvitations", "responses": { "200": { "description": "Invitations", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "invitations": { "type": "array", "items": { "$ref": "#/components/schemas/FleetInvitation" } } } } } } } } }, "403": { "description": "fleet_not_enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/fleet/invitations/{invitation}/resend": { "post": { "tags": [ "Fleet partner" ], "summary": "Send the invitation SMS again (at most 3 reminders)", "operationId": "fleetResendInvitation", "parameters": [ { "name": "invitation", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/FleetInvitation" } } } } } }, "422": { "description": "Not open, or reminder limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/fleet/invitations/{invitation}": { "delete": { "tags": [ "Fleet partner" ], "summary": "Cancel an open invitation", "operationId": "fleetCancelInvitation", "parameters": [ { "name": "invitation", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/FleetInvitation" } } } } } }, "422": { "description": "Not open", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/fleet/vehicles/{vehicle}/assign": { "post": { "tags": [ "Fleet partner" ], "summary": "Put an active fleet driver in a free vehicle", "operationId": "fleetAssignVehicle", "parameters": [ { "name": "vehicle", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "driver_id" ], "properties": { "driver_id": { "type": "string" }, "reason": { "type": "string", "maxLength": 255 } } } } } }, "responses": { "200": { "description": "The vehicle with its driver", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" } } } } } }, "422": { "description": "Driver not in your fleet, vehicle not free, or driver already in another vehicle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not your vehicle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/fleet/vehicles/{vehicle}/unassign": { "post": { "tags": [ "Fleet partner" ], "summary": "Take the driver out of a vehicle, with a reason", "operationId": "fleetUnassignVehicle", "parameters": [ { "name": "vehicle", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string", "maxLength": 255 } } } } } }, "responses": { "200": { "description": "The vehicle, free again", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" } } } } } }, "422": { "description": "Nobody assigned, or a trip is under way", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not your vehicle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/fleet/drivers/{driver}": { "delete": { "tags": [ "Fleet partner" ], "summary": "Remove a driver from your fleet (status removed, reason kept; their vehicle is freed; the driver is told)", "operationId": "fleetRemoveDriver", "parameters": [ { "name": "driver", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Driver id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string", "maxLength": 255 } } } } } }, "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "driver_id": { "type": "string" }, "status": { "type": "string", "enum": [ "removed" ] }, "removed_at": { "type": "string" }, "removed_reason": { "type": "string" } } } } } } } }, "404": { "description": "Not one of your fleet drivers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/fleet/summary": { "get": { "tags": [ "Fleet partner" ], "summary": "Totals for a month or a date range, per vehicle and per driver", "operationId": "fleetSummary", "parameters": [ { "name": "period", "in": "query", "schema": { "type": "string" }, "description": "YYYY-MM; default the current month" }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Totals", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "currency": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "totals": { "allOf": [ { "$ref": "#/components/schemas/FleetMoneyTotals" }, { "type": "object", "properties": { "fixed_fees": { "type": "number" }, "rto_instalments": { "type": "number" }, "owner_total": { "type": "number", "description": "owner_earnings + fixed_fees + rto_instalments" } } } ] }, "by_vehicle": { "type": "array", "items": { "allOf": [ { "type": "object", "properties": { "vehicle_id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "plate_number": { "type": [ "string", "null" ] } } }, { "$ref": "#/components/schemas/FleetMoneyTotals" } ] } }, "by_driver": { "type": "array", "items": { "allOf": [ { "type": "object", "properties": { "driver_id": { "type": "string" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] } } }, { "$ref": "#/components/schemas/FleetMoneyTotals" } ] } }, "outstanding_fees": { "type": "number" } } } } } } } }, "403": { "description": "fleet_not_enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/fleet/settlements": { "get": { "tags": [ "Fleet partner" ], "summary": "Your settlement statements with payout status, newest first", "operationId": "fleetSettlements", "responses": { "200": { "description": "Statements", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FleetSettlement" } }, "bank_on_file": { "type": "boolean" }, "auto_payout": { "type": "boolean" }, "cadence": { "type": "string" } } } } } } } }, "403": { "description": "fleet_not_enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/fleet/settlements/{settlement}": { "get": { "tags": [ "Fleet partner" ], "summary": "One statement with every trip, vehicle and driver line; JSON, PDF or CSV", "operationId": "fleetSettlement", "parameters": [ { "name": "settlement", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "pdf", "csv" ], "default": "json" } } ], "responses": { "200": { "description": "The statement (JSON), or a file download for pdf/csv", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "allOf": [ { "$ref": "#/components/schemas/FleetSettlement" }, { "type": "object", "properties": { "trips": { "type": "array", "items": { "$ref": "#/components/schemas/FleetTripLine" } }, "by_vehicle": { "type": "array", "items": { "allOf": [ { "type": "object", "properties": { "vehicle_id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "plate_number": { "type": [ "string", "null" ] } } }, { "$ref": "#/components/schemas/FleetMoneyTotals" } ] } }, "by_driver": { "type": "array", "items": { "allOf": [ { "type": "object", "properties": { "driver_id": { "type": "string" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] } } }, { "$ref": "#/components/schemas/FleetMoneyTotals" } ] } }, "fixed_fee_lines": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string" }, "description": { "type": "string" }, "amount": { "type": "number" } } } } } } ] } } } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "text/csv": { "schema": { "type": "string" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "fleet_not_enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/fleet/settlements/{settlement}/request-payout": { "post": { "tags": [ "Fleet partner" ], "summary": "Ask Areye to pay a statement's amount to the bank on file (signed-in owner or portal admin)", "operationId": "fleetRequestPayout", "description": "Creates the same payout request as Billing \u2192 Request payout: pending until Areye pays it; the withdrawable balance (wallet less payouts already requested) must cover the amount. The statement becomes requested, then paid; a rejected or cancelled payout returns it to statement.", "parameters": [ { "name": "settlement", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "notes": { "type": "string", "maxLength": 500 } } } } } }, "responses": { "201": { "description": "Requested", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "settlement": { "$ref": "#/components/schemas/FleetSettlement" }, "payout": { "type": "object" }, "message": { "type": "string" } } } } } } } }, "422": { "description": "payout_not_requested: no bank on file, already requested, already paid, nothing to pay, or above the withdrawable balance (the message says which)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "signed_in_admin_only | fleet_not_enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/tow/options": { "get": { "tags": [ "Breakdown towing" ], "summary": "Tow classes, faults, destinations and payment for a point", "operationId": "towOptions", "parameters": [ { "name": "lat", "in": "query", "required": true, "schema": { "type": "number" } }, { "name": "lng", "in": "query", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Options" }, "422": { "description": "lat/lng missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "tow_disabled: towing is switched off for this account (the message says why)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/tow/quote": { "post": { "tags": [ "Breakdown towing" ], "summary": "Price a tow before booking", "operationId": "towQuote", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pickup", "dropoff", "fault", "drivable" ], "properties": { "pickup": { "type": "object", "required": [ "lat", "lng" ], "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "address": { "type": "string" } } }, "dropoff": { "type": "object", "required": [ "lat", "lng" ], "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "address": { "type": "string" } } }, "tow_class": { "type": "string", "enum": [ "flatbed", "wheel_lift", "heavy" ] }, "fault": { "type": "string", "enum": [ "wont_start", "accident", "flat_tyre", "overheating", "out_of_fuel", "locked_out", "stuck", "mechanical", "other" ] }, "drivable": { "type": "boolean" }, "vehicle_model_id": { "type": "string" }, "vehicle_body_type": { "type": "string", "enum": [ "hatchback", "sedan", "coupe", "suv", "bakkie", "mpv", "van", "motor_bike", "minibus", "truck", "bus" ], "description": "Body type; picks the truck with the fault (the higher wins). pickup is accepted for bakkie. Omitted: taken from vehicle_model_id" }, "vehicle_flags": { "type": "array", "items": { "type": "string", "enum": [ "luxury", "low_clearance", "ev", "awd" ] }, "description": "Any of these means a flatbed at least" }, "vehicle_weight_class": { "type": "string", "enum": [ "light", "heavy" ], "description": "heavy = 3.5 tonnes or more (heavy tow)" } } } } } }, "responses": { "200": { "description": "Quote", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/TowQuote" } } } } } }, "422": { "description": "Validation, or the pickup is outside every service area", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "tow_disabled: towing is switched off for this account (the message says why)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/tow/jobs": { "post": { "tags": [ "Breakdown towing" ], "summary": "Book a tow for a policyholder (retry safely with Idempotency-Key)", "operationId": "towBook", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Same key within 24 h returns the same job (200, replayed: true)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pickup", "dropoff", "destination_kind", "fault", "drivable", "payment_method", "motorist", "policy_number" ], "properties": { "quote_id": { "type": "string" }, "pickup": { "type": "object", "required": [ "lat", "lng" ], "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "address": { "type": "string" } } }, "dropoff": { "type": "object", "required": [ "lat", "lng" ], "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "address": { "type": "string" } } }, "destination_kind": { "type": "string", "enum": [ "home", "workshop", "panel_beater", "saved_place", "other" ] }, "destination_label": { "type": "string" }, "vehicle_brand_id": { "type": "string" }, "vehicle_model_id": { "type": "string" }, "vehicle_other": { "type": "string" }, "vehicle_registration": { "type": "string" }, "vehicle_colour": { "type": "string" }, "vehicle_body_type": { "type": "string", "enum": [ "hatchback", "sedan", "coupe", "suv", "bakkie", "mpv", "van", "motor_bike", "minibus", "truck", "bus" ], "description": "Body type; picks the truck with the fault (the higher wins). pickup is accepted for bakkie. Omitted: taken from vehicle_model_id" }, "vehicle_flags": { "type": "array", "items": { "type": "string", "enum": [ "luxury", "low_clearance", "ev", "awd" ] }, "description": "Any of these means a flatbed at least" }, "vehicle_weight_class": { "type": "string", "enum": [ "light", "heavy" ], "description": "heavy = 3.5 tonnes or more (heavy tow)" }, "fault": { "type": "string", "enum": [ "wont_start", "accident", "flat_tyre", "overheating", "out_of_fuel", "locked_out", "stuck", "mechanical", "other" ] }, "fault_note": { "type": "string" }, "drivable": { "type": "boolean" }, "tow_class": { "type": "string", "enum": [ "flatbed", "wheel_lift", "heavy" ] }, "motorist": { "type": "object", "required": [ "first_name", "last_name", "phone" ], "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone": { "type": "string" } } }, "policy_number": { "type": "string" }, "claim_reference": { "type": "string", "description": "Required unless Areye switched the requirement off for your account" }, "payment_method": { "type": "string", "enum": [ "business_wallet", "credit" ] } } } } } }, "responses": { "201": { "description": "Booked", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "job": { "$ref": "#/components/schemas/TowJob" } } } } } } } }, "200": { "description": "Idempotent replay", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "job": { "$ref": "#/components/schemas/TowJob" } } } } } } } }, "422": { "description": "Validation (policy_number, claim_reference, motorist first and last name)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "tow_disabled: towing is switched off for this account (the message says why)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Breakdown towing" ], "summary": "List tows, newest first", "operationId": "towList", "parameters": [ { "name": "stage", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "claim_reference", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "policy_number", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{data: [TowJob], meta: {page, per_page, total, has_more}}" }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "tow_disabled: towing is switched off for this account (the message says why)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/tow/jobs/{reference}": { "get": { "tags": [ "Breakdown towing" ], "summary": "One tow", "operationId": "towShow", "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tow reference, e.g. TOW-8K2Q1M" } ], "responses": { "200": { "description": "The job", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "job": { "$ref": "#/components/schemas/TowJob" } } } } } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "tow_disabled: towing is switched off for this account (the message says why)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/tow/jobs/{reference}/cancel": { "post": { "tags": [ "Breakdown towing" ], "summary": "Cancel (fee rules: free before assignment or within the free window; a fixed fee once a truck is on the way; a share of the call-out after arrival; not after loading)", "operationId": "towCancel", "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tow reference, e.g. TOW-8K2Q1M" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Cancelled; data.cancel_fee" }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "already_loaded | invalid_transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "tow_disabled: towing is switched off for this account (the message says why)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/tow/jobs/{reference}/change-destination": { "post": { "tags": [ "Breakdown towing" ], "summary": "Re-quote a new destination; send confirm=true to apply", "operationId": "towChangeDestination", "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tow reference, e.g. TOW-8K2Q1M" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "dropoff" ], "properties": { "dropoff": { "type": "object", "required": [ "lat", "lng" ], "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "address": { "type": "string" } } }, "confirm": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "{previous_total, new_total, confirmed}" }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "invalid_transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "tow_disabled: towing is switched off for this account (the message says why)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/tow/jobs/{reference}/evidence": { "get": { "tags": [ "Breakdown towing" ], "summary": "Photos (15-minute signed links, sha256), stage events and route trail", "operationId": "towEvidence", "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tow reference, e.g. TOW-8K2Q1M" } ], "responses": { "200": { "description": "Evidence", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/TowEvidence" } } } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "tow_disabled: towing is switched off for this account (the message says why)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/tow/jobs/{reference}/report.pdf": { "get": { "tags": [ "Breakdown towing" ], "summary": "PDF job report", "operationId": "towReport", "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tow reference, e.g. TOW-8K2Q1M" } ], "responses": { "200": { "description": "application/pdf" }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "not_finished: ready once delivered or cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "tow_disabled: towing is switched off for this account (the message says why)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/tow/jobs/{reference}/tracking-link": { "post": { "tags": [ "Breakdown towing" ], "summary": "A live tracking link for the policyholder (optionally sent by SMS)", "operationId": "towTrackingLink", "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tow reference, e.g. TOW-8K2Q1M" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "send_sms": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "{url, expires_at, sms_sent}" }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "not_active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "tow_disabled: towing is switched off for this account (the message says why)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/tow/statements": { "get": { "tags": [ "Breakdown towing" ], "summary": "Monthly statement with policy number and claim reference per line", "operationId": "towStatement", "parameters": [ { "name": "period", "in": "query", "required": false, "schema": { "type": "string" }, "description": "YYYY-MM" }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Statement", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/TowStatement" } } } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "tow_disabled: towing is switched off for this account (the message says why)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/tow/statements/{period}.{format}": { "get": { "tags": [ "Breakdown towing" ], "summary": "Statement as PDF or CSV", "operationId": "towStatementFile", "parameters": [ { "name": "period", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "pdf", "csv" ] } } ], "responses": { "200": { "description": "File" }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "tow_disabled: towing is switched off for this account (the message says why)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/tow/map": { "get": { "tags": [ "Breakdown towing" ], "summary": "Active tows with operator positions (live map)", "operationId": "towMap", "responses": { "200": { "description": "{jobs: [{reference, stage, operator_lat, operator_lng, pickup, dropoff}]}" }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "tow_disabled: towing is switched off for this account (the message says why)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/business/sandbox/tow/{reference}/{action}": { "post": { "tags": [ "Sandbox", "Breakdown towing" ], "summary": "Sandbox only: move the simulated tow operator one step", "operationId": "towSandboxStep", "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tow reference, e.g. TOW-8K2Q1M" }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "assign", "en_route", "arrive", "load", "in_transit", "deliver", "cancel_by_operator", "no_operator" ] } } ], "responses": { "200": { "description": "The job after the step", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "job": { "$ref": "#/components/schemas/TowJob" } } } } } } } }, "404": { "description": "not_found, or not the sandbox", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "invalid_transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": { "batch.created": { "post": { "operationId": "onBatchCreated", "summary": "A batch was booked", "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": { "allOf": [ { "$ref": "#/components/schemas/Batch" }, { "type": "object", "properties": [] } ] } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery" } } } }, "batch.accepted": { "post": { "operationId": "onBatchAccepted", "summary": "A driver took the batch; each live stop also sends trip.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": { "allOf": [ { "$ref": "#/components/schemas/Batch" }, { "type": "object", "properties": [] } ] } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery" } } } }, "batch.completed": { "post": { "operationId": "onBatchCompleted", "summary": "Nothing left to do and at least one order was delivered or is returning", "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": { "allOf": [ { "$ref": "#/components/schemas/Batch" }, { "type": "object", "properties": [] } ] } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery" } } } }, "batch.cancelled": { "post": { "operationId": "onBatchCancelled", "summary": "The batch ended with nothing 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": { "allOf": [ { "$ref": "#/components/schemas/Batch" }, { "type": "object", "properties": [] } ] } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery" } } } }, "batch.stop_cancelled": { "post": { "operationId": "onBatchStopCancelled", "summary": "You cancelled one order; the rest go on", "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": { "allOf": [ { "$ref": "#/components/schemas/Batch" }, { "type": "object", "properties": { "stop": { "$ref": "#/components/schemas/BatchStop" }, "reason": { "type": "string" } } } ] } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery" } } } }, "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" ] }, "batch_reference": { "type": "string", "description": "Present when the trip is a stop of a batch" } } } } } ] } } } }, "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" }, "batch_reference": { "type": "string", "description": "Present when the trip is a stop of a batch" } } } } } ] } } } }, "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" } } }, "FleetSettings": { "type": "object", "properties": { "fleet_default_payment_model": { "type": "string", "enum": [ "revenue_share", "fixed_fee", "rent_to_own" ] }, "fleet_default_driver_share_pct": { "type": [ "number", "null" ] }, "fleet_default_fixed_fee": { "type": [ "number", "null" ] }, "fleet_default_fee_cadence": { "type": "string", "enum": [ "daily", "weekly", "biweekly", "monthly" ] }, "fleet_settlement_cadence": { "type": "string", "enum": [ "weekly", "monthly", "manual" ] }, "fleet_settlement_day": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 28, "description": "weekly: 1 = Monday \u2026 7; monthly: day of month 1..28" }, "fleet_auto_payout": { "type": "boolean" }, "fleet_bank_name": { "type": [ "string", "null" ] }, "fleet_account_name": { "type": [ "string", "null" ] }, "fleet_account_number": { "type": [ "string", "null" ] }, "fleet_branch_code": { "type": [ "string", "null" ] }, "fleet_work_allow": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Work categories your drivers may take besides your fleet's ride-hailing" } } }, "FleetOverview": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "currency": { "type": "string" }, "defaults": { "type": "object", "properties": { "payment_model": { "type": "string" }, "driver_share_pct": { "type": [ "number", "null" ] }, "fixed_fee": { "type": [ "number", "null" ] }, "fee_cadence": { "type": [ "string", "null" ] } } }, "settlement": { "type": "object", "properties": { "cadence": { "type": "string" }, "day": { "type": [ "integer", "null" ] }, "auto_payout": { "type": "boolean" }, "bank": { "type": "object", "properties": { "bank_name": { "type": [ "string", "null" ] }, "account_name": { "type": [ "string", "null" ] }, "account_number_masked": { "type": [ "string", "null" ] }, "branch_code": { "type": [ "string", "null" ] }, "on_file": { "type": "boolean" } } } } }, "counts": { "type": "object", "properties": { "vehicles": { "type": "integer" }, "drivers": { "type": "integer" }, "invitations_pending": { "type": "integer" }, "online_now": { "type": "integer" }, "on_trip_now": { "type": "integer" } } }, "today": { "type": "object", "properties": { "trips": { "type": "integer" }, "gross": { "type": "number" }, "owner_earnings": { "type": "number" } } }, "month": { "type": "object", "properties": { "trips": { "type": "integer" }, "gross": { "type": "number" }, "owner_earnings": { "type": "number" }, "fixed_fees": { "type": "number" } } }, "outstanding_fees": { "type": "number" }, "wallet_balance": { "type": "number" }, "alerts": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "licence_expires_at", "insurance_expires_at", "roadworthy_expires_at", "service_due_at" ] }, "vehicle_id": { "type": "integer" }, "vehicle_name": { "type": "string" }, "message": { "type": "string" }, "due_at": { "type": "string", "format": "date" }, "overdue": { "type": "boolean" } } } } } }, "FleetComplianceItem": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "string" }, "due_at": { "type": "string", "format": "date" }, "days": { "type": "integer", "description": "Negative when overdue" }, "message": { "type": "string" } } }, "FleetLiveVehicle": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "plate_number": { "type": [ "string", "null" ] }, "make": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "listing_mode": { "type": "string" }, "payment_model": { "type": [ "string", "null" ], "enum": [ "revenue_share", "fixed_fee" ] }, "driver_share_pct": { "type": [ "number", "null" ] }, "fixed_fee": { "type": [ "number", "null" ] }, "fee_cadence": { "type": [ "string", "null" ] }, "driver": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone": { "type": "string" }, "driver_status": { "type": "string" }, "online": { "type": "boolean" }, "on_duty": { "type": "boolean" }, "ready": { "type": "boolean" }, "last_seen_at": { "type": [ "string", "null" ] }, "lat": { "type": [ "number", "null" ] }, "lng": { "type": [ "number", "null" ] } } }, "current_trip": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "reference": { "type": "string" }, "status": { "type": "string" }, "type": { "type": "string" }, "pickup_address": { "type": "string" }, "dest_address": { "type": "string" }, "started_at": { "type": [ "string", "null" ] } } }, "tracker": { "type": [ "object", "null" ], "description": "Tracker Connect status when a tracker is fitted and the integration is on" }, "compliance": { "type": "object", "properties": { "licence_expires_at": { "type": [ "string", "null" ] }, "insurance_expires_at": { "type": [ "string", "null" ] }, "roadworthy_expires_at": { "type": [ "string", "null" ] }, "service_due_at": { "type": [ "string", "null" ] }, "odometer_km": { "type": [ "integer", "null" ] }, "overdue": { "type": "array", "items": { "$ref": "#/components/schemas/FleetComplianceItem" } }, "due_soon": { "type": "array", "items": { "$ref": "#/components/schemas/FleetComplianceItem" } } } } } }, "FleetTripLine": { "type": "object", "properties": { "id": { "type": "integer" }, "reference": { "type": "string" }, "type": { "type": "string" }, "completed_at": { "type": [ "string", "null" ] }, "driver": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" } } }, "vehicle_id": { "type": [ "integer", "null" ] }, "vehicle_name": { "type": [ "string", "null" ] }, "plate_number": { "type": [ "string", "null" ] }, "pickup_address": { "type": "string" }, "dest_address": { "type": "string" }, "distance_km": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "fare": { "type": "number" }, "platform_commission": { "type": "number", "description": "Areye's commission" }, "driver_take": { "type": "number" }, "owner_earning": { "type": "number", "description": "Your share (revenue share, or the rent-to-own skim)" }, "payment_method_label": { "type": "string", "enum": [ "Card", "Wallet", "Cash", "Business account", "Orange Money", "DuelaEasy" ] } } }, "FleetMoneyTotals": { "type": "object", "properties": { "trips": { "type": "integer" }, "gross": { "type": "number" }, "platform_commission": { "type": "number" }, "driver_takes": { "type": "number" }, "owner_earnings": { "type": "number" } } }, "FleetTripsPage": { "type": "object", "properties": { "vehicle": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "plate_number": { "type": [ "string", "null" ] } } }, "driver": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" } } }, "trips": { "type": "array", "items": { "$ref": "#/components/schemas/FleetTripLine" } }, "meta": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "last_page": { "type": "integer" } } }, "totals": { "$ref": "#/components/schemas/FleetMoneyTotals" } } }, "FleetDriver": { "type": "object", "properties": { "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone": { "type": "string" }, "driver_status": { "type": "string" }, "documents": { "type": "object", "properties": { "approved": { "type": "integer" }, "pending": { "type": "integer" }, "rejected": { "type": "integer" }, "missing": { "type": "array", "items": { "type": "string", "enum": [ "national_id", "drivers_license", "vehicle_registration", "vehicle_photo" ] } } } }, "vehicle": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "plate_number": { "type": [ "string", "null" ] } } }, "online": { "type": "boolean" }, "ready": { "type": "boolean" }, "last_seen_at": { "type": [ "string", "null" ] }, "today": { "type": "object", "properties": { "trips": { "type": "integer" }, "gross": { "type": "number" }, "owner_earnings": { "type": "number" } } }, "wallet_balance": { "type": "number" }, "wallet_currency": { "type": [ "string", "null" ] }, "joined_at": { "type": [ "string", "null" ] }, "in_fleet": { "type": "boolean" } } }, "FleetInvitation": { "type": "object", "properties": { "id": { "type": "integer" }, "phone": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "vehicle": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "plate_number": { "type": [ "string", "null" ] } } }, "status": { "type": "string", "enum": [ "pending", "accepted", "declined", "expired", "cancelled" ] }, "invited_at": { "type": "string" }, "expires_at": { "type": "string" }, "accepted_at": { "type": [ "string", "null" ] }, "reminder_count": { "type": "integer" }, "accept_url": { "type": "string" } } }, "FleetSettlement": { "type": "object", "properties": { "id": { "type": "integer" }, "reference": { "type": "string" }, "currency": { "type": "string" }, "period_start": { "type": "string", "format": "date" }, "period_end": { "type": "string", "format": "date" }, "period_label": { "type": "string" }, "cadence": { "type": "string", "enum": [ "weekly", "monthly", "manual" ] }, "trips_count": { "type": "integer" }, "gross_fares": { "type": "number" }, "platform_commission": { "type": "number" }, "driver_takes": { "type": "number" }, "owner_earnings": { "type": "number" }, "fixed_fees": { "type": "number" }, "rto_instalments": { "type": "number" }, "amount": { "type": "number", "description": "owner_earnings + fixed_fees + rto_instalments: what may be paid out" }, "status": { "type": "string", "enum": [ "statement", "requested", "paid", "cancelled" ] }, "payout": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "reference": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "approved", "paid", "rejected", "cancelled" ] }, "amount": { "type": "number" }, "bank_name": { "type": [ "string", "null" ] }, "account_number_masked": { "type": [ "string", "null" ] }, "processed_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } } }, "generated_at": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ] } } }, "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, "description": "Food and Groceries ride inside the car, never in the boot \u2014 for hygiene and safety. A restaurant's deliveries always do." }, "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" ] }, "keep_in_cabin": { "type": "boolean", "description": "True for food and groceries, and for every restaurant delivery: the driver carries it inside the car, never in the boot." }, "cabin_note": { "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" } } } ] } } }, "BatchStopRequest": { "type": "object", "required": [ "pickup_address", "pickup_lat", "pickup_lng", "dest_address", "dest_lat", "dest_lng" ], "properties": { "external_reference": { "type": "string", "maxLength": 80, "description": "Your order id for this stop; unique within the batch; echoed on every trip.* webhook" }, "pickup_address": { "type": "string" }, "pickup_lat": { "type": "number" }, "pickup_lng": { "type": "number" }, "dest_address": { "type": "string" }, "dest_lat": { "type": "number" }, "dest_lng": { "type": "number" }, "recipient_name": { "type": "string" }, "recipient_phone": { "type": "string" }, "description": { "type": "string" }, "notes": { "type": "string" }, "order_note": { "type": "string" }, "items": { "type": "array", "maxItems": 100, "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "qty": { "type": "number" }, "price": { "type": "number" }, "options": { "type": "string" }, "sku": { "type": "string" } } } }, "driver_tip": { "type": "number", "minimum": 0, "maximum": 500, "description": "The customer's tip: held from your wallet at booking, paid to the driver in full on delivery, refunded if the stop is cancelled" }, "delivery_code": { "type": "string", "pattern": "^[0-9]{4}$", "minLength": 4, "maxLength": 4, "description": "The recipient's code. Omitted on an immediate batch: minted and returned on the stop" }, "ready_at": { "type": "string", "format": "date-time", "description": "When the order will be ready to collect; at most two hours ahead" }, "contents_category": { "type": "string", "description": "e.g. food, groceries, alcohol, pharmacy, electronics; food and groceries ride in the cabin" }, "contents_description": { "type": "string" }, "declared_value": { "type": "number" }, "age_verification_required": { "type": "boolean", "description": "18+ goods (alcohol, tobacco): the driver checks ID at this door before handing over; refused goods come back (trip.age_verification_failed)" }, "fragile": { "type": "boolean" }, "handover_required": { "type": "boolean", "description": "The driver may collect only once you mark the order ready" }, "size": { "type": "string", "enum": [ "S", "M", "L", "XL" ] }, "weight_kg": { "type": "number" }, "payment_method": { "type": "string", "enum": [ "business_wallet", "cash", "duela_easy" ] }, "cod_amount": { "type": "number" }, "delivery_speed": { "type": "string", "enum": [ "standard" ], "description": "priority is refused: priority_not_batchable" } } }, "BatchRequest": { "type": "object", "required": [ "stops" ], "properties": { "dispatch_mode": { "type": "string", "enum": [ "immediate", "reserved" ], "description": "immediate = collected now, for any retail order (routing, times, the max_added_minutes guard, ready-driven release). Omitted = the legacy path" }, "external_reference": { "type": "string", "maxLength": 80, "description": "Your id for the batch: a retry with the same id and body returns the first batch" }, "max_added_minutes": { "type": "integer", "minimum": 1, "maximum": 180, "description": "Immediate only: refuse the batch if it adds more than this to any order. Default 25" }, "segment": { "type": "string", "enum": [ "parcel", "cargo" ] }, "scheduled_at": { "type": "string", "format": "date-time", "description": "Not with immediate" }, "vehicle_type_id": { "type": "integer" }, "sandbox_scenario": { "type": "string", "enum": [ "delivered", "failed_delivery" ], "description": "Sandbox only: run the simulated driver through this batch" }, "stops": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/components/schemas/BatchStopRequest" } } } }, "BatchStop": { "type": "object", "properties": { "stop_id": { "type": "integer" }, "stop_order": { "type": "integer", "description": "Delivery order Areye chose (1 = first door)" }, "status": { "type": "string", "enum": [ "pending", "picked_up", "delivered", "failed", "cancelled" ] }, "reference": { "type": "string", "description": "The stop's Areye trip reference (use it with /business/trip/{reference}/ready and /business/trips/{reference})" }, "external_reference": { "type": [ "string", "null" ] }, "trip_id": { "type": "integer" }, "trip_status": { "$ref": "#/components/schemas/TripStatus" }, "tracking_url": { "type": [ "string", "null" ] }, "items": { "type": [ "array", "null" ], "items": { "type": "object" } }, "fee": { "type": "number" }, "driver_tip": { "type": [ "number", "null" ] }, "delivery_code": { "type": [ "string", "null" ], "pattern": "^[0-9]{4}$", "minLength": 4, "maxLength": 4, "description": "Show it to your customer; null once used" }, "ready_at": { "type": [ "string", "null" ] }, "ready_confirmed_at": { "type": [ "string", "null" ] }, "eta_minutes": { "type": [ "integer", "null" ], "description": "Minutes from booking to this door (immediate)" }, "estimated_delivery_at": { "type": [ "string", "null" ] }, "added_minutes": { "type": [ "integer", "null" ], "description": "How much later than the same order carried alone" }, "pickup_address": { "type": "string" }, "pickup_lat": { "type": "number" }, "pickup_lng": { "type": "number" }, "dest_address": { "type": "string" }, "dest_lat": { "type": "number" }, "dest_lng": { "type": "number" }, "recipient_name": { "type": [ "string", "null" ] }, "recipient_phone": { "type": [ "string", "null" ] }, "contents_category": { "type": [ "string", "null" ] }, "contents_description": { "type": [ "string", "null" ] }, "declared_value": { "type": [ "number", "null" ] }, "age_verification_required": { "type": "boolean" }, "age_verified_at": { "type": [ "string", "null" ] }, "fragile": { "type": "boolean" }, "handover_required": { "type": "boolean" }, "keep_in_cabin": { "type": [ "boolean", "null" ], "description": "Food and groceries ride inside the car, never the boot" }, "cod_amount": { "type": [ "number", "null" ] }, "cod_status": { "type": [ "string", "null" ] }, "picked_up_at": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ] }, "failed_at": { "type": [ "string", "null" ] }, "fail_reason": { "type": [ "string", "null" ] }, "cancelled_at": { "type": [ "string", "null" ] } } }, "Batch": { "type": "object", "properties": { "batch_id": { "type": "integer" }, "id": { "type": "integer" }, "reference": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending_offer", "offered", "driver_accepted", "driver_declined", "in_progress", "completed", "cancelled" ] }, "dispatch_mode": { "type": "string", "enum": [ "immediate", "reserved" ] }, "segment": { "type": "string" }, "release_at": { "type": [ "string", "null" ], "description": "Held off the market until then (orders not ready yet)" }, "scheduled_at": { "type": [ "string", "null" ] }, "total_stops": { "type": "integer" }, "total_distance_km": { "type": [ "number", "null" ] }, "estimated_duration_minutes": { "type": [ "integer", "null" ] }, "total_fee": { "type": "number" }, "total_driver_tips": { "type": "number" }, "billing_currency": { "type": "string" }, "driver": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "rating": { "type": "number" }, "vehicle_make": { "type": [ "string", "null" ] }, "vehicle_model": { "type": [ "string", "null" ] }, "plate_number": { "type": [ "string", "null" ] } } }, "driver_accepted_at": { "type": [ "string", "null" ] }, "collected_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "cancelled_at": { "type": [ "string", "null" ] }, "cancel_reason": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "stops": { "type": "array", "items": { "$ref": "#/components/schemas/BatchStop" } } } }, "BatchBooked": { "type": "object", "properties": { "success": { "type": "boolean" }, "replayed": { "type": "boolean" }, "data": { "type": "object", "properties": { "reference": { "type": "string" }, "stops": { "type": "integer", "description": "Number of stops" }, "status": { "type": "string" }, "dispatch_mode": { "type": "string" }, "batch": { "$ref": "#/components/schemas/Batch" }, "bulky": { "type": "object" }, "review_state": { "type": [ "string", "null" ] }, "stop_quotes": { "type": "array", "items": { "type": "object" } } } } } }, "BatchEstimate": { "type": "object", "properties": { "currency": { "type": "string" }, "dispatch_mode": { "type": "string" }, "stops": { "type": "array", "items": { "type": "object", "properties": { "stop": { "type": "integer" }, "external_reference": { "type": [ "string", "null" ] }, "stop_order": { "type": "integer" }, "fee": { "type": "number", "description": "This stop's fee in the batch" }, "alone_fee": { "type": [ "number", "null" ], "description": "The same delivery booked on its own" }, "driver_tip": { "type": "number" }, "payment_method": { "type": "string" }, "distance_km": { "type": "number" }, "ready_at": { "type": [ "string", "null" ] }, "eta_minutes": { "type": "integer" }, "estimated_delivery_at": { "type": "string" }, "alone_minutes": { "type": "integer" }, "added_minutes": { "type": "integer" } } } }, "batch_total": { "type": "number" }, "alone_total": { "type": "number" }, "saving": { "type": "number" }, "driver_tips_total": { "type": "number" }, "charged_at_booking": { "type": "number", "description": "Fees your wallet pays plus the tips it holds" }, "max_added_minutes": { "type": [ "integer", "null" ] }, "release_at": { "type": [ "string", "null" ] }, "total_distance_km": { "type": [ "number", "null" ] } } }, "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)." } } }, "TowQuote": { "type": "object", "properties": { "quote_id": { "type": "string" }, "expires_at": { "type": "string" }, "currency": { "type": "string" }, "tow_class": { "type": "string" }, "total": { "type": "number" }, "class_needed": { "type": "string", "description": "The lowest truck the fault and vehicle rules allow" }, "class_reason": { "type": "string" }, "truck_needed": { "type": "string", "description": "e.g. \"Truck needed: Flatbed because it is an SUV\"" }, "vehicle": { "type": [ "object", "null" ], "description": "label, brand, model, body_type, body_type_label, flags, weight_class, registration, colour" }, "breakdown": { "type": "object", "properties": { "callout": { "type": "number" }, "to_pickup_km": { "type": "number" }, "to_pickup_amount": { "type": "number" }, "tow_km": { "type": "number" }, "tow_amount": { "type": "number" }, "class_multiplier": { "type": "number" }, "surcharge_percent": { "type": "number" }, "surcharge_reason": { "type": "string" }, "surcharge_amount": { "type": "number" }, "minimum_applied": { "type": "boolean" } } }, "final_price_rules": { "type": "object", "properties": { "waiting_free_minutes": { "type": "integer" }, "waiting_per_min": { "type": "number" }, "waiting_cap": { "type": "number" }, "extra_km_tolerance_percent": { "type": "number" }, "extra_km_cap_percent": { "type": "number" }, "explained": { "type": "string" } } }, "operators_nearby": { "type": "integer" }, "eta_minutes": { "type": [ "integer", "null" ] }, "warning": { "type": [ "string", "null" ] } } }, "TowJob": { "type": "object", "properties": { "reference": { "type": "string" }, "trip_id": { "type": "integer" }, "stage": { "type": "string", "enum": [ "requested", "assigned", "en_route", "arrived", "loaded", "in_transit", "delivered", "cancelled" ] }, "stage_label": { "type": "string" }, "timestamps": { "type": "object", "description": "requested_at \u2026 cancelled_at, ISO-8601 or null" }, "tow_class": { "type": "string" }, "class_needed": { "type": "string" }, "class_reason": { "type": "string" }, "truck_needed": { "type": "string" }, "vehicle": { "type": "object", "properties": { "label": { "type": "string" }, "brand": { "type": "string" }, "model": { "type": "string" }, "other": { "type": "string" }, "body_type": { "type": "string" }, "body_type_label": { "type": "string" }, "flags": { "type": "array", "items": { "type": "string" } }, "weight_class": { "type": "string" }, "registration": { "type": "string" }, "colour": { "type": "string" } } }, "billed_to": { "type": "string", "enum": [ "you", "insurer", "fleet_owner" ] }, "fault": { "type": "string" }, "drivable": { "type": "boolean" }, "pickup": { "type": "object", "required": [ "lat", "lng" ], "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "address": { "type": "string" } } }, "dropoff": { "type": "object", "required": [ "lat", "lng" ], "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "address": { "type": "string" } } }, "motorist": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone": { "type": "string" } } }, "operator": { "type": [ "object", "null" ], "description": "first_name, last_name, phone (direct), vehicle_registration, lat, lng, eta_minutes" }, "policy_number": { "type": "string" }, "claim_reference": { "type": "string" }, "payer": { "type": "string" }, "payment_method": { "type": "string" }, "payment_method_label": { "type": "string" }, "price": { "type": "object", "properties": { "currency": { "type": "string" }, "quote_total": { "type": "string", "description": "Decimal string, 2 places" }, "waiting_amount": { "type": "string", "description": "Decimal string, 2 places" }, "extra_km_amount": { "type": "string", "description": "Decimal string, 2 places" }, "final_total": { "type": "string", "description": "Decimal string, 2 places" } } }, "cancel_fee": { "type": "string", "description": "Decimal string, 2 places" }, "photos": { "type": "object" }, "tracking_url": { "type": [ "string", "null" ] }, "report_url": { "type": [ "string", "null" ] }, "sandbox": { "type": "boolean" } } }, "TowEvidence": { "type": "object", "properties": { "photos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "kind": { "type": "string" }, "taken_at": { "type": "string" }, "lat": { "type": "number" }, "lng": { "type": "number" }, "sha256": { "type": "string" }, "url": { "type": "string" } } } }, "events": { "type": "array", "items": { "type": "object" } }, "trail": { "type": "array", "items": { "type": "array" } } } }, "TowStatement": { "type": "object", "properties": { "period": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "reference": { "type": "string" }, "policy_number": { "type": "string" }, "claim_reference": { "type": "string" }, "amount": { "type": "number" }, "credit_notes": { "type": "number" }, "invoice": { "type": "string" } } } }, "totals": { "type": "array", "items": { "type": "object" } } } }, "TowWebhookEvent": { "type": "object", "description": "The standard webhook envelope with event tow.* and data {job: TowJob, previous_stage, sandbox}.", "properties": { "id": { "type": "string" }, "event": { "type": "string" }, "business_id": { "type": "integer" }, "occurred_at": { "type": "string" }, "data": { "type": "object", "properties": { "job": { "$ref": "#/components/schemas/TowJob" }, "previous_stage": { "type": [ "string", "null" ] }, "sandbox": { "type": "boolean" } } } } } } } }