BOOKING API
Qualification, identity and revisions
Foryn accepts carrier-confirmed commercial booking state, not every booking request or operational movement.
What qualifies
- CARRIER_CONFIRMED is the default qualification milestone; confirmedAt and sourceEvidenceId are required.
- EQUIVALENT_CONFIRMED is accepted only when the integration credential is explicitly authorized for equivalent milestones.
- The API trusts a credentialed forwarder's source attestation; it does not independently verify a carrier's digital signature.
- A booking request, EDI interchange acknowledgment, vessel departure or completed transport document is not automatically booking confirmation.
Stable identity
sourceBookingId is stable within the authenticated source system. carrierBookingReference and carrierId must also remain consistent when updating that source booking.
eventId identifies the delivered message, revision identifies the booking state. These are different fields and must not be substituted for each other.
The API uses a tenant/source/booking identity boundary and serializable transactions. Exactly repeating an event with the same eventId and content is reported as DUPLICATE_EVENT.
Lifecycle response states
| data.status | Meaning | Recommended client action |
|---|---|---|
| ACCEPTED | Booking assessed; no consequential finding | Acknowledge and continue |
| EXCEPTION | Evidence-backed consequential finding | Route to operations if configured |
| INSUFFICIENT_EVIDENCE | Commercial match or precedence unresolved | Review source/reference completeness |
| OUT_OF_COVERAGE | Lane not included in subscribed booking coverage | Do not retry unchanged as a failure |
| NOT_QUALIFIED | No permitted confirmed milestone established | Retain at source until qualified |
| DUPLICATE_EVENT | Exact event ID and payload already recorded | Treat as idempotent acknowledgment |
| UNCHANGED_SNAPSHOT | No new commercial state; revision may advance | Do not count twice |
| STALE_REVISION | Older than recorded revision | Stop replay or reconcile ordering |
| CANCELLED | Previously qualified booking made inactive | Remove active volume from source-side view |
Amendments and cancellation
- Submit AMENDED only when updated facts reflect an accepted, commercially qualified booking state.
- An amendment uses the same sourceBookingId with a greater monotonic revision and a different eventId.
- For cancellation, submit action CANCELLED with sourceBookingId, greater revision and source document identity; do not include the booking property.
- Previously canceled bookings cannot be silently reactivated. Explicit reinstatement policy is not implemented.
API v1 · Fictional examples · Production access requires coordinated onboarding · OpenAPI contract ↗