{"openapi":"3.1.0","info":{"title":"Shipment Sentry API","version":"1.1.0","description":"Tenant-scoped EDI validation, conversion, mapping, shipment evidence and acknowledgement APIs. Requests are limited to 5242880 bytes and 120 requests per minute per key. Partner acceptance remains controlled by current partner specifications."},"externalDocs":{"description":"Implementation guide","url":"https:\/\/shipmentsentry.com\/developers"},"servers":[{"url":"https:\/\/shipmentsentry.com\/api\/v1","description":"Production API v1"}],"tags":[{"name":"Discovery","description":"Formats, limits, partner packs and tenant-owned rule profiles."},{"name":"Validation","description":"Single-document and shipment-evidence validation."},{"name":"Routing","description":"Multi-partner conversion and routing."},{"name":"Operations","description":"Acknowledgement ingestion and mapping resolution."}],"paths":{"\/capabilities":{"get":{"operationId":"getCapabilities","tags":["Discovery"],"summary":"Discover formats, limits and related API resources","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CapabilitiesResponse"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"429":{"$ref":"#\/components\/responses\/RateLimited"}}}},"\/partner-packs":{"get":{"operationId":"listPartnerPacks","tags":["Discovery"],"summary":"List available partner-pack capability declarations","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/PartnerPackListResponse"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"429":{"$ref":"#\/components\/responses\/RateLimited"}}}},"\/rule-profiles":{"get":{"operationId":"listRuleProfiles","tags":["Discovery"],"summary":"List active operational rule profiles owned by this workspace","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/RuleProfileListResponse"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"429":{"$ref":"#\/components\/responses\/RateLimited"}}}},"\/gate":{"post":{"operationId":"gateDocument","tags":["Validation"],"summary":"Validate and gate one EDI or invoice document","security":[{"bearerAuth":[]}],"x-required-ability":"gate:write","requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/GateRequest"},"example":{"format":"x12-856","file_name":"ASN-000184.edi","retain_payload":false,"payload":"ISA*00*...~IEA*1*000000184~"}}}},"responses":{"200":{"description":"Successful response or idempotent replay","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/GateResponse"}}}},"201":{"description":"Created","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/GateResponse"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"413":{"$ref":"#\/components\/responses\/PayloadTooLarge"},"422":{"$ref":"#\/components\/responses\/ValidationError"},"429":{"$ref":"#\/components\/responses\/RateLimited"},"409":{"$ref":"#\/components\/responses\/Conflict"}},"parameters":[{"$ref":"#\/components\/parameters\/IdempotencyKey"}]}},"\/partner-batches":{"post":{"operationId":"createPartnerBatch","tags":["Routing"],"summary":"Convert, validate and route 1 to 1,000 partner documents","security":[{"bearerAuth":[]}],"x-required-ability":"gate:write","requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/PartnerBatchRequest"},"example":{"name":"Warehouse close 2026-07-21","documents":[{"partner_code":"RETAILER_UK","format":"csv","file_name":"shipment-184.csv","payload":"po,sku,qty\nPO184,SKU1,4"}]}}}},"responses":{"200":{"description":"Successful response or idempotent replay","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/PartnerBatchResponse"}}}},"201":{"description":"Created","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/PartnerBatchResponse"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"413":{"$ref":"#\/components\/responses\/PayloadTooLarge"},"422":{"$ref":"#\/components\/responses\/ValidationError"},"429":{"$ref":"#\/components\/responses\/RateLimited"},"409":{"$ref":"#\/components\/responses\/Conflict"}},"parameters":[{"$ref":"#\/components\/parameters\/IdempotencyKey"}]}},"\/shipment-cases":{"post":{"operationId":"createShipmentCase","tags":["Validation"],"summary":"Evaluate shipment evidence against a tenant-owned rule profile","security":[{"bearerAuth":[]}],"x-required-ability":"shipments:write","requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ShipmentCaseRequest"},"example":{"external_reference":"LOAD-184","retailer_key":"amazon_vendor","rule_profile_id":"01JREPLACE_WITH_DISCOVERED_PROFILE","order":{"purchase_order":"PO184","items":[{"item_id":"SKU1","quantity":4,"uom":"EA"}]},"asn":{"reference":"LOAD-184","purchase_order":"PO184","items":[{"item_id":"SKU1","quantity":4,"uom":"EA"}]},"actual":{"reference":"LOAD-184","purchase_order":"PO184","items":[{"item_id":"SKU1","quantity":4,"uom":"EA"}]}}}}},"responses":{"200":{"description":"Successful response or idempotent replay","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ShipmentCaseResponse"}}}},"201":{"description":"Created","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ShipmentCaseResponse"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"413":{"$ref":"#\/components\/responses\/PayloadTooLarge"},"422":{"$ref":"#\/components\/responses\/ValidationError"},"429":{"$ref":"#\/components\/responses\/RateLimited"},"409":{"$ref":"#\/components\/responses\/Conflict"}},"parameters":[{"$ref":"#\/components\/parameters\/IdempotencyKey"}]}},"\/acknowledgements":{"post":{"operationId":"ingestAcknowledgement","tags":["Operations"],"summary":"Ingest an X12 or EDIFACT acknowledgement","security":[{"bearerAuth":[]}],"x-required-ability":"acknowledgements:write","requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AcknowledgementRequest"},"example":{"payload":"ISA*00*...~ST*997*0001~...~SE*...~IEA*1*...~"}}}},"responses":{"200":{"description":"Successful response or idempotent replay","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AcknowledgementResponse"}}}},"201":{"description":"Created","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AcknowledgementResponse"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"413":{"$ref":"#\/components\/responses\/PayloadTooLarge"},"422":{"$ref":"#\/components\/responses\/ValidationError"},"429":{"$ref":"#\/components\/responses\/RateLimited"}}}},"\/mapping-resolutions":{"post":{"operationId":"resolveMapping","tags":["Operations"],"summary":"Resolve a tenant-owned identifier or code mapping","security":[{"bearerAuth":[]}],"x-required-ability":"mappings:read","requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/MappingResolutionRequest"},"example":{"kind":"identifier","entity_type":"product","scheme":"GTIN","value":"05012345678903","partner_code":"RETAILER_UK","on":"2026-07-21"}}}},"responses":{"200":{"description":"Successful response or idempotent replay","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/MappingResolutionResponse"}}}},"201":{"description":"Created","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/MappingResolutionResponse"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"413":{"$ref":"#\/components\/responses\/PayloadTooLarge"},"422":{"$ref":"#\/components\/responses\/ValidationError"},"429":{"$ref":"#\/components\/responses\/RateLimited"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"ss_live_*","description":"A scoped workspace key shown once when it is created."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"description":"A stable 8 to 128 character identity. Reuse it only for an identical request; changed content returns 409.","schema":{"type":"string","minLength":8,"maxLength":128},"example":"warehouse-dispatch-000184"}},"responses":{"Unauthorized":{"description":"Missing, invalid, expired, revoked or under-scoped API key.","headers":{"WWW-Authenticate":{"schema":{"type":"string"}}},"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"Conflict":{"description":"Idempotency key conflict, duplicate external reference or original work still processing.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"ValidationError":{"description":"Request shape, identifier, mapping, document validation or workspace document quota failed.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ValidationError"}}}},"PayloadTooLarge":{"description":"The raw JSON request body exceeded the advertised byte limit.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"RateLimited":{"description":"The per-IP authentication ceiling or authenticated per-key request rate was exceeded.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":0}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}}},"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}},"schemas":{"Error":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}}},"ValidationError":{"type":"object","required":["message","errors"],"properties":{"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}},"Counts":{"type":"object","required":["errors","warnings"],"properties":{"errors":{"type":"integer","minimum":0},"warnings":{"type":"integer","minimum":0},"passed":{"type":"integer","minimum":0}}},"Finding":{"type":"object","required":["code","severity","title","message"],"properties":{"code":{"type":"string"},"severity":{"type":"string","enum":["error","warning","pass"]},"title":{"type":"string"},"message":{"type":"string"},"location":{"type":"string"},"evidence_class":{"type":"string"},"source_label":{"type":"string"},"source_url":{"type":"string"},"suggestion":{"type":["string","null"]}},"additionalProperties":true},"ResponseMeta":{"type":"object","properties":{"remaining":{"type":"integer","minimum":0},"replayed":{"type":"boolean"},"request_id":{"type":"string","format":"uuid"}}},"GateRequest":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"string","maxLength":5242880},"format":{"type":["string","null"],"enum":["x12-auto","x12-810","x12-824","x12-846","x12-850","x12-855","x12-856","x12-997","x12-999","sp-api-json","edifact-desadv","peppol-bis-billing","zugferd-factur-x",null]},"file_name":{"type":["string","null"],"maxLength":180},"retain_payload":{"type":"boolean","default":false}}},"GateResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","decision","status","format","score","counts","findings"],"properties":{"id":{"type":"string"},"decision":{"type":"string"},"status":{"type":"string"},"format":{"type":"string"},"score":{"type":"integer","minimum":0,"maximum":100},"counts":{"$ref":"#\/components\/schemas\/Counts"},"findings":{"type":"array","items":{"$ref":"#\/components\/schemas\/Finding"}},"summary":{"type":"object","additionalProperties":true}}},"meta":{"$ref":"#\/components\/schemas\/ResponseMeta"}}},"PartnerBatchRequest":{"type":"object","additionalProperties":false,"required":["documents"],"properties":{"name":{"type":["string","null"],"maxLength":180},"documents":{"type":"array","minItems":1,"maxItems":1000,"items":{"type":"object","additionalProperties":false,"required":["partner_code","payload","file_name"],"properties":{"partner_code":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{1,31}$"},"payload":{"type":"string"},"format":{"type":["string","null"],"enum":["source-auto","canonical-shipment-json","csv","tsv","xlsx","xls","json-source","xml","idoc","txt","ascii","x12-auto","x12-810","x12-824","x12-846","x12-850","x12-855","x12-856","x12-997","x12-999","sp-api-json","edifact-desadv","peppol-bis-billing","zugferd-factur-x",null]},"file_name":{"type":"string","maxLength":180}}}}}},"PartnerBatchResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["batch_id","status","counts","items"],"properties":{"batch_id":{"type":"string"},"status":{"type":"string"},"counts":{"type":"object","additionalProperties":{"type":"integer"}},"items":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"meta":{"$ref":"#\/components\/schemas\/ResponseMeta"}}},"ShipmentCaseRequest":{"type":"object","additionalProperties":false,"required":["external_reference","retailer_key","rule_profile_id","order","asn","actual"],"properties":{"external_reference":{"type":"string","maxLength":128},"retailer_key":{"type":"string","description":"Use GET \/partner-packs to discover supported values."},"rule_profile_id":{"type":"string","maxLength":26,"description":"Use GET \/rule-profiles; IDs are tenant-scoped."},"order":{"$ref":"#\/components\/schemas\/OrderEvidence"},"asn":{"$ref":"#\/components\/schemas\/ShipmentEvidence"},"actual":{"$ref":"#\/components\/schemas\/ShipmentEvidence"}}},"EvidenceItem":{"type":"object","additionalProperties":false,"required":["item_id","quantity"],"properties":{"item_id":{"type":"string","maxLength":128},"quantity":{"type":"number","exclusiveMinimum":0},"uom":{"type":"string","pattern":"^[A-Za-z0-9]{1,8}$"},"container_id":{"type":["string","null"],"maxLength":128}}},"ContainerEvidence":{"type":"object","additionalProperties":false,"required":["container_id"],"properties":{"container_id":{"type":"string","maxLength":128},"carton_count":{"type":"integer","minimum":0},"weight":{"type":["number","null"],"minimum":0},"type":{"type":["string","null"],"maxLength":64}}},"OrderEvidence":{"type":"object","additionalProperties":false,"required":["purchase_order","items"],"properties":{"purchase_order":{"type":"string","maxLength":128},"items":{"type":"array","minItems":1,"maxItems":1000,"items":{"$ref":"#\/components\/schemas\/EvidenceItem"}}}},"ShipmentEvidence":{"type":"object","additionalProperties":false,"required":["reference","purchase_order","items"],"properties":{"reference":{"type":"string","maxLength":128},"purchase_order":{"type":"string","maxLength":128},"items":{"type":"array","minItems":1,"maxItems":1000,"items":{"$ref":"#\/components\/schemas\/EvidenceItem"}},"containers":{"type":"array","maxItems":1000,"items":{"$ref":"#\/components\/schemas\/ContainerEvidence"}},"ship_date":{"type":["string","null"],"format":"date"},"receive_by":{"type":["string","null"],"format":"date"}}},"ShipmentCaseResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","additionalProperties":true},"meta":{"$ref":"#\/components\/schemas\/ResponseMeta"}}},"AcknowledgementRequest":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"string","maxLength":5242880}}},"AcknowledgementResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":true}}},"MappingResolutionRequest":{"type":"object","additionalProperties":false,"required":["kind","value"],"properties":{"kind":{"type":"string","enum":["identifier","code"]},"entity_type":{"type":"string","enum":["party","location","product"]},"scheme":{"type":"string","enum":["GLN","VAT","TAX_ID","PEPPOL_PARTICIPANT","DUNS","SCAC","PARTNER_ALIAS","UNLOCODE","STORE_CODE","WAREHOUSE_CODE","GTIN","EAN","UPC","BUYER_ITEM","SUPPLIER_ITEM","MANUFACTURER_ITEM","PARTNER_ARTICLE","SKU"]},"value":{"type":"string","maxLength":191},"code_list":{"type":"string","enum":["UOM","PACK","TAX_CATEGORY","CURRENCY","PAYMENT_TERMS","SHIPMENT_METHOD","SERVICE_LEVEL","CARRIER","INCOTERMS","DOCUMENT_PURPOSE","STATUS","QUALIFIER"]},"partner_code":{"type":["string","null"],"maxLength":32},"on":{"type":["string","null"],"format":"date"}}},"MappingResolutionResponse":{"type":"object","required":["data"],"properties":{"data":{"type":["object","null"],"additionalProperties":true}}},"CapabilitiesResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["api_version","formats","abilities","limits","discovery","webhook_signing"],"properties":{"api_version":{"type":"string","const":"v1"},"formats":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"abilities":{"type":"array","items":{"type":"string","enum":["gate:write","acknowledgements:write","shipments:write","mappings:read"]}},"limits":{"type":"object","additionalProperties":{"type":"integer"}},"discovery":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"webhook_signing":{"type":"object","additionalProperties":true}}}}},"PartnerPack":{"type":"object","required":["key","label","retailer_key","status","standard","version","default_output","source_urls"],"properties":{"key":{"type":"string"},"label":{"type":"string"},"retailer_key":{"type":"string"},"status":{"type":"string","enum":["verified_public","partner_guide_required"]},"standard":{"type":"string"},"version":{"type":"integer","minimum":1},"default_output":{"type":"string"},"source_urls":{"type":"array","items":{"type":"string","format":"uri"}}}},"PartnerPackListResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/PartnerPack"}},"meta":{"$ref":"#\/components\/schemas\/ListMeta"}}},"RuleProfile":{"type":"object","required":["id","name","profile_key","version","retailer_key","rules"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"profile_key":{"type":"string"},"version":{"type":"integer","minimum":1},"retailer_key":{"type":"string"},"rules":{"type":"object","additionalProperties":true}}},"RuleProfileListResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/RuleProfile"}},"meta":{"$ref":"#\/components\/schemas\/ListMeta"}}},"ListMeta":{"type":"object","required":["count"],"properties":{"count":{"type":"integer","minimum":0}}}}}}