{"openapi":"3.1.0","info":{"title":"Bob Box selector middleware","version":"1.0.0","description":"Versioned /v1 contract. Live-only middleware; unconfigured shipment integration returns 501; no capacity reservation. Search matches location address text, not arbitrary address geocoding. Latitude and longitude must be supplied together. Pagination is offset based and may change on refresh. Unknown fields are rejected. Breaking changes require a new major URL version."},"servers":[{"url":"http://localhost:3000","description":"Local development"}],"components":{"securitySchemes":{"ServerKey":{"type":"http","scheme":"bearer","description":"Unique merchant middleware API key; never expose in browsers. The server resolves the merchant's Shiplogic credentials/account from its registry."}}},"paths":{"/api-specification.json":{"get":{"operationId":"specification","summary":"Retrieve the API specification","parameters":[],"security":[],"responses":{"200":{"description":"Success","headers":{"X-Correlation-Id":{"schema":{"type":"string"},"description":"Server-generated request ID"}},"content":{"application/json":{"schema":{"type":"object","properties":{"openapi":{"type":"string","const":"3.1.0"}},"required":["openapi"],"additionalProperties":{}},"example":{"openapi":"3.1.0","info":{"title":"Bob Box selector middleware","version":"1.0.0"},"paths":{}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"403":{"description":"Origin or tenant forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"413":{"description":"Body too large","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"415":{"description":"Unsupported media type","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"422":{"description":"Invalid selection","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until rate limit window ends"}}},"500":{"description":"Internal failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"501":{"description":"Vendor capability unconfirmed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"502":{"description":"Upstream contract error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"503":{"description":"Upstream unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}}}}},"/health":{"get":{"operationId":"health","summary":"Liveness; does not certify upstream connectivity","parameters":[],"security":[],"responses":{"200":{"description":"Success","headers":{"X-Correlation-Id":{"schema":{"type":"string"},"description":"Server-generated request ID"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded"]},"mode":{"type":"string","const":"live"}},"required":["status","mode"],"additionalProperties":false},"example":{"status":"ok","mode":"live"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"403":{"description":"Origin or tenant forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"413":{"description":"Body too large","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"415":{"description":"Unsupported media type","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"422":{"description":"Invalid selection","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until rate limit window ends"}}},"500":{"description":"Internal failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"501":{"description":"Vendor capability unconfirmed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"502":{"description":"Upstream contract error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"503":{"description":"Upstream unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}}}}},"/ready":{"get":{"operationId":"ready","summary":"Readiness of configured location adapters","parameters":[],"security":[],"responses":{"200":{"description":"Success","headers":{"X-Correlation-Id":{"schema":{"type":"string"},"description":"Server-generated request ID"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded"]},"mode":{"type":"string","const":"live"}},"required":["status","mode"],"additionalProperties":false},"example":{"status":"ok","mode":"live"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"403":{"description":"Origin or tenant forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"413":{"description":"Body too large","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"415":{"description":"Unsupported media type","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"422":{"description":"Invalid selection","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until rate limit window ends"}}},"500":{"description":"Internal failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"501":{"description":"Vendor capability unconfirmed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"502":{"description":"Upstream contract error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"503":{"description":"Location cache is unavailable or stale","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded"]},"mode":{"type":"string","const":"live"}},"required":["status","mode"],"additionalProperties":false},"example":{"status":"degraded","mode":"live"}}}}}}},"/v1/locations":{"get":{"operationId":"locations","summary":"Search location address fields; offset pagination; coordinates enable distance sorting","parameters":[{"name":"X-Provider-Id","in":"header","required":false,"schema":{"type":"integer","enum":[9,39]},"description":"9 Internet Express or 39 Citi Sprint. Alternatively use providerId in query/body. Conflicting selectors are rejected. Merchant identity is derived from the authentication key; the selected courier must match that customer's connection."},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":150}},{"name":"providerId","in":"query","required":false,"schema":{"type":"number"}},{"name":"latitude","in":"query","required":false,"schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"longitude","in":"query","required":false,"schema":{"type":"number","minimum":-180,"maximum":180}},{"name":"limit","in":"query","required":false,"schema":{"default":20,"type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":100000}}],"security":[],"responses":{"200":{"description":"Success","headers":{"X-Correlation-Id":{"schema":{"type":"string"},"description":"Server-generated request ID"}},"content":{"application/json":{"schema":{"type":"object","properties":{"providerId":{"anyOf":[{"type":"number","const":9},{"type":"number","const":39}]},"providerName":{"type":"string","enum":["Internet Express","Citi Sprint"]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^bobbox:[0-9]+$"},"sourceId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"name":{"type":"string","minLength":1,"maxLength":255},"address":{"type":"string","minLength":1,"maxLength":255},"street":{"type":"string","minLength":1,"maxLength":255},"suburb":{"type":"string","maxLength":255},"city":{"type":"string","minLength":1,"maxLength":255},"province":{"type":"string","minLength":1,"maxLength":255},"postalCode":{"type":"string","minLength":1,"maxLength":255},"country":{"type":"string","const":"ZA"},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"hours":{"type":"string","maxLength":2000},"description":{"type":"string","maxLength":2000},"status":{"type":"string","const":"active"},"source":{"type":"string","enum":["mock","bobbox"]},"distanceKm":{"type":"number","minimum":0}},"required":["id","sourceId","name","address","street","suburb","city","province","postalCode","country","latitude","longitude","status","source"],"additionalProperties":false}},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextOffset":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"lastUpdated":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"stale":{"type":"boolean"},"source":{"type":"string","enum":["mock","bobbox"]}},"required":["providerId","providerName","items","total","nextOffset","lastUpdated","stale","source"],"additionalProperties":false},"example":{"providerId":9,"providerName":"Internet Express","items":[{"id":"bobbox:101","sourceId":101,"name":"Demo · Menlyn collection point","address":"180 Amarand Avenue, Waterkloof Glen, Pretoria, 0063","street":"180 Amarand Avenue","suburb":"Waterkloof Glen","city":"Pretoria","province":"Gauteng","postalCode":"0063","country":"ZA","latitude":-25.78506,"longitude":28.28117,"hours":"Demo hours: Monday–Friday, 09:00–17:00","description":"Synthetic demonstration location. Do not use for a real delivery.","status":"active","source":"mock"}],"total":1,"nextOffset":null,"lastUpdated":"2026-09-28T10:00:00.000Z","stale":false,"source":"mock"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"403":{"description":"Origin or tenant forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"413":{"description":"Body too large","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"415":{"description":"Unsupported media type","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"422":{"description":"Invalid selection","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until rate limit window ends"}}},"500":{"description":"Internal failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"501":{"description":"Vendor capability unconfirmed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"502":{"description":"Upstream contract error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"503":{"description":"Upstream unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}}}},"options":{"operationId":"widgetPreflight0","summary":"Public location CORS preflight; no authentication","security":[],"parameters":[{"name":"Origin","in":"header","required":false,"schema":{"type":"string","format":"uri"}}],"responses":{"204":{"description":"Public browser access","headers":{"Access-Control-Allow-Origin":{"schema":{"type":"string"}},"Access-Control-Allow-Headers":{"schema":{"type":"string"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/selections/validate":{"post":{"operationId":"validate","summary":"Refresh and validate an active location; does not reserve capacity","parameters":[{"name":"X-Provider-Id","in":"header","required":false,"schema":{"type":"integer","enum":[9,39]},"description":"9 Internet Express or 39 Citi Sprint. Alternatively use providerId in query/body. Conflicting selectors are rejected. Merchant identity is derived from the authentication key; the selected courier must match that customer's connection."}],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"locationId":{"type":"string","pattern":"^bobbox:[0-9]+$"},"providerId":{"anyOf":[{"type":"number","const":9},{"type":"number","const":39}]}},"required":["locationId"],"additionalProperties":false},"example":{"locationId":"bobbox:101"}}}},"responses":{"200":{"description":"Success","headers":{"X-Correlation-Id":{"schema":{"type":"string"},"description":"Server-generated request ID"}},"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"1"},"tenantId":{"type":"string","enum":["internet-express","citi-sprint"]},"providerId":{"anyOf":[{"type":"number","const":9},{"type":"number","const":39}]},"providerName":{"type":"string","enum":["Internet Express","Citi Sprint"]},"location":{"type":"object","properties":{"id":{"type":"string","pattern":"^bobbox:[0-9]+$"},"sourceId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"name":{"type":"string","minLength":1,"maxLength":255},"address":{"type":"string","minLength":1,"maxLength":255},"street":{"type":"string","minLength":1,"maxLength":255},"suburb":{"type":"string","maxLength":255},"city":{"type":"string","minLength":1,"maxLength":255},"province":{"type":"string","minLength":1,"maxLength":255},"postalCode":{"type":"string","minLength":1,"maxLength":255},"country":{"type":"string","const":"ZA"},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"hours":{"type":"string","maxLength":2000},"description":{"type":"string","maxLength":2000},"status":{"type":"string","const":"active"},"source":{"type":"string","enum":["mock","bobbox"]},"distanceKm":{"type":"number","minimum":0}},"required":["id","sourceId","name","address","street","suburb","city","province","postalCode","country","latitude","longitude","status","source"],"additionalProperties":false},"validatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"reservationCreated":{"type":"boolean","const":false}},"required":["version","tenantId","providerId","providerName","location","validatedAt","reservationCreated"],"additionalProperties":false},"example":{"version":"1","providerName":"Internet Express","tenantId":"internet-express","providerId":9,"location":{"id":"bobbox:101","sourceId":101,"name":"Demo · Menlyn collection point","address":"180 Amarand Avenue, Waterkloof Glen, Pretoria, 0063","street":"180 Amarand Avenue","suburb":"Waterkloof Glen","city":"Pretoria","province":"Gauteng","postalCode":"0063","country":"ZA","latitude":-25.78506,"longitude":28.28117,"hours":"Demo hours: Monday–Friday, 09:00–17:00","description":"Synthetic demonstration location. Do not use for a real delivery.","status":"active","source":"mock"},"validatedAt":"2026-09-28T10:00:00.000Z","reservationCreated":false}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"403":{"description":"Origin or tenant forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"413":{"description":"Body too large","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"415":{"description":"Unsupported media type","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"422":{"description":"Invalid selection","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until rate limit window ends"}}},"500":{"description":"Internal failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"501":{"description":"Vendor capability unconfirmed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"502":{"description":"Upstream contract error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"503":{"description":"Upstream unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}}}},"options":{"operationId":"widgetPreflight1","summary":"Public location CORS preflight; no authentication","security":[],"parameters":[{"name":"Origin","in":"header","required":false,"schema":{"type":"string","format":"uri"}}],"responses":{"204":{"description":"Public browser access","headers":{"Access-Control-Allow-Origin":{"schema":{"type":"string"}},"Access-Control-Allow-Headers":{"schema":{"type":"string"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/rates":{"post":{"operationId":"rates","summary":"Discover the live Shiplogic locker and return pickup-point services/prices with a ten-minute checkout quote","parameters":[{"name":"X-Provider-Id","in":"header","required":false,"schema":{"type":"integer","enum":[9,39]},"description":"9 Internet Express or 39 Citi Sprint. Alternatively use providerId in query/body. Conflicting selectors are rejected. Merchant identity is derived from the authentication key; the selected courier must match that customer's connection."}],"security":[{"ServerKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"providerId":{"anyOf":[{"type":"number","const":9},{"type":"number","const":39}]},"locationId":{"type":"string","pattern":"^bobbox:[0-9]+$"},"collectionAddress":{"type":"object","properties":{"street_address":{"type":"string","minLength":1,"maxLength":255},"local_area":{"type":"string","minLength":1,"maxLength":255},"city":{"type":"string","minLength":1,"maxLength":255},"zone":{"type":"string","minLength":1,"maxLength":255},"country":{"type":"string","const":"ZA"},"code":{"type":"string","minLength":1,"maxLength":255},"company":{"type":"string","maxLength":255},"type":{"default":"business","type":"string","enum":["business","residential"]}},"required":["street_address","local_area","city","zone","country","code"],"additionalProperties":false},"parcel":{"type":"object","properties":{"lengthCm":{"type":"number","exclusiveMinimum":0,"maximum":300},"widthCm":{"type":"number","exclusiveMinimum":0,"maximum":300},"heightCm":{"type":"number","exclusiveMinimum":0,"maximum":300},"weightKg":{"type":"number","exclusiveMinimum":0,"maximum":100}},"required":["lengthCm","widthCm","heightCm","weightKg"],"additionalProperties":false}},"required":["locationId","collectionAddress","parcel"],"additionalProperties":false},"example":{"providerId":9,"locationId":"bobbox:101","collectionAddress":{"street_address":"1 Test Street","local_area":"Gardens","city":"Cape Town","zone":"Western Cape","country":"ZA","code":"8001"},"parcel":{"lengthCm":20,"widthCm":10,"heightCm":5,"weightKg":1}}}}},"responses":{"200":{"description":"Success","headers":{"X-Correlation-Id":{"schema":{"type":"string"},"description":"Server-generated request ID"}},"content":{"application/json":{"schema":{"type":"object","properties":{"merchantId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"quoteId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"providerId":{"anyOf":[{"type":"number","const":9},{"type":"number","const":39}]},"locationId":{"type":"string","pattern":"^bobbox:[0-9]+$"},"pickupPointId":{"type":"string","minLength":1,"maxLength":255},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"rates":{"type":"array","items":{"type":"object","properties":{"serviceLevelCode":{"type":"string","minLength":1,"maxLength":255},"serviceLevelName":{"type":"string","minLength":1,"maxLength":255},"amount":{"type":"number","minimum":0},"currency":{"type":"string","const":"ZAR"}},"required":["serviceLevelCode","serviceLevelName","amount","currency"],"additionalProperties":false}},"reservationCreated":{"type":"boolean","const":false}},"required":["quoteId","providerId","locationId","pickupPointId","expiresAt","rates","reservationCreated"],"additionalProperties":false},"example":{"quoteId":"0bb895b3-445a-48f6-ad16-11d0b1f203ba","providerId":9,"locationId":"bobbox:101","pickupPointId":"example-pickup-point","expiresAt":"2026-10-16T10:10:00.000Z","reservationCreated":false,"rates":[{"serviceLevelCode":"DEMO","serviceLevelName":"Example delivery","amount":55,"currency":"ZAR"}]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"403":{"description":"Origin or tenant forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"413":{"description":"Body too large","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"415":{"description":"Unsupported media type","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"422":{"description":"Invalid selection","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until rate limit window ends"}}},"500":{"description":"Internal failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"501":{"description":"Vendor capability unconfirmed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"502":{"description":"Upstream contract error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"503":{"description":"Upstream unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}}}}},"/v1/shipments":{"post":{"operationId":"create","summary":"Book the selected quoted service after revalidating the live locker mapping; live Shiplogic requires quoteId","parameters":[{"name":"X-Provider-Id","in":"header","required":false,"schema":{"type":"integer","enum":[9,39]},"description":"9 Internet Express or 39 Citi Sprint. Alternatively use providerId in query/body. Conflicting selectors are rejected. Merchant identity is derived from the authentication key; the selected courier must match that customer's connection."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"},"example":"checkout-order-123","description":"Retained indefinitely per authenticated merchant and provider. Same canonical body replays the saved result; different body returns 409. Saved attempts are never automatically resubmitted, including rejections."}],"security":[{"ServerKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"providerId":{"anyOf":[{"type":"number","const":9},{"type":"number","const":39}]},"locationId":{"type":"string","pattern":"^bobbox:[0-9]+$"},"customerReference":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,80}$"},"collectionAddress":{"type":"object","properties":{"street_address":{"type":"string","minLength":1,"maxLength":255},"local_area":{"type":"string","minLength":1,"maxLength":255},"city":{"type":"string","minLength":1,"maxLength":255},"zone":{"type":"string","minLength":1,"maxLength":255},"country":{"type":"string","const":"ZA"},"code":{"type":"string","minLength":1,"maxLength":255},"company":{"type":"string","maxLength":255},"type":{"default":"business","type":"string","enum":["business","residential"]}},"required":["street_address","local_area","city","zone","country","code"],"additionalProperties":false},"collectionContact":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"email":{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"mobile_number":{"type":"string","pattern":"^\\+?[0-9 ()-]{7,30}$"}},"required":["name","email"],"additionalProperties":false},{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"email":{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"mobile_number":{"type":"string","pattern":"^\\+?[0-9 ()-]{7,30}$"}},"required":["name","mobile_number"],"additionalProperties":false}],"description":"At least email or mobile_number is required"},"deliveryContact":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"email":{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"mobile_number":{"type":"string","pattern":"^\\+?[0-9 ()-]{7,30}$"}},"required":["name","email"],"additionalProperties":false},{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"email":{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"mobile_number":{"type":"string","pattern":"^\\+?[0-9 ()-]{7,30}$"}},"required":["name","mobile_number"],"additionalProperties":false}],"description":"At least email or mobile_number is required"},"serviceLevelCode":{"type":"string","minLength":1,"maxLength":255},"quoteId":{"description":"Required for live Shiplogic booking; returned by POST /v1/rates","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"parcel":{"type":"object","properties":{"lengthCm":{"type":"number","exclusiveMinimum":0,"maximum":300},"widthCm":{"type":"number","exclusiveMinimum":0,"maximum":300},"heightCm":{"type":"number","exclusiveMinimum":0,"maximum":300},"weightKg":{"type":"number","exclusiveMinimum":0,"maximum":100}},"required":["lengthCm","widthCm","heightCm","weightKg"],"additionalProperties":false}},"required":["locationId","customerReference","collectionAddress","collectionContact","deliveryContact","serviceLevelCode","parcel"],"additionalProperties":false},"example":{"locationId":"bobbox:101","providerId":9,"customerReference":"order-123","collectionAddress":{"street_address":"1 Test Street","local_area":"Gardens","city":"Cape Town","zone":"Western Cape","country":"ZA","code":"8001"},"collectionContact":{"name":"Sender","email":"sender@example.com"},"deliveryContact":{"name":"Receiver","email":"receiver@example.com"},"serviceLevelCode":"DEMO","quoteId":"0bb895b3-445a-48f6-ad16-11d0b1f203ba","parcel":{"lengthCm":20,"widthCm":10,"heightCm":5,"weightKg":1}}}}},"responses":{"201":{"description":"Success","headers":{"X-Correlation-Id":{"schema":{"type":"string"},"description":"Server-generated request ID"},"Idempotent-Replayed":{"schema":{"type":"string","enum":["true"]},"description":"Present on duplicate submission"}},"content":{"application/json":{"schema":{"type":"object","properties":{"merchantId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"tenantId":{"type":"string","enum":["internet-express","citi-sprint"]},"providerId":{"anyOf":[{"type":"number","const":9},{"type":"number","const":39}]},"locationId":{"type":"string","pattern":"^bobbox:[0-9]+$"},"status":{"type":"string","enum":["pending","succeeded","rejected","unknown"]},"mode":{"type":"string","const":"live"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"upstreamReference":{"type":"string"},"upstreamShipmentId":{"type":"string","maxLength":255},"upstreamShipmentStatus":{"type":"string","maxLength":80},"upstreamStatusCode":{"type":"integer","minimum":400,"maximum":599},"errorCode":{"type":"string"},"message":{"type":"string"}},"required":["id","tenantId","providerId","locationId","status","mode","createdAt"],"additionalProperties":false},"example":{"id":"98e4c68e-9de1-4e7e-9457-c51e7f35e27f","tenantId":"internet-express","providerId":9,"locationId":"bobbox:101","status":"succeeded","mode":"live","createdAt":"2026-09-28T10:00:00.000Z","upstreamReference":"example-courier-reference"}}}},"202":{"description":"Existing pending or unknown attempt. Poll result; do not resend with a new key.","headers":{"X-Correlation-Id":{"schema":{"type":"string"},"description":"Server-generated request ID"},"Idempotent-Replayed":{"schema":{"type":"string","enum":["true"]},"description":"Present on duplicate submission"}},"content":{"application/json":{"schema":{"type":"object","properties":{"merchantId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"tenantId":{"type":"string","enum":["internet-express","citi-sprint"]},"providerId":{"anyOf":[{"type":"number","const":9},{"type":"number","const":39}]},"locationId":{"type":"string","pattern":"^bobbox:[0-9]+$"},"status":{"type":"string","enum":["pending","succeeded","rejected","unknown"]},"mode":{"type":"string","const":"live"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"upstreamReference":{"type":"string"},"upstreamShipmentId":{"type":"string","maxLength":255},"upstreamShipmentStatus":{"type":"string","maxLength":80},"upstreamStatusCode":{"type":"integer","minimum":400,"maximum":599},"errorCode":{"type":"string"},"message":{"type":"string"}},"required":["id","tenantId","providerId","locationId","status","mode","createdAt"],"additionalProperties":false},"example":{"id":"98e4c68e-9de1-4e7e-9457-c51e7f35e27f","tenantId":"internet-express","providerId":9,"locationId":"bobbox:101","status":"succeeded","mode":"live","createdAt":"2026-09-28T10:00:00.000Z","upstreamReference":"example-courier-reference"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"403":{"description":"Origin or tenant forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"413":{"description":"Body too large","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"415":{"description":"Unsupported media type","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"422":{"description":"Invalid location/mapping/service (ErrorBody), or durable Shiplogic rejection (IntegrationResult with status rejected). Inspect error or status to distinguish.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},{"type":"object","properties":{"merchantId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"tenantId":{"type":"string","enum":["internet-express","citi-sprint"]},"providerId":{"anyOf":[{"type":"number","const":9},{"type":"number","const":39}]},"locationId":{"type":"string","pattern":"^bobbox:[0-9]+$"},"status":{"type":"string","enum":["pending","succeeded","rejected","unknown"]},"mode":{"type":"string","const":"live"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"upstreamReference":{"type":"string"},"upstreamShipmentId":{"type":"string","maxLength":255},"upstreamShipmentStatus":{"type":"string","maxLength":80},"upstreamStatusCode":{"type":"integer","minimum":400,"maximum":599},"errorCode":{"type":"string"},"message":{"type":"string"}},"required":["id","tenantId","providerId","locationId","status","mode","createdAt"],"additionalProperties":false}]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until rate limit window ends"}}},"500":{"description":"Internal failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"501":{"description":"Vendor capability unconfirmed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"502":{"description":"Upstream contract error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"503":{"description":"Upstream unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}}}}},"/v1/integrations/{id}":{"get":{"operationId":"result","summary":"Retrieve the durable tenant-scoped integration result","parameters":[{"name":"X-Provider-Id","in":"header","required":false,"schema":{"type":"integer","enum":[9,39]},"description":"9 Internet Express or 39 Citi Sprint. Alternatively use providerId in query/body. Conflicting selectors are rejected. Merchant identity is derived from the authentication key; the selected courier must match that customer's connection."},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"security":[{"ServerKey":[]}],"responses":{"200":{"description":"Success","headers":{"X-Correlation-Id":{"schema":{"type":"string"},"description":"Server-generated request ID"}},"content":{"application/json":{"schema":{"type":"object","properties":{"merchantId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"tenantId":{"type":"string","enum":["internet-express","citi-sprint"]},"providerId":{"anyOf":[{"type":"number","const":9},{"type":"number","const":39}]},"locationId":{"type":"string","pattern":"^bobbox:[0-9]+$"},"status":{"type":"string","enum":["pending","succeeded","rejected","unknown"]},"mode":{"type":"string","const":"live"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"upstreamReference":{"type":"string"},"upstreamShipmentId":{"type":"string","maxLength":255},"upstreamShipmentStatus":{"type":"string","maxLength":80},"upstreamStatusCode":{"type":"integer","minimum":400,"maximum":599},"errorCode":{"type":"string"},"message":{"type":"string"}},"required":["id","tenantId","providerId","locationId","status","mode","createdAt"],"additionalProperties":false},"example":{"id":"98e4c68e-9de1-4e7e-9457-c51e7f35e27f","tenantId":"internet-express","providerId":9,"locationId":"bobbox:101","status":"succeeded","mode":"live","createdAt":"2026-09-28T10:00:00.000Z","upstreamReference":"example-courier-reference"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"403":{"description":"Origin or tenant forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"413":{"description":"Body too large","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"415":{"description":"Unsupported media type","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"422":{"description":"Invalid selection","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until rate limit window ends"}}},"500":{"description":"Internal failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"501":{"description":"Vendor capability unconfirmed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"502":{"description":"Upstream contract error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"503":{"description":"Upstream unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}}}}},"/v1/shipments/{id}":{"patch":{"operationId":"update","summary":"Reserved; returns 501 until pickup-point updates are confirmed","parameters":[{"name":"X-Provider-Id","in":"header","required":false,"schema":{"type":"integer","enum":[9,39]},"description":"9 Internet Express or 39 Citi Sprint. Alternatively use providerId in query/body. Conflicting selectors are rejected. Merchant identity is derived from the authentication key; the selected courier must match that customer's connection."},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"security":[{"ServerKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"locationId":{"type":"string","pattern":"^bobbox:[0-9]+$"},"providerId":{"anyOf":[{"type":"number","const":9},{"type":"number","const":39}]}},"required":["locationId"],"additionalProperties":false},"example":{"locationId":"bobbox:101"}}}},"responses":{"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"403":{"description":"Origin or tenant forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"413":{"description":"Body too large","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"415":{"description":"Unsupported media type","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"422":{"description":"Invalid selection","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until rate limit window ends"}}},"500":{"description":"Internal failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"501":{"description":"Not implemented; requires vendor confirmation","headers":{"X-Correlation-Id":{"schema":{"type":"string"},"description":"Server-generated request ID"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"UPDATE_UNCONFIRMED","message":"Changing a booked Bob Box requires courier confirmation; update is disabled","correlationId":"request-id"}}}}},"502":{"description":"Upstream contract error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}},"503":{"description":"Upstream unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlationId":{"type":"string"}},"required":["code","message","correlationId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"example":{"error":{"code":"LOCATIONS_UNAVAILABLE","message":"Location data is temporarily unavailable","correlationId":"example-request-id"}}}}}}}}}}