{ "openapi": "3.1.0", "info": { "title": "Foryn Ocean Booking Intelligence API", "version": "1.0.0", "description": "Implemented Ocean HTTP API. API paths are /api/ocean/v1. Booking document schema version is foryn.ocean.booking.v1. External production base URLs and credentials require direct onboarding. No public sandbox or production availability is represented by this specification." }, "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "tags": [ { "name": "Bookings", "description": "Authenticated booking qualification and commercial assessment" }, { "name": "Messages", "description": "Partner-profile message normalization or partial event extract" }, { "name": "Resolutions", "description": "Optional authorized exception resolution" } ], "paths": { "/api/ocean/v1/bookings": { "post": { "tags": [ "Bookings" ], "operationId": "submitOceanBooking", "summary": "Submit a qualified booking or update", "description": "Requires intake scope. The authenticated credential determines tenant and source. A 200 response may indicate ACCEPTED, EXCEPTION, INSUFFICIENT_EVIDENCE, OUT_OF_COVERAGE, DUPLICATE_EVENT, UNCHANGED_SNAPSHOT, STALE_REVISION, NOT_QUALIFIED or CANCELLED. Never infer financial exposure from null fields.", "security": [ { "OceanIntegrationBearer": [] } ], "requestBody": { "required": true, "description": "Exactly one canonical booking event, 64 KiB maximum.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OceanBookingEvent" }, "example": { "schemaVersion": "foryn.ocean.booking.v1", "eventId": "synthetic-event-0001", "revision": 1, "action": "CONFIRMED", "sourceBookingId": "synthetic-source-booking-001", "booking": { "carrierBookingReference": "SYNTHETIC-CBR-001", "carrierId": "fictional-carrier", "originUnlocode": "CNSHG", "destinationUnlocode": "USLAX", "bookingDate": "2026-10-12", "equipmentType": "40HC", "quantity": 2, "commodity": "GENERAL", "namedAccountId": "account-1", "agreementReference": "agreement-1", "serviceType": "contract", "qualification": { "milestone": "CARRIER_CONFIRMED", "confirmedAt": "2026-10-12T12:00:00.000Z", "sourceEvidenceId": "synthetic-confirmation-001" } }, "source": { "recordId": "synthetic-source-row-1", "documentId": "fictional-booking-document", "documentVersion": "1" } } } } }, "responses": { "200": { "description": "Delivery accepted for processing; inspect data.status and data.assessment.", "headers": { "x-request-id": { "description": "Correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingSuccess" }, "example": { "ok": true, "data": { "accepted": true, "status": "ACCEPTED", "bookingReference": "synthetic-source-booking-001", "sourceRevision": 1, "assessment": { "status": "ASSESSED", "issues": [], "matchedRateIds": [ "base-amended" ], "quantity": { "status": "COUNTED", "amount": 2, "unit": "FEU" }, "reference": { "id": "agreement-1", "version": 1, "documentId": "fictional-sc-2026-01", "documentVersion": "synthetic-v2" }, "findings": [] }, "exceptions": [] } } } } }, "400": { "description": "Malformed or invalid JSON payload", "headers": { "x-request-id": { "description": "Correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "No valid bearer token", "headers": { "x-request-id": { "description": "Correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Revoked credential or insufficient intake scope", "headers": { "x-request-id": { "description": "Correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Event identity, revision or booking identity conflict", "headers": { "x-request-id": { "description": "Correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "Request exceeds 64 KiB", "headers": { "x-request-id": { "description": "Correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "415": { "description": "JSON content type required", "headers": { "x-request-id": { "description": "Correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded or too many failed authentications; honor the Retry-After header", "headers": { "x-request-id": { "description": "Correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Intake persistence unavailable, or the Ocean API is not enabled in this environment", "headers": { "x-request-id": { "description": "Correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/ocean/v1/messages": { "post": { "tags": [ "Messages" ], "operationId": "submitOceanMessage", "summary": "Submit a supported EDI profile or partial booking extract", "description": "JSON wrapper around X12 301 MSC 005030, EDIFACT IFTMBC MSC D.99B or a partial canonical events extract. DCSA_BOOKING_2_0_0 is explicitly UNSUPPORTED. Each batch record is validated independently; no omission-based cancellation.", "security": [ { "OceanIntegrationBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OceanMessageEnvelope" }, "example": { "format": "FORYN_EXTRACT_EVENTS_V1", "snapshotKind": "PARTIAL", "records": [ { "schemaVersion": "foryn.ocean.booking.v1", "eventId": "synthetic-event-0001", "revision": 1, "action": "CONFIRMED", "sourceBookingId": "synthetic-source-booking-001", "booking": { "carrierBookingReference": "SYNTHETIC-CBR-001", "carrierId": "fictional-carrier", "originUnlocode": "CNSHG", "destinationUnlocode": "USLAX", "bookingDate": "2026-10-12", "equipmentType": "40HC", "quantity": 2, "commodity": "GENERAL", "namedAccountId": "account-1", "agreementReference": "agreement-1", "serviceType": "contract", "qualification": { "milestone": "CARRIER_CONFIRMED", "confirmedAt": "2026-10-12T12:00:00.000Z", "sourceEvidenceId": "synthetic-confirmation-001" } }, "source": { "recordId": "synthetic-source-row-1", "documentId": "fictional-booking-document", "documentVersion": "1" } }, { "schemaVersion": "foryn.ocean.booking.v1", "eventId": "invalid-fixture", "revision": 1, "action": "CONFIRMED", "sourceBookingId": "synthetic-source-booking-001", "booking": { "carrierBookingReference": "SYNTHETIC-CBR-001", "carrierId": "fictional-carrier", "originUnlocode": "CNSHG", "destinationUnlocode": "USLAX", "bookingDate": "2026-10-12", "equipmentType": "40HC", "quantity": 0, "commodity": "GENERAL", "namedAccountId": "account-1", "agreementReference": "agreement-1", "serviceType": "contract", "qualification": { "milestone": "CARRIER_CONFIRMED", "confirmedAt": "2026-10-12T12:00:00.000Z", "sourceEvidenceId": "synthetic-confirmation-001" } }, "source": { "recordId": "synthetic-source-row-1", "documentId": "fictional-booking-document", "documentVersion": "1" } } ] } } } }, "responses": { "200": { "description": "Message mapping status or a per-record partial extract response", "headers": { "x-request-id": { "description": "Correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageSuccess" } } } }, "400": { "description": "Malformed message or invalid JSON wrapper", "headers": { "x-request-id": { "description": "Correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid credential", "headers": { "x-request-id": { "description": "Correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Credential not authorized", "headers": { "x-request-id": { "description": "Correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Canonical booking returned a conflict; outer adapter envelope remains ok:true, nested bookingResponse contains ApiError.", "headers": { "x-request-id": { "description": "Correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageSuccess" } } } }, "413": { "description": "Request exceeds 64 KiB", "headers": { "x-request-id": { "description": "Correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "415": { "description": "JSON content type required", "headers": { "x-request-id": { "description": "Correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded or too many failed authentications; honor the Retry-After header", "headers": { "x-request-id": { "description": "Correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Canonical intake unavailable; inspect nested bookingResponse when a mapped message was submitted.", "headers": { "x-request-id": { "description": "Correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageSuccess" } } } } } } }, "/api/ocean/v1/exceptions/{exceptionId}/resolutions": { "post": { "tags": [ "Resolutions" ], "operationId": "submitOceanExceptionResolution", "summary": "Record an optional resolution or explanation", "description": "Requires separate resolution scope. Actor reference is asserted by the source system, not a Foryn human login. Only exceptions belonging to the authenticated tenant are accessible.", "security": [ { "OceanIntegrationBearer": [] } ], "parameters": [ { "name": "exceptionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": "Opaque tenant-scoped exception ID returned by a consequential booking assessment" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OceanResolution" }, "example": { "schemaVersion": "foryn.ocean.resolution.v1", "eventId": "synthetic-resolution-1", "status": "RESOLVED", "reasonCode": "REVIEWED_BY_REGIONAL_OPS", "explanation": "Source account restriction reviewed.", "actorReference": "source-operator-1", "occurredAt": "2026-10-16T12:00:00.000Z" } } } }, "responses": { "200": { "description": "Resolution recorded or exact idempotent retry", "headers": { "x-request-id": { "description": "Correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolutionSuccess" } } } }, "400": { "description": "Invalid body or exception ID", "headers": { "x-request-id": { "description": "Correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing bearer credential", "headers": { "x-request-id": { "description": "Correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Resolution scope missing", "headers": { "x-request-id": { "description": "Correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Exception absent from authenticated tenant", "headers": { "x-request-id": { "description": "Correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Resolution event ID reused with different content", "headers": { "x-request-id": { "description": "Correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "Request exceeds 64 KiB", "headers": { "x-request-id": { "description": "Correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "415": { "description": "JSON content type required", "headers": { "x-request-id": { "description": "Correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded or too many failed authentications; honor the Retry-After header", "headers": { "x-request-id": { "description": "Correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Resolution persistence unavailable, or the Ocean API is not enabled in this environment", "headers": { "x-request-id": { "description": "Correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } } }, "components": { "securitySchemes": { "OceanIntegrationBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "opaque", "description": "Customer-specific integration token. Prefix foc_ followed by 64 lowercase hex characters. No self-service production credential API. Store in a secret manager; never log." } }, "schemas": { "OceanBookingEvent": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "foryn.ocean.booking.v1" }, "eventId": { "type": "string", "minLength": 1, "maxLength": 160 }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "action": { "type": "string", "enum": [ "CONFIRMED", "AMENDED", "CANCELLED" ] }, "sourceBookingId": { "type": "string", "minLength": 1, "maxLength": 160 }, "booking": { "type": "object", "properties": { "carrierBookingReference": { "type": "string", "minLength": 1, "maxLength": 160 }, "carrierId": { "type": "string", "minLength": 1, "maxLength": 160 }, "originUnlocode": { "type": "string", "pattern": "^[A-Z]{2}[A-Z0-9]{3}$" }, "destinationUnlocode": { "type": "string", "pattern": "^[A-Z]{2}[A-Z0-9]{3}$" }, "bookingDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "sailingDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "equipmentType": { "type": "string", "enum": [ "20GP", "40GP", "40HC", "45HC" ] }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "commodity": { "type": "string", "minLength": 1, "maxLength": 120 }, "agreementReference": { "type": "string", "minLength": 1, "maxLength": 160 }, "namedAccountId": { "type": "string", "minLength": 1, "maxLength": 160 }, "serviceType": { "type": "string", "minLength": 1, "maxLength": 80 }, "qualification": { "type": "object", "properties": { "milestone": { "type": "string", "enum": [ "CARRIER_CONFIRMED", "EQUIVALENT_CONFIRMED" ] }, "confirmedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "sourceEvidenceId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "milestone", "confirmedAt", "sourceEvidenceId" ], "additionalProperties": false } }, "required": [ "carrierBookingReference", "carrierId", "originUnlocode", "destinationUnlocode", "bookingDate", "equipmentType", "quantity", "commodity", "qualification" ], "additionalProperties": false }, "source": { "type": "object", "properties": { "recordId": { "type": "string", "minLength": 1, "maxLength": 160 }, "documentId": { "type": "string", "minLength": 1, "maxLength": 160 }, "documentVersion": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "recordId", "documentId", "documentVersion" ], "additionalProperties": false } }, "required": [ "schemaVersion", "eventId", "revision", "action", "sourceBookingId", "source" ], "additionalProperties": false, "description": "Ocean booking event (generated from Foryn Zod source)" }, "OceanResolution": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "foryn.ocean.resolution.v1" }, "eventId": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "RESOLVED", "NOT_RESOLVED", "DISPUTED" ] }, "reasonCode": { "type": "string", "minLength": 1, "maxLength": 160 }, "explanation": { "type": "string", "maxLength": 2000 }, "actorReference": { "type": "string", "minLength": 1, "maxLength": 160 }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "schemaVersion", "eventId", "status", "reasonCode", "actorReference", "occurredAt" ], "additionalProperties": false, "description": "Ocean exception resolution (generated from Foryn Zod source)" }, "OceanMessageEnvelope": { "oneOf": [ { "type": "object", "properties": { "format": { "type": "string", "const": "X12_301_MSC_005030" }, "payload": { "type": "string", "minLength": 1, "maxLength": 48000 }, "sourceRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "documentId": { "type": "string", "minLength": 1, "maxLength": 160 }, "documentVersion": { "type": "string", "minLength": 1, "maxLength": 160 }, "supplement": { "type": "object", "properties": { "confirmedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "carrierId": { "type": "string", "minLength": 1, "maxLength": 160 }, "expectedCarrierCode": { "type": "string", "minLength": 1, "maxLength": 16 }, "carrierBookingReference": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceBookingId": { "type": "string", "minLength": 1, "maxLength": 160 }, "commodity": { "type": "string", "minLength": 1, "maxLength": 120 }, "agreementReference": { "type": "string", "minLength": 1, "maxLength": 160 }, "namedAccountId": { "type": "string", "minLength": 1, "maxLength": 160 }, "serviceType": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "carrierId", "commodity" ], "additionalProperties": false } }, "required": [ "format", "payload", "sourceRevision", "documentId", "documentVersion", "supplement" ], "additionalProperties": false }, { "type": "object", "properties": { "format": { "type": "string", "const": "EDIFACT_IFTMBC_MSC_D99B" }, "payload": { "type": "string", "minLength": 1, "maxLength": 48000 }, "sourceRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "documentId": { "type": "string", "minLength": 1, "maxLength": 160 }, "documentVersion": { "type": "string", "minLength": 1, "maxLength": 160 }, "supplement": { "type": "object", "properties": { "confirmedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "carrierId": { "type": "string", "minLength": 1, "maxLength": 160 }, "expectedCarrierCode": { "type": "string", "minLength": 1, "maxLength": 16 }, "carrierBookingReference": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceBookingId": { "type": "string", "minLength": 1, "maxLength": 160 }, "commodity": { "type": "string", "minLength": 1, "maxLength": 120 }, "agreementReference": { "type": "string", "minLength": 1, "maxLength": 160 }, "namedAccountId": { "type": "string", "minLength": 1, "maxLength": 160 }, "serviceType": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "carrierId", "commodity" ], "additionalProperties": false } }, "required": [ "format", "payload", "sourceRevision", "documentId", "documentVersion", "supplement" ], "additionalProperties": false }, { "type": "object", "properties": { "format": { "type": "string", "const": "DCSA_BOOKING_2_0_0" }, "payload": { "type": "string", "minLength": 1, "maxLength": 48000 }, "sourceRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "documentId": { "type": "string", "minLength": 1, "maxLength": 160 }, "documentVersion": { "type": "string", "minLength": 1, "maxLength": 160 }, "supplement": { "type": "object", "properties": { "confirmedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "carrierId": { "type": "string", "minLength": 1, "maxLength": 160 }, "expectedCarrierCode": { "type": "string", "minLength": 1, "maxLength": 16 }, "carrierBookingReference": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceBookingId": { "type": "string", "minLength": 1, "maxLength": 160 }, "commodity": { "type": "string", "minLength": 1, "maxLength": 120 }, "agreementReference": { "type": "string", "minLength": 1, "maxLength": 160 }, "namedAccountId": { "type": "string", "minLength": 1, "maxLength": 160 }, "serviceType": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "carrierId", "commodity" ], "additionalProperties": false } }, "required": [ "format", "payload", "sourceRevision", "documentId", "documentVersion", "supplement" ], "additionalProperties": false }, { "type": "object", "properties": { "format": { "type": "string", "const": "FORYN_EXTRACT_EVENTS_V1" }, "snapshotKind": { "type": "string", "const": "PARTIAL" }, "records": { "minItems": 1, "maxItems": 50, "type": "array", "items": {} } }, "required": [ "format", "snapshotKind", "records" ], "additionalProperties": false } ], "description": "Ocean message/batch request (generated from Foryn Zod source)" }, "CommercialException": { "type": "object", "additionalProperties": false, "required": [ "id", "type", "severity", "audience", "reason", "agreementReference", "evidence", "missing", "financialExposureMinor" ], "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "severity": { "const": "HIGH" }, "audience": { "const": "REGIONAL_OPERATIONS" }, "reason": { "type": "string" }, "agreementReference": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "string" } }, "missing": { "type": "array", "items": { "type": "string" } }, "financialExposureMinor": { "type": "null", "description": "No monetary loss is inferred without supporting evidence." } } }, "CommercialAssessment": { "type": "object", "additionalProperties": false, "required": [ "status", "issues", "matchedRateIds", "quantity", "reference", "findings" ], "properties": { "status": { "enum": [ "ASSESSED", "UNRESOLVED" ] }, "issues": { "type": "array", "items": { "type": "string" } }, "matchedRateIds": { "type": "array", "items": { "type": "string" } }, "quantity": { "type": "object", "additionalProperties": false, "required": [ "status", "amount", "unit" ], "properties": { "status": { "enum": [ "COUNTED", "NOT_COUNTED" ] }, "amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "reference": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "version", "documentId", "documentVersion" ], "properties": { "id": { "type": "string" }, "version": { "type": "integer" }, "documentId": { "type": "string" }, "documentVersion": { "type": "string" } } }, { "type": "null" } ] }, "findings": { "type": "array", "items": { "type": "object", "required": [ "code", "reason", "severity", "audience", "agreementReference", "evidence", "missing", "financialExposureMinor" ], "properties": { "code": { "type": "string" }, "reason": { "type": "string" }, "severity": { "const": "HIGH" }, "audience": { "const": "REGIONAL_OPERATIONS" }, "agreementReference": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "string" } }, "missing": { "type": "array", "items": { "type": "string" } }, "financialExposureMinor": { "type": "null" } } } } } }, "BookingResult": { "type": "object", "additionalProperties": false, "required": [ "accepted", "status", "bookingReference", "sourceRevision", "assessment", "exceptions" ], "properties": { "accepted": { "type": "boolean" }, "status": { "type": "string", "enum": [ "ACCEPTED", "EXCEPTION", "INSUFFICIENT_EVIDENCE", "OUT_OF_COVERAGE", "NOT_QUALIFIED", "DUPLICATE_EVENT", "UNCHANGED_SNAPSHOT", "STALE_REVISION", "CANCELLED" ] }, "bookingReference": { "type": "string" }, "sourceRevision": { "type": "integer" }, "assessment": { "anyOf": [ { "$ref": "#/components/schemas/CommercialAssessment" }, { "type": "null" } ] }, "exceptions": { "type": "array", "items": { "$ref": "#/components/schemas/CommercialException" } } } }, "BookingSuccess": { "type": "object", "additionalProperties": false, "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/BookingResult" } } }, "ApiError": { "type": "object", "additionalProperties": false, "required": [ "ok", "error" ], "properties": { "ok": { "const": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "message", "requestId" ], "properties": { "status": { "type": "integer" }, "code": { "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "BAD_REQUEST", "CONFLICT", "INPUT_TOO_LONG", "UNPROCESSABLE", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE", "RATE_LIMITED" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "string" }, { "type": "null" } ] } } } } }, "ResolutionSuccess": { "type": "object", "additionalProperties": false, "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object", "additionalProperties": false, "required": [ "accepted", "status", "exceptionId", "resolutionId", "sourceSystem" ], "properties": { "accepted": { "const": true }, "status": { "enum": [ "RECORDED", "DUPLICATE" ] }, "exceptionId": { "type": "string" }, "resolutionId": { "type": "string" }, "sourceSystem": { "type": "string" } } } } }, "MessageSuccess": { "type": "object", "additionalProperties": false, "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "description": "Union of single-message mapped result and partial-extract per-record result; see x-foryn-response-variants", "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "accepted", "status", "reason", "profile", "evidence" ], "properties": { "accepted": { "const": false }, "status": { "enum": [ "UNSUPPORTED", "UNRESOLVED", "NOT_QUALIFIED" ] }, "reason": { "type": "string" }, "profile": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "additionalProperties": false, "required": [ "profile", "sourceEvidence", "normalizedBookingEvent", "responseHttpStatus", "bookingResponse" ], "properties": { "profile": { "type": "string" }, "sourceEvidence": { "type": "array", "items": { "type": "string" } }, "normalizedBookingEvent": { "$ref": "#/components/schemas/OceanBookingEvent" }, "responseHttpStatus": { "type": "integer" }, "bookingResponse": { "oneOf": [ { "$ref": "#/components/schemas/BookingSuccess" }, { "$ref": "#/components/schemas/ApiError" } ] } } }, { "type": "object", "additionalProperties": false, "required": [ "format", "snapshotKind", "processed", "results", "omissionBasedCancellation" ], "properties": { "format": { "const": "FORYN_EXTRACT_EVENTS_V1" }, "snapshotKind": { "const": "PARTIAL" }, "processed": { "type": "integer" }, "omissionBasedCancellation": { "const": false }, "results": { "type": "array", "items": { "type": "object", "required": [ "index", "status" ], "properties": { "index": { "type": "integer" }, "status": { "enum": [ "INVALID_RECORD", "PROCESSED", "FAILED" ] }, "eventId": { "type": "string" }, "reason": { "type": "string" }, "httpStatus": { "type": "integer" }, "result": { "oneOf": [ { "$ref": "#/components/schemas/BookingSuccess" }, { "$ref": "#/components/schemas/ApiError" } ] } } } } } } ] } } } } }, "x-foryn-contract-sources": { "bookings": "lib/domain-packs/ocean-commercial/api/intakeContract.ts", "messages": "lib/domain-packs/ocean-commercial/adapters/contract.ts", "bookingHandler": "lib/api/handlers/oceanBooking.ts", "messageHandler": "lib/api/handlers/oceanMessages.ts", "resolutionHandler": "lib/api/handlers/oceanResolution.ts", "requestBodyMaxBytes": 65536, "statusCodes": [ "ACCEPTED", "EXCEPTION", "INSUFFICIENT_EVIDENCE", "OUT_OF_COVERAGE", "NOT_QUALIFIED", "DUPLICATE_EVENT", "UNCHANGED_SNAPSHOT", "STALE_REVISION", "CANCELLED" ], "docRevision": "2026-10-18", "notes": "All example payloads synthetic. Public portal is separate from the not-yet-deployed integration API." } }