{ "openapi": "3.1.1", "info": { "description": "Create shipment requests from your own systems, update and cancel the requests created through the API where the app's rules allow, keep your own metadata on them, and follow them; read the deals your company is a party to (the deal, its documents, its operation and its costs, as your company sees them in the app) and upload documents to them; and hear about what happens through signed webhooks (see the webhooks section). Authenticate every call with your company's integration key, 'Authorization: Bearer qk_...', or, where your security policy wants a short-lived credential, with an access token from POST /api/integrations/v1/oauth/token (OAuth 2.0 client credentials: the client id is the key's prefix, the secret is the key; tokens live 15 minutes and die with the key). A key acts as its integration's own service identity, limited to its scopes (requests:read, requests:write, deals:read, tracking:read, documents:read, documents:write, costs:read), to its company's calls a minute per key (60 on Exchange, 300 on Enterprise by default), and to its IP allowlist when it has one; every key expires within 12 months and can be rotated. A test key (qk_test_...) works the same way against a sandbox of your own and never touches real data: its answers say livemode: false. Send an X-Idempotency-Key header with every write (create, update, cancel, upload); repeat the same key to retry safely. Reads of a request carry an ETag; send it as If-Match on an update or a cancel to refuse the write (412) if the request changed in between. Webhooks: Every delivery is a POST with a JSON body and four headers: Quatlas-Event-Id (the event's id; dedupe on it, a delivery can arrive more than once), Quatlas-Event-Type, Quatlas-Timestamp (Unix seconds) and Quatlas-Signature: v1=, the lowercase hex HMAC-SHA256 of \".\" keyed with your subscription's signing secret (whsec_...). During a secret rotation the header carries one v1= value per valid secret, comma-separated; accept the delivery when any one matches. Compute the HMAC over the raw bytes you received, compare in constant time, and refuse a timestamp more than 5 minutes from your clock (replay). Answer any 2xx within 10 seconds to acknowledge; anything else, a redirect included, is retried after 1 minute, 5, 30, 2 hours, 6 and 12. After 20 failures in a row the subscription is switched off. Bodies are thin on purpose: fetch the details through the read API with your key's scopes.", "title": "Quatlas Integration API", "version": "v1" }, "servers": [ { "url": "https://app.quatlasglobal.com" } ], "components": { "schemas": { "CancelShipmentRequestV1": { "properties": { "reason": { "description": "Optional, at most 500 characters. Kept with the request and sent in the request.cancelled webhook.", "type": [ "null", "string" ] } }, "required": [ "reason" ], "type": "object" }, "CostLineV1": { "properties": { "amount": { "format": "double", "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ] }, "category": { "type": "string" }, "currency": { "type": "string" }, "description": { "type": [ "null", "string" ] }, "incurredAt": { "format": "date-time", "type": "string" }, "recordedBy": { "description": "Which side booked it: Shipper or Carrier.", "type": "string" }, "status": { "description": "Approved: the other side signed it off. Declared: booked by one side alone, not approved. In the totals, a Declared line the shipper booked itself counts as agreed (the shipper pays it); a Declared line the carrier booked is in declaredTotal.", "type": "string" } }, "required": [ "category", "amount", "currency", "description", "incurredAt", "recordedBy", "status" ], "type": "object" }, "CostTotalV1": { "properties": { "additionalTotal": { "description": "The agreed additional costs in this currency: every line with status Approved, and every line the shipper booked itself (recordedBy Shipper), since the shipper pays them. Declared costs not yet agreed are in declaredTotal, never here.", "format": "double", "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ] }, "contractAmount": { "description": "The contract amount (the agreed price) when this row is the contract's currency; 0 for a currency that only appears among the additional costs.", "format": "double", "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ] }, "currency": { "description": "ISO 4217 currency of this row. Amounts in different currencies are never added together or converted.", "type": "string" }, "declaredTotal": { "description": "The declared additional costs in this currency, not yet agreed: lines the carrier booked that the shipper has not approved (status Declared, recordedBy Carrier). Beside the grand total, never in it; 0 when there are none.", "format": "double", "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ] }, "grandTotal": { "description": "The contract amount plus the agreed additional costs; declared costs not yet agreed are in declaredTotal and never in the grand total.", "format": "double", "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ] } }, "required": [ "currency", "contractAmount", "additionalTotal", "grandTotal", "declaredTotal" ], "type": "object" }, "CreateShipmentRequestV1": { "properties": { "cargo": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ShipmentCargoV1" } ] }, "costCenter": { "description": "Optional, at most 100 characters. Kept with the request and visible only to your company.", "type": [ "null", "string" ] }, "destination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ShipmentLocationV1" } ] }, "externalReference": { "description": "Your own id for the request (for example the eBA record number). Required, at most 100 characters, unique within your company: the same reference again returns 409 with the first request's id.", "type": [ "null", "string" ] }, "incoterm": { "description": "An Incoterms 2020 code: EXW, FCA, FAS, FOB, CFR, CIF, CPT, CIP, DAP, DPU or DDP. Optional.", "type": [ "null", "string" ] }, "isFlexibleSchedule": { "type": "boolean" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Your own fields on the request (a cost centre, a PO number, a process number): at most 20 keys of 1 to 40 characters from A-Z, a-z, 0-9, '_' and '-', string values of at most 500 characters, 8 KB in all. Visible only to your company: returned in your reads and in webhooks sent to you, never to a carrier or anyone else. Empty or absent: none.", "type": [ "null", "object" ] }, "modePolicy": { "description": "Required (default) or Open.", "type": [ "null", "string" ] }, "notes": { "type": [ "null", "string" ] }, "origin": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ShipmentLocationV1" } ] }, "preferredDeliveryDate": { "format": "date", "type": [ "null", "string" ] }, "preferredDeliveryTime": { "format": "time", "type": [ "null", "string" ] }, "preferredPickupDate": { "format": "date", "type": [ "null", "string" ] }, "publish": { "description": "False (default): the request is created as a Draft. True: it is also published to the open market when the acting member may publish.", "type": "boolean" }, "purchaseOrderNumber": { "description": "Optional, at most 100 characters. Kept with the request and visible only to your company.", "type": [ "null", "string" ] }, "transportMode": { "description": "Road, Sea, Air, Rail, Multimodal or HandCarry. Leave empty with modePolicy Open.", "type": [ "null", "string" ] } }, "required": [ "externalReference", "purchaseOrderNumber", "costCenter", "publish", "origin", "destination", "transportMode", "modePolicy", "cargo", "preferredPickupDate", "preferredDeliveryDate", "preferredDeliveryTime", "isFlexibleSchedule", "incoterm", "notes" ], "type": "object" }, "DealCostsV1": { "properties": { "contractAmount": { "format": "double", "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ] }, "contractCurrency": { "type": [ "null", "string" ] }, "dealId": { "format": "uuid", "type": "string" }, "dealNumber": { "description": "The deal's business number (DEAL-206447).", "type": [ "null", "string" ] }, "lines": { "items": { "$ref": "#/components/schemas/CostLineV1" }, "type": "array" }, "livemode": { "type": "boolean" }, "totals": { "description": "One row per currency in play, never converted: the operation statement's totals. additionalTotal and grandTotal count agreed additional costs only; declared costs not yet agreed are in declaredTotal, beside the grand total and never in it.", "items": { "$ref": "#/components/schemas/CostTotalV1" }, "type": "array" } }, "required": [ "dealId", "contractAmount", "contractCurrency", "lines", "totals", "livemode" ], "type": "object" }, "DealDocumentV1": { "properties": { "category": { "description": "The document's category (CommercialInvoice, PackingList, BillOfLading, ...).", "type": "string" }, "dealId": { "format": "uuid", "type": "string" }, "fileName": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "scanStatus": { "description": "Malware scan: Clean, Pending, Infected or Failed. Only a Clean document can be downloaded.", "type": "string" }, "uploadedAt": { "format": "date-time", "type": "string" }, "uploadedBySide": { "description": "Which side uploaded it: Shipper or Carrier.", "type": "string" } }, "required": [ "id", "dealId", "category", "fileName", "uploadedAt", "uploadedBySide", "scanStatus" ], "type": "object" }, "DealDocumentsV1": { "properties": { "dealId": { "format": "uuid", "type": "string" }, "dealNumber": { "description": "The deal's business number (DEAL-206447).", "type": [ "null", "string" ] }, "items": { "items": { "$ref": "#/components/schemas/DealDocumentV1" }, "type": "array" }, "livemode": { "type": "boolean" } }, "required": [ "dealId", "items", "livemode" ], "type": "object" }, "DealListV1": { "properties": { "items": { "items": { "$ref": "#/components/schemas/DealV1" }, "type": "array" }, "livemode": { "type": "boolean" } }, "required": [ "items", "livemode" ], "type": "object" }, "DealTrackingV1": { "properties": { "cancelledAt": { "description": "When the operation was cancelled after going live, if it was.", "format": "date-time", "type": [ "null", "string" ] }, "completedAt": { "description": "When the shipper confirmed the delivery.", "format": "date-time", "type": [ "null", "string" ] }, "currentEta": { "description": "The carrier's latest delivery estimate (the planned date until it is revised).", "format": "date", "type": [ "null", "string" ] }, "dealId": { "format": "uuid", "type": "string" }, "dealNumber": { "description": "The deal's business number (DEAL-206447).", "type": [ "null", "string" ] }, "deliveredAt": { "format": "date-time", "type": [ "null", "string" ] }, "etaRevisedAt": { "format": "date-time", "type": [ "null", "string" ] }, "livemode": { "type": "boolean" }, "milestones": { "items": { "$ref": "#/components/schemas/MilestoneV1" }, "type": "array" }, "plannedEta": { "description": "The delivery date agreed when the deal went live: the promise a delivery is judged against.", "format": "date", "type": [ "null", "string" ] }, "proofOfDelivery": { "description": "Whether a proof of delivery was captured.", "type": "boolean" }, "shipmentNumber": { "description": "The operation's business number (SHPT-012618). Never changes.", "type": [ "null", "string" ] } }, "required": [ "dealId", "milestones", "plannedEta", "currentEta", "etaRevisedAt", "deliveredAt", "proofOfDelivery", "completedAt", "cancelledAt", "livemode" ], "type": "object" }, "DealV1": { "properties": { "agreedAmount": { "description": "The agreed price: a renegotiated price when the parties accepted one, else the winning offer's amount.", "format": "double", "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ] }, "closedAt": { "description": "When the deal ended: delivery confirmed (Completed) or withdrawn (Withdrawn). Null while it runs.", "format": "date-time", "type": [ "null", "string" ] }, "counterpartyName": { "description": "The other party's company name, which the app shows both sides once a deal exists.", "type": [ "null", "string" ] }, "createdAt": { "format": "date-time", "type": "string" }, "currency": { "description": "ISO 4217 currency of the agreed price.", "type": [ "null", "string" ] }, "dealNumber": { "description": "The deal's business number (DEAL-206447). Never changes.", "type": [ "null", "string" ] }, "externalReference": { "description": "Your own reference for the request, when your company owns it (the shipper side). Null on the carrier side.", "type": [ "null", "string" ] }, "id": { "format": "uuid", "type": "string" }, "incoterm": { "description": "Incoterms 2020 code the deal runs on, when one was stated.", "type": [ "null", "string" ] }, "livemode": { "description": "True for a live key. False for a test key: a sandbox deal, never real data.", "type": "boolean" }, "quoteNumber": { "description": "The winning quote's business number (QTE-731905).", "type": [ "null", "string" ] }, "requestNumber": { "description": "The business number of the request the deal was made from (REQ-048213).", "type": [ "null", "string" ] }, "shipmentNumber": { "description": "The operation's business number (SHPT-012618), once the deal went live. Never changes.", "type": [ "null", "string" ] }, "shipmentRequestId": { "format": "uuid", "type": "string" }, "side": { "description": "Your company's side of the deal: Shipper or Carrier.", "type": "string" }, "stage": { "description": "Closing (closing room), Live (the operation runs), Completed (delivery confirmed) or Withdrawn (called off in the closing room).", "type": "string" }, "wentLiveAt": { "description": "When the closing room finished and the deal went live.", "format": "date-time", "type": [ "null", "string" ] } }, "required": [ "id", "shipmentRequestId", "externalReference", "side", "agreedAmount", "currency", "incoterm", "counterpartyName", "stage", "createdAt", "wentLiveAt", "closedAt", "livemode" ], "type": "object" }, "DocumentUploadedV1": { "properties": { "category": { "description": "The document's category, as the app names it.", "type": "string" }, "contentType": { "type": "string" }, "dealId": { "format": "uuid", "type": "string" }, "dealNumber": { "description": "The deal's business number (DEAL-206447).", "type": [ "null", "string" ] }, "fileName": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "livemode": { "description": "True for a live key. False for a test key: the sandbox checked and scanned the file like a live upload, then kept only this record, never the file.", "type": "boolean" }, "scanStatus": { "description": "Clean. A file is scanned for malware before it is stored, as in the app: an infected file is refused (422 Document.Infected) and never stored, so an accepted upload is always Clean.", "type": "string" }, "sizeBytes": { "format": "int64", "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ] }, "uploadedAt": { "format": "date-time", "type": "string" }, "uploadedBySide": { "description": "Which side uploaded it: your company's side on the deal.", "type": "string" } }, "required": [ "id", "dealId", "category", "fileName", "contentType", "sizeBytes", "uploadedAt", "uploadedBySide", "scanStatus", "livemode" ], "type": "object" }, "HttpValidationProblemDetails": { "properties": { "detail": { "type": [ "null", "string" ] }, "errors": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "type": "object" }, "instance": { "type": [ "null", "string" ] }, "status": { "format": "int32", "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ] }, "title": { "type": [ "null", "string" ] }, "type": { "type": [ "null", "string" ] } }, "type": "object" }, "IFormFile": { "format": "binary", "type": "string" }, "MilestoneV1": { "properties": { "location": { "description": "The place the carrier named, as text. Never coordinates.", "type": [ "null", "string" ] }, "occurredAt": { "format": "date-time", "type": "string" }, "type": { "description": "Loaded, Departed, Arrived, InTransit, AtCustoms, ModeHandover, OutForDelivery, Delivered, Exception, Refused or PartiallyDelivered.", "type": "string" } }, "required": [ "type", "occurredAt", "location" ], "type": "object" }, "OAuthErrorV1": { "properties": { "error": { "description": "invalid_request, invalid_client, unsupported_grant_type or invalid_scope.", "type": "string" }, "error_description": { "type": [ "null", "string" ] } }, "required": [ "error", "error_description" ], "type": "object" }, "OAuthTokenRequestV1": { "properties": { "client_id": { "description": "client_secret_post only: your key's prefix (qk_... or qk_test_...).", "type": [ "null", "string" ] }, "client_secret": { "description": "client_secret_post only: the key itself.", "type": [ "null", "string" ] }, "grant_type": { "description": "Always client_credentials.", "type": "string" }, "scope": { "description": "Optional: the scopes wanted, space-separated; at most the key's own. Default: all of them.", "type": [ "null", "string" ] } }, "required": [ "grant_type", "client_id", "client_secret", "scope" ], "type": "object" }, "OAuthTokenResponseV1": { "properties": { "access_token": { "description": "The bearer token for Authorization: Bearer on the Integration API.", "type": "string" }, "expires_in": { "description": "Seconds the token is valid for (900).", "format": "int32", "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ] }, "scope": { "description": "The scopes granted, space-separated.", "type": "string" }, "token_type": { "description": "Always Bearer.", "type": "string" } }, "required": [ "access_token", "token_type", "expires_in", "scope" ], "type": "object" }, "ProblemDetails": { "properties": { "detail": { "type": [ "null", "string" ] }, "instance": { "type": [ "null", "string" ] }, "status": { "format": "int32", "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ] }, "title": { "type": [ "null", "string" ] }, "type": { "type": [ "null", "string" ] } }, "type": "object" }, "PublishOutcomeV1": { "properties": { "published": { "description": "The request is on the market.", "type": "boolean" }, "refusalCode": { "description": "Why it was not published; the request stays a Draft a person can publish in the app.", "type": [ "null", "string" ] }, "refusalDetail": { "type": [ "null", "string" ] }, "requested": { "description": "You sent publish: true.", "type": "boolean" } }, "required": [ "requested", "published", "refusalCode", "refusalDetail" ], "type": "object" }, "SandboxAdvanceV1": { "properties": { "step": { "description": "Published, BidReceived, Awarded or Delivered. Each step follows the one before it: Published from Draft, BidReceived and Awarded from Published, Delivered from Awarded.", "type": [ "null", "string" ] } }, "required": [ "step" ], "type": "object" }, "ShipmentCargoUpdateV1": { "properties": { "description": { "type": [ "null", "string" ] }, "dimensions": { "type": [ "null", "string" ] }, "exceedsStandard": { "type": [ "null", "boolean" ] }, "fragile": { "type": [ "null", "boolean" ] }, "hazardous": { "type": [ "null", "boolean" ] }, "maxStackLayers": { "format": "int32", "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ] }, "maxTopLoadKg": { "format": "double", "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ] }, "outOfGauge": { "type": [ "null", "boolean" ] }, "packageCount": { "format": "int32", "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ] }, "stackable": { "type": [ "null", "boolean" ] }, "standardType": { "type": [ "null", "string" ] }, "temperatureMaxC": { "format": "double", "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ] }, "temperatureMinC": { "format": "double", "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ] }, "volumeM3": { "format": "double", "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ] }, "weightKg": { "format": "double", "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ] } }, "required": [ "description", "standardType", "weightKg", "volumeM3", "dimensions", "packageCount", "hazardous", "stackable", "fragile", "temperatureMinC", "temperatureMaxC", "exceedsStandard", "outOfGauge", "maxStackLayers", "maxTopLoadKg" ], "type": "object" }, "ShipmentCargoV1": { "properties": { "description": { "description": "What is moved. Required, at most 500 characters.", "type": [ "null", "string" ] }, "dimensions": { "type": [ "null", "string" ] }, "exceedsStandard": { "type": "boolean" }, "fragile": { "type": "boolean" }, "hazardous": { "type": "boolean" }, "maxStackLayers": { "format": "int32", "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ] }, "maxTopLoadKg": { "format": "double", "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ] }, "outOfGauge": { "type": "boolean" }, "packageCount": { "format": "int32", "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ] }, "stackable": { "type": "boolean" }, "standardType": { "type": [ "null", "string" ] }, "temperatureMaxC": { "format": "double", "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ] }, "temperatureMinC": { "format": "double", "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ] }, "volumeM3": { "format": "double", "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ] }, "weightKg": { "format": "double", "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ] } }, "required": [ "description", "standardType", "weightKg", "volumeM3", "dimensions", "packageCount", "hazardous", "stackable", "fragile", "temperatureMinC", "temperatureMaxC", "exceedsStandard", "outOfGauge", "maxStackLayers", "maxTopLoadKg" ], "type": "object" }, "ShipmentLocationV1": { "properties": { "addressLine": { "type": [ "null", "string" ] }, "city": { "type": [ "null", "string" ] }, "contactName": { "type": [ "null", "string" ] }, "contactPhone": { "type": [ "null", "string" ] }, "countryCode": { "description": "ISO 3166-1 alpha-2 country code. Required.", "type": [ "null", "string" ] }, "handling": { "type": [ "null", "string" ] }, "locationType": { "type": [ "null", "string" ] }, "postalCode": { "type": [ "null", "string" ] }, "unLocode": { "type": [ "null", "string" ] }, "windowFrom": { "format": "time", "type": [ "null", "string" ] }, "windowTo": { "format": "time", "type": [ "null", "string" ] } }, "required": [ "countryCode", "city", "locationType", "unLocode", "addressLine", "postalCode", "contactName", "contactPhone", "windowFrom", "windowTo", "handling" ], "type": "object" }, "ShipmentRequestCreatedV1": { "properties": { "externalReference": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "livemode": { "description": "True for a live key. False for a test key (qk_test_...): the request is in the sandbox and never touches real data.", "type": "boolean" }, "publish": { "$ref": "#/components/schemas/PublishOutcomeV1" }, "requestNumber": { "description": "The request's business number (REQ-048213): the number a person reads out and your system can store. Never changes.", "type": [ "null", "string" ] }, "status": { "description": "Draft or Published.", "type": "string" }, "webUrl": { "description": "Where a person opens the request in the app.", "type": "string" } }, "required": [ "id", "externalReference", "status", "webUrl", "publish", "livemode" ], "type": "object" }, "ShipmentRequestStatusV1": { "properties": { "awardedAt": { "format": "date-time", "type": [ "null", "string" ] }, "awardedCarrierName": { "description": "The awarded carrier, once a deal exists (when the app names it).", "type": [ "null", "string" ] }, "bidCount": { "description": "Open offers right now: a count only, never who made them or what they offered.", "format": "int32", "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ] }, "biddingDeadline": { "format": "date-time", "type": [ "null", "string" ] }, "cancellationReason": { "description": "The reason given when the request was cancelled, if any.", "type": [ "null", "string" ] }, "cancelledAt": { "format": "date-time", "type": [ "null", "string" ] }, "costCenter": { "type": [ "null", "string" ] }, "createdAt": { "format": "date-time", "type": "string" }, "dealId": { "format": "uuid", "type": [ "null", "string" ] }, "dealNumber": { "description": "The deal's business number (DEAL-206447), once a deal exists. Never changes.", "type": [ "null", "string" ] }, "deliveredAt": { "format": "date-time", "type": [ "null", "string" ] }, "externalReference": { "type": [ "null", "string" ] }, "id": { "format": "uuid", "type": "string" }, "livemode": { "description": "True for a live key. False for a test key (qk_test_...): a sandbox request, never real data.", "type": "boolean" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Your own fields on the request: your company's only, never shown to anyone else. An empty object when there are none.", "type": "object" }, "operationStatus": { "description": "Once a deal exists: Closing, InProgress, Delivered, Completed, Cancelled, Withdrawn or Ended.", "type": [ "null", "string" ] }, "publishedAt": { "format": "date-time", "type": [ "null", "string" ] }, "purchaseOrderNumber": { "type": [ "null", "string" ] }, "quoteNumber": { "description": "The winning quote's business number (QTE-731905), once a deal exists. Never changes.", "type": [ "null", "string" ] }, "requestNumber": { "description": "The request's business number (REQ-048213): the number a person reads out and your system can store. Never changes.", "type": [ "null", "string" ] }, "revision": { "description": "Which version of the listing this is: 1 until the first change, then one more for each change of its fields (in the app or through PATCH).", "format": "int32", "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ] }, "shipmentNumber": { "description": "The operation's business number (SHPT-012618), once the deal went live. Never changes.", "type": [ "null", "string" ] }, "status": { "description": "Draft, Published, BiddingClosed, Awarded or Cancelled.", "type": "string" }, "webUrl": { "type": "string" } }, "required": [ "id", "externalReference", "purchaseOrderNumber", "costCenter", "status", "createdAt", "publishedAt", "biddingDeadline", "bidCount", "awardedAt", "awardedCarrierName", "dealId", "operationStatus", "deliveredAt", "cancelledAt", "webUrl", "livemode", "metadata", "revision", "cancellationReason" ], "type": "object" }, "UpdateShipmentRequestV1": { "properties": { "cargo": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ShipmentCargoUpdateV1" } ] }, "costCenter": { "description": "Only on a request created through the API. Null clears it. At most 100 characters.", "type": [ "null", "string" ] }, "destination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ShipmentLocationV1", "description": "As origin." } ] }, "incoterm": { "description": "An Incoterms 2020 code. Cannot be null.", "type": [ "null", "string" ] }, "isFlexibleSchedule": { "description": "Cannot be null.", "type": [ "null", "boolean" ] }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Merged into the request's metadata: a key set to a string is added or changed, a key set to null is removed, other keys stay. \"metadata\": null removes every key. The create's limits apply to the result.", "type": [ "null", "object" ] }, "modePolicy": { "description": "Required or Open. Open clears the transport mode. Cannot be null.", "type": [ "null", "string" ] }, "notes": { "description": "Null or an empty string clears the notes.", "type": [ "null", "string" ] }, "origin": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ShipmentLocationV1", "description": "Any of the create's origin fields. countryCode, windowFrom and windowTo cannot be cleared; the text fields are cleared with null. The object itself cannot be null." } ] }, "preferredDeliveryDate": { "description": "Cannot be null.", "format": "date", "type": [ "null", "string" ] }, "preferredDeliveryTime": { "description": "Cannot be null.", "format": "time", "type": [ "null", "string" ] }, "preferredPickupDate": { "description": "Cannot be null.", "format": "date", "type": [ "null", "string" ] }, "purchaseOrderNumber": { "description": "Only on a request created through the API. Null clears it. At most 100 characters.", "type": [ "null", "string" ] }, "reason": { "description": "Optional, at most 500 characters: your words to the carriers who are asked to look at the request again. Not stored on the request's fields.", "type": [ "null", "string" ] }, "transportMode": { "description": "Road, Sea, Air, Rail, Multimodal or HandCarry. Cannot be null: send modePolicy Open to leave the mode open.", "type": [ "null", "string" ] } }, "required": [ "origin", "destination", "transportMode", "modePolicy", "cargo", "preferredPickupDate", "preferredDeliveryDate", "preferredDeliveryTime", "isFlexibleSchedule", "incoterm", "notes", "reason", "purchaseOrderNumber", "costCenter", "metadata" ], "type": "object" }, "WebhookCostApproved": { "description": "The body of a cost.approved delivery.", "properties": { "data": { "description": "The identifying fields, and the facts this type carries.", "properties": { "dealId": { "description": "The deal the event is about, when there is one.", "format": "uuid", "type": [ "null", "string" ] }, "dealNumber": { "description": "The deal's business number (DEAL-206447), once there is a deal.", "type": [ "null", "string" ] }, "externalReference": { "description": "Your own reference for the request, only when your company owns it.", "type": [ "null", "string" ] }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Your metadata on the request: only in a delivery to your company when it owns the request and has set some. Absent otherwise; never sent to another company.", "type": "object" }, "quoteNumber": { "description": "The quote's business number (QTE-731905): the winning quote once a deal exists, or the offer that arrived on request.bid_received.", "type": [ "null", "string" ] }, "requestNumber": { "description": "The request's business number (REQ-048213), when there is a request.", "type": [ "null", "string" ] }, "shipmentNumber": { "description": "The operation's business number (SHPT-012618), once the deal went live.", "type": [ "null", "string" ] }, "shipmentRequestId": { "description": "The request the event is about, when there is one.", "format": "uuid", "type": [ "null", "string" ] } }, "required": [ "shipmentRequestId", "externalReference", "dealId", "requestNumber", "quoteNumber", "dealNumber", "shipmentNumber" ], "type": "object" }, "id": { "description": "The event's id, also in Quatlas-Event-Id.", "format": "uuid", "type": "string" }, "livemode": { "description": "False for a sandbox (test integration) event and for webhook.test.", "type": "boolean" }, "occurredAt": { "description": "When the fact became true (UTC).", "format": "date-time", "type": "string" }, "type": { "const": "cost.approved", "description": "The event's type.", "type": "string" } }, "required": [ "id", "type", "occurredAt", "livemode", "data" ], "type": "object" }, "WebhookDealLive": { "description": "The body of a deal.live delivery.", "properties": { "data": { "description": "The identifying fields, and the facts this type carries.", "properties": { "dealId": { "description": "The deal the event is about, when there is one.", "format": "uuid", "type": [ "null", "string" ] }, "dealNumber": { "description": "The deal's business number (DEAL-206447), once there is a deal.", "type": [ "null", "string" ] }, "externalReference": { "description": "Your own reference for the request, only when your company owns it.", "type": [ "null", "string" ] }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Your metadata on the request: only in a delivery to your company when it owns the request and has set some. Absent otherwise; never sent to another company.", "type": "object" }, "quoteNumber": { "description": "The quote's business number (QTE-731905): the winning quote once a deal exists, or the offer that arrived on request.bid_received.", "type": [ "null", "string" ] }, "requestNumber": { "description": "The request's business number (REQ-048213), when there is a request.", "type": [ "null", "string" ] }, "shipmentNumber": { "description": "The operation's business number (SHPT-012618), once the deal went live.", "type": [ "null", "string" ] }, "shipmentRequestId": { "description": "The request the event is about, when there is one.", "format": "uuid", "type": [ "null", "string" ] } }, "required": [ "shipmentRequestId", "externalReference", "dealId", "requestNumber", "quoteNumber", "dealNumber", "shipmentNumber" ], "type": "object" }, "id": { "description": "The event's id, also in Quatlas-Event-Id.", "format": "uuid", "type": "string" }, "livemode": { "description": "False for a sandbox (test integration) event and for webhook.test.", "type": "boolean" }, "occurredAt": { "description": "When the fact became true (UTC).", "format": "date-time", "type": "string" }, "type": { "const": "deal.live", "description": "The event's type.", "type": "string" } }, "required": [ "id", "type", "occurredAt", "livemode", "data" ], "type": "object" }, "WebhookDocumentUploaded": { "description": "The body of a document.uploaded delivery.", "properties": { "data": { "description": "The identifying fields, and the facts this type carries.", "properties": { "category": { "description": "The document's category (CommercialInvoice, PackingList, BillOfLading, ...).", "type": "string" }, "dealId": { "description": "The deal the event is about, when there is one.", "format": "uuid", "type": [ "null", "string" ] }, "dealNumber": { "description": "The deal's business number (DEAL-206447), once there is a deal.", "type": [ "null", "string" ] }, "documentId": { "description": "The document's id.", "format": "uuid", "type": "string" }, "externalReference": { "description": "Your own reference for the request, only when your company owns it.", "type": [ "null", "string" ] }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Your metadata on the request: only in a delivery to your company when it owns the request and has set some. Absent otherwise; never sent to another company.", "type": "object" }, "quoteNumber": { "description": "The quote's business number (QTE-731905): the winning quote once a deal exists, or the offer that arrived on request.bid_received.", "type": [ "null", "string" ] }, "requestNumber": { "description": "The request's business number (REQ-048213), when there is a request.", "type": [ "null", "string" ] }, "shipmentNumber": { "description": "The operation's business number (SHPT-012618), once the deal went live.", "type": [ "null", "string" ] }, "shipmentRequestId": { "description": "The request the event is about, when there is one.", "format": "uuid", "type": [ "null", "string" ] } }, "required": [ "documentId", "category", "shipmentRequestId", "externalReference", "dealId", "requestNumber", "quoteNumber", "dealNumber", "shipmentNumber" ], "type": "object" }, "id": { "description": "The event's id, also in Quatlas-Event-Id.", "format": "uuid", "type": "string" }, "livemode": { "description": "False for a sandbox (test integration) event and for webhook.test.", "type": "boolean" }, "occurredAt": { "description": "When the fact became true (UTC).", "format": "date-time", "type": "string" }, "type": { "const": "document.uploaded", "description": "The event's type.", "type": "string" } }, "required": [ "id", "type", "occurredAt", "livemode", "data" ], "type": "object" }, "WebhookInvoiceIssued": { "description": "The body of a invoice.issued delivery.", "properties": { "data": { "description": "The identifying fields, and the facts this type carries.", "properties": { "dealId": { "description": "The deal the event is about, when there is one.", "format": "uuid", "type": [ "null", "string" ] }, "dealNumber": { "description": "The deal's business number (DEAL-206447), once there is a deal.", "type": [ "null", "string" ] }, "externalReference": { "description": "Your own reference for the request, only when your company owns it.", "type": [ "null", "string" ] }, "invoiceId": { "description": "The invoice's id.", "format": "uuid", "type": "string" }, "invoiceNumber": { "description": "The invoice's number.", "type": "string" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Your metadata on the request: only in a delivery to your company when it owns the request and has set some. Absent otherwise; never sent to another company.", "type": "object" }, "quoteNumber": { "description": "The quote's business number (QTE-731905): the winning quote once a deal exists, or the offer that arrived on request.bid_received.", "type": [ "null", "string" ] }, "requestNumber": { "description": "The request's business number (REQ-048213), when there is a request.", "type": [ "null", "string" ] }, "shipmentNumber": { "description": "The operation's business number (SHPT-012618), once the deal went live.", "type": [ "null", "string" ] }, "shipmentRequestId": { "description": "The request the event is about, when there is one.", "format": "uuid", "type": [ "null", "string" ] } }, "required": [ "invoiceId", "invoiceNumber", "shipmentRequestId", "externalReference", "dealId", "requestNumber", "quoteNumber", "dealNumber", "shipmentNumber" ], "type": "object" }, "id": { "description": "The event's id, also in Quatlas-Event-Id.", "format": "uuid", "type": "string" }, "livemode": { "description": "False for a sandbox (test integration) event and for webhook.test.", "type": "boolean" }, "occurredAt": { "description": "When the fact became true (UTC).", "format": "date-time", "type": "string" }, "type": { "const": "invoice.issued", "description": "The event's type.", "type": "string" } }, "required": [ "id", "type", "occurredAt", "livemode", "data" ], "type": "object" }, "WebhookRequestAwarded": { "description": "The body of a request.awarded delivery.", "properties": { "data": { "description": "The identifying fields, and the facts this type carries.", "properties": { "dealId": { "description": "The deal the event is about, when there is one.", "format": "uuid", "type": [ "null", "string" ] }, "dealNumber": { "description": "The deal's business number (DEAL-206447), once there is a deal.", "type": [ "null", "string" ] }, "externalReference": { "description": "Your own reference for the request, only when your company owns it.", "type": [ "null", "string" ] }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Your metadata on the request: only in a delivery to your company when it owns the request and has set some. Absent otherwise; never sent to another company.", "type": "object" }, "quoteNumber": { "description": "The quote's business number (QTE-731905): the winning quote once a deal exists, or the offer that arrived on request.bid_received.", "type": [ "null", "string" ] }, "requestNumber": { "description": "The request's business number (REQ-048213), when there is a request.", "type": [ "null", "string" ] }, "shipmentNumber": { "description": "The operation's business number (SHPT-012618), once the deal went live.", "type": [ "null", "string" ] }, "shipmentRequestId": { "description": "The request the event is about, when there is one.", "format": "uuid", "type": [ "null", "string" ] } }, "required": [ "shipmentRequestId", "externalReference", "dealId", "requestNumber", "quoteNumber", "dealNumber", "shipmentNumber" ], "type": "object" }, "id": { "description": "The event's id, also in Quatlas-Event-Id.", "format": "uuid", "type": "string" }, "livemode": { "description": "False for a sandbox (test integration) event and for webhook.test.", "type": "boolean" }, "occurredAt": { "description": "When the fact became true (UTC).", "format": "date-time", "type": "string" }, "type": { "const": "request.awarded", "description": "The event's type.", "type": "string" } }, "required": [ "id", "type", "occurredAt", "livemode", "data" ], "type": "object" }, "WebhookRequestBidReceived": { "description": "The body of a request.bid_received delivery.", "properties": { "data": { "description": "The identifying fields, and the facts this type carries.", "properties": { "bidCount": { "description": "Open offers on the request right now.", "format": "int32", "type": "integer" }, "dealId": { "description": "The deal the event is about, when there is one.", "format": "uuid", "type": [ "null", "string" ] }, "dealNumber": { "description": "The deal's business number (DEAL-206447), once there is a deal.", "type": [ "null", "string" ] }, "externalReference": { "description": "Your own reference for the request, only when your company owns it.", "type": [ "null", "string" ] }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Your metadata on the request: only in a delivery to your company when it owns the request and has set some. Absent otherwise; never sent to another company.", "type": "object" }, "quoteNumber": { "description": "The quote's business number (QTE-731905): the winning quote once a deal exists, or the offer that arrived on request.bid_received.", "type": [ "null", "string" ] }, "requestNumber": { "description": "The request's business number (REQ-048213), when there is a request.", "type": [ "null", "string" ] }, "shipmentNumber": { "description": "The operation's business number (SHPT-012618), once the deal went live.", "type": [ "null", "string" ] }, "shipmentRequestId": { "description": "The request the event is about, when there is one.", "format": "uuid", "type": [ "null", "string" ] } }, "required": [ "bidCount", "shipmentRequestId", "externalReference", "dealId", "requestNumber", "quoteNumber", "dealNumber", "shipmentNumber" ], "type": "object" }, "id": { "description": "The event's id, also in Quatlas-Event-Id.", "format": "uuid", "type": "string" }, "livemode": { "description": "False for a sandbox (test integration) event and for webhook.test.", "type": "boolean" }, "occurredAt": { "description": "When the fact became true (UTC).", "format": "date-time", "type": "string" }, "type": { "const": "request.bid_received", "description": "The event's type.", "type": "string" } }, "required": [ "id", "type", "occurredAt", "livemode", "data" ], "type": "object" }, "WebhookRequestCancelled": { "description": "The body of a request.cancelled delivery.", "properties": { "data": { "description": "The identifying fields, and the facts this type carries.", "properties": { "dealId": { "description": "The deal the event is about, when there is one.", "format": "uuid", "type": [ "null", "string" ] }, "dealNumber": { "description": "The deal's business number (DEAL-206447), once there is a deal.", "type": [ "null", "string" ] }, "externalReference": { "description": "Your own reference for the request, only when your company owns it.", "type": [ "null", "string" ] }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Your metadata on the request: only in a delivery to your company when it owns the request and has set some. Absent otherwise; never sent to another company.", "type": "object" }, "quoteNumber": { "description": "The quote's business number (QTE-731905): the winning quote once a deal exists, or the offer that arrived on request.bid_received.", "type": [ "null", "string" ] }, "reason": { "description": "The owner's reason, when one was given; else null.", "type": [ "null", "string" ] }, "requestNumber": { "description": "The request's business number (REQ-048213), when there is a request.", "type": [ "null", "string" ] }, "shipmentNumber": { "description": "The operation's business number (SHPT-012618), once the deal went live.", "type": [ "null", "string" ] }, "shipmentRequestId": { "description": "The request the event is about, when there is one.", "format": "uuid", "type": [ "null", "string" ] } }, "required": [ "reason", "shipmentRequestId", "externalReference", "dealId", "requestNumber", "quoteNumber", "dealNumber", "shipmentNumber" ], "type": "object" }, "id": { "description": "The event's id, also in Quatlas-Event-Id.", "format": "uuid", "type": "string" }, "livemode": { "description": "False for a sandbox (test integration) event and for webhook.test.", "type": "boolean" }, "occurredAt": { "description": "When the fact became true (UTC).", "format": "date-time", "type": "string" }, "type": { "const": "request.cancelled", "description": "The event's type.", "type": "string" } }, "required": [ "id", "type", "occurredAt", "livemode", "data" ], "type": "object" }, "WebhookRequestPublished": { "description": "The body of a request.published delivery.", "properties": { "data": { "description": "The identifying fields, and the facts this type carries.", "properties": { "dealId": { "description": "The deal the event is about, when there is one.", "format": "uuid", "type": [ "null", "string" ] }, "dealNumber": { "description": "The deal's business number (DEAL-206447), once there is a deal.", "type": [ "null", "string" ] }, "externalReference": { "description": "Your own reference for the request, only when your company owns it.", "type": [ "null", "string" ] }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Your metadata on the request: only in a delivery to your company when it owns the request and has set some. Absent otherwise; never sent to another company.", "type": "object" }, "quoteNumber": { "description": "The quote's business number (QTE-731905): the winning quote once a deal exists, or the offer that arrived on request.bid_received.", "type": [ "null", "string" ] }, "requestNumber": { "description": "The request's business number (REQ-048213), when there is a request.", "type": [ "null", "string" ] }, "shipmentNumber": { "description": "The operation's business number (SHPT-012618), once the deal went live.", "type": [ "null", "string" ] }, "shipmentRequestId": { "description": "The request the event is about, when there is one.", "format": "uuid", "type": [ "null", "string" ] } }, "required": [ "shipmentRequestId", "externalReference", "dealId", "requestNumber", "quoteNumber", "dealNumber", "shipmentNumber" ], "type": "object" }, "id": { "description": "The event's id, also in Quatlas-Event-Id.", "format": "uuid", "type": "string" }, "livemode": { "description": "False for a sandbox (test integration) event and for webhook.test.", "type": "boolean" }, "occurredAt": { "description": "When the fact became true (UTC).", "format": "date-time", "type": "string" }, "type": { "const": "request.published", "description": "The event's type.", "type": "string" } }, "required": [ "id", "type", "occurredAt", "livemode", "data" ], "type": "object" }, "WebhookRequestUpdated": { "description": "The body of a request.updated delivery.", "properties": { "data": { "description": "The identifying fields, and the facts this type carries.", "properties": { "changedFields": { "description": "What moved: origin, destination, transportMode, modePolicy, cargo, schedule, incoterm or notes (the listing), purchaseOrderNumber, costCenter or metadata (your bookkeeping).", "items": { "type": "string" }, "type": "array" }, "dealId": { "description": "The deal the event is about, when there is one.", "format": "uuid", "type": [ "null", "string" ] }, "dealNumber": { "description": "The deal's business number (DEAL-206447), once there is a deal.", "type": [ "null", "string" ] }, "externalReference": { "description": "Your own reference for the request, only when your company owns it.", "type": [ "null", "string" ] }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Your metadata on the request: only in a delivery to your company when it owns the request and has set some. Absent otherwise; never sent to another company.", "type": "object" }, "quoteNumber": { "description": "The quote's business number (QTE-731905): the winning quote once a deal exists, or the offer that arrived on request.bid_received.", "type": [ "null", "string" ] }, "requestNumber": { "description": "The request's business number (REQ-048213), when there is a request.", "type": [ "null", "string" ] }, "revision": { "description": "The listing's revision after the change (it moves only when the listing changes).", "format": "int32", "type": "integer" }, "shipmentNumber": { "description": "The operation's business number (SHPT-012618), once the deal went live.", "type": [ "null", "string" ] }, "shipmentRequestId": { "description": "The request the event is about, when there is one.", "format": "uuid", "type": [ "null", "string" ] } }, "required": [ "changedFields", "revision", "shipmentRequestId", "externalReference", "dealId", "requestNumber", "quoteNumber", "dealNumber", "shipmentNumber" ], "type": "object" }, "id": { "description": "The event's id, also in Quatlas-Event-Id.", "format": "uuid", "type": "string" }, "livemode": { "description": "False for a sandbox (test integration) event and for webhook.test.", "type": "boolean" }, "occurredAt": { "description": "When the fact became true (UTC).", "format": "date-time", "type": "string" }, "type": { "const": "request.updated", "description": "The event's type.", "type": "string" } }, "required": [ "id", "type", "occurredAt", "livemode", "data" ], "type": "object" }, "WebhookShipmentDelivered": { "description": "The body of a shipment.delivered delivery.", "properties": { "data": { "description": "The identifying fields, and the facts this type carries.", "properties": { "dealId": { "description": "The deal the event is about, when there is one.", "format": "uuid", "type": [ "null", "string" ] }, "dealNumber": { "description": "The deal's business number (DEAL-206447), once there is a deal.", "type": [ "null", "string" ] }, "externalReference": { "description": "Your own reference for the request, only when your company owns it.", "type": [ "null", "string" ] }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Your metadata on the request: only in a delivery to your company when it owns the request and has set some. Absent otherwise; never sent to another company.", "type": "object" }, "quoteNumber": { "description": "The quote's business number (QTE-731905): the winning quote once a deal exists, or the offer that arrived on request.bid_received.", "type": [ "null", "string" ] }, "requestNumber": { "description": "The request's business number (REQ-048213), when there is a request.", "type": [ "null", "string" ] }, "shipmentNumber": { "description": "The operation's business number (SHPT-012618), once the deal went live.", "type": [ "null", "string" ] }, "shipmentRequestId": { "description": "The request the event is about, when there is one.", "format": "uuid", "type": [ "null", "string" ] } }, "required": [ "shipmentRequestId", "externalReference", "dealId", "requestNumber", "quoteNumber", "dealNumber", "shipmentNumber" ], "type": "object" }, "id": { "description": "The event's id, also in Quatlas-Event-Id.", "format": "uuid", "type": "string" }, "livemode": { "description": "False for a sandbox (test integration) event and for webhook.test.", "type": "boolean" }, "occurredAt": { "description": "When the fact became true (UTC).", "format": "date-time", "type": "string" }, "type": { "const": "shipment.delivered", "description": "The event's type.", "type": "string" } }, "required": [ "id", "type", "occurredAt", "livemode", "data" ], "type": "object" }, "WebhookShipmentEtaChanged": { "description": "The body of a shipment.eta_changed delivery.", "properties": { "data": { "description": "The identifying fields, and the facts this type carries.", "properties": { "dealId": { "description": "The deal the event is about, when there is one.", "format": "uuid", "type": [ "null", "string" ] }, "dealNumber": { "description": "The deal's business number (DEAL-206447), once there is a deal.", "type": [ "null", "string" ] }, "externalReference": { "description": "Your own reference for the request, only when your company owns it.", "type": [ "null", "string" ] }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Your metadata on the request: only in a delivery to your company when it owns the request and has set some. Absent otherwise; never sent to another company.", "type": "object" }, "quoteNumber": { "description": "The quote's business number (QTE-731905): the winning quote once a deal exists, or the offer that arrived on request.bid_received.", "type": [ "null", "string" ] }, "requestNumber": { "description": "The request's business number (REQ-048213), when there is a request.", "type": [ "null", "string" ] }, "shipmentNumber": { "description": "The operation's business number (SHPT-012618), once the deal went live.", "type": [ "null", "string" ] }, "shipmentRequestId": { "description": "The request the event is about, when there is one.", "format": "uuid", "type": [ "null", "string" ] } }, "required": [ "shipmentRequestId", "externalReference", "dealId", "requestNumber", "quoteNumber", "dealNumber", "shipmentNumber" ], "type": "object" }, "id": { "description": "The event's id, also in Quatlas-Event-Id.", "format": "uuid", "type": "string" }, "livemode": { "description": "False for a sandbox (test integration) event and for webhook.test.", "type": "boolean" }, "occurredAt": { "description": "When the fact became true (UTC).", "format": "date-time", "type": "string" }, "type": { "const": "shipment.eta_changed", "description": "The event's type.", "type": "string" } }, "required": [ "id", "type", "occurredAt", "livemode", "data" ], "type": "object" }, "WebhookShipmentMilestone": { "description": "The body of a shipment.milestone delivery.", "properties": { "data": { "description": "The identifying fields, and the facts this type carries.", "properties": { "dealId": { "description": "The deal the event is about, when there is one.", "format": "uuid", "type": [ "null", "string" ] }, "dealNumber": { "description": "The deal's business number (DEAL-206447), once there is a deal.", "type": [ "null", "string" ] }, "externalReference": { "description": "Your own reference for the request, only when your company owns it.", "type": [ "null", "string" ] }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Your metadata on the request: only in a delivery to your company when it owns the request and has set some. Absent otherwise; never sent to another company.", "type": "object" }, "milestoneAt": { "description": "When the milestone happened.", "format": "date-time", "type": "string" }, "milestoneType": { "description": "Loaded, Departed, Arrived, InTransit, AtCustoms, ModeHandover, OutForDelivery, Delivered, Exception, Refused or PartiallyDelivered.", "type": "string" }, "quoteNumber": { "description": "The quote's business number (QTE-731905): the winning quote once a deal exists, or the offer that arrived on request.bid_received.", "type": [ "null", "string" ] }, "requestNumber": { "description": "The request's business number (REQ-048213), when there is a request.", "type": [ "null", "string" ] }, "shipmentNumber": { "description": "The operation's business number (SHPT-012618), once the deal went live.", "type": [ "null", "string" ] }, "shipmentRequestId": { "description": "The request the event is about, when there is one.", "format": "uuid", "type": [ "null", "string" ] } }, "required": [ "milestoneType", "milestoneAt", "shipmentRequestId", "externalReference", "dealId", "requestNumber", "quoteNumber", "dealNumber", "shipmentNumber" ], "type": "object" }, "id": { "description": "The event's id, also in Quatlas-Event-Id.", "format": "uuid", "type": "string" }, "livemode": { "description": "False for a sandbox (test integration) event and for webhook.test.", "type": "boolean" }, "occurredAt": { "description": "When the fact became true (UTC).", "format": "date-time", "type": "string" }, "type": { "const": "shipment.milestone", "description": "The event's type.", "type": "string" } }, "required": [ "id", "type", "occurredAt", "livemode", "data" ], "type": "object" }, "WebhookWebhookTest": { "description": "The body of a webhook.test delivery.", "properties": { "data": { "description": "The identifying fields, and the facts this type carries.", "properties": { "integrationId": { "description": "Its integration.", "format": "uuid", "type": "string" }, "subscriptionId": { "description": "The subscription the test was sent to.", "format": "uuid", "type": "string" } }, "required": [ "subscriptionId", "integrationId" ], "type": "object" }, "id": { "description": "The event's id, also in Quatlas-Event-Id.", "format": "uuid", "type": "string" }, "livemode": { "description": "False for a sandbox (test integration) event and for webhook.test.", "type": "boolean" }, "occurredAt": { "description": "When the fact became true (UTC).", "format": "date-time", "type": "string" }, "type": { "const": "webhook.test", "description": "The event's type.", "type": "string" } }, "required": [ "id", "type", "occurredAt", "livemode", "data" ], "type": "object" } }, "securitySchemes": { "IntegrationClient": { "description": "The token endpoint's client authentication (client_secret_basic): the key's prefix as the user name and the key as the password. Or send client_id and client_secret in the form (client_secret_post), never both.", "scheme": "basic", "type": "http" }, "IntegrationKey": { "description": "Your company's integration key (qk_... or, for the sandbox, qk_test_...), or an access token the token endpoint issued for it. Send as 'Authorization: Bearer ...'.", "scheme": "bearer", "type": "http" }, "IntegrationOAuth": { "description": "OAuth 2.0 client credentials. Access tokens live 15 minutes; revoking the key refuses them at once.", "flows": { "clientCredentials": { "scopes": { "costs:read": "Read a deal's additional costs and statement totals.", "deals:read": "Read the deals your company is a party to.", "documents:read": "List a deal's documents and download clean ones.", "documents:write": "Upload documents to the deals your company is a party to, under the app's upload rules.", "requests:read": "Read your shipment requests' status.", "requests:write": "Create, update and cancel your shipment requests.", "tracking:read": "Read a deal's milestones, planned and current ETA and delivery." }, "tokenUrl": "/api/integrations/v1/oauth/token" } }, "type": "oauth2" } } }, "paths": { "/api/integrations/v1/shipment-requests": { "post": { "description": "Requires the requests:write scope and an X-Idempotency-Key header (the same key with a different body answers 422 Integration.IdempotencyKeyReused). A repeated externalReference returns 409 with the existing request's id. With a test key (qk_test_...) the request goes to your sandbox and the answer says livemode: false.", "operationId": "IntegrationsV1CreateShipmentRequest", "parameters": [ { "in": "header", "name": "X-Idempotency-Key", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShipmentRequestV1" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentRequestCreatedV1" } } }, "description": "Created" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Forbidden" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Too Many Requests" } }, "security": [ { "IntegrationKey": [] }, { "IntegrationOAuth": [] } ], "summary": "Create a shipment request", "tags": [ "Integrations" ] }, "get": { "description": "Requires the requests:read scope and the externalReference query parameter. A test key reads your sandbox. Answers with the request's ETag, as the read by id does.", "operationId": "IntegrationsV1FindShipmentRequest", "parameters": [ { "in": "query", "name": "externalReference", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentRequestStatusV1" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Not Found" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Too Many Requests" } }, "security": [ { "IntegrationKey": [] }, { "IntegrationOAuth": [] } ], "summary": "Find a shipment request by your externalReference", "tags": [ "Integrations" ] } }, "/api/integrations/v1/shipment-requests/{id}": { "get": { "description": "Requires the requests:read scope. Only your company's own requests exist here; a test key reads your sandbox. The ETag header is the request's version: send it back as If-Match on an update or a cancel to refuse the write (412) if the request changed in between.", "operationId": "IntegrationsV1GetShipmentRequest", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentRequestStatusV1" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Not Found" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Too Many Requests" } }, "security": [ { "IntegrationKey": [] }, { "IntegrationOAuth": [] } ], "summary": "Read a shipment request's status", "tags": [ "Integrations" ] }, "patch": { "description": "Requires the requests:write scope and an X-Idempotency-Key header; If-Match (the read's ETag) is optional and answers 412 when the request changed since, checked under the request's lock so two writers with one tag cannot both win. Only a request your systems created through the API (409 Integration.RequestNotCreatedViaApi for one opened in the app). A JSON merge patch of at most 64 KB (413 Integration.BodyTooLarge): a field you leave out stays as it is; null clears a field where the app lets an owner clear it, and is refused (Integration.FieldNotClearable) where it does not. The listing's fields change only while the request is Published, as in the app (409 ShipmentRequest.InvalidTransition otherwise); a material change holds every standing offer until its carrier reconfirms, and extends the bidding to at least 12 hours. Your metadata, purchaseOrderNumber and costCenter change in any state. The whole patch is written in one transaction, or nothing is, and raises one request.updated. Answers the request as the read does, with its new ETag.", "operationId": "IntegrationsV1UpdateShipmentRequest", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-Idempotency-Key", "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateShipmentRequestV1" } }, "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/UpdateShipmentRequestV1" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentRequestStatusV1" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Precondition Failed" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Payload Too Large" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Too Many Requests" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Service Unavailable" } }, "security": [ { "IntegrationKey": [] }, { "IntegrationOAuth": [] } ], "summary": "Update a shipment request", "tags": [ "Integrations" ] } }, "/api/integrations/v1/shipment-requests/by-number/{number}": { "get": { "description": "Requires the requests:read scope. The request's business number (REQ-048213), in any case, with or without the REQ- prefix (another kind's prefix is 400 Integration.InvalidBusinessNumber). Answers exactly as the read by id, ETag included, under the same rules: only your company's own requests; any other number is 404. A test key reads your sandbox.", "operationId": "IntegrationsV1GetShipmentRequestByNumber", "parameters": [ { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentRequestStatusV1" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Not Found" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Too Many Requests" } }, "security": [ { "IntegrationKey": [] }, { "IntegrationOAuth": [] } ], "summary": "Read a shipment request by its business number", "tags": [ "Integrations" ] } }, "/api/integrations/v1/shipment-requests/{id}/cancel": { "post": { "description": "Requires the requests:write scope and an X-Idempotency-Key header; If-Match is optional (412 on a mismatch, checked under the request's lock). Only a request your systems created through the API (409 Integration.RequestNotCreatedViaApi). Cancels where the app lets an owner cancel: Draft, Published or BiddingClosed; the pending offers expire and their carriers are told, as in the app. Cancelling a cancelled request answers it again (200). Once awarded the request is a deal: 409 Integration.RequestAwarded with the dealId; withdrawing a deal or cancelling its operation is done in the app.", "operationId": "IntegrationsV1CancelShipmentRequest", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-Idempotency-Key", "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CancelShipmentRequestV1" } ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentRequestStatusV1" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Too Many Requests" } }, "security": [ { "IntegrationKey": [] }, { "IntegrationOAuth": [] } ], "summary": "Cancel a shipment request", "tags": [ "Integrations" ] } }, "/api/integrations/v1/sandbox/shipment-requests/{id}/advance": { "post": { "description": "Requires a test key (qk_test_...) with the requests:write scope. Moves a sandbox request through the life a real one has: Published, then BidReceived (any number of times), Awarded, Delivered. A live key gets 403 and nothing real ever moves.", "operationId": "IntegrationsV1AdvanceSandboxRequest", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxAdvanceV1" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentRequestStatusV1" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Conflict" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Too Many Requests" } }, "security": [ { "IntegrationKey": [] }, { "IntegrationOAuth": [] } ], "summary": "Move a sandbox request to its next status (test keys only)", "tags": [ "Integrations" ] } }, "/api/integrations/v1/deals": { "get": { "description": "Requires the deals:read scope and exactly one of shipmentRequestId or externalReference (your own reference, for a request your company owns). Lists only the deals your company is a party to, oldest first; a request re-awarded after a withdrawal has more than one.", "operationId": "IntegrationsV1ListDeals", "parameters": [ { "in": "query", "name": "shipmentRequestId", "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "externalReference", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealListV1" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Forbidden" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Too Many Requests" } }, "security": [ { "IntegrationKey": [] }, { "IntegrationOAuth": [] } ], "summary": "List the deals made from a request", "tags": [ "Integrations" ] } }, "/api/integrations/v1/deals/{id}": { "get": { "description": "Requires the deals:read scope. Your company's side, the agreed price and currency, the Incoterm, the counterparty's name, the stage and its dates, as your company sees them in the app. A deal your company is not a party to answers 404.", "operationId": "IntegrationsV1GetDeal", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealV1" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Not Found" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Too Many Requests" } }, "security": [ { "IntegrationKey": [] }, { "IntegrationOAuth": [] } ], "summary": "Read a deal", "tags": [ "Integrations" ] } }, "/api/integrations/v1/deals/by-number/{number}": { "get": { "description": "Requires the deals:read scope. The deal's business number (DEAL-206447), in any case, with or without the DEAL- prefix (another kind's prefix is 400 Integration.InvalidBusinessNumber). Answers exactly as the read by id: a deal your company is not a party to, or a number that does not exist, is 404.", "operationId": "IntegrationsV1GetDealByNumber", "parameters": [ { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealV1" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Not Found" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Too Many Requests" } }, "security": [ { "IntegrationKey": [] }, { "IntegrationOAuth": [] } ], "summary": "Read a deal by its business number", "tags": [ "Integrations" ] } }, "/api/integrations/v1/deals/{id}/tracking": { "get": { "description": "Requires the tracking:read scope. The milestones with their times, the planned delivery date (as agreed when the deal went live) and the current estimate, the delivery time and whether a proof of delivery exists. No live position. 404 until the deal goes live.", "operationId": "IntegrationsV1GetDealTracking", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealTrackingV1" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Not Found" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Too Many Requests" } }, "security": [ { "IntegrationKey": [] }, { "IntegrationOAuth": [] } ], "summary": "Read a deal's operation", "tags": [ "Integrations" ] } }, "/api/integrations/v1/operations/by-number/{number}": { "get": { "description": "Requires the tracking:read scope. The operation's business number (SHPT-012618), in any case, with or without the SHPT- prefix (another kind's prefix is 400 Integration.InvalidBusinessNumber). Answers exactly as /deals/{id}/tracking for its deal: an operation of a deal your company is not a party to, or a number that does not exist, is 404.", "operationId": "IntegrationsV1GetOperationByNumber", "parameters": [ { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealTrackingV1" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Not Found" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Too Many Requests" } }, "security": [ { "IntegrationKey": [] }, { "IntegrationOAuth": [] } ], "summary": "Read an operation by its business number", "tags": [ "Integrations" ] } }, "/api/integrations/v1/deals/{id}/documents": { "post": { "description": "Requires the documents:write scope and an X-Idempotency-Key header. multipart/form-data with the file in 'file' and its category in 'category'. The category must be one the app offers your side at the deal's stage (400 Document.CategoryNotOffered otherwise): in the closing room the shipper uploads PackingList, CommercialInvoice, DangerousGoodsCertificate (hazardous cargo only), Other and LoadingInstruction, the carrier its transport document for the deal's mode, WeighbridgeTicket and Other; once the deal is live either side uploads any current category, the dangerous goods certificate still the shipper's for hazardous cargo and the loading instruction still the shipper's; a withdrawn deal takes none (409 Document.DealNotOpen). CustomsDeclaration, CertificateOfOrigin and InsuranceCertificate are retired and AdditionalCostReceipt belongs to a cost line in the app, so the API takes none of them. The app's own upload rules apply: at most 25 MB; PDF, JPEG, PNG, DOCX or XLSX, checked against the file's contents (a DOCX or XLSX must be a Word or Excel package, recognised through its main part as Office reads it; a Word document sent as XLSX, or a workbook sent as DOCX, is kept as what it is and answered with its real contentType and a fileName with that type's extension; any other archive or an empty file is refused, 415 saying what the file is); a malware scan before anything is stored (an infected file is refused with 422 Document.Infected and never stored); the loading instruction is the shipper's; the carrier's transport document waits for the shipper's approved papers. The same X-Idempotency-Key with a different file or category answers 422 Integration.IdempotencyKeyReused. The other party is told as in the app, and document.uploaded goes to both parties' webhooks. Your company's uploads through the API are capped per UTC day (by default 50 files and 250 MB on Exchange, 200 files and 1 GiB on Enterprise; 429 Integration.DailyUploadLimit). A test key's upload is checked and scanned the same way; the sandbox keeps the record, never the file.", "operationId": "IntegrationsV1UploadDealDocument", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-Idempotency-Key", "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "allOf": [ { "properties": { "file": { "$ref": "#/components/schemas/IFormFile" } }, "type": "object" }, { "properties": { "category": { "type": "string" } }, "type": "object" } ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentUploadedV1" } } }, "description": "Created" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Conflict" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Payload Too Large" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Unsupported Media Type" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Too Many Requests" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Bad Gateway" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Service Unavailable" } }, "security": [ { "IntegrationKey": [] }, { "IntegrationOAuth": [] } ], "summary": "Upload a document to a deal", "tags": [ "Integrations" ] }, "get": { "description": "Requires the documents:read scope. The current version of each document in the deal's vault, newest first: category, file name, when and by which side it was uploaded, and its malware scan status. Never the file itself: download a Clean one through /documents/{id}/download.", "operationId": "IntegrationsV1ListDealDocuments", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealDocumentsV1" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Not Found" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Too Many Requests" } }, "security": [ { "IntegrationKey": [] }, { "IntegrationOAuth": [] } ], "summary": "List a deal's documents (metadata)", "tags": [ "Integrations" ] } }, "/api/integrations/v1/documents/{id}/download": { "get": { "description": "Requires the documents:read scope. Answers 302 to a download link that works for five minutes. Only the current version of a document of a deal your company is a party to, and only once it passed its malware scan (409 otherwise). Follow the redirect without sending your key to the storage host.", "operationId": "IntegrationsV1DownloadDocument", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "302": { "description": "Found" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Conflict" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Too Many Requests" } }, "security": [ { "IntegrationKey": [] }, { "IntegrationOAuth": [] } ], "summary": "Download a document", "tags": [ "Integrations" ] } }, "/api/integrations/v1/deals/{id}/costs": { "get": { "description": "Requires the costs:read scope. Every additional cost on the operation's ledger, each Approved (the other side signed it off) or Declared (booked by one side alone), and the operation statement's totals per currency, never converted: the contract amount plus the agreed additional costs, with declared costs not yet agreed in declaredTotal beside them, never in the grand total.", "operationId": "IntegrationsV1GetDealCosts", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealCostsV1" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Not Found" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Too Many Requests" } }, "security": [ { "IntegrationKey": [] }, { "IntegrationOAuth": [] } ], "summary": "Read a deal's additional costs and statement totals", "tags": [ "Integrations" ] } }, "/api/integrations/v1/oauth/token": { "post": { "description": "Form-encoded, grant_type=client_credentials. Authenticate with HTTP Basic (client_secret_basic) or the client_id and client_secret fields (client_secret_post): the client id is your key's prefix, the secret is the key. Returns a bearer token valid for 15 minutes, for Authorization: Bearer on the other routes. Revoking the key refuses its tokens at once. A key whose \"direct key allowed\" setting is off works here only.", "operationId": "IntegrationsV1OAuthToken", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/OAuthTokenRequestV1" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthTokenResponseV1" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthErrorV1" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthErrorV1" } } }, "description": "Unauthorized" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Too Many Requests" } }, "security": [ { "IntegrationClient": [] } ], "summary": "Get an access token (OAuth 2.0 client credentials)", "tags": [ "Integrations" ] } } }, "tags": [ { "name": "Integrations" } ], "webhooks": { "request.published": { "post": { "description": "To the request's owner. Fetch it with GET /shipment-requests/{id} (requests:read). Every delivery is a POST with a JSON body and four headers: Quatlas-Event-Id (the event's id; dedupe on it, a delivery can arrive more than once), Quatlas-Event-Type, Quatlas-Timestamp (Unix seconds) and Quatlas-Signature: v1=, the lowercase hex HMAC-SHA256 of \".\" keyed with your subscription's signing secret (whsec_...). During a secret rotation the header carries one v1= value per valid secret, comma-separated; accept the delivery when any one matches. Compute the HMAC over the raw bytes you received, compare in constant time, and refuse a timestamp more than 5 minutes from your clock (replay). Answer any 2xx within 10 seconds to acknowledge; anything else, a redirect included, is retried after 1 minute, 5, 30, 2 hours, 6 and 12. After 20 failures in a row the subscription is switched off. Bodies are thin on purpose: fetch the details through the read API with your key's scopes.", "parameters": [ { "description": "The event's id (uuid). The same event delivered twice carries the same id: dedupe on it.", "in": "header", "name": "Quatlas-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The event's type: request.published.", "in": "header", "name": "Quatlas-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "When this delivery was signed, in Unix seconds. Refuse one more than 5 minutes from your clock.", "in": "header", "name": "Quatlas-Timestamp", "required": true, "schema": { "type": "string" } }, { "description": "v1=.\")>, one value per valid secret, comma-separated.", "in": "header", "name": "Quatlas-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRequestPublished" } } }, "required": true }, "responses": { "2XX": { "description": "Any 2xx within 10 seconds acknowledges the delivery." } }, "summary": "A request went out to the market" } }, "request.bid_received": { "post": { "description": "To the request's owner, with the number of open offers only: never who bid or what they offered. Every delivery is a POST with a JSON body and four headers: Quatlas-Event-Id (the event's id; dedupe on it, a delivery can arrive more than once), Quatlas-Event-Type, Quatlas-Timestamp (Unix seconds) and Quatlas-Signature: v1=, the lowercase hex HMAC-SHA256 of \".\" keyed with your subscription's signing secret (whsec_...). During a secret rotation the header carries one v1= value per valid secret, comma-separated; accept the delivery when any one matches. Compute the HMAC over the raw bytes you received, compare in constant time, and refuse a timestamp more than 5 minutes from your clock (replay). Answer any 2xx within 10 seconds to acknowledge; anything else, a redirect included, is retried after 1 minute, 5, 30, 2 hours, 6 and 12. After 20 failures in a row the subscription is switched off. Bodies are thin on purpose: fetch the details through the read API with your key's scopes.", "parameters": [ { "description": "The event's id (uuid). The same event delivered twice carries the same id: dedupe on it.", "in": "header", "name": "Quatlas-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The event's type: request.bid_received.", "in": "header", "name": "Quatlas-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "When this delivery was signed, in Unix seconds. Refuse one more than 5 minutes from your clock.", "in": "header", "name": "Quatlas-Timestamp", "required": true, "schema": { "type": "string" } }, { "description": "v1=.\")>, one value per valid secret, comma-separated.", "in": "header", "name": "Quatlas-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRequestBidReceived" } } }, "required": true }, "responses": { "2XX": { "description": "Any 2xx within 10 seconds acknowledges the delivery." } }, "summary": "An offer arrived on your request" } }, "request.updated": { "post": { "description": "To the request's owner: its listing was amended (in the app or through PATCH /shipment-requests/{id}), or its metadata, purchase order number or cost centre changed through the API. Read the request with GET /shipment-requests/{id} (requests:read). Every delivery is a POST with a JSON body and four headers: Quatlas-Event-Id (the event's id; dedupe on it, a delivery can arrive more than once), Quatlas-Event-Type, Quatlas-Timestamp (Unix seconds) and Quatlas-Signature: v1=, the lowercase hex HMAC-SHA256 of \".\" keyed with your subscription's signing secret (whsec_...). During a secret rotation the header carries one v1= value per valid secret, comma-separated; accept the delivery when any one matches. Compute the HMAC over the raw bytes you received, compare in constant time, and refuse a timestamp more than 5 minutes from your clock (replay). Answer any 2xx within 10 seconds to acknowledge; anything else, a redirect included, is retried after 1 minute, 5, 30, 2 hours, 6 and 12. After 20 failures in a row the subscription is switched off. Bodies are thin on purpose: fetch the details through the read API with your key's scopes.", "parameters": [ { "description": "The event's id (uuid). The same event delivered twice carries the same id: dedupe on it.", "in": "header", "name": "Quatlas-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The event's type: request.updated.", "in": "header", "name": "Quatlas-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "When this delivery was signed, in Unix seconds. Refuse one more than 5 minutes from your clock.", "in": "header", "name": "Quatlas-Timestamp", "required": true, "schema": { "type": "string" } }, { "description": "v1=.\")>, one value per valid secret, comma-separated.", "in": "header", "name": "Quatlas-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRequestUpdated" } } }, "required": true }, "responses": { "2XX": { "description": "Any 2xx within 10 seconds acknowledges the delivery." } }, "summary": "A request was changed" } }, "request.awarded": { "post": { "description": "To the request's owner and to the carrier whose offer won. Fetch the deal with GET /deals/{id} (deals:read). Every delivery is a POST with a JSON body and four headers: Quatlas-Event-Id (the event's id; dedupe on it, a delivery can arrive more than once), Quatlas-Event-Type, Quatlas-Timestamp (Unix seconds) and Quatlas-Signature: v1=, the lowercase hex HMAC-SHA256 of \".\" keyed with your subscription's signing secret (whsec_...). During a secret rotation the header carries one v1= value per valid secret, comma-separated; accept the delivery when any one matches. Compute the HMAC over the raw bytes you received, compare in constant time, and refuse a timestamp more than 5 minutes from your clock (replay). Answer any 2xx within 10 seconds to acknowledge; anything else, a redirect included, is retried after 1 minute, 5, 30, 2 hours, 6 and 12. After 20 failures in a row the subscription is switched off. Bodies are thin on purpose: fetch the details through the read API with your key's scopes.", "parameters": [ { "description": "The event's id (uuid). The same event delivered twice carries the same id: dedupe on it.", "in": "header", "name": "Quatlas-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The event's type: request.awarded.", "in": "header", "name": "Quatlas-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "When this delivery was signed, in Unix seconds. Refuse one more than 5 minutes from your clock.", "in": "header", "name": "Quatlas-Timestamp", "required": true, "schema": { "type": "string" } }, { "description": "v1=.\")>, one value per valid secret, comma-separated.", "in": "header", "name": "Quatlas-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRequestAwarded" } } }, "required": true }, "responses": { "2XX": { "description": "Any 2xx within 10 seconds acknowledges the delivery." } }, "summary": "A request was awarded and a deal opened" } }, "request.cancelled": { "post": { "description": "To the request's owner, cancelled in the app or through the API, with the reason given. Every delivery is a POST with a JSON body and four headers: Quatlas-Event-Id (the event's id; dedupe on it, a delivery can arrive more than once), Quatlas-Event-Type, Quatlas-Timestamp (Unix seconds) and Quatlas-Signature: v1=, the lowercase hex HMAC-SHA256 of \".\" keyed with your subscription's signing secret (whsec_...). During a secret rotation the header carries one v1= value per valid secret, comma-separated; accept the delivery when any one matches. Compute the HMAC over the raw bytes you received, compare in constant time, and refuse a timestamp more than 5 minutes from your clock (replay). Answer any 2xx within 10 seconds to acknowledge; anything else, a redirect included, is retried after 1 minute, 5, 30, 2 hours, 6 and 12. After 20 failures in a row the subscription is switched off. Bodies are thin on purpose: fetch the details through the read API with your key's scopes.", "parameters": [ { "description": "The event's id (uuid). The same event delivered twice carries the same id: dedupe on it.", "in": "header", "name": "Quatlas-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The event's type: request.cancelled.", "in": "header", "name": "Quatlas-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "When this delivery was signed, in Unix seconds. Refuse one more than 5 minutes from your clock.", "in": "header", "name": "Quatlas-Timestamp", "required": true, "schema": { "type": "string" } }, { "description": "v1=.\")>, one value per valid secret, comma-separated.", "in": "header", "name": "Quatlas-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRequestCancelled" } } }, "required": true }, "responses": { "2XX": { "description": "Any 2xx within 10 seconds acknowledges the delivery." } }, "summary": "A request was cancelled" } }, "deal.live": { "post": { "description": "To both parties: the closing room finished and the operation started. Every delivery is a POST with a JSON body and four headers: Quatlas-Event-Id (the event's id; dedupe on it, a delivery can arrive more than once), Quatlas-Event-Type, Quatlas-Timestamp (Unix seconds) and Quatlas-Signature: v1=, the lowercase hex HMAC-SHA256 of \".\" keyed with your subscription's signing secret (whsec_...). During a secret rotation the header carries one v1= value per valid secret, comma-separated; accept the delivery when any one matches. Compute the HMAC over the raw bytes you received, compare in constant time, and refuse a timestamp more than 5 minutes from your clock (replay). Answer any 2xx within 10 seconds to acknowledge; anything else, a redirect included, is retried after 1 minute, 5, 30, 2 hours, 6 and 12. After 20 failures in a row the subscription is switched off. Bodies are thin on purpose: fetch the details through the read API with your key's scopes.", "parameters": [ { "description": "The event's id (uuid). The same event delivered twice carries the same id: dedupe on it.", "in": "header", "name": "Quatlas-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The event's type: deal.live.", "in": "header", "name": "Quatlas-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "When this delivery was signed, in Unix seconds. Refuse one more than 5 minutes from your clock.", "in": "header", "name": "Quatlas-Timestamp", "required": true, "schema": { "type": "string" } }, { "description": "v1=.\")>, one value per valid secret, comma-separated.", "in": "header", "name": "Quatlas-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDealLive" } } }, "required": true }, "responses": { "2XX": { "description": "Any 2xx within 10 seconds acknowledges the delivery." } }, "summary": "A deal went live" } }, "shipment.milestone": { "post": { "description": "To both parties, with the milestone's type and time. Fetch the trail with GET /deals/{id}/tracking (tracking:read). Every delivery is a POST with a JSON body and four headers: Quatlas-Event-Id (the event's id; dedupe on it, a delivery can arrive more than once), Quatlas-Event-Type, Quatlas-Timestamp (Unix seconds) and Quatlas-Signature: v1=, the lowercase hex HMAC-SHA256 of \".\" keyed with your subscription's signing secret (whsec_...). During a secret rotation the header carries one v1= value per valid secret, comma-separated; accept the delivery when any one matches. Compute the HMAC over the raw bytes you received, compare in constant time, and refuse a timestamp more than 5 minutes from your clock (replay). Answer any 2xx within 10 seconds to acknowledge; anything else, a redirect included, is retried after 1 minute, 5, 30, 2 hours, 6 and 12. After 20 failures in a row the subscription is switched off. Bodies are thin on purpose: fetch the details through the read API with your key's scopes.", "parameters": [ { "description": "The event's id (uuid). The same event delivered twice carries the same id: dedupe on it.", "in": "header", "name": "Quatlas-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The event's type: shipment.milestone.", "in": "header", "name": "Quatlas-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "When this delivery was signed, in Unix seconds. Refuse one more than 5 minutes from your clock.", "in": "header", "name": "Quatlas-Timestamp", "required": true, "schema": { "type": "string" } }, { "description": "v1=.\")>, one value per valid secret, comma-separated.", "in": "header", "name": "Quatlas-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookShipmentMilestone" } } }, "required": true }, "responses": { "2XX": { "description": "Any 2xx within 10 seconds acknowledges the delivery." } }, "summary": "A milestone was recorded" } }, "shipment.eta_changed": { "post": { "description": "To both parties. Read the new estimate with GET /deals/{id}/tracking (tracking:read). Every delivery is a POST with a JSON body and four headers: Quatlas-Event-Id (the event's id; dedupe on it, a delivery can arrive more than once), Quatlas-Event-Type, Quatlas-Timestamp (Unix seconds) and Quatlas-Signature: v1=, the lowercase hex HMAC-SHA256 of \".\" keyed with your subscription's signing secret (whsec_...). During a secret rotation the header carries one v1= value per valid secret, comma-separated; accept the delivery when any one matches. Compute the HMAC over the raw bytes you received, compare in constant time, and refuse a timestamp more than 5 minutes from your clock (replay). Answer any 2xx within 10 seconds to acknowledge; anything else, a redirect included, is retried after 1 minute, 5, 30, 2 hours, 6 and 12. After 20 failures in a row the subscription is switched off. Bodies are thin on purpose: fetch the details through the read API with your key's scopes.", "parameters": [ { "description": "The event's id (uuid). The same event delivered twice carries the same id: dedupe on it.", "in": "header", "name": "Quatlas-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The event's type: shipment.eta_changed.", "in": "header", "name": "Quatlas-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "When this delivery was signed, in Unix seconds. Refuse one more than 5 minutes from your clock.", "in": "header", "name": "Quatlas-Timestamp", "required": true, "schema": { "type": "string" } }, { "description": "v1=.\")>, one value per valid secret, comma-separated.", "in": "header", "name": "Quatlas-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookShipmentEtaChanged" } } }, "required": true }, "responses": { "2XX": { "description": "Any 2xx within 10 seconds acknowledges the delivery." } }, "summary": "The delivery estimate changed" } }, "shipment.delivered": { "post": { "description": "To both parties: the run ended with the goods handed over, in whole or in part. Every delivery is a POST with a JSON body and four headers: Quatlas-Event-Id (the event's id; dedupe on it, a delivery can arrive more than once), Quatlas-Event-Type, Quatlas-Timestamp (Unix seconds) and Quatlas-Signature: v1=, the lowercase hex HMAC-SHA256 of \".\" keyed with your subscription's signing secret (whsec_...). During a secret rotation the header carries one v1= value per valid secret, comma-separated; accept the delivery when any one matches. Compute the HMAC over the raw bytes you received, compare in constant time, and refuse a timestamp more than 5 minutes from your clock (replay). Answer any 2xx within 10 seconds to acknowledge; anything else, a redirect included, is retried after 1 minute, 5, 30, 2 hours, 6 and 12. After 20 failures in a row the subscription is switched off. Bodies are thin on purpose: fetch the details through the read API with your key's scopes.", "parameters": [ { "description": "The event's id (uuid). The same event delivered twice carries the same id: dedupe on it.", "in": "header", "name": "Quatlas-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The event's type: shipment.delivered.", "in": "header", "name": "Quatlas-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "When this delivery was signed, in Unix seconds. Refuse one more than 5 minutes from your clock.", "in": "header", "name": "Quatlas-Timestamp", "required": true, "schema": { "type": "string" } }, { "description": "v1=.\")>, one value per valid secret, comma-separated.", "in": "header", "name": "Quatlas-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookShipmentDelivered" } } }, "required": true }, "responses": { "2XX": { "description": "Any 2xx within 10 seconds acknowledges the delivery." } }, "summary": "The shipment was delivered" } }, "document.uploaded": { "post": { "description": "To both parties, with the document's id and category only. List and download with documents:read. Every delivery is a POST with a JSON body and four headers: Quatlas-Event-Id (the event's id; dedupe on it, a delivery can arrive more than once), Quatlas-Event-Type, Quatlas-Timestamp (Unix seconds) and Quatlas-Signature: v1=, the lowercase hex HMAC-SHA256 of \".\" keyed with your subscription's signing secret (whsec_...). During a secret rotation the header carries one v1= value per valid secret, comma-separated; accept the delivery when any one matches. Compute the HMAC over the raw bytes you received, compare in constant time, and refuse a timestamp more than 5 minutes from your clock (replay). Answer any 2xx within 10 seconds to acknowledge; anything else, a redirect included, is retried after 1 minute, 5, 30, 2 hours, 6 and 12. After 20 failures in a row the subscription is switched off. Bodies are thin on purpose: fetch the details through the read API with your key's scopes.", "parameters": [ { "description": "The event's id (uuid). The same event delivered twice carries the same id: dedupe on it.", "in": "header", "name": "Quatlas-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The event's type: document.uploaded.", "in": "header", "name": "Quatlas-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "When this delivery was signed, in Unix seconds. Refuse one more than 5 minutes from your clock.", "in": "header", "name": "Quatlas-Timestamp", "required": true, "schema": { "type": "string" } }, { "description": "v1=.\")>, one value per valid secret, comma-separated.", "in": "header", "name": "Quatlas-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDocumentUploaded" } } }, "required": true }, "responses": { "2XX": { "description": "Any 2xx within 10 seconds acknowledges the delivery." } }, "summary": "A document was uploaded to a deal" } }, "cost.approved": { "post": { "description": "To both parties. Read the costs with GET /deals/{id}/costs (costs:read). Every delivery is a POST with a JSON body and four headers: Quatlas-Event-Id (the event's id; dedupe on it, a delivery can arrive more than once), Quatlas-Event-Type, Quatlas-Timestamp (Unix seconds) and Quatlas-Signature: v1=, the lowercase hex HMAC-SHA256 of \".\" keyed with your subscription's signing secret (whsec_...). During a secret rotation the header carries one v1= value per valid secret, comma-separated; accept the delivery when any one matches. Compute the HMAC over the raw bytes you received, compare in constant time, and refuse a timestamp more than 5 minutes from your clock (replay). Answer any 2xx within 10 seconds to acknowledge; anything else, a redirect included, is retried after 1 minute, 5, 30, 2 hours, 6 and 12. After 20 failures in a row the subscription is switched off. Bodies are thin on purpose: fetch the details through the read API with your key's scopes.", "parameters": [ { "description": "The event's id (uuid). The same event delivered twice carries the same id: dedupe on it.", "in": "header", "name": "Quatlas-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The event's type: cost.approved.", "in": "header", "name": "Quatlas-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "When this delivery was signed, in Unix seconds. Refuse one more than 5 minutes from your clock.", "in": "header", "name": "Quatlas-Timestamp", "required": true, "schema": { "type": "string" } }, { "description": "v1=.\")>, one value per valid secret, comma-separated.", "in": "header", "name": "Quatlas-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCostApproved" } } }, "required": true }, "responses": { "2XX": { "description": "Any 2xx within 10 seconds acknowledges the delivery." } }, "summary": "An additional cost was approved" } }, "invoice.issued": { "post": { "description": "To the invoice's recipient only: each side's fee is private. Every delivery is a POST with a JSON body and four headers: Quatlas-Event-Id (the event's id; dedupe on it, a delivery can arrive more than once), Quatlas-Event-Type, Quatlas-Timestamp (Unix seconds) and Quatlas-Signature: v1=, the lowercase hex HMAC-SHA256 of \".\" keyed with your subscription's signing secret (whsec_...). During a secret rotation the header carries one v1= value per valid secret, comma-separated; accept the delivery when any one matches. Compute the HMAC over the raw bytes you received, compare in constant time, and refuse a timestamp more than 5 minutes from your clock (replay). Answer any 2xx within 10 seconds to acknowledge; anything else, a redirect included, is retried after 1 minute, 5, 30, 2 hours, 6 and 12. After 20 failures in a row the subscription is switched off. Bodies are thin on purpose: fetch the details through the read API with your key's scopes.", "parameters": [ { "description": "The event's id (uuid). The same event delivered twice carries the same id: dedupe on it.", "in": "header", "name": "Quatlas-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The event's type: invoice.issued.", "in": "header", "name": "Quatlas-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "When this delivery was signed, in Unix seconds. Refuse one more than 5 minutes from your clock.", "in": "header", "name": "Quatlas-Timestamp", "required": true, "schema": { "type": "string" } }, { "description": "v1=.\")>, one value per valid secret, comma-separated.", "in": "header", "name": "Quatlas-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInvoiceIssued" } } }, "required": true }, "responses": { "2XX": { "description": "Any 2xx within 10 seconds acknowledges the delivery." } }, "summary": "A commission invoice was issued to you" } }, "webhook.test": { "post": { "description": "Sent when someone presses \"send test event\" for the subscription, whatever event types it names. Always livemode false. Every delivery is a POST with a JSON body and four headers: Quatlas-Event-Id (the event's id; dedupe on it, a delivery can arrive more than once), Quatlas-Event-Type, Quatlas-Timestamp (Unix seconds) and Quatlas-Signature: v1=, the lowercase hex HMAC-SHA256 of \".\" keyed with your subscription's signing secret (whsec_...). During a secret rotation the header carries one v1= value per valid secret, comma-separated; accept the delivery when any one matches. Compute the HMAC over the raw bytes you received, compare in constant time, and refuse a timestamp more than 5 minutes from your clock (replay). Answer any 2xx within 10 seconds to acknowledge; anything else, a redirect included, is retried after 1 minute, 5, 30, 2 hours, 6 and 12. After 20 failures in a row the subscription is switched off. Bodies are thin on purpose: fetch the details through the read API with your key's scopes.", "parameters": [ { "description": "The event's id (uuid). The same event delivered twice carries the same id: dedupe on it.", "in": "header", "name": "Quatlas-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The event's type: webhook.test.", "in": "header", "name": "Quatlas-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "When this delivery was signed, in Unix seconds. Refuse one more than 5 minutes from your clock.", "in": "header", "name": "Quatlas-Timestamp", "required": true, "schema": { "type": "string" } }, { "description": "v1=.\")>, one value per valid secret, comma-separated.", "in": "header", "name": "Quatlas-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookWebhookTest" } } }, "required": true }, "responses": { "2XX": { "description": "Any 2xx within 10 seconds acknowledges the delivery." } }, "summary": "A test event" } } } }