Owners create keys under API keys. The plaintext ss_live_… token is shown once. Give each workload only the abilities it needs.
Developer implementation / API v1
Put a deterministic EDI gate in your document flow.
Create a scoped key, send exact bytes with an idempotency key, then route only cleared output. Use the same evidence ledger for mapping holds, delivery receipts and acknowledgements.
01 / Getting started
One key. One stable request identity.
Do not normalize separators or whitespace before sending EDI. Hashes, release identity and replay safety bind to the bytes received.
Reuse the same 8–128 character Idempotency-Key only for the same request. A changed body under that key returns HTTP 409.
Request
curl --request POST 'https://shipmentsentry.com/api/v1/gate' \
--header 'Authorization: Bearer ss_live_REPLACE_ME' \
--header 'Idempotency-Key: shipment-000184' \
--header 'Content-Type: application/json' \
--data '{
"format": "x12-856",
"file_name": "ASN-000184.edi",
"retain_payload": false,
"payload": "ISA*00*...~IEA*1*000000184~"
}'Response
{
"data": {
"id": "01J...",
"decision": "cleared",
"status": "ready",
"score": 100,
"counts": {"errors": 0, "warnings": 0, "passed": 18}
},
"meta": {"replayed": false, "request_id": "..."}
}02 / Discover capabilities
Do not hard-code workspace IDs or format lists.
Every active scoped key can read discovery endpoints. Start with capabilities, then fetch partner packs and the active rule profiles owned by that key’s workspace. Rule-profile IDs are tenant-scoped and must never be copied between customers.
GET /api/v1/capabilities
curl 'https://shipmentsentry.com/api/v1/capabilities' \
--header 'Authorization: Bearer ss_live_REPLACE_ME'
GET /api/v1/partner-packs
GET /api/v1/rule-profiles{
"data": {
"api_version": "v1",
"formats": {"gate": ["x12-auto", "x12-856", "..."]},
"limits": {
"max_request_bytes": 5242880,
"max_batch_documents": 1000,
"requests_per_minute": 120
}
}
}03 / Validate and gate
Use POST /api/v1/gate for one document.
The response returns a release decision, format, score, stable finding codes, exact locations, evidence classes and a request ID. Supported inputs include X12 810/824/846/850/855/856/997/999, Vendor Shipments JSON, EDIFACT DESADV, Peppol UBL and ZUGFeRD CII XML.
Retention boundary
Authenticated API payloads are not retained unless retain_payload is explicitly true. Structured findings and the content hash remain as operational evidence.
04 / Partner batches
Convert and route up to 1,000 files per call.
Every document declares a workspace partner code. A valid active route can convert source formats, validate rendered output and stage exact cleared bytes. An unknown partner or unconfirmed source map quarantines only that document and returns a hold ID.
- ✓ Ability:
gate:write - ✓ 1–1,000 documents within the 5 MiB request limit
- ✓ Required per file: partner_code, payload, file_name
- ✓ Idempotent response and per-file decision
{
"name": "Warehouse close 2026-07-20",
"documents": [{
"partner_code": "RETAILER_UK",
"format": "csv",
"file_name": "shipment-184.csv",
"payload": "po,sku,qty..."
}]
}05 / Mappings and held documents
Resolve identities before release.
The tenant registry holds partner, customer, supplier, store, warehouse and product identities—including GLN, GS1 company prefix, GTIN/EAN/UPC, SKU and partner-specific codes. Date-effective mappings can be scoped to a partner route.
POST /api/v1/mapping-resolutions
Authorization: Bearer ss_live_REPLACE_ME
{
"kind": "identifier",
"entity_type": "product",
"scheme": "GTIN",
"value": "05012345678903",
"partner_code": "RETAILER_UK",
"on": "2026-07-20"
}Held source bytes are encrypted. Release requires the confirmed heading signature and mapping recipe still to match; this prevents a stale decision from releasing changed input.
06 / Result webhooks
Verify the raw body before parsing JSON.
Callbacks use the Standard Webhooks HMAC-SHA256 shape. Read webhook-id, webhook-timestamp, webhook-signature and webhook-event. Decode the bytes after the whsec_ prefix, sign the exact raw request body, and compare signatures in constant time.
signed_content = webhook_id + "." + timestamp + "." + raw_body
expected = base64(hmac_sha256(decoded_whsec_key, signed_content))
received = value after "v1," in webhook-signature
constant_time_compare(expected, received){
"id": "evt_01j...",
"type": "partner.batch.completed",
"timestamp": "2026-07-21T12:00:00Z",
"data": {"batch_id": "01J...", "counts": {"cleared": 4}}
}Replay rule
Reject timestamps outside your chosen tolerance (five minutes is a common default), persist each webhook-id, and return a 2xx only after durable acceptance. Duplicate IDs must be a no-op. Non-2xx responses retry with backoff; repeated terminal failures can disable the endpoint.
07 / AS2 and Peppol
Delivery proof is not business acceptance.
AS2
Configure the HTTPS endpoint, AS2-From, AS2-To, signing certificate, matching private key and the partner certificate used to verify signed MDNs; optionally add the partner encryption certificate. Shipment Sentry signs with SHA-256, can encrypt with AES-256-CBC, requests a signed MDN and verifies the returned SHA-256 MIC before marking delivery.
The route UI exposes only non-secret SHA-256 certificate fingerprints and expiry health. Invalid or expired required certificates block go-live readiness, and scheduled checks alert operators before expiry. Certificate replacement remains an explicit operator action; Shipment Sentry does not rotate partner certificates automatically.
Protocol reference: RFC 4130.
Peppol
Shipment Sentry integrates with your certified Peppol access point over its authenticated REST adapter. Configure sender and receiver participant IDs, document type and process ID. Network membership, Peppol PKI, SMP/SML discovery and AS4 conformance remain the certified access point’s responsibility.
Network reference: OpenPeppol AS4 profile.
08 / Business Central
A durable ERP document loop.
The self-serve connector verifies the exact company, pulls changed sales orders, sales invoices, purchase orders, purchase invoices, customers, vendors and items, and can push the four document resources with ETag concurrency. Webhook receipts are deduplicated before queued pulls.
- 1 / Save
Encrypted Microsoft Entra credentials.
- 2 / Verify
Fail closed unless the company resolves.
- 3 / Sync
Pull cursor-based changes or push mapped records.
- 4 / Subscribe
Handshake, clientState validation and scheduled renewal.
Implementation reference: Microsoft Business Central webhooks.
09 / Errors, limits and support boundary
Fail closed and keep the reason actionable.
The complete authenticated JSON body is limited to 5 MiB before parsing and each API key is limited to 120 requests per minute. A partner batch may contain 1–1,000 documents only while the complete JSON request remains inside that byte limit.
| Status | Meaning | Client action |
|---|---|---|
| 401 | Token missing, revoked, expired or lacks the endpoint ability. | Use a correctly scoped live key. |
| 409 | Idempotency key reused with different content or original work is active. | Do not mutate a retried request. |
| 413 | The complete JSON request exceeded the byte limit. | Split the request or reduce document size before retrying. |
| 422 | Schema, format, mapping, document validation or workspace quota failure. | Read the field errors or stable finding codes; increase the plan limit for exhausted quota. |
| 429 | The per-IP or per-key request rate was exceeded. | Honor Retry-After and retry with backoff. |
A cleared preflight proves only that the configured rule surface found no blocking issue. Current partner guides, network rules, country profiles and end-to-end certification remain controlling.