# FleetBridge Order Source Integration Contract **API major:** v1 **Contract revision:** 1.1.0 **Audience:** engineering teams at POS systems, restaurant platforms, e-commerce systems, ordering applications, marketplaces, and ERP/order-management systems that create delivery orders through FleetBridge (an "Order Source"). This document describes the public Order Source API as it actually behaves. Every field name, header, status code, and behavior below comes straight from the running FleetBridge implementation, not a design doc someone wrote before the code existed. If something genuinely isn't built yet (a fixed per-key rate limit, for instance), we say so plainly instead of pretending it's there. --- ## 1. Integration model ``` Order Source ──HTTP request───► FleetBridge Order API Order Source ◄──HTTPS webhook── FleetBridge (delivery status / tracking events) ``` FleetBridge sits between your system and one or more Delivery Providers. You never talk to a Delivery Provider directly, you never hold its credentials, and you never see its webhook format. Here's the flow: 1. Create an order with FleetBridge. 2. FleetBridge resolves a branch and dispatches a Delivery Provider, failing over to another one automatically if needed (before pickup only), and manages the delivery from there. 3. FleetBridge sends you webhooks as the delivery progresses. 4. You update or cancel the order through FleetBridge, not through the Delivery Provider. 5. You always correlate on the identifiers FleetBridge gives you back. Not on the identity of whichever Delivery Provider happens to be handling the order at a given moment — that can change. A few things this API deliberately doesn't do. There's no quotes or pricing endpoint; FleetBridge doesn't calculate delivery pricing or shop it across providers. There's no `items[]` concept anywhere in the contract, because FleetBridge orchestrates the delivery, not what's inside the order. And `PaymentMethod` is just order metadata passed through to the Delivery Provider — FleetBridge never settles or reconciles COD funds. --- ## 2. Authentication ### 2.1 Header Every request is authenticated with a single header: ``` X-Api-Key: key_<64 lowercase hex characters> ``` The header must be present **exactly once**, with a non-empty value. There's no `Authorization: Bearer` scheme for Order Source calls — that one's reserved for FleetBridge's own dashboard users. ### 2.2 Key format A raw key is always `key_` followed by 64 lowercase hexadecimal characters (68 characters total), for example: ``` key_9f2c1a7b3e5d8046a1c2b3d4e5f60718293a4b5c6d7e8f9012345678abcdef0 ``` FleetBridge generates the key and shows it to you **exactly once**, at creation time, in the tenant dashboard. It can't be redisplayed after that — FleetBridge only keeps a short, non-secret prefix (the first 12 characters, e.g. `key_9f2c1a7b`) for identification purposes. Lose it and it's gone for good; issue a new one and revoke the old one (Section 2.4). **There's no separate test/sandbox key format.** A key authenticates against whatever FleetBridge environment (Base URL) it was issued for — see Section 20. Don't look for a `_test_` / `_live_` naming convention in the key itself, because there isn't one. ### 2.3 What the key identifies A key belongs to exactly one **Order Source** inside exactly one **Tenant**. You never send a tenant ID or Order Source ID anywhere in the request — FleetBridge resolves both from the key itself. Your `externalOrderId` only needs to be unique **within your Order Source**, not across the whole tenant. A different Order Source under the same tenant can reuse the same `externalOrderId` for a completely unrelated order and FleetBridge keeps them apart without any extra effort on your part. Every order, cancellation, update, and read you perform is scoped to what your own Order Source created. Try to read or modify an order that belongs to a different Order Source, even one under the same tenant, and you'll get `404 ORDER_NOT_FOUND` — FleetBridge won't confirm or deny that such an order exists for someone else. ### 2.4 Rotation and revocation Unlike webhook secrets (Section 9.10, which support rotation with an overlap window), there's no in-place "rotate" for an Order Source API key. To rotate one without downtime: 1. Ask FleetBridge (through your tenant's dashboard user) to issue a **new** key for your Order Source. Multiple keys can be active for the same Order Source at once for exactly this reason. 2. Deploy the new key to your systems. 3. Ask FleetBridge to **revoke** the old key once you've confirmed the new one is working. A revoked or expired key fails authentication immediately (Section 2.5). Both creation and revocation get recorded in FleetBridge's audit log. ### 2.5 Authentication failures Two different failure layers here, with two different response shapes. Getting this distinction right matters for building correct error handling. **(a) The key itself is missing, malformed, unknown, revoked, or expired.** This fails inside FleetBridge's authentication layer before your request ever reaches business logic. You get back: ``` HTTP/1.1 401 Unauthorized ``` with an **empty body** — not a JSON error object. Don't try to parse one from a `401` here. **(b) The key is valid, but your Order Source or Tenant can't currently accept orders** (disabled Order Source, suspended tenant). This is a business-rule rejection that happens *after* authentication succeeds, so it comes back through FleetBridge's standard error envelope (Section 16): ```json { "status": 403, "title": "Forbidden", "detail": "This order source is disabled.", "errorCode": "ORDER_SOURCE_DISABLED", "correlationId": "0HNOOIIC1J8FA:00000001" } ``` | errorCode | HTTP status | Meaning | |---|---|---| | `TENANT_SUSPENDED` | 403 | The tenant is not currently accepting new orders. | | `ORDER_SOURCE_DISABLED` | 403 | Your Order Source has been deactivated. | | `INVALID_API_KEY` | 403 | The authenticated caller is not a valid Order Source context for this operation (should not occur in normal use of a correctly issued key). | ### 2.6 What not to log Never log the raw `X-Api-Key` header value, the raw webhook signing secret (Section 9), or full request bodies that carry customer phone numbers and addresses into whatever log retention policy you run. If you need to identify which credential made a call, log the key **prefix** (first 12 characters) instead — that part isn't sensitive. --- ## 3. Base URL and environments We don't publish one fixed public hostname in this document, because your Base URL gets issued during onboarding and activation and is specific to your deployment. You'll receive: - A **staging Base URL** and staging API key during development/certification. - A **production Base URL** and production API key at activation. Every example here uses the placeholder: ``` https:// ``` Swap in the actual Base URL you were given. The paths themselves (`/api/v1/orders`, etc.) are real and literal — only the host is a stand-in. All endpoints are versioned under `/api/v1`. Section 21 covers the versioning and backward-compatibility policy if you want the details now. --- ## 4. Quick start 1. Get your `X-Api-Key` and Base URL from FleetBridge during onboarding. 2. Register a webhook callback URL and grab your webhook signing secret (Section 9) — you'll want this before relying on lifecycle updates, though it's not required just to create a test order. 3. Create an order (Section 7). Store the `platformOrderId` you get back. 4. Poll `GET /api/v1/orders/{platformOrderId}/status` once, or just wait for your first webhook, to watch the order move past `PendingRouting`. 5. Implement webhook signature verification (Section 10) so you can actually trust the events you're receiving. 6. Wire up Update and Cancel (Sections 11–12) for whichever parts of your own order lifecycle need them. 7. Reconcile: if you're ever unsure whether a Create request actually went through (timeout, no response), replay the exact same request with the same `Idempotency-Key`. Read Section 13 before you build any retry logic — the behavior here isn't what you'd guess. ### First request, end to end ```bash curl -X POST "https:///api/v1/orders" \ -H "X-Api-Key: key_9f2c1a7b3e5d8046a1c2b3d4e5f60718293a4b5c6d7e8f9012345678abcdef0" \ -H "Idempotency-Key: order-1001-create-1" \ -H "Content-Type: application/json" \ -d '{ "externalOrderId": "ORD-1001", "branchId": null, "externalBranchId": "MAIN-BRANCH", "deliveryProviderCode": null, "scheduledDeliveryAt": null, "pickup": { "address": "Ramallah Branch, Al-Manara St.", "lat": 31.9021, "lng": 35.2034 }, "dropoff": { "customerName": "Ahmed Khalil", "customerPhone": "+970590000000", "customerEmail": null, "address": "Al-Tireh, Ramallah", "lat": 31.9102, "lng": 35.2111 }, "payment": { "method": "Cash", "methodRaw": "cash_on_delivery", "amount": 85.00, "deliveryFee": 10.00, "currency": "ILS" }, "preparationTimeMinutes": 15, "notes": "Call before arrival" }' ``` Response: ``` HTTP/1.1 201 Created Location: /api/v1/orders/6e1c1a2b-3d4e-4f5a-8b6c-7d8e9f0a1b2c Content-Type: application/json ``` ```json { "platformOrderId": "6e1c1a2b-3d4e-4f5a-8b6c-7d8e9f0a1b2c", "externalOrderId": "ORD-1001", "externalOrderNumber": "ORD-1001", "status": "PendingRouting", "branchId": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e", "routingMode": "PriorityFailover", "createdAt": "2026-09-22T13:00:00Z" } ``` **Store `platformOrderId`.** Every subsequent call — Update, Cancel, GetById, GetStatus, GetTracking, GetTrackingHistory — uses it as a path parameter. `externalOrderId` comes back unchanged too, and you can use it to look the order up later (Section 12.4), scoped to your own Order Source. `externalOrderNumber` echoes your display number, or `externalOrderId` when you didn't send one (Section 7.1). --- ## 5. Every endpoint — summary All paths are relative to your Base URL. All are under `/api/v1`. | Method | Path | Purpose | |---|---|---| | POST | `/api/v1/orders` | Create an order | | PATCH | `/api/v1/orders/{platformOrderId}` | Update mutable order business data | | GET | `/api/v1/orders/{platformOrderId}` | Get full order detail | | GET | `/api/v1/orders/by-external-id/{externalOrderId}` | Look up an order by your own reference | | GET | `/api/v1/orders/{platformOrderId}/status` | Get current order + delivery status | | GET | `/api/v1/orders/{platformOrderId}/tracking` | Get current driver/tracking snapshot | | GET | `/api/v1/orders/{platformOrderId}/tracking-history` | Get the full tracking event timeline | | POST | `/api/v1/orders/{platformOrderId}/cancel` | Cancel an order | | POST | `/api/v1/webhooks/test` | Send a test webhook to your own registered endpoint | All nine of these, webhook test included, require the `X-Api-Key` header (Section 2) and operate only on orders (or webhook endpoints) belonging to your own Order Source. **A few endpoints exist on this API but aren't available to an Order Source key** — listed here just so you don't go looking for them: order search/listing, manual provider dispatch, return resolution, webhook endpoint management (create/rotate/subscribe), and Order Source or API key management. Those need a FleetBridge dashboard user session, so they're out of scope for this document. --- ## 6. Common conventions - Request and response bodies are `application/json`, fields in `camelCase`. - Enum values are always JSON strings (`"Cash"`, not `0`). An unrecognized enum string gets rejected as a validation error — it won't silently coerce to something else. - Any timestamp you send (`scheduledDeliveryAt`) needs ISO 8601 **with an explicit UTC offset** (`2026-09-01T18:30:00+03:00` or `...Z`). Leave the offset off and it's rejected. Everything FleetBridge sends back is UTC, suffixed `Z`. - GUIDs (`platformOrderId`, `branchId`, etc.) are lowercase, hyphenated UUID strings. - Unknown or extra JSON properties in a request get silently ignored, not rejected. Don't rely on that to smuggle data through — it's just how the underlying JSON binding happens to work. --- ## 7. Create Order ``` POST /api/v1/orders ``` Optional header: `Idempotency-Key` (Section 13). We'd strongly recommend sending it on every Create call — without it, a network-level retry looks identical to a second, separate order. ### 7.1 Request fields | Field | Type | Required | Notes | |---|---|---|---| | `externalOrderId` | string, ≤200 chars | **Yes** | Your own technical order identifier: the correlation, lookup, and de-dup key. Unique within your Order Source (Section 2.3). | | `externalOrderNumber` | string, ≤200 chars | No | Your human-readable order number (for example the number printed on the receipt). Shown to operators and sent to the Delivery Provider as its visible order reference. Display only: not unique, never used for correlation, lookup, de-duplication, or idempotency. Omitted or blank means FleetBridge uses `externalOrderId`. Set at create only. | | `branchId` | GUID | No | FleetBridge branch ID, if known. See Section 19 for resolution priority. | | `externalBranchId` | string | No | Your own branch/store code, if you don't track FleetBridge branch GUIDs. | | `deliveryProviderCode` | string | No | Request a specific Delivery Provider by code. See Section 15. | | `scheduledDeliveryAt` | ISO 8601 datetime w/ offset | No | Omit or `null` for an immediate (ASAP) order. See Section 14. | | `pickup.address` | string, ≤500 chars | **Yes** | Free-text pickup address (display/reference only — resolution uses coordinates/branch). | | `pickup.lat` | number | **Yes** | −90..90. | | `pickup.lng` | number | **Yes** | −180..180. | | `dropoff.customerName` | string, ≤200 chars | **Yes** | | | `dropoff.customerPhone` | string, ≤50 chars | **Yes** | | | `dropoff.customerEmail` | string, ≤320 chars | No | | | `dropoff.address` | string, ≤500 chars | **Yes** | | | `dropoff.lat` | number | **Yes** | −90..90. | | `dropoff.lng` | number | **Yes** | −180..180. | | `payment.method` | enum | **Yes** | One of `Cash`, `Card`, `Online`, `Wallet`, `Other`. See Section 17. | | `payment.methodRaw` | string, ≤100 chars | No | Your own original payment-method label, preserved alongside the normalized `method`. | | `payment.amount` | decimal | **Yes** | ≥0, at most 2 decimal places, at most 9,999,999,999.99. The order total. | | `payment.deliveryFee` | decimal | No | Same range/precision rules as `amount`. Informational only — never used in routing or provider selection. | | `payment.currency` | string, exactly ≤3 chars | **Yes** | e.g. `ILS`, `USD`. Normalized to uppercase. | | `preparationTimeMinutes` | integer | **Yes** | ≥0. No enforced upper bound. | | `notes` | string, ≤2000 chars | No | | One gotcha: if a required value-type field (`lat`, `lng`, `amount`, `preparationTimeMinutes`, `payment.method`) is missing from the JSON entirely, FleetBridge treats that exactly like an explicit required-and-missing field — it gets rejected, not quietly defaulted to zero. Send these explicitly, every time. ### 7.2 Minimal valid Create ```json { "externalOrderId": "ORD-2002", "externalBranchId": "MAIN-BRANCH", "pickup": { "address": "Main Branch", "lat": 31.9021, "lng": 35.2034 }, "dropoff": { "customerName": "Sara Ahmad", "customerPhone": "+970599111222", "address": "Al-Bireh", "lat": 31.9075, "lng": 35.2160 }, "payment": { "method": "Cash", "amount": 42.5, "currency": "ILS" }, "preparationTimeMinutes": 10 } ``` ### 7.3 Full Create (every optional field populated) ```json { "externalOrderId": "ORD-2003", "externalOrderNumber": "1042", "branchId": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e", "externalBranchId": null, "deliveryProviderCode": "cervo", "scheduledDeliveryAt": "2026-09-22T18:30:00+03:00", "pickup": { "address": "Downtown Branch", "lat": 31.9021, "lng": 35.2034 }, "dropoff": { "customerName": "Ahmed Khalil", "customerPhone": "+970590000000", "customerEmail": "ahmed@example.com", "address": "Al-Tireh, Ramallah, Building 12", "lat": 31.9102, "lng": 35.2111 }, "payment": { "method": "Card", "methodRaw": "visa_online", "amount": 120.00, "deliveryFee": 12.00, "currency": "ILS" }, "preparationTimeMinutes": 20, "notes": "Leave at the door, ring the bell twice" } ``` ### 7.4 Response — 201 Created ```json { "platformOrderId": "6e1c1a2b-3d4e-4f5a-8b6c-7d8e9f0a1b2c", "externalOrderId": "ORD-2003", "externalOrderNumber": "1042", "status": "Scheduled", "branchId": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e", "routingMode": "PriorityFailover", "createdAt": "2026-09-22T13:05:00Z" } ``` The `Location` header comes back set to `/api/v1/orders/{platformOrderId}`. `status` is the order's first computed status: `Scheduled` if `scheduledDeliveryAt` was in the future, otherwise `PendingRouting` (Section 14). `routingMode` (`DefaultOnly` | `ManualProvider` | `PriorityFailover` | `BroadcastToAll`) comes from your tenant/branch configuration — it's not something you ask for per order. A `deliveryProviderCode` override (Section 15) changes which provider gets targeted, not the routing mode itself. ### 7.5 Errors specific to Create | errorCode | Status | Cause | |---|---|---| | `BRANCH_NOT_FOUND` | 404 | `branchId`/`externalBranchId` didn't resolve to an active branch, and no active branch matches the pickup coordinates either. | | `INVALID_PICKUP_LOCATION` | 400 | `pickup.lat`/`pickup.lng` out of range. | | `INVALID_DROPOFF_LOCATION` | 400 | `dropoff.lat`/`dropoff.lng` out of range. | | `INVALID_AMOUNT` | 400 | `payment.amount` or `payment.deliveryFee` negative. | | `STRUCTURAL_LIMIT_EXCEEDED` | 400 | A string field exceeded its max length, or an amount had more than 2 decimal places / exceeded the numeric cap. | | `INVALID_PREPARATION_TIME` | 400 | `preparationTimeMinutes` negative. | | `INVALID_PAYMENT_METHOD` | 400 | `payment.method` was not a recognized enum value. | | `INVALID_SCHEDULED_TIME` | 400 | `scheduledDeliveryAt` less than the minimum lead time in the future. See Section 14. | | `PROVIDER_NOT_ENABLED` | 400 | `deliveryProviderCode` unknown or not enabled for your tenant. | | `MANUAL_OVERRIDE_NOT_ALLOWED` | 400 | `deliveryProviderCode` supplied but manual provider selection is not permitted for this branch/tenant, or the requested provider isn't eligible right now. | | `TENANT_SUSPENDED` / `ORDER_SOURCE_DISABLED` | 403 | See Section 2.5. | | `RATE_LIMIT_EXCEEDED` | 429 | See Section 22. | --- ## 8. Order status, delivery status, and tracking ### 8.1 Two lifecycles, not one FleetBridge keeps **order status** (your business view) and **delivery status** (the physical delivery view) separate. They're related, but not the same thing, and you should show/store both. - `OrderStatus` — the field you see as `status`/`orderStatus` — is your order's business lifecycle. FleetBridge derives it automatically from the order's attempts and shipment; you never set it directly. It moves in response to routing, provider events, cancellation, and operator actions. - `UnifiedDeliveryStatus` — nested as `delivery.status`/`delivery.unifiedStatus` — is the physical delivery, once one exists. It stays `null`/absent until a Delivery Provider has actually been sent the order. ### 8.2 OrderStatus values | Value | Meaning | Terminal? | Can you still Update/Cancel? | |---|---|---|---| | `Created` | Momentary internal state immediately before the order is first persisted. **You will never observe this value from any GET call** — by the time an order is readable, it has already moved to `Scheduled` or `PendingRouting`. | No | — | | `Scheduled` | `scheduledDeliveryAt` is in the future; dispatch has not started. | No | Yes | | `PendingRouting` | Waiting for the routing engine to select/dispatch a provider. | No | Yes | | `Dispatching` | One or more delivery attempts are in flight — sent, awaiting acceptance, or failing over to the next provider. | No | Update yes; Cancel yes (immediate, platform-side). | | `InDelivery` | A Delivery Provider has accepted and the delivery is actively progressing (accepted through on-the-way). | No | Update yes; Cancel only if the provider supports cancellation at the current stage (Section 12). | | `CancellationRequested` | You (or an operator) requested cancellation; FleetBridge is waiting for the Delivery Provider to confirm. | No | A repeat Cancel call is safe (Section 12.3). | | `ReturnInProgress` | The delivery failed **after pickup**; a return-to-branch flow is active. See Section 18. | No | Read-only from your side; no self-service action. | | `Delivered` | Final: delivered to the customer. | **Yes** | No — `409 ORDER_ALREADY_FINAL`. | | `Cancelled` | Final: cancellation confirmed. | **Yes** | No. | | `Failed` | Final: the delivery failed terminally, including "returned to origin" outcomes. | **Yes** | No. | | `NoProviderAvailable` | Held: every eligible provider was exhausted during automatic routing; a FleetBridge operator must intervene. | No | Update yes; Cancel yes. | | `ManualReviewRequired` | Held: a failure needs operator attention (failed cancellation, failed return, correlation problem). | No | Update yes; Cancel yes. | Only **`Delivered`**, **`Cancelled`**, and **`Failed`** are truly final. The two "held" statuses (`NoProviderAvailable`, `ManualReviewRequired`) can resume automatically once a FleetBridge operator steps in, so don't treat them as final in your own state machine — and keep expecting webhooks for orders sitting in either state. ### 8.3 UnifiedDeliveryStatus values (the `delivery.status` field) | Value | Meaning | |---|---| | `SentToProvider` | Sent to a Delivery Provider, awaiting acceptance. | | `ProviderAccepted` | The Delivery Provider accepted the delivery. | | `DriverAssigned` | A driver has been assigned. | | `ArrivedAtPickup` | The driver has arrived at the branch. | | `PickedUp` | The driver has collected the order. | | `OnTheWay` | The order is en route to the customer. | | `Delivered` | Final: delivered. | | `Cancelled` | Final: cancelled. | | `Failed` | Final: failed (not a return case). | | `ReturnRequested` | Post-pickup failure; a return has been initiated. | | `ReturningToOrigin` | Goods are on the way back to the branch. | | `ReturnedToOrigin` | Final: goods are back at the branch (order-level status becomes `Failed`). | | `ReturnFailed` | The return itself could not be completed; requires operator resolution (order-level status becomes `ManualReviewRequired`). | ### 8.4 Lifecycle diagram ``` ┌───────────┐ │ Scheduled │ (only if scheduledDeliveryAt is in the future) └─────┬─────┘ │ dispatch time reached ▼ ┌────────────────┐ ┌────────────────┐ ┌─────────────┐ ┌────────────┐ │ PendingRouting │───►│ Dispatching │───►│ InDelivery │───►│ Delivered │ (final) └────────────────┘ │ (attempts/ │ │ (accepted → │ └────────────┘ │ failover) │ │ on the way)│ └───────┬────────┘ └──────┬──────┘ │ │ all providers exhausted failure after pickup │ │ ▼ ▼ ┌────────────────────┐ ┌──────────────────┐ │ NoProviderAvailable │ │ ReturnInProgress │ │ (held) │ └────────┬─────────┘ └─────────────────────┘ │ ▼ ┌────────────┐ │ Failed │ (final; includes └────────────┘ "returned to origin") Cancellation, from any non-final status, at any point above: Dispatching/PendingRouting/Scheduled → Cancelled directly (platform-side) InDelivery (before pickup, if supported) → CancellationRequested → Cancelled InDelivery (after pickup, if supported) → CancellationRequested → Cancelled Any unexpected failure needing a human → ManualReviewRequired (held) ``` Treat this as an orientation aid, not the literal implementation. `OrderStatus` gets **recomputed from scratch** on every relevant event — it's not a fixed adjacency list you could hard-code — so the exact transitions you see depend on your tenant's routing configuration and whatever the Delivery Provider itself supports. For what's actually authoritative, go back to the table in 8.2 (terminal vs. held vs. active). ### 8.5 Get order status ``` GET /api/v1/orders/{platformOrderId}/status ``` ```json { "platformOrderId": "6e1c1a2b-3d4e-4f5a-8b6c-7d8e9f0a1b2c", "orderStatus": "InDelivery", "delivery": { "shipmentId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "platformReference": "att_18c9a4f2b3c1a2b3c4d5e6f708192a3b", "deliveryProviderId": "5e9ca8a5-0c61-4312-ba14-cf9546aea68a", "providerCode": "cervo", "unifiedStatus": "DriverAssigned", "slaStatus": "OnTrack" } } ``` `delivery` stays `null` until a Delivery Provider has actually been sent the order — so while `orderStatus` is still `Scheduled` or `PendingRouting`, expect it to be empty. `slaStatus` is one of `OnTrack`, `AtRisk`, `Breached`, `CompletedWithinSla`, `CompletedBreached`, `NotApplicable`. `GET /api/v1/orders/{platformOrderId}` (full detail) gives you everything above plus your original business fields: customer, addresses, payment, notes, and the `createdAt`/`deliveredAt`/`cancelledAt`/`failedAt` timestamps. ### 8.6 Get tracking ``` GET /api/v1/orders/{platformOrderId}/tracking ``` ```json { "platformOrderId": "6e1c1a2b-3d4e-4f5a-8b6c-7d8e9f0a1b2c", "shipmentId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "unifiedStatus": "OnTheWay", "driverName": "Mohammed", "driverPhone": "0590000000", "driverLat": 31.9038, "driverLng": 35.2034, "driverLocationUpdatedAt": "2026-09-22T13:40:00Z", "trackingUrl": "https://tracking.example.com/abc", "currentEta": "2026-09-22T14:05:00Z" } ``` Every field here is nullable. You'll see `null` when there's no shipment yet, or simply because the current Delivery Provider doesn't supply that signal — not every provider sends live driver coordinates, a tracking URL, or an ETA. Presence is provider-dependent; don't count on it universally. ### 8.7 Get full tracking history ``` GET /api/v1/orders/{platformOrderId}/tracking-history ``` Returns every recorded tracking/status event for the order's shipment, oldest first, as a plain array (empty, not an error, if no shipment exists yet): ```json [ { "eventTimeUtc": "2026-09-22T13:28:54Z", "receivedAtUtc": "2026-09-22T13:28:55Z", "status": "ArrivedAtPickup", "providerStatus": "arrived_at_store", "source": "Webhook", "driverName": "Mohammed", "driverPhone": "0590000000", "driverLat": 31.9038, "driverLng": 35.2034, "estimatedDeliveryAtUtc": "2026-09-22T14:05:00Z", "providerCorrelationId": "DLV-9001" } ] ``` `status` is always a `UnifiedDeliveryStatus` value (Section 8.3), the normalized, provider-agnostic status. `providerStatus` and `providerCorrelationId` are different — they're **opaque, best-effort diagnostic text** straight from the Delivery Provider's own raw event. Useful for support and debugging, but not a stable contract: exact values differ per provider and per integration, and FleetBridge makes no promises about their format. Build your business logic against `status`, never against `providerStatus`. `source` is one of `Webhook`, `Polling`, `Platform` (FleetBridge's own administrative actions). --- ## 9. Webhooks — FleetBridge → you ### 9.1 Direction This section flips the direction: FleetBridge is **calling your server** now, not the other way around like everything in Sections 7 and 8: ``` Order Source ◄──HTTPS POST── FleetBridge (this section) Order Source ──HTTPS POST──► FleetBridge (Sections 7, 8, 11, 12) ``` ### 9.2 How your callback URL is configured FleetBridge registers your webhook callback URL and signing secret for you (through your tenant's dashboard user) as part of onboarding. An Order Source API key can't create or modify its own webhook endpoint registration. You get the secret once, at registration time — capture it right then, because FleetBridge can't show it to you again later. Rotating it is possible (Section 9.10); redisplaying the old one isn't. You **can**, though, trigger a one-off test delivery to your own registered endpoint with your API key: ``` POST /api/v1/webhooks/test ``` This fires a `webhook.test` event (Section 9.9) at your registered URL, signed exactly like any real event, so you can check connectivity and signature verification before going live. ### 9.3 Delivery mechanics Every webhook is an HTTP `POST` with `Content-Type: application/json` to your registered URL. A `2xx` counts as acknowledged. Anything else — non-2xx, timeout, connection failure — counts as a failure and gets retried per the schedule below. FleetBridge waits **15 seconds** for your response, so respond fast and push any slow processing to the background on your side. ### 9.4 Retry schedule If your endpoint doesn't return `2xx`, FleetBridge retries up to **5 times** after the initial attempt (6 attempts total), at increasing delays: ``` attempt 1 (immediate) → fail +1 minute → attempt 2 +5 minutes → attempt 3 +15 minutes → attempt 4 +1 hour → attempt 5 +3 hours → attempt 6 → still failing → delivery marked Exhausted, no further automatic retry ``` Each attempt's number rides along in the `X-Platform-Retry-Count` header (`0` on the first try). An Exhausted delivery isn't gone forever — a FleetBridge operator can still resend it manually. It's just done retrying on its own. ### 9.5 At-least-once delivery — you must deduplicate FleetBridge's webhook delivery is **at-least-once, not exactly-once, and not guaranteed in-order**. In rare recovery scenarios the same logical event can land on your server twice, and two different events for the same order can arrive out of order relative to each other — a fast retry of an older event racing a newer event's first attempt, for example. So your webhook handler needs to be: - **Idempotent**: dedupe on the `eventId` field (it's also in the `X-Platform-Event-Id` header). Processing the same `eventId` twice should have zero additional effect the second time. - **Order-tolerant**: use `eventTime`, or for delivery-status events the `delivery.status` value itself against whatever you last recorded, to decide if an incoming event is actually newer than what you already have. Don't assume events arrive in the order they happened. ### 9.6 Headers on every webhook request ```http POST /your/callback/url HTTP/1.1 Content-Type: application/json X-Platform-Event-Id: evt_9f1c2b3a4d5e6f708192a3b4c5d6e7f8 X-Platform-Timestamp: 2026-09-22T13:20:00Z X-Platform-Signature: sha256=1a2b3c4d5e6f... X-Platform-Retry-Count: 0 X-Platform-Api-Version: v1 ``` Section 10 (Webhook Security) covers exactly how `X-Platform-Signature` gets computed and how to verify it. Don't skip it before going to production. **FleetBridge doesn't enforce a server-side replay window** — no built-in expiry on how old a valid signature can be. If your security posture needs old or replayed requests rejected, that's on you to build: an `X-Platform-Timestamp` freshness check (rejecting anything older than, say, 5 minutes) as part of your own verification code. The worked examples in Section 10.5 show how. ### 9.7 Event catalog | Event type | Fires when | |---|---| | `order.created` | The order was created inside FleetBridge. | | `order.updated` | Order business data was changed via Update (Section 11); includes per-field propagation results. | | `delivery.provider_assigned` | A Delivery Provider was selected for this dispatch round. | | `delivery.sent_to_provider` | The order was actually sent to that provider. | | `delivery.accepted` | The provider accepted the delivery. | | `driver.assigned` | A driver was assigned. | | `driver.location_updated` | Driver coordinates changed. | | `tracking.updated` | The tracking URL changed. | | `delivery.arrived_at_pickup` | The driver arrived at the branch. | | `delivery.picked_up` | The driver collected the order. | | `delivery.on_the_way` | The order is en route. | | `eta.updated` | The estimated delivery time changed. | | `sla.at_risk` | The order is at risk of breaching its configured SLA. | | `sla.breached` | The order breached its configured SLA. | | `delivery.delivered` | The order was delivered. | | `order.cancellation_requested` | A cancellation was accepted into the workflow; provider confirmation is pending. | | `delivery.cancelled` | The delivery was cancelled and confirmed. | | `order.cancellation_failed` | A provider-side cancellation attempt failed; the order needs manual attention. | | `delivery.failed` | The delivery failed terminally (not a return case). | | `delivery.return_requested` | A post-pickup failure triggered a return. | | `delivery.returning_to_origin` | Goods are on the way back to the branch. | | `delivery.returned_to_origin` | Goods are back at the branch. | | `delivery.return_failed` | The return itself could not be completed. | | `provider.failed` | The current provider failed and FleetBridge is trying the next eligible one (see Section 15.3). | | `order.no_provider_available` | Every eligible provider was exhausted. | | `order.manual_review_required` | The order needs FleetBridge operator attention. | | `webhook.test` | A manually triggered connectivity test (Section 9.2) — **different payload shape**, see 9.9. | You don't need to subscribe to every event type. Subscriptions are configured per callback URL by FleetBridge on your behalf during onboarding — just tell them which ones you want. ### 9.8 Standard payload shape Every event except `webhook.test` (9.9) uses this shape. Sections that don't apply to a given event are `null` — for example `driver`/`tracking`/`eta` are all `null` on an `order.created` event, since no shipment exists yet. ```json { "eventId": "evt_9f1c2b3a4d5e6f708192a3b4c5d6e7f8", "eventType": "delivery.accepted", "eventTime": "2026-09-22T13:20:00Z", "apiVersion": "v1", "tenantId": "3f2504e0-4f89-11d3-9a0c-0305e82c3301", "orderSource": { "id": "8a1b2c3d-4e5f-4a3b-8c2d-1e0f9a8b7c6d", "code": "qr_menu", "name": "QR Menu" }, "order": { "platformOrderId": "6e1c1a2b-3d4e-4f5a-8b6c-7d8e9f0a1b2c", "externalOrderId": "ORD-2003", "branchId": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e", "orderStatus": "InDelivery" }, "delivery": { "shipmentId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "platformReference": "att_18c9a4f2b3c1a2b3c4d5e6f708192a3b", "providerCode": "cervo", "providerDeliveryId": "DLV-9001", "status": "ProviderAccepted" }, "driver": null, "tracking": null, "eta": null, "sla": { "isAtRisk": false, "isBreached": false, "breachedStages": [] }, "failure": null, "routing": null, "updatePropagation": null } ``` Field reference: | Path | Type | Notes | |---|---|---| | `eventId` | string | Globally unique. **Your deduplication key.** | | `eventType` | string | One of Section 9.7. | | `eventTime` | ISO 8601 UTC | When FleetBridge recorded the event. | | `apiVersion` | string | Always `"v1"` today. | | `tenantId` | GUID | Your tenant. | | `orderSource.{id,code,name}` | | Always your own Order Source. | | `order.platformOrderId` | GUID | Matches what Create returned. | | `order.orderStatus` | string | `OrderStatus` value, Section 8.2. | | `delivery.status` | string | `UnifiedDeliveryStatus` value, Section 8.3. `delivery` itself is `null` before dispatch. | | `delivery.platformReference` | string | An internal correlation id, format `att_`. Not the same as `providerDeliveryId`. | | `delivery.providerDeliveryId` | string, nullable | The Delivery Provider's own id for this delivery, when the provider exposes one. | | `driver.{name,phone,lat,lng}` | | `null` until a driver is assigned; individual fields may still be `null` afterward depending on the provider. | | `tracking.trackingUrl` | string, nullable | Provider-hosted tracking page, when the provider supplies one. | | `eta.estimatedDeliveryAt` / `remainingMinutes` / `confidence` | | Best-effort; not every provider supplies an ETA. | | `sla.{isAtRisk,isBreached,breachedStages}` | | Reflects your tenant's configured SLA thresholds. | | `failure.{reasonCode,reasonText,rawProviderReason}` | | Populated on `provider.failed`/`delivery.failed`/cancellation-failure events. | | `routing.{nextAction,nextProviderCode}` | | Populated on `provider.failed` — see Section 15.3. | | `updatePropagation.fields` | object | Populated only on `order.updated` — mirrors the per-field propagation result from the Update response (Section 11). | ### 9.9 `webhook.test` payload (different shape) ```json { "eventId": "evt_test_1a2b3c4d5e6f7081", "eventType": "webhook.test", "eventTime": "2026-09-22T13:00:00Z", "apiVersion": "v1", "tenantId": "3f2504e0-4f89-11d3-9a0c-0305e82c3301", "orderSourceId": "8a1b2c3d-4e5f-4a3b-8c2d-1e0f9a8b7c6d", "message": "This is a test event from FleetBridge to verify your webhook endpoint is reachable and correctly signed." } ``` `webhook.test` is intentionally flat, with no `order`/`delivery`/`orderSource` nested objects. If your handler assumes every event has the full Section 9.8 shape, it'll break on this one — check `eventType` first and branch your parsing from there. ### 9.10 Secret rotation If FleetBridge rotates your webhook signing secret, you get a **24-hour overlap window** where both the old and new secret are valid. During that window, `X-Platform-Signature` carries **both** signatures, comma-separated, newest first: ``` X-Platform-Signature: sha256=,sha256= ``` Your verification code needs to accept the request if **any** of the comma-separated values matches what you compute. Don't assume there's exactly one value in this header. --- ## 10. Webhook signature verification Don't skip this section. An unverified webhook is just a POST request from the internet with no authentication behind it. ### 10.1 What is signed The signing input is the concatenation, in this exact order, of four values, with **no delimiter** between them: ``` signingInput = apiVersion + timestamp + eventId + rawRequestBody ``` - `apiVersion` — the literal string `v1`, always. - `timestamp` — the exact string value of the `X-Platform-Timestamp` header (not a re-formatted version of it). - `eventId` — the exact string value of the `X-Platform-Event-Id` header. - `rawRequestBody` — the **exact raw bytes of the HTTP request body**, before any JSON parsing — see 10.4 for why this matters. ### 10.2 Which secret Your per-endpoint webhook signing secret, handed to you once at registration. Format is `whsec_` followed by 64 lowercase hex characters — structurally similar to your `X-Api-Key`, but a different credential. Never send it to FleetBridge or anyone else. It's used only locally, by you, to verify. ### 10.3 Algorithm HMAC-SHA256 over the UTF-8 bytes of `signingInput`, keyed by the UTF-8 bytes of your secret, hex-encoded in **lowercase**. The header value is prefixed `sha256=`: ``` X-Platform-Signature: sha256=<64 lowercase hex characters> ``` (During a secret-rotation overlap window, the header may contain two comma-separated `sha256=...` values — see Section 9.10.) ### 10.4 Why you must use the raw body FleetBridge signs the **exact bytes** it sent — not a value derived from re-serializing the parsed JSON. Here's the trap: most web frameworks parse the JSON body before your signature-verification code even runs. If you then re-serialize that parsed object to build your comparison string, key ordering, whitespace, or number formatting can drift just enough to produce a different byte sequence — and a signature "mismatch" that has nothing to do with an actual security problem. Capture and verify against the **raw, unparsed body bytes**, before or independent of JSON parsing, no matter which language you're in. ### 10.5 Verification steps (all languages) 1. Read the raw request body as bytes (or a string, using the same encoding your framework received it in — UTF-8) **before** any JSON deserialization. 2. Read the `X-Platform-Timestamp`, `X-Platform-Event-Id`, and `X-Platform-Signature` headers. 3. (Optional, recommended) Check that `X-Platform-Timestamp` is within your own acceptable freshness window (Section 9.6 — FleetBridge does not enforce one for you). 4. Build `signingInput = "v1" + timestamp + eventId + rawBody`. 5. Compute `HMAC-SHA256(secret, signingInput)`, hex-encode it in lowercase. 6. Split `X-Platform-Signature` on commas. For each candidate value, strip the `sha256=` prefix and compare it to your computed value using a **constant-time comparison** (never `==`/`.equals` on secret-derived strings) — accept if **any** candidate matches. 7. Only after verification succeeds, parse the body as JSON and process the event. ### 10.6 C# ```csharp using System.Security.Cryptography; using System.Text; public static bool VerifyFleetBridgeWebhook( string rawBody, string timestamp, string eventId, string signatureHeader, string secret) { var signingInput = "v1" + timestamp + eventId + rawBody; var computedBytes = HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), Encoding.UTF8.GetBytes(signingInput)); var computedHex = Convert.ToHexString(computedBytes).ToLowerInvariant(); foreach (var candidate in signatureHeader.Split(',')) { var trimmed = candidate.Trim(); if (!trimmed.StartsWith("sha256=", StringComparison.Ordinal)) { continue; } var presentedHex = trimmed["sha256=".Length..]; var presentedBytes = Encoding.UTF8.GetBytes(presentedHex); var computedHexBytes = Encoding.UTF8.GetBytes(computedHex); if (presentedBytes.Length == computedHexBytes.Length && CryptographicOperations.FixedTimeEquals(presentedBytes, computedHexBytes)) { return true; } } return false; } // ASP.NET Core minimal API example — read the RAW body before model binding: app.MapPost("/fleetbridge/webhooks", async (HttpRequest request) => { request.EnableBuffering(); using var reader = new StreamReader(request.Body, Encoding.UTF8, leaveOpen: true); var rawBody = await reader.ReadToEndAsync(); request.Body.Position = 0; var timestamp = request.Headers["X-Platform-Timestamp"].ToString(); var eventId = request.Headers["X-Platform-Event-Id"].ToString(); var signature = request.Headers["X-Platform-Signature"].ToString(); if (!VerifyFleetBridgeWebhook(rawBody, timestamp, eventId, signature, YourStoredSecret)) { return Results.Unauthorized(); } // Only now parse rawBody as JSON and process the event, deduplicating on eventId. return Results.Ok(); }); ``` ### 10.7 JavaScript (Node.js) ```javascript const crypto = require("crypto"); function verifyFleetBridgeWebhook(rawBody, timestamp, eventId, signatureHeader, secret) { const signingInput = "v1" + timestamp + eventId + rawBody; const computedHex = crypto.createHmac("sha256", secret).update(signingInput, "utf8").digest("hex"); return signatureHeader.split(",").some((candidate) => { const trimmed = candidate.trim(); if (!trimmed.startsWith("sha256=")) return false; const presentedHex = trimmed.slice("sha256=".length); const presented = Buffer.from(presentedHex, "utf8"); const computed = Buffer.from(computedHex, "utf8"); return presented.length === computed.length && crypto.timingSafeEqual(presented, computed); }); } // Express example — you MUST capture the raw body before express.json() parses it. const express = require("express"); const app = express(); app.use( "/fleetbridge/webhooks", express.raw({ type: "application/json" }), // gives req.body as a Buffer, unparsed ); app.post("/fleetbridge/webhooks", (req, res) => { const rawBody = req.body.toString("utf8"); const timestamp = req.header("X-Platform-Timestamp"); const eventId = req.header("X-Platform-Event-Id"); const signature = req.header("X-Platform-Signature"); if (!verifyFleetBridgeWebhook(rawBody, timestamp, eventId, signature, process.env.FLEETBRIDGE_WEBHOOK_SECRET)) { return res.status(401).end(); } const event = JSON.parse(rawBody); // Deduplicate on event.eventId, then process. res.status(200).end(); }); ``` ### 10.8 Python ```python import hashlib import hmac def verify_fleetbridge_webhook(raw_body: bytes, timestamp: str, event_id: str, signature_header: str, secret: str) -> bool: signing_input = ("v1" + timestamp + event_id).encode("utf-8") + raw_body computed_hex = hmac.new(secret.encode("utf-8"), signing_input, hashlib.sha256).hexdigest() for candidate in signature_header.split(","): candidate = candidate.strip() if not candidate.startswith("sha256="): continue presented_hex = candidate[len("sha256="):] if hmac.compare_digest(presented_hex, computed_hex): return True return False # Flask example — request.get_data() returns the raw, unparsed body. from flask import Flask, request, abort app = Flask(__name__) @app.route("/fleetbridge/webhooks", methods=["POST"]) def fleetbridge_webhook(): raw_body = request.get_data() # bytes, raw — read before request.get_json() timestamp = request.headers.get("X-Platform-Timestamp", "") event_id = request.headers.get("X-Platform-Event-Id", "") signature = request.headers.get("X-Platform-Signature", "") if not verify_fleetbridge_webhook(raw_body, timestamp, event_id, signature, FLEETBRIDGE_WEBHOOK_SECRET): abort(401) event = request.get_json() # Deduplicate on event["eventId"], then process. return "", 200 ``` --- ## 11. Update Order ``` PATCH /api/v1/orders/{platformOrderId} ``` ### 11.1 Partial-update semantics — read this before building your client The request body only ever describes the fields you want to change. There are three distinct states for every field: 1. **Omit the field from the JSON body entirely** → left unchanged. 2. **Send the field with an explicit `null`** (only meaningful for fields that are nullable, like `customerEmail` or `notes`) → clears it. 3. **Send the field with a value** → sets it to that value. This means `{}` is a valid (no-op) request body, and you must not send a field just because your own internal object happens to have that property populated — only send what actually changed. ### 11.2 Mutable fields | Field | Notes | |---|---| | `customerName` | | | `customerPhone` | | | `customerEmail` | Nullable — send `null` to clear. | | `dropoff.address` | Independent of `dropoff.lat`/`dropoff.lng` — patching one doesn't reset the others. | | `dropoff.lat` / `dropoff.lng` | | | `notes` | Nullable. | | `paymentMethod` | | | `paymentMethodRaw` | Nullable. | | `amount` | | | `deliveryFee` | Nullable. | | `currency` | Re-normalized to uppercase; a same-currency different-casing PATCH is treated as a no-op. | | `preparationTimeMinutes` | | | `scheduledDeliveryAt` | Nullable; see restriction below. | ### 11.3 Immutable fields `externalOrderId`, `externalOrderNumber`, `branchId`/pickup location, and the routing/provider selection fields can't be changed through Update — send them anyway and they're just silently ignored, since they're not even part of the request schema. Need a different branch? Cancel and recreate the order. Need a different provider? That happens through cancellation too, never through Update. ### 11.4 Example: Request → Success ```json { "customerPhone": "+970590000111", "notes": "Leave with the neighbor if no answer", "amount": 92.00 } ``` ``` HTTP/1.1 200 OK ``` ```json { "orderId": "6e1c1a2b-3d4e-4f5a-8b6c-7d8e9f0a1b2c", "addressPropagation": "NotApplicable", "phonePropagation": "Propagated", "scheduledDeliveryPropagation": "NotApplicable", "notesPropagation": "Propagated", "customerNamePropagation": "NotApplicable", "customerEmailPropagation": "NotApplicable", "amountPropagation": "Propagated", "currencyPropagation": "NotApplicable", "paymentMethodPropagation": "NotApplicable", "deliveryFeePropagation": "NotApplicable", "preparationTimePropagation": "NotApplicable" } ``` **FleetBridge always saves your update on its own side first**, whether or not the active Delivery Provider can accept the change. The response then tells you, field by field, what happened when FleetBridge tried to forward that specific change to whoever's handling the delivery right now: | Value | Meaning | |---|---| | `Propagated` | Successfully forwarded to the Delivery Provider. | | `NotSupportedByProvider` | The current provider's integration doesn't support changing this field once a delivery is in flight. Your change is saved in FleetBridge, but the provider (and its driver) may not see it. | | `PropagationFailed` | FleetBridge tried to forward the change and the provider call failed (transient/technical). Your change is still saved in FleetBridge. | | `NotApplicable` | This field wasn't part of your request, or there is no active shipment yet to propagate to. | A `NotSupportedByProvider` or `PropagationFailed` result isn't an HTTP error by itself — the update succeeded from FleetBridge's point of view. But if a field's real-world propagation matters to you (a changed dropoff address after the driver's already en route, say), check that specific field in the response and handle a non-`Propagated` result in your own UI or ops process. FleetBridge won't escalate it to an operator on your behalf. ### 11.5 Updating never changes order status Update never pushes `orderStatus`/`delivery.status` forward or back. Change a customer's phone number on an order that's `DriverAssigned` and it stays `DriverAssigned` — it can't slip back to `PendingRouting`, and it can't jump ahead either. Lifecycle transitions only happen through routing, Delivery Provider events, Cancel, and FleetBridge's own operator workflows. ### 11.6 Scheduled-delivery-specific restriction You can change `scheduledDeliveryAt` only while the shipment hasn't progressed past `ProviderAccepted` — unless the current Delivery Provider explicitly supports updating a scheduled time after acceptance. Otherwise you'll get `400 PROVIDER_UPDATE_NOT_SUPPORTED`. ### 11.7 Invalid update example ```json { "amount": -5 } ``` ``` HTTP/1.1 400 Bad Request Content-Type: application/problem+json ``` ```json { "status": 400, "title": "Bad Request", "detail": "'amount' must not be negative.", "errorCode": "INVALID_AMOUNT", "correlationId": "0HNOOIIC1J8FA:00000002" } ``` ### 11.8 When Update is rejected outright | errorCode | Status | Cause | |---|---|---| | `ORDER_ALREADY_FINAL` | 409 | The order is `Delivered`, `Cancelled`, or `Failed`. | | `PROVIDER_UPDATE_NOT_SUPPORTED` | 400 | `scheduledDeliveryAt` change rejected per Section 11.6. | | (validation errors) | 400 | Same field-length/amount/payment-method rules as Create, Section 7.5, applied to the merged (post-patch) values. | --- ## 12. Cancel Order ``` POST /api/v1/orders/{platformOrderId}/cancel ``` Optional body: ```json { "reason": "customer_requested" } ``` `reason` is a free-text string, ≤500 characters, entirely optional. Skip the body altogether if you've got nothing to say. ### 12.1 Behavior by stage | Order / delivery stage | What happens | |---|---| | `Created`, `Scheduled`, `PendingRouting` — nothing dispatched yet | Cancelled immediately, platform-side. No call to any Delivery Provider. `outcome: "Cancelled"`. | | `Dispatching` — sent to a provider, not yet accepted | Open delivery attempts are cancelled; FleetBridge notifies the provider best-effort. Order becomes `Cancelled` immediately once no attempt remains active. `outcome: "Cancelled"`. | | `InDelivery`, **before pickup** (`ProviderAccepted` / `DriverAssigned` / `ArrivedAtPickup`) | Allowed **only if** the current Delivery Provider supports cancellation before pickup. If not supported: rejected, `409 CANCELLATION_NOT_SUPPORTED_AT_STAGE`. If supported: order moves to `CancellationRequested` and FleetBridge waits for the provider to confirm; `outcome: "ConfirmationPending"`. | | `InDelivery`, **after pickup** (`PickedUp` / `OnTheWay`) | Allowed **only if** the current Delivery Provider supports cancellation after pickup (this is uncommon — most providers do not). If not supported: `409 CANCELLATION_NOT_SUPPORTED_AT_STAGE`. If supported: same `CancellationRequested` / `ConfirmationPending` flow as above. | | Any final status (`Delivered`/`Cancelled`/`Failed`) | Rejected: `409 ORDER_ALREADY_FINAL`. | Once pickup has happened and the provider doesn't support after-pickup cancellation, there are only two ways forward: delivery, or a provider-side failure that FleetBridge handles as a Return (Section 18). There's no "force cancel a physically-picked-up order" button available to an Order Source — it just doesn't exist. ### 12.2 Response ``` HTTP/1.1 200 OK ``` ```json { "orderId": "6e1c1a2b-3d4e-4f5a-8b6c-7d8e9f0a1b2c", "status": "CancellationRequested", "outcome": "ConfirmationPending" } ``` `outcome` is either `Cancelled` (finalized right away) or `ConfirmationPending` (waiting on the provider). Watch for the `delivery.cancelled` webhook — or `order.cancellation_failed` if the provider-side cancellation itself fails, in which case the order moves to `ManualReviewRequired` instead of sitting in limbo forever. FleetBridge never marks an order `Cancelled` while a provider that already accepted it hasn't actually confirmed. ### 12.3 Idempotent repeated cancellation Calling Cancel again on an order that's already `CancellationRequested` or already `Cancelled` is safe. A repeat call on an already-final `Cancelled` order comes back `409 ORDER_ALREADY_FINAL`, which you can just treat as "already cancelled, nothing to do" in your retry logic. A repeat call while still `CancellationRequested` won't create a duplicate cancellation attempt either. ### 12.4 Related: look up by your own reference ``` GET /api/v1/orders/by-external-id/{externalOrderId} ``` Same shape as `GET /api/v1/orders/{platformOrderId}`, scoped to orders your Order Source created. Handy if you need to re-establish `platformOrderId` from your own stored `externalOrderId` before calling Update or Cancel — after a crash, say, where you're not sure whether you'd already persisted the FleetBridge id. Lookup is by `externalOrderId` only; `externalOrderNumber` is never a lookup key. --- ## 13. Idempotency ### 13.1 Header ``` Idempotency-Key: ``` Supported **only on Create** (`POST /api/v1/orders`). Update and Cancel don't accept or need one — Cancel is naturally idempotent already (Section 12.3), and Update's partial-patch semantics mean a retried identical PATCH just re-applies the same, already-applied change harmlessly. ### 13.2 Scope An idempotency key is scoped to `(your tenant, your Order Source, the key string)`. So two different Order Sources under the same tenant can reuse the identical key string with zero risk of collision. ### 13.3 Behavior on repeat — same key, read carefully Say you send a second Create request with an `Idempotency-Key` that already succeeded once. **FleetBridge returns the original order, unconditionally: `201 Created`, the same `platformOrderId`, the same response shape as the first call — whether or not the new request body matches the original.** There's no payload-equality check, and no "conflicting payload" error. Replay the same key with a genuinely different body — a bug on your side, or a legitimate change of mind — and FleetBridge does **not** create a second order and does **not** apply your new body to the existing one. It just quietly hands back the original order, exactly as it already was. Need to change something about an order you already created? Use Update (Section 11). Never a second Create with the same key and different fields. ### 13.4 Behavior with no idempotency key Skip `Idempotency-Key` entirely and FleetBridge still protects you from an accidental true duplicate: a second Create with the same `externalOrderId` (scoped to your Order Source) resolves to the existing order the same way a matching `Idempotency-Key` would. You get the original back, not a new one. **`externalOrderId` itself is always a de-dup key, with or without an explicit `Idempotency-Key` header.** `externalOrderNumber` never is: two orders may share one. We'd still recommend sending the header explicitly — it lets you retry safely with the *same* `externalOrderId` semantics even in flows where you generate that id late, and it says what you mean more clearly than relying on a side effect. ### 13.5 Retention Idempotency records stick around **indefinitely**. There's no expiry after which the same key could suddenly create a second order — it's permanently tied to whatever it first created. ### 13.6 What to do after a timeout / unknown outcome Create request times out, or you get a network error with no HTTP response at all — now you can't tell if FleetBridge actually processed it. The right move: **retry the exact same request, including the same `Idempotency-Key`.** Whether the original attempt succeeded or never arrived, that retry is safe. You'll either get the freshly created order or the original one back. Don't generate a new `Idempotency-Key` for what you think is a retry of the same logical order — that defeats the whole mechanism and can actually create a duplicate. ### 13.7 Worked examples **First request:** ``` POST /api/v1/orders Idempotency-Key: web-order-7781 { "externalOrderId": "WEB-7781", "payment": { "method": "Cash", "amount": 50, "currency": "ILS" }, ... } → 201 Created, platformOrderId = "aaa...", externalOrderId = "WEB-7781" ``` **Exact retry (same key, same body) — safe, expected:** ``` POST /api/v1/orders Idempotency-Key: web-order-7781 { "externalOrderId": "WEB-7781", "payment": { "method": "Cash", "amount": 50, "currency": "ILS" }, ... } → 201 Created, platformOrderId = "aaa..." (identical to the first response) ``` **Same key, different body — still returns the original, does NOT apply the new body:** ``` POST /api/v1/orders Idempotency-Key: web-order-7781 { "externalOrderId": "WEB-7781", "payment": { "method": "Card", "amount": 999, "currency": "ILS" }, ... } → 201 Created, platformOrderId = "aaa..." — still Cash/50, the ORIGINAL order, unchanged ``` --- ## 14. Scheduled orders ### 14.1 Semantics - `scheduledDeliveryAt` omitted or `null` → immediate (ASAP) order, dispatched under your tenant's normal immediate-routing rules right away. - `scheduledDeliveryAt` set to a future timestamp → the order is created with `status: "Scheduled"` and dispatched automatically when due. ### 14.2 Validation `scheduledDeliveryAt` needs to be at least a minimum lead time out — **15 minutes** by FleetBridge's platform default, though your tenant might be configured differently. Treat 15 minutes as the floor to design against, not a guarantee. Anything before that minimum, or in the past, gets rejected: ```json { "status": 400, "title": "Bad Request", "detail": "scheduledDeliveryAt must be at least 15 minutes in the future.", "errorCode": "INVALID_SCHEDULED_TIME", "correlationId": "..." } ``` Must be ISO 8601 with an explicit UTC offset (Section 6). ### 14.3 Dispatch timing FleetBridge doesn't wait until the exact `scheduledDeliveryAt` moment to start dispatching. It starts **ahead of time**, so the delivery actually has a shot at arriving on schedule: ``` dispatchAt = scheduledDeliveryAt − dispatchLeadTimeMinutes ``` `dispatchLeadTimeMinutes` is a per-tenant setting (30 minutes by platform default) that can be overridden per branch. You don't send this value at all — it's purely a FleetBridge/tenant configuration concern. At `dispatchAt`, the order moves from `Scheduled` to `PendingRouting` and enters normal routing. ### 14.4 While scheduled A `Scheduled` order can be updated (Section 11) and cancelled (Section 12) freely. Cancellation before dispatch is always platform-side only, since no provider is involved yet. SLA timers don't start until the order actually dispatches — not at creation time. ### 14.5 Example ```json { "externalOrderId": "ORD-3010", "externalBranchId": "MAIN-BRANCH", "scheduledDeliveryAt": "2026-09-23T09:00:00+03:00", "pickup": { "address": "Main Branch", "lat": 31.9021, "lng": 35.2034 }, "dropoff": { "customerName": "Layla Odeh", "customerPhone": "+970598765432", "address": "Al-Masyoun", "lat": 31.9130, "lng": 35.2010 }, "payment": { "method": "Online", "amount": 65, "currency": "ILS" }, "preparationTimeMinutes": 10 } ``` ```json { "platformOrderId": "7f2d1a3b-4c5d-4e6f-8a7b-9c0d1e2f3a4b", "externalOrderId": "ORD-3010", "externalOrderNumber": "ORD-3010", "status": "Scheduled", "branchId": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e", "routingMode": "PriorityFailover", "createdAt": "2026-09-22T14:00:00Z" } ``` --- ## 15. Provider routing and failover ### 15.1 You integrate with FleetBridge, not with a Delivery Provider ``` Order Source │ ▼ FleetBridge Order API ← this document │ ▼ Routing / Orchestration (FleetBridge-internal — provider selection, failover, retries) │ ▼ Delivery Provider ← you never see this layer directly ``` You never get Delivery Provider credentials, never see its webhook format, and never need to know how FleetBridge's internal adapter for a given provider actually works. `delivery.providerCode`/`delivery.providerDeliveryId`, when present, are informational — handy for support conversations and driver-facing tracking links, but not something your integration logic should branch on. ### 15.2 Requesting a specific provider (optional) You can set `deliveryProviderCode` on Create to request a specific Delivery Provider by its FleetBridge-known code (`"cervo"`, say). It's honored only if: - The provider is known and enabled for your tenant. - Manual provider selection is permitted for the branch/tenant. - The provider is currently eligible — enabled, active credentials, allowed for this branch. Unknown or not-enabled code: `400 PROVIDER_NOT_ENABLED`. Real, known provider but the override isn't currently honorable (disabled for this branch, credentials not configured, manual override turned off for your tenant): `400 MANUAL_OVERRIDE_NOT_ALLOWED`. Leave the field out entirely and FleetBridge picks the provider per your tenant's normal routing configuration — the default, and the right choice unless you have a specific reason to override it for a given order. ### 15.3 Failover — what you observe, and what you should do Before pickup, if a Delivery Provider fails — rejects, times out, cancels — FleetBridge may automatically route the order to another eligible one, depending on your tenant's routing mode. Here's what you'll see: ```json { "eventType": "provider.failed", "delivery": { "providerCode": "cervo", "attemptStatus": "CancelledByProvider" }, "failure": { "reasonCode": "NO_DRIVERS_AVAILABLE", "reasonText": "No drivers available", "rawProviderReason": "No couriers nearby" }, "routing": { "nextAction": "RetryingWithNextProvider", "nextProviderCode": "provider_b" } } ``` If a next provider is found, that's followed by the normal `delivery.provider_assigned` / `delivery.sent_to_provider` sequence again, just for the new provider — same `platformOrderId`, same `externalOrderId`. If every eligible provider gets exhausted, `routing.nextAction` becomes `NoProviderAvailable`, you get `order.no_provider_available`, and the order status becomes `NoProviderAvailable` (held, Section 8.2) until a FleetBridge operator steps in. **What you actually need to do**: keep correlating on `platformOrderId`/`externalOrderId`. **Never create a second order because a provider failed** — that's exactly the scenario failover exists to handle transparently for you. Don't key any of your own logic off `providerCode` either, since it can legitimately change mid-order. And failover only happens before pickup — once the order is physically picked up, a delivery problem becomes a Return (Section 18), never a silent re-dispatch to a different provider. --- ## 16. Error model Every business-logic rejection (as opposed to a raw authentication failure, Section 2.5, or malformed-JSON parse failure) comes back in this shape, `content-type: application/problem+json`: ```json { "status": 404, "title": "Not Found", "detail": "No active branch was found for the provided branchId or pickup location.", "errorCode": "BRANCH_NOT_FOUND", "details": { "pickupLat": 31.9021, "pickupLng": 35.2034 }, "correlationId": "0HNOOIIC1J8FA:00000003" } ``` `details` shows up only for some error codes, when FleetBridge has specific structured context to offer. `correlationId` is there whenever available, and worth logging — include it if you ever need to ask FleetBridge support about a specific failed request. ### 16.1 Status code matrix | HTTP | Meaning here | Retryable? | Typical client action | |---|---|---|---| | 400 | Request failed validation (bad field value, bad JSON, missing required field). | No — fix the request first. | Correct the field named in `detail`/`errorCode` and resend with a **new** logical attempt (existing `Idempotency-Key`, if any, is unaffected since no order was created). | | 401 | Missing/invalid/expired/revoked API key. Empty body — see Section 2.5. | No, unless you can fix the credential. | Check the `X-Api-Key` header is present, well-formed, and current. | | 403 | Authenticated, but your Order Source or Tenant cannot act right now (disabled/suspended). | No. | Contact FleetBridge/your tenant admin; this is a configuration state, not a transient fault. | | 404 | The referenced order (or branch, on Create) does not exist, or does not belong to your Order Source. | No. | Re-check the id; if you expected it to exist, look it up again via `GET .../by-external-id/{externalOrderId}`. | | 409 | The request is well-formed, but conflicts with the order's current state (already final, cancellation not supported at this stage). | No — the state itself needs to change first, if it ever will. | Read the order's current status before deciding what to do next; do not blindly retry a 409. | | 429 | Rate limited. See Section 22. | **Yes**, after the delay in `Retry-After`. | Back off and retry; safe to retry a Create with the same `Idempotency-Key`. | | 5xx | An unexpected server-side fault. | Situational — see below. | See 16.2. | ### 16.2 On a 5xx or no response at all Don't blindly retry every 5xx with a brand-new request. For **Create** specifically, always retry with the **same** `Idempotency-Key` (Section 13.6) — that's what makes a 5xx/timeout retry safe, regardless of whether the original request actually succeeded server-side before failing to respond. Update and Cancel are naturally safe to retry as-is (Update re-applies the same patch; Cancel is idempotent, Section 12.3), so a plain retry with backoff works fine there. Use increasing backoff between attempts — 1s, 2s, 5s, say — rather than hammering it in a tight loop. ### 16.3 Full error code reference (Order-Source-relevant) | errorCode | HTTP | Where you'll see it | |---|---|---| | `BRANCH_NOT_FOUND` | 404 | Create — Section 7.5, 19. | | `INVALID_PICKUP_LOCATION` | 400 | Create — bad `pickup.lat`/`lng`. | | `INVALID_DROPOFF_LOCATION` | 400 | Create/Update — bad `dropoff.lat`/`lng`. | | `INVALID_AMOUNT` | 400 | Create/Update — negative `amount`/`deliveryFee`. | | `STRUCTURAL_LIMIT_EXCEEDED` | 400 | Create/Update — string too long, or amount precision/size. | | `INVALID_PREPARATION_TIME` | 400 | Create/Update — negative `preparationTimeMinutes`. | | `INVALID_PAYMENT_METHOD` | 400 | Create/Update — unrecognized `payment.method`. | | `INVALID_SCHEDULED_TIME` | 400 | Create/Update — `scheduledDeliveryAt` too soon. | | `PROVIDER_NOT_ENABLED` | 400 | Create — unknown/disabled `deliveryProviderCode`. | | `MANUAL_OVERRIDE_NOT_ALLOWED` | 400 | Create — provider override not currently honorable. | | `PROVIDER_UPDATE_NOT_SUPPORTED` | 400 | Update — `scheduledDeliveryAt` change rejected post-acceptance. | | `TENANT_SUSPENDED` | 403 | Any call — Section 2.5. | | `ORDER_SOURCE_DISABLED` | 403 | Any call — Section 2.5. | | `INVALID_API_KEY` | 403 | Rare/abnormal caller-context mismatch. | | `ORDER_NOT_FOUND` | 404 | Any order-scoped call — wrong id, or belongs to a different Order Source. | | `ORDER_ALREADY_FINAL` | 409 | Update/Cancel on `Delivered`/`Cancelled`/`Failed`. | | `CANCELLATION_NOT_SUPPORTED_AT_STAGE` | 409 | Cancel — Section 12.1. | | `RATE_LIMIT_EXCEEDED` | 429 | Section 22. | `DUPLICATE_ORDER` and `IMMUTABLE_FIELD` aren't real runtime error codes you'll ever actually receive. Duplicate Create requests get handled transparently by idempotent replay (Section 13), and immutable fields just aren't part of the Update schema in the first place (Section 11.3) — there's nothing to error on. --- ## 17. PaymentMethod ```json "payment": { "method": "Cash", "methodRaw": "cash_on_delivery" } ``` `method` (required on Create) is one of exactly five values: ``` Cash | Card | Online | Wallet | Other ``` `methodRaw` (optional) lets you keep your own original label alongside the normalized value. Handy if your system has a richer payment taxonomy than FleetBridge's five buckets — map whatever doesn't fit cleanly to `Other` and put your real value in `methodRaw`. **`PaymentMethod` is order metadata, nothing more. FleetBridge is not a payment processor.** Setting `method: "Cash"` doesn't make FleetBridge collect, hold, settle, or reconcile any cash-on-delivery funds — that stays entirely between you, your Delivery Provider, and your customer. FleetBridge just passes the value through to the Delivery Provider where its contract accepts it, and reports it back to you. It never affects routing or provider selection. --- ## 18. Returns **Phase 1 has no self-service return action for an Order Source.** If a delivery fails **after** physical pickup — customer unreachable, refuses delivery, address unusable, provider cancels mid-route — FleetBridge doesn't silently re-dispatch to another provider. Normal failover stops at pickup (Section 15.3). Instead, the order enters a return flow that a FleetBridge operator resolves by hand. There's no API call an Order Source can make to trigger, speed up, or resolve a return. What you *can* do: - **Observe.** `orderStatus` becomes `ReturnInProgress` while the return is active, and `Failed` once goods are confirmed back at the branch. If the return itself can't be completed, the order becomes `ManualReviewRequired` (Section 8.2) and needs a human — on FleetBridge's or your tenant's side — to sort it out. - **Subscribe to return webhooks**: `delivery.return_requested`, `delivery.returning_to_origin`, `delivery.returned_to_origin`, `delivery.return_failed` (Section 9.7) keep you posted in real time without polling. - **Re-delivery is a new order.** FleetBridge won't automatically re-attempt delivery of returned goods. If your business needs a second delivery attempt after a return, create a new order for it once the original is resolved. Don't advertise automated return handling to your own end users based on this integration. "FleetBridge notifies us and our operations team follows up" is the honest description of what happens today — stick to that. --- ## 19. Branch / pickup resolution Create resolves the delivery's origin branch in this priority order: 1. **`branchId`**, if supplied — must resolve to an active branch belonging to your tenant, or `404 BRANCH_NOT_FOUND`. 2. Else **`externalBranchId`**, if supplied and non-blank — same active-branch requirement. 3. Else **nearest match by `pickup.lat`/`pickup.lng`** — FleetBridge finds the closest active branch whose configured match radius (a per-branch setting, 100 meters by default) contains your supplied pickup coordinates. If no active branch is within its own radius of the supplied point, `404 BRANCH_NOT_FOUND` (with `pickupLat`/`pickupLng` echoed in `details`). If you already know your FleetBridge `branchId` — most integrations will, once set up — send it. It's the fastest, least ambiguous path. `externalBranchId` is for integrations that track their own store/branch codes instead. The coordinate-based fallback exists for integrations that only know a physical location, not a code, but it's inherently less precise (a pickup point sitting exactly between two branches' radii is genuinely ambiguous). Avoid leaning on it as your primary mechanism if you can help it. --- ## 20. Environments FleetBridge doesn't publish one fixed hostname for every customer. As part of onboarding you get: - A staging Base URL and staging `X-Api-Key`, for development and certification (Section 23). - A production Base URL and production `X-Api-Key`, issued at activation. There's no way to tell "which environment" a key belongs to from its format (Section 2.2) — the Base URL you point at is what determines that. Keep staging and production credentials in clearly separate configuration in your own systems. FleetBridge can't protect you from accidentally pointing a production key at a staging URL, or the reverse. --- ## 21. Versioning - **API major version**: `v1`, in every path (`/api/v1/...`). A breaking change (wire format, authentication, signature algorithm, a required field, or a status/event semantic change) would require a new major version and a distinct migration path — it would never be silently applied to `v1`. - **This document's revision**: `1.1.0`, tracked in the Changelog (`CHANGELOG.md`) alongside this package. - **Additive changes** (a new optional field, a new event type, a new enum value in a non-exhaustively-matched position) may ship within `v1` without notice beyond the changelog. Write your JSON parsing to ignore unknown fields (Section 6) and your event-type handling to tolerate an event type you don't recognize yet (skip it, don't crash), so additive changes never break your integration. - **Removing or renaming a field, changing a field's type, or changing the meaning of an existing status/event** is a breaking change and would ship as a new API major version with its own contract document, never silently inside `v1`. --- ## 22. Rate limits There's currently **one** rate limit on Order Source traffic, and it's intentionally coarse. We're documenting it honestly here rather than implying some business-level quota that doesn't actually exist: - **300 requests per minute, per source IP address**, applied to *any* request carrying an `X-Api-Key` header. Not specific to order creation, not scoped per API key, not configurable per tenant. It exists purely to bound abusive traffic before it reaches authentication, not as a fair-use business quota. - On rejection: `429 Too Many Requests`, a `Retry-After` header (seconds), and the standard error envelope: ``` HTTP/1.1 429 Too Many Requests Retry-After: 42 Content-Type: application/problem+json ``` ```json { "status": 429, "title": "Too Many Requests", "detail": "Too many requests carrying an API key from this address. Please try again later.", "errorCode": "RATE_LIMIT_EXCEEDED", "correlationId": "..." } ``` Respect `Retry-After` instead of guessing your own backoff. If you're behind a shared outbound IP — a NAT gateway, a shared hosting provider — remember this limit is IP-scoped, not key-scoped, and plan capacity with that in mind. There's no separate, higher, per-tenant business quota to request right now. If your real traffic needs exceed this ceiling, talk to FleetBridge directly rather than architecting around a quota that isn't actually part of the contract. Retrying a rate-limited **Create** call is always safe if you reuse the same `Idempotency-Key` (Section 13). --- ## 23. Integration checklist ### Before development - [ ] Staging `X-Api-Key` and staging Base URL received. - [ ] Your callback URL is reachable over HTTPS from the public internet. - [ ] Webhook endpoint registered by FleetBridge and your webhook signing secret captured and stored securely (Section 9.2, 10.2). - [ ] You understand the idempotency-replay semantics in Section 13.3 before writing any retry logic. ### Development - [ ] Authentication works — a valid Create request returns `201` with the expected shape. - [ ] Create works for both immediate and scheduled orders. - [ ] Idempotent replay proven: same `Idempotency-Key`, same body, twice → same `platformOrderId` both times. - [ ] Update works, and you've confirmed a field's `NotApplicable`/`NotSupportedByProvider`/ `PropagationFailed` result doesn't crash your handling. - [ ] Cancel works for at least the "before dispatch" case; you understand the `CANCELLATION_NOT_SUPPORTED_AT_STAGE` case can legitimately happen. - [ ] `GET .../status`, `.../tracking`, `.../tracking-history` all work and null-safe your parsing (most tracking fields are nullable). - [ ] Webhook signature verification implemented and tested against `POST /api/v1/webhooks/test` (Section 9.2), using the **raw** request body (Section 10.4). - [ ] Your webhook handler deduplicates on `eventId` and tolerates out-of-order delivery (Section 9.5). ### Staging certification (Section 24) - [ ] Duplicate Create (same `Idempotency-Key`) returns the original order, not a new one. - [ ] Create with the same `Idempotency-Key` but a **different** body still returns the original, unchanged — confirms you are not relying on a "conflict" error that does not exist. - [ ] A scheduled order validates the minimum lead time and dispatches around the expected time. - [ ] An invalid request (bad coordinates, bad enum, missing required field) returns the expected `400` + `errorCode`. - [ ] Cancellation at each reachable stage behaves as documented in Section 12.1. - [ ] A webhook delivery failure (temporarily break your own endpoint) is retried per the schedule in Section 9.4, and you can observe/request a manual resend through FleetBridge if needed. - [ ] Duplicate webhook delivery does not double-process on your end. - [ ] If your staging environment lets you exercise a failover scenario, confirm you continue correlating correctly on `platformOrderId` across a provider change (Section 15.3). ### Production activation - [ ] Production `X-Api-Key` and production Base URL configured, kept separate from staging (Section 20). - [ ] Production callback URL registered and its own webhook secret captured. - [ ] You have a documented process for what happens if/when FleetBridge needs to rotate your webhook secret (Section 9.10 — you have a 24-hour overlap window, not zero downtime, if you react promptly). - [ ] You know who to contact at FleetBridge for integration issues, and you log `correlationId` from error responses so a support conversation can reference a specific failed request. --- ## 24. Certification / self-test Check `certification/README.md` in this package for a runnable checklist and script (`certification/certify.py`) that exercises this whole contract — Create, idempotent replay, Update, Cancel, validation errors, and optionally webhook signature verification against a local receiver — using your own staging credentials. No access to FleetBridge's source code or infrastructure required; it just calls the public HTTP contract described in this document, and prints a pass/fail report per checklist item plus a machine-readable JSON result file you can attach to a certification request. --- ## 25. Changelog See `CHANGELOG.md` in this package.