{ "openapi": "3.0.3", "info": { "title": "FleetBridge Standard Delivery Provider API", "version": "1.1.0", "description": "Provider-facing API only. Revision 2026-09-19." }, "servers": [ { "url": "https://provider.example/fleetbridge/v1", "description": "Example only" } ], "paths": { "/deliveries": { "post": { "operationId": "createDelivery", "summary": "Create a delivery durably and idempotently", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDeliveryRequest" } } } }, "responses": { "200": { "description": "Processed create result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDeliveryResponse" } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Unknown delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Semantic validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "Retry-After": { "description": "Delay in seconds or an HTTP date", "schema": { "type": "string" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ], "callbacks": { "deliveryEvent": { "{$request.body#/webhook/url}": { "post": { "operationId": "receiveDeliveryEvent", "summary": "Provider sends a signed delivery event to the selected FleetBridge callback", "parameters": [ { "name": "X-Platform-Signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Event settled" }, "400": { "description": "Invalid payload" }, "401": { "description": "Invalid signature or connection" }, "404": { "description": "Unknown connection" }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "schema": { "type": "string" } } } }, "503": { "description": "Event parked; retry unchanged" } } } } } } } }, "/deliveries/{providerDeliveryId}/status": { "get": { "operationId": "getDeliveryStatus", "parameters": [ { "name": "providerDeliveryId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Current status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusResponse" } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Unknown delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Semantic validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "Retry-After": { "description": "Delay in seconds or an HTTP date", "schema": { "type": "string" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/deliveries/{providerDeliveryId}/tracking": { "get": { "operationId": "getDeliveryTracking", "parameters": [ { "name": "providerDeliveryId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Current tracking data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackingResponse" } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Unknown delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Semantic validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "Retry-After": { "description": "Delay in seconds or an HTTP date", "schema": { "type": "string" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/deliveries/{providerDeliveryId}": { "patch": { "operationId": "updateDelivery", "parameters": [ { "name": "providerDeliveryId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDeliveryRequest" } } } }, "responses": { "200": { "description": "Field-level update result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDeliveryResponse" } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Unknown delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Semantic validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "Retry-After": { "description": "Delay in seconds or an HTTP date", "schema": { "type": "string" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/deliveries/{providerDeliveryId}/cancel": { "post": { "operationId": "cancelDelivery", "parameters": [ { "name": "providerDeliveryId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelDeliveryRequest" } } } }, "responses": { "200": { "description": "Cancellation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelDeliveryResponse" } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Unknown delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Semantic validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "Retry-After": { "description": "Delay in seconds or an HTTP date", "schema": { "type": "string" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/deliveries/{providerDeliveryId}/return": { "post": { "operationId": "requestReturn", "parameters": [ { "name": "providerDeliveryId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnDeliveryRequest" } } } }, "responses": { "200": { "description": "Return result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnDeliveryResponse" } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Unknown delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Semantic validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "Retry-After": { "description": "Delay in seconds or an HTTP date", "schema": { "type": "string" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/webhooks/test": { "post": { "operationId": "testWebhookConnectivity", "summary": "Authenticate and test Provider reachability; this does not prove outgoing webhooks", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "responses": { "200": { "description": "Authenticated and reachable" }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Unknown delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Semantic validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "Retry-After": { "description": "Delay in seconds or an HTTP date", "schema": { "type": "string" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "CreateDeliveryRequest": { "type": "object", "required": [ "platformReference", "idempotencyKey", "pickupAddress", "pickupLat", "pickupLng", "customerName", "customerPhone", "dropoffAddress", "dropoffLat", "dropoffLng", "paymentMethod", "amount", "currency", "preparationTimeMinutes" ], "properties": { "platformReference": { "type": "string", "maxLength": 200 }, "idempotencyKey": { "type": "string", "maxLength": 200 }, "pickupAddress": { "type": "string", "maxLength": 500 }, "pickupLat": { "type": "number", "minimum": -90, "maximum": 90 }, "pickupLng": { "type": "number", "minimum": -180, "maximum": 180 }, "customerName": { "type": "string", "maxLength": 200 }, "customerPhone": { "type": "string", "maxLength": 50 }, "dropoffAddress": { "type": "string", "maxLength": 500 }, "dropoffLat": { "type": "number", "minimum": -90, "maximum": 90 }, "dropoffLng": { "type": "number", "minimum": -180, "maximum": 180 }, "paymentMethod": { "type": "string", "maxLength": 100 }, "amount": { "type": "number", "minimum": 0, "maximum": 9999999999.99, "multipleOf": 0.01 }, "deliveryFeeAmount": { "type": "number", "minimum": 0, "maximum": 9999999999.99, "multipleOf": 0.01, "nullable": true }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "maxLength": 3 }, "notes": { "type": "string", "maxLength": 2000, "nullable": true }, "preparationTimeMinutes": { "type": "integer", "minimum": 0 }, "scheduledDeliveryAtUtc": { "type": "string", "format": "date-time", "nullable": true }, "webhook": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https://" } }, "additionalProperties": false, "nullable": true } }, "additionalProperties": false }, "CreateDeliveryResponse": { "type": "object", "required": [ "accepted" ], "properties": { "accepted": { "type": "boolean" }, "providerDeliveryId": { "type": "string", "nullable": true }, "providerTrackingId": { "type": "string", "nullable": true }, "rejectionReason": { "type": "string", "nullable": true } }, "additionalProperties": false }, "UpdateDeliveryRequest": { "type": "object", "properties": { "customerName": { "type": "string", "maxLength": 200 }, "customerPhone": { "type": "string", "maxLength": 50 }, "dropoffAddress": { "type": "string", "maxLength": 500 }, "dropoffLat": { "type": "number", "minimum": -90, "maximum": 90 }, "dropoffLng": { "type": "number", "minimum": -180, "maximum": 180 }, "paymentMethod": { "type": "string", "maxLength": 100 }, "amount": { "type": "number", "minimum": 0, "maximum": 9999999999.99, "multipleOf": 0.01 }, "deliveryFeeAmount": { "type": "number", "minimum": 0, "maximum": 9999999999.99, "multipleOf": 0.01, "nullable": true }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "maxLength": 3 }, "notes": { "type": "string", "maxLength": 2000, "nullable": true }, "preparationTimeMinutes": { "type": "integer", "minimum": 0 }, "scheduledDeliveryAtUtc": { "type": "string", "format": "date-time", "nullable": true }, "customerEmail": { "type": "string", "format": "email", "maxLength": 320, "nullable": true } }, "additionalProperties": false, "description": "Only non-null properties change. Omitted and null both mean unchanged." }, "UpdateDeliveryResponse": { "type": "object", "required": [ "fieldAccepted" ], "properties": { "fieldAccepted": { "type": "object", "additionalProperties": { "type": "boolean" } }, "errorMessage": { "type": "string", "nullable": true } }, "additionalProperties": false }, "StatusResponse": { "type": "object", "required": [ "status", "eventTimeUtc" ], "properties": { "status": { "type": "string", "enum": [ "sent_to_provider", "provider_accepted", "driver_assigned", "arrived_at_pickup", "picked_up", "on_the_way", "delivered", "cancelled", "failed", "return_requested", "returning_to_origin", "returned_to_origin", "return_failed" ] }, "eventTimeUtc": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "TrackingResponse": { "type": "object", "required": [ "eventTimeUtc" ], "properties": { "driverName": { "type": "string", "nullable": true }, "driverPhone": { "type": "string", "nullable": true }, "driverLat": { "type": "number", "minimum": -90, "maximum": 90, "nullable": true }, "driverLng": { "type": "number", "minimum": -180, "maximum": 180, "nullable": true }, "trackingUrl": { "type": "string", "format": "uri", "nullable": true }, "estimatedDeliveryAtUtc": { "type": "string", "format": "date-time", "nullable": true }, "eventTimeUtc": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "CancelDeliveryRequest": { "type": "object", "required": [ "stage" ], "properties": { "stage": { "type": "string", "enum": [ "before_pickup", "after_pickup" ] } }, "additionalProperties": false }, "CancelDeliveryResponse": { "type": "object", "required": [ "confirmed" ], "properties": { "confirmed": { "type": "boolean" }, "errorMessage": { "type": "string", "nullable": true } }, "additionalProperties": false }, "ReturnDeliveryRequest": { "type": "object", "properties": { "reasonCode": { "type": "string", "nullable": true } }, "additionalProperties": false }, "ReturnDeliveryResponse": { "type": "object", "required": [ "accepted" ], "properties": { "accepted": { "type": "boolean" }, "errorMessage": { "type": "string", "nullable": true } }, "additionalProperties": false }, "WebhookEvent": { "type": "object", "required": [ "platformReference", "status", "eventTimeUtc" ], "properties": { "eventType": { "type": "string", "enum": [ "delivery.accepted", "driver.assigned", "driver.location_updated", "eta.updated", "tracking.updated", "delivery.picked_up", "delivery.delivered", "delivery.cancelled", "delivery.failed" ] }, "platformReference": { "type": "string" }, "providerDeliveryId": { "type": "string", "nullable": true }, "providerTrackingId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "sent_to_provider", "provider_accepted", "driver_assigned", "arrived_at_pickup", "picked_up", "on_the_way", "delivered", "cancelled", "failed", "return_requested", "returning_to_origin", "returned_to_origin", "return_failed" ] }, "eventTimeUtc": { "type": "string", "format": "date-time" }, "driverName": { "type": "string", "nullable": true }, "driverPhone": { "type": "string", "nullable": true }, "driverLat": { "type": "number", "minimum": -90, "maximum": 90, "nullable": true }, "driverLng": { "type": "number", "minimum": -180, "maximum": 180, "nullable": true }, "trackingUrl": { "type": "string", "format": "uri", "nullable": true }, "estimatedDeliveryAtUtc": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false }, "ErrorResponse": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "fieldErrors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "additionalProperties": false } } }, "x-fleetbridge-contract": { "apiMajor": "v1", "semanticVersion": "1.1.0", "revision": "2026-09-19", "webhookSignatureHeader": "X-Platform-Signature", "webhookSignatureAlgorithm": "HMAC-SHA256 lowercase hex over exact raw body", "requestTimeoutSeconds": 15, "maxResponseBytes": 5242880, "maxTotalIdempotentAttempts": 3 } }