{ "openapi": "3.1.0", "info": { "title": "TTISG API — Travel and Transport Interconnect Systems Gateway", "version": "1.0.0-demo", "description": "Local integration contract for agency and carrier website backends. ICPP renders HTML only on the HTTP server. No DB access from webpages. Demo authentication administration, billing, payments and physical scans are simulated; production HTTPS, staff identity, payment integration and operational qualification remain pending." }, "servers": [ { "url": "http://127.0.0.1:8099", "description": "Local development only" } ], "security": [ { "BearerKey": [] } ], "paths": { "/api/v1/catalog": { "get": { "summary": "List permitted transport offers", "description": "Agency or carrier API key required. Agency subscriptions and per-carrier grants are enforced.", "operationId": "list_permitted_transport_offers", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "agency": { "type": "integer" }, "offers": { "type": "array", "items": { "type": "object" } } }, "required": [] } } } }, "400": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/shipments/quotes": { "post": { "summary": "Quote shipment with sender and recipient", "description": "Agency or carrier API key required. Agency subscriptions and per-carrier grants are enforced.", "operationId": "quote_shipment_with_sender_and_recipient", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" }, "description": "Required here or in body key/eventKey; reuse only for identical requests." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Journey" } } } }, "400": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentQuote" } } } } } }, "/api/v1/shipments/{key}": { "get": { "summary": "Read authorized shipment status and case records", "description": "Agency or carrier API key required. Agency subscriptions and per-carrier grants are enforced.", "operationId": "read_authorized_shipment_status_and_case_records", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/shipments/{key}/tracking": { "get": { "summary": "Read current package custody and delivery records", "description": "Agency or carrier API key required. Agency subscriptions and per-carrier grants are enforced.", "operationId": "read_current_package_custody_and_delivery_records", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/shipments/{key}/delivery-confirmations": { "get": { "summary": "List shipment delivery confirmations", "description": "Agency or carrier API key required. Agency subscriptions and per-carrier grants are enforced.", "operationId": "list_shipment_delivery_confirmations", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Confirm package delivery with proof", "description": "Carrier API key with carrier:manage scope required. The key determines the operating carrier.", "operationId": "confirm_package_delivery_with_proof", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryConfirmation" } } } } } }, "/api/v1/shipments/{key}/claims": { "get": { "summary": "List shipment loss and damage claims", "description": "Agency or carrier API key required. Agency subscriptions and per-carrier grants are enforced.", "operationId": "list_shipment_loss_and_damage_claims", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "File a package loss or damage claim", "description": "Agency or carrier API key required. Agency subscriptions and per-carrier grants are enforced.", "operationId": "file_a_package_loss_or_damage_claim", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParcelClaim" } } } } } }, "/api/v1/claims/{key}": { "get": { "summary": "Read an authorized package claim", "description": "Agency or carrier API key required. Agency subscriptions and per-carrier grants are enforced.", "operationId": "read_an_authorized_package_claim", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/claims/{key}/review": { "post": { "summary": "Investigate approve or reject a package claim", "description": "Carrier API key with carrier:manage scope required. The key determines the operating carrier.", "operationId": "investigate_approve_or_reject_a_package_claim", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimReview" } } } } } }, "/api/v1/claims/{key}/evidence": { "post": { "summary": "Add claimant evidence and reopen a rejected case", "description": "Agency or carrier API key required. Agency subscriptions and per-carrier grants are enforced.", "operationId": "add_claimant_evidence_and_reopen_a_rejected_case", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimEvidence" } } } } } }, "/api/v1/claims/{key}/settle": { "post": { "summary": "Accept and settle a test claim award", "description": "Agency or carrier API key required. Agency subscriptions and per-carrier grants are enforced.", "operationId": "accept_and_settle_a_test_claim_award", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceExecute" } } } } } }, "/api/v1/quotes": { "post": { "summary": "Quote travel or shipment", "description": "Agency or carrier API key required. Agency subscriptions and per-carrier grants are enforced.", "operationId": "quote_travel_or_shipment", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" }, "description": "Required here or in body key/eventKey; reuse only for identical requests." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Journey" } } } }, "400": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" } } } } } }, "/api/v1/bookings": { "post": { "summary": "Confirm all quoted legs", "description": "Agency or carrier API key required. Agency subscriptions and per-carrier grants are enforced.", "operationId": "confirm_all_quoted_legs", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Journey" } } } }, "400": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingRequest" } } } } }, "get": { "summary": "List visible quotes and bookings", "description": "Agency or carrier API key required. Agency subscriptions and per-carrier grants are enforced.", "operationId": "list_visible_quotes_and_bookings", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "bookings": { "type": "array", "items": { "$ref": "#/components/schemas/Journey" } }, "total": { "type": "integer" }, "offset": { "type": "integer" }, "limit": { "type": "integer" } }, "required": [] } } } }, "400": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/bookings/{key}": { "get": { "summary": "Read a journey", "description": "Agency or carrier API key required. Agency subscriptions and per-carrier grants are enforced.", "operationId": "read_a_journey", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Journey" } } } }, "400": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/bookings/{key}/servicing": { "get": { "summary": "List ticket servicing requests", "description": "Agency or carrier API key required. Agency subscriptions and per-carrier grants are enforced.", "operationId": "list_ticket_servicing_requests", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Request ticket servicing", "description": "Agency or carrier API key required. Agency subscriptions and per-carrier grants are enforced.", "operationId": "request_ticket_servicing", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceRequest" } } } } } }, "/api/v1/servicing/{key}": { "get": { "summary": "Read a servicing request", "description": "Agency or carrier API key required. Agency subscriptions and per-carrier grants are enforced.", "operationId": "read_a_servicing_request", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/servicing/{key}/decision": { "post": { "summary": "Approve or reject own carrier servicing", "description": "Carrier API key with carrier:manage scope required. The key determines the operating carrier.", "operationId": "approve_or_reject_own_carrier_servicing", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceDecision" } } } } } }, "/api/v1/servicing/{key}/execute": { "post": { "summary": "Accept fees and execute ticket servicing", "description": "Agency or carrier API key required. Agency subscriptions and per-carrier grants are enforced.", "operationId": "accept_fees_and_execute_ticket_servicing", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceExecute" } } } } } }, "/api/v1/servicing/{key}/withdraw": { "post": { "summary": "Withdraw an unexecuted servicing request", "description": "Agency or carrier API key required. Agency subscriptions and per-carrier grants are enforced.", "operationId": "withdraw_an_unexecuted_servicing_request", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceEmpty" } } } } } }, "/api/v1/bookings/{key}/tracking": { "get": { "summary": "Read bag and package custody history", "description": "Agency or carrier API key required. Agency subscriptions and per-carrier grants are enforced.", "operationId": "read_bag_and_package_custody_history", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "object" } }, "events": { "type": "array", "items": { "type": "object" } } }, "required": [] } } } }, "400": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/quotes/{key}/approval": { "post": { "summary": "Approve own operating legs", "description": "Carrier API key with carrier:manage scope required. The key determines the operating carrier.", "operationId": "approve_own_operating_legs", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Journey" } } } }, "400": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] } } } } } }, "/api/v1/bookings/{key}/tracking-events": { "post": { "summary": "Record authenticated handling event", "description": "Carrier API key with carrier:manage scope required. The key determines the operating carrier.", "operationId": "record_authenticated_handling_event", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" }, "description": "Required here or in body key/eventKey; reuse only for identical requests." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Scan" } } } } } }, "/api/v1/carrier/pricing-policies": { "get": { "summary": "List own pricing policies", "description": "Carrier API key with carrier:manage scope required. The key determines the operating carrier.", "operationId": "list_own_pricing_policies", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create or update own pricing policy", "description": "Carrier API key with carrier:manage scope required. The key determines the operating carrier.", "operationId": "create_or_update_own_pricing_policy", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingPolicy" } } } } } }, "/api/v1/carrier/agency-agreements": { "post": { "summary": "Grant or revoke agency selling access", "description": "Carrier API key with carrier:manage scope required. The key determines the operating carrier.", "operationId": "grant_or_revoke_agency_selling_access", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgencyAgreement" } } } } } }, "/api/v1/carrier/selling-agreements": { "post": { "summary": "Allow another carrier to sell own services", "description": "Carrier API key with carrier:manage scope required. The key determines the operating carrier.", "operationId": "allow_another_carrier_to_sell_own_services", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellingAgreement" } } } } } } }, "components": { "securitySchemes": { "BearerKey": { "type": "http", "scheme": "bearer", "description": "Opaque API key issued to a subscribed agency or carrier website backend; keep out of browser HTML." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ] }, "Parcel": { "type": "object", "properties": { "type": { "enum": [ "LETTER", "PARCEL", "HEAVY" ] }, "kg": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000 }, "cm": { "type": "array", "items": { "type": "number", "exclusiveMinimum": 0, "maximum": 500 }, "minItems": 3, "maxItems": 3 } }, "required": [ "type", "kg", "cm" ] }, "QuoteRequest": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" }, "kind": { "enum": [ "TRAVEL", "SHIPMENT" ], "default": "TRAVEL" }, "services": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 24, "uniqueItems": true }, "ticketType": { "enum": [ "ONE_WAY", "RETURN" ], "default": "ONE_WAY" }, "bags": { "type": "array", "items": { "type": "number", "exclusiveMinimum": 0, "maximum": 32 }, "maxItems": 3 }, "automatic": { "type": "boolean" }, "parcels": { "type": "array", "items": { "$ref": "#/components/schemas/Parcel" }, "minItems": 1, "maxItems": 20 }, "code": { "type": "string", "maxLength": 30 }, "seats": { "type": "object", "description": "Optional travel seat selection keyed by service ID. Omit a service for free automatic assignment at confirmation. Selected-seat fees appear in quote lines. Seats are not held by a quote.", "additionalProperties": { "type": "string", "maxLength": 8 } }, "original": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$", "description": "Optional existing ticket reference for an authorized replacement quote. Preserves original seller, traveller, baggage and ticket type. Confirm through a TRANSFER request, not ordinary checkout." } }, "required": [ "services" ], "allOf": [ { "if": { "properties": { "kind": { "const": "SHIPMENT" } }, "required": [ "kind" ] }, "then": { "required": [ "parcels" ] }, "else": { "required": [ "bags", "automatic" ] } } ] }, "Journey": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" }, "kind": { "enum": [ "TRAVEL", "SHIPMENT" ] }, "ticketType": { "enum": [ "ONE_WAY", "RETURN", "SHIPMENT" ] }, "seller": { "type": "integer" }, "phase": { "enum": [ "QUOTED", "BOOKING", "CONFIRMED", "FAILED", "CANCELLED", "TRANSFERRED" ] }, "expires": { "type": "integer" }, "total": { "type": "integer", "description": "Final USD cents" }, "currency": { "const": "USD" }, "legs": { "type": "array", "items": { "type": "object" } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "leg": { "type": "integer" }, "kind": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "integer" } }, "required": [ "leg", "kind", "label", "amount" ] } }, "boundaries": { "type": "array", "items": { "type": "object" } }, "automaticUntil": { "type": "string" }, "tags": { "type": "array", "items": { "type": "object" } } }, "required": [ "key", "phase", "total", "legs", "lines" ] }, "BookingRequest": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" }, "payment": { "enum": [ "success", "declined" ], "description": "Local demo payment simulation only; no payment details accepted." } }, "required": [ "key", "payment" ] }, "Scan": { "type": "object", "properties": { "tag": { "type": "string" }, "eventKey": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" }, "action": { "enum": [ "CHECK_IN", "ARRIVE", "RELEASE", "ACCEPT", "COLLECT", "RECHECK" ] } }, "required": [ "tag", "action" ] }, "PricingPolicy": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" }, "name": { "type": "string", "maxLength": 70 }, "service": { "type": "string", "default": "*" }, "component": { "enum": [ "FARE", "BAGGAGE", "LUGGAGE_TRANSFER", "SHIPPING_RATE" ] }, "type": { "enum": [ "FIXED", "PERCENT" ] }, "value": { "type": "number", "description": "FIXED: nonnegative integer USD cents. PERCENT: adjustment -100 to 500." }, "priority": { "type": "integer", "minimum": 0, "maximum": 1000 }, "ticketType": { "enum": [ "ANY", "ONE_WAY", "RETURN", "SHIPMENT" ] }, "timezone": { "type": "string", "default": "UTC" }, "startDate": { "type": "string", "description": "Inclusive departure-local date YYYY-MM-DD or empty" }, "endDate": { "type": "string", "description": "Inclusive departure-local date YYYY-MM-DD or empty" }, "startTime": { "type": "string", "description": "Inclusive HH:MM or empty" }, "endTime": { "type": "string", "description": "Exclusive HH:MM; overnight windows supported" }, "weekdays": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 } }, "code": { "type": "string", "maxLength": 30 }, "active": { "type": "boolean" } }, "required": [ "id", "name", "component", "type", "value" ] }, "AgencyAgreement": { "type": "object", "properties": { "agency": { "type": "integer" }, "products": { "type": "array", "items": { "enum": [ "TRAVEL", "SHIPMENT" ] } }, "acceptance": { "enum": [ "AUTO", "APPROVAL", "REVOKED" ] } }, "required": [ "agency", "acceptance" ] }, "SellingAgreement": { "type": "object", "properties": { "seller": { "type": "integer" }, "acceptance": { "enum": [ "AUTO", "APPROVAL" ] } }, "required": [ "seller", "acceptance" ] }, "ServiceRequest": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" }, "action": { "enum": [ "CHANGE", "CANCEL", "REFUND", "TRANSFER" ] }, "replacement": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" }, "first": { "type": "string" }, "last": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "required": [ "id", "action" ] }, "ServiceDecision": { "type": "object", "properties": { "decision": { "enum": [ "APPROVE", "REJECT" ] } }, "required": [ "decision" ] }, "ServiceExecute": { "type": "object", "properties": { "accept": { "const": "yes" }, "payment": { "enum": [ "success", "decline" ], "description": "Test settlement only. No money moves." } }, "required": [ "accept", "payment" ] }, "ServiceEmpty": { "type": "object", "properties": {}, "required": [] }, "ShipmentContacts": { "type": "object", "properties": { "first": { "type": "string" }, "last": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string", "format": "email" }, "sender": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "street": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "postal": { "type": "string" }, "country": { "type": "string", "minLength": 2, "maxLength": 2 } }, "required": [ "name", "phone", "street", "city", "country" ] }, "recipient": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "street": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "postal": { "type": "string" }, "country": { "type": "string", "minLength": 2, "maxLength": 2 } }, "required": [ "name", "phone", "street", "city", "country" ] } }, "required": [ "first", "last", "phone", "email", "sender", "recipient" ] }, "ShipmentQuote": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" }, "services": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 24, "uniqueItems": true }, "parcels": { "type": "array", "items": { "$ref": "#/components/schemas/Parcel" }, "minItems": 1, "maxItems": 20 }, "contacts": { "$ref": "#/components/schemas/ShipmentContacts" } }, "required": [ "key", "services", "parcels", "contacts" ] }, "DeliveryConfirmation": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" }, "tag": { "type": "string" }, "receiver": { "type": "string" }, "relationship": { "enum": [ "RECIPIENT", "AUTHORIZED_PERSON" ] }, "condition": { "enum": [ "INTACT", "DAMAGED" ] }, "location": { "type": "string", "description": "Must match booked final destination" }, "proof": { "type": "string", "description": "Carrier-held delivery evidence reference; no file upload or independent signature verification" }, "accept": { "const": "yes" } }, "required": [ "id", "tag", "receiver", "relationship", "condition", "location", "proof", "accept" ] }, "ParcelClaim": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,70}$" }, "tag": { "type": "string" }, "kind": { "enum": [ "LOST", "DAMAGED" ] }, "amount": { "type": "integer", "minimum": 1, "maximum": 100000000, "description": "Requested USD cents" }, "description": { "type": "string" }, "evidence": { "type": "string" } }, "required": [ "id", "tag", "kind", "amount", "description", "evidence" ] }, "ClaimReview": { "type": "object", "properties": { "decision": { "enum": [ "START_REVIEW", "APPROVE", "REJECT" ] }, "reason": { "type": "string" }, "amount": { "type": "integer", "minimum": 1, "maximum": 100000000, "description": "Approved USD cents; required for APPROVE, cannot exceed claim request" } }, "required": [ "decision", "reason" ] }, "ClaimEvidence": { "type": "object", "properties": { "evidence": { "type": "string" }, "kind": { "enum": [ "LOST", "DAMAGED" ], "description": "Optional correction from LOST to DAMAGED on an unsettled case; preserves case ID and requires new carrier review" } }, "required": [ "evidence" ] } } } }