{ "openapi": "3.0.3", "info": { "title": "SeaPillar API", "version": "2.0.0", "description": "Digital Parcel Custody System API for ship agents. Manage vessel registrations, parcel lifecycle tracking, customs manifests, GDN generation, and webhook subscriptions.\n\nAll responses follow a consistent envelope: `{ success, data, meta }` for successes and `{ success, error, meta }` for errors.", "contact": { "name": "SeaPillar Support", "url": "https://www.seapillar.com/contact", "email": "support@seapillar.com" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://www.seapillar.com/api", "description": "Production" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Parcels", "description": "Parcel lifecycle management — create, update, transition status, and generate GDN documents." }, { "name": "Vessels", "description": "Vessel registration and lookup." }, { "name": "Customs Manifests", "description": "Bonded cargo declarations and MIO workflow management." }, { "name": "Webhooks", "description": "Subscribe to real-time event notifications." }, { "name": "Search", "description": "Full-text search across parcels and vessels." }, { "name": "GDN", "description": "Goods Delivery Note generation and PDF export." } ], "paths": { "/parcels": { "get": { "tags": ["Parcels"], "summary": "List parcels", "description": "Retrieve a paginated list of parcels. Supports filtering by status, vessel, vessel call, bonded flag, and free-text search.", "operationId": "listParcels", "parameters": [ { "name": "status", "in": "query", "description": "Filter by parcel status.", "schema": { "type": "string", "enum": ["EXPECTED", "RECEIVED", "IN_WAREHOUSE", "IN_BONDED_STORE", "STAGED", "DELIVERED", "DISPATCHED", "CONFIRMED", "CLOSED", "ON_HOLD", "CANCELLED"] } }, { "name": "vesselId", "in": "query", "description": "Filter by vessel UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "callId", "in": "query", "description": "Filter by vessel call UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "bonded", "in": "query", "description": "Filter bonded parcels only (`true`) or exclude bonded (`false`).", "schema": { "type": "string", "enum": ["true", "false"] } }, { "name": "search", "in": "query", "description": "Free-text search across description, supplier name, tracking ref, and customs ref. Minimum 2 characters.", "schema": { "type": "string", "minLength": 2 } }, { "name": "page", "in": "query", "description": "Page number (offset-based pagination). Default: 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Items per page. Default: 50, max: 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Cursor for cursor-based pagination. When provided, offset params are ignored.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of parcels.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Parcel" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } ] }, "example": { "success": true, "data": { "items": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "description": "Engine spare parts - cylinder liners", "supplierName": "Wartsila Marine Parts", "quantity": 4, "weight": 120.5, "volume": 0.85, "direction": "INBOUND", "status": "IN_WAREHOUSE", "trackingRef": "DHL-9903881", "customsRef": null, "storageLocation": "Bay A-12", "vesselId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "callId": "c3d4e5f6-a7b8-9012-cdef-123456789012", "createdAt": "2026-04-10T08:30:00.000Z", "updatedAt": "2026-04-11T14:22:00.000Z", "vessel": { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "MV Nordic Spirit", "imo": "9876543" }, "call": { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "etaAt": "2026-04-12T06:00:00.000Z" }, "_count": { "documents": 2, "events": 3 } } ], "pagination": { "page": 1, "limit": 50, "total": 127, "pages": 3, "hasMore": true } }, "meta": { "requestId": "req-a1b2c3d4-e5f6-7890-abcd-ef1234567890", "timestamp": "2026-04-13T10:00:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "tags": ["Parcels"], "summary": "Create a parcel", "description": "Register a new parcel. The parcel starts in `EXPECTED` status. A vessel ID is required; vessel call ID is optional.", "operationId": "createParcel", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateParcelInput" }, "example": { "description": "Engine spare parts - cylinder liners", "supplierName": "Wartsila Marine Parts", "quantity": 4, "weight": 120.5, "volume": 0.85, "vesselId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "callId": "c3d4e5f6-a7b8-9012-cdef-123456789012", "direction": "INBOUND", "trackingRef": "DHL-9903881" } } } }, "responses": { "201": { "description": "Parcel created successfully.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Parcel" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/parcels/{id}": { "get": { "tags": ["Parcels"], "summary": "Get parcel detail", "description": "Retrieve a single parcel with its full context: vessel, vessel call, storage zone, customs manifest, and created-by user.", "operationId": "getParcel", "parameters": [ { "$ref": "#/components/parameters/ParcelId" } ], "responses": { "200": { "description": "Parcel detail.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ParcelDetail" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "tags": ["Parcels"], "summary": "Update a parcel", "description": "Update editable fields on a parcel. GDN-material fields (description, quantity, weight, volume, supplierName, customsRef) cannot be changed on confirmed/closed parcels.", "operationId": "updateParcel", "parameters": [ { "$ref": "#/components/parameters/ParcelId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateParcelInput" }, "example": { "storageLocation": "Bay B-04", "trackingRef": "DHL-9903882" } } } }, "responses": { "200": { "description": "Parcel updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Parcel" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Business rule violation (e.g., editing GDN-material fields on confirmed parcel).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "tags": ["Parcels"], "summary": "Delete a parcel", "description": "Soft-delete a parcel. Cannot delete confirmed or closed parcels (to preserve the custody chain).", "operationId": "deleteParcel", "parameters": [ { "$ref": "#/components/parameters/ParcelId" } ], "responses": { "200": { "description": "Parcel deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true } } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/parcels/{id}/gdn": { "get": { "tags": ["GDN"], "summary": "Get Goods Delivery Note", "description": "Generate a GDN for the parcel. Returns JSON by default, or HTML with `?format=html`. The GDN includes the full custody chain, captain confirmation, digital signature, and bonded documents. Available from RECEIVED status onwards.", "operationId": "getParcelGdn", "parameters": [ { "$ref": "#/components/parameters/ParcelId" }, { "name": "format", "in": "query", "description": "Response format.", "schema": { "type": "string", "enum": ["json", "html"], "default": "json" } } ], "responses": { "200": { "description": "GDN data.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GDN" } } } ] } }, "text/html": { "schema": { "type": "string", "description": "Self-contained HTML document for printing." } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/parcels/{id}/gdn/pdf": { "get": { "tags": ["GDN"], "summary": "Download GDN as PDF", "description": "Generate and download a professional A4 PDF of the Goods Delivery Note. Includes digital signature and integrity hash.", "operationId": "getParcelGdnPdf", "parameters": [ { "$ref": "#/components/parameters/ParcelId" } ], "responses": { "200": { "description": "PDF document.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/vessels": { "get": { "tags": ["Vessels"], "summary": "List vessels", "description": "Retrieve a paginated list of vessels. Supports free-text search across name, IMO, and call sign.", "operationId": "listVessels", "parameters": [ { "name": "q", "in": "query", "description": "Search query (searches name, IMO, call sign).", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number. Default: 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Items per page. Default: 50, max: 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Paginated list of vessels.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Vessel" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } ] }, "example": { "success": true, "data": { "items": [ { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "MV Nordic Spirit", "imo": "9876543", "flag": "DK", "vesselType": "Bulk Carrier", "mmsi": "219000123", "callSign": "OWAB2", "status": "ACTIVE", "grossTonnage": 32000, "deadweightTonnage": 55000, "builtYear": 2018, "createdAt": "2026-03-01T12:00:00.000Z", "_count": { "calls": 2 } } ], "pagination": { "page": 1, "limit": 50, "total": 12, "pages": 1, "hasMore": false } }, "meta": { "requestId": "req-xyz", "timestamp": "2026-04-13T10:00:00.000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "tags": ["Vessels"], "summary": "Create a vessel", "description": "Register a new vessel in the organization. If a valid IMO is provided, the vessel is automatically linked to the global vessel registry.", "operationId": "createVessel", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVesselInput" }, "example": { "name": "MV Nordic Spirit", "imo": "9876543", "captain": "Capt. Erik Hansen", "email": "captain@nordicspirit.com", "phone": "+45 1234 5678" } } } }, "responses": { "201": { "description": "Vessel created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "vessel": { "$ref": "#/components/schemas/Vessel" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Business rule violation (e.g., vessel limit reached).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/vessels/{id}": { "get": { "tags": ["Vessels"], "summary": "Get vessel detail", "description": "Retrieve a single vessel by ID.", "operationId": "getVessel", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Vessel UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Vessel detail.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Vessel" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/customs-manifests": { "get": { "tags": ["Customs Manifests"], "summary": "List customs manifests", "description": "Retrieve customs manifests with optional type, status, and vessel filters. Uses cursor-based pagination.", "operationId": "listCustomsManifests", "parameters": [ { "name": "type", "in": "query", "description": "Filter by manifest type.", "schema": { "type": "string", "enum": ["IMPORT", "EXPORT", "TRANSIT"] } }, { "name": "status", "in": "query", "description": "Filter by manifest status.", "schema": { "type": "string", "enum": ["DRAFT", "SUBMITTED", "UNDER_REVIEW", "APPROVED", "RELEASED", "REJECTED", "CLOSED"] } }, { "name": "vesselId", "in": "query", "description": "Filter by vessel UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "description": "Pagination cursor.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Items per page. Default: 50, max: 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Paginated list of customs manifests.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomsManifest" } }, "pageInfo": { "$ref": "#/components/schemas/CursorPageInfo" }, "totalCount": { "type": "integer" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "tags": ["Customs Manifests"], "summary": "Create a customs manifest", "description": "Create a new customs manifest in DRAFT status. A vessel ID and reference number are required.", "operationId": "createCustomsManifest", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomsManifestInput" }, "example": { "vesselId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "reference": "MIO-2026-0042", "type": "IMPORT", "declarantName": "Nordic Customs Brokers A/S", "declarantRef": "NCB-REF-8821", "portOfEntry": "DKCPH", "notes": "Bonded engine parts for MV Nordic Spirit" } } } }, "responses": { "201": { "description": "Customs manifest created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomsManifest" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/customs-manifests/{id}": { "get": { "tags": ["Customs Manifests"], "summary": "Get customs manifest detail", "description": "Retrieve a single customs manifest with linked parcels and documents.", "operationId": "getCustomsManifest", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Customs manifest UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Customs manifest detail.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomsManifest" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/customs-manifests/{id}/transition": { "post": { "tags": ["Customs Manifests"], "summary": "Transition manifest status", "description": "Advance the customs manifest through its state machine: DRAFT -> SUBMITTED -> UNDER_REVIEW -> APPROVED -> RELEASED -> CLOSED. REJECTED returns to DRAFT.", "operationId": "transitionCustomsManifest", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Customs manifest UUID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransitionCustomsManifestInput" }, "example": { "toStatus": "SUBMITTED" } } } }, "responses": { "200": { "description": "Manifest transitioned.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomsManifest" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v2/webhooks": { "get": { "tags": ["Webhooks"], "summary": "List webhook endpoints", "description": "Retrieve all active webhook endpoints for the organization, including delivery counts.", "operationId": "listWebhooks", "responses": { "200": { "description": "List of webhook endpoints.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } } } ] }, "example": { "success": true, "data": { "endpoints": [ { "id": "d4e5f6a7-b8c9-0123-defg-234567890123", "url": "https://your-app.com/webhooks/seapillar", "events": ["parcel.status_changed", "manifest.released"], "isActive": true, "createdAt": "2026-04-01T08:00:00.000Z", "updatedAt": "2026-04-01T08:00:00.000Z", "_count": { "deliveries": 42 } } ] }, "meta": { "requestId": "req-xyz", "timestamp": "2026-04-13T10:00:00.000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "tags": ["Webhooks"], "summary": "Register a webhook endpoint", "description": "Register a new HTTPS endpoint to receive webhook event notifications. Each delivery includes an HMAC-SHA256 signature for verification. Requires Port Command plan or higher.", "operationId": "createWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookInput" }, "example": { "url": "https://your-app.com/webhooks/seapillar", "events": ["parcel.status_changed", "manifest.released"], "secret": "whsec_your_secret_at_least_16_chars" } } } }, "responses": { "201": { "description": "Webhook endpoint registered.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "endpoint": { "$ref": "#/components/schemas/Webhook" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v2/webhooks/{id}": { "delete": { "tags": ["Webhooks"], "summary": "Deactivate a webhook endpoint", "description": "Soft-deactivate a webhook endpoint. The endpoint stops receiving deliveries immediately.", "operationId": "deleteWebhook", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook endpoint UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Webhook endpoint deactivated." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/search": { "get": { "tags": ["Search"], "summary": "Full-text search", "description": "Search across parcels and vessels using PostgreSQL full-text search. Minimum query length is 2 characters.", "operationId": "search", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query (minimum 2 characters).", "schema": { "type": "string", "minLength": 2 } }, { "name": "type", "in": "query", "description": "Restrict search to a specific entity type.", "schema": { "type": "string", "enum": ["parcels", "vessels", "all"], "default": "all" } }, { "name": "limit", "in": "query", "description": "Maximum results. Default: 20, max: 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "offset", "in": "query", "description": "Result offset. Default: 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Search results.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "query": { "type": "string" }, "type": { "type": "string" }, "total": { "type": "integer" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } } } } } } ] }, "example": { "success": true, "data": { "query": "Nordic", "type": "all", "total": 3, "results": [ { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "type": "vessel", "title": "MV Nordic Spirit", "subtitle": "IMO 9876543", "url": "/portal/vessels/b2c3d4e5-f6a7-8901-bcde-f12345678901" } ] }, "meta": { "requestId": "req-xyz", "timestamp": "2026-04-13T10:00:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "API key prefixed with `sk_live_`. Created by Agency Admins in Settings > API Keys. Each key is scoped to a single organization." } }, "parameters": { "ParcelId": { "name": "id", "in": "path", "required": true, "description": "Parcel UUID.", "schema": { "type": "string", "format": "uuid" } } }, "schemas": { "SuccessEnvelope": { "type": "object", "required": ["success"], "properties": { "success": { "type": "boolean", "enum": [true] }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "ErrorEnvelope": { "type": "object", "required": ["success", "error"], "properties": { "success": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "required": ["message", "code"], "properties": { "message": { "type": "string", "description": "Human-readable error message." }, "code": { "type": "string", "description": "Machine-readable error code.", "example": "VALIDATION_ERROR" }, "details": { "description": "Additional error context (e.g., field-level validation errors)." } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "ResponseMeta": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique request identifier for debugging.", "example": "req-a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "timestamp": { "type": "string", "format": "date-time", "description": "Server timestamp.", "example": "2026-04-13T10:00:00.000Z" } } }, "Pagination": { "type": "object", "properties": { "page": { "type": "integer", "description": "Current page number.", "example": 1 }, "limit": { "type": "integer", "description": "Items per page.", "example": 50 }, "total": { "type": "integer", "description": "Total matching items.", "example": 127 }, "pages": { "type": "integer", "description": "Total pages.", "example": 3 }, "hasMore": { "type": "boolean", "description": "Whether more pages exist.", "example": true } } }, "CursorPageInfo": { "type": "object", "properties": { "hasNextPage": { "type": "boolean" }, "hasPreviousPage": { "type": "boolean" }, "startCursor": { "type": "string", "nullable": true }, "endCursor": { "type": "string", "nullable": true } } }, "Parcel": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "description": { "type": "string", "description": "Parcel contents description.", "example": "Engine spare parts - cylinder liners" }, "supplierName": { "type": "string", "nullable": true, "example": "Wartsila Marine Parts" }, "quantity": { "type": "integer", "nullable": true, "example": 4 }, "weight": { "type": "number", "nullable": true, "description": "Weight in kg.", "example": 120.5 }, "volume": { "type": "number", "nullable": true, "description": "Volume in cubic meters.", "example": 0.85 }, "direction": { "type": "string", "enum": ["INBOUND", "OUTBOUND", "BONDED"], "example": "INBOUND" }, "status": { "type": "string", "enum": ["EXPECTED", "RECEIVED", "IN_WAREHOUSE", "IN_BONDED_STORE", "STAGED", "DELIVERED", "DISPATCHED", "CONFIRMED", "CLOSED", "ON_HOLD", "CANCELLED"], "example": "IN_WAREHOUSE" }, "trackingRef": { "type": "string", "nullable": true, "description": "External tracking reference.", "example": "DHL-9903881" }, "customsRef": { "type": "string", "nullable": true, "description": "Customs authority reference number." }, "storageLocation": { "type": "string", "nullable": true, "description": "Physical storage location.", "example": "Bay A-12" }, "vesselId": { "type": "string", "format": "uuid" }, "callId": { "type": "string", "format": "uuid", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "vessel": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "imo": { "type": "string", "nullable": true } } }, "call": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "etaAt": { "type": "string", "format": "date-time", "nullable": true } } }, "_count": { "type": "object", "properties": { "documents": { "type": "integer" }, "events": { "type": "integer" } } } } }, "ParcelDetail": { "type": "object", "description": "Extended parcel object returned by the detail endpoint.", "allOf": [ { "$ref": "#/components/schemas/Parcel" }, { "type": "object", "properties": { "call": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "etaAt": { "type": "string", "format": "date-time", "nullable": true }, "berthRef": { "type": "string", "nullable": true }, "portName": { "type": "string", "nullable": true }, "voyageRef": { "type": "string", "nullable": true } } }, "zone": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "code": { "type": "string" } } }, "contract": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "freeDays": { "type": "integer" }, "dailyRate": { "type": "number" } } }, "manifest": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "reference": { "type": "string" }, "status": { "type": "string" } } }, "createdBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } } } } } ] }, "CreateParcelInput": { "type": "object", "required": ["description", "vesselId"], "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "supplierName": { "type": "string", "maxLength": 200 }, "quantity": { "type": "integer", "minimum": 0, "maximum": 100000 }, "weight": { "type": "number", "minimum": 0, "maximum": 1000000, "description": "Weight in kg." }, "volume": { "type": "number", "minimum": 0, "maximum": 1000000, "description": "Volume in cubic meters." }, "vesselId": { "type": "string", "format": "uuid" }, "callId": { "type": "string", "format": "uuid" }, "direction": { "type": "string", "enum": ["INBOUND", "OUTBOUND", "BONDED"], "default": "INBOUND" }, "customsRef": { "type": "string", "maxLength": 100 }, "trackingRef": { "type": "string", "maxLength": 100 }, "storageLocation": { "type": "string", "maxLength": 200 } } }, "UpdateParcelInput": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "supplierName": { "type": "string", "maxLength": 200, "nullable": true }, "quantity": { "type": "integer", "minimum": 1 }, "weight": { "type": "number", "nullable": true }, "volume": { "type": "number", "nullable": true }, "storageLocation": { "type": "string", "maxLength": 100, "nullable": true }, "trackingRef": { "type": "string", "maxLength": 100, "nullable": true }, "customsRef": { "type": "string", "maxLength": 100, "nullable": true }, "callId": { "type": "string", "format": "uuid", "nullable": true }, "direction": { "type": "string", "enum": ["INBOUND", "OUTBOUND", "BONDED"] } } }, "Vessel": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "MV Nordic Spirit" }, "imo": { "type": "string", "nullable": true, "description": "7-digit IMO number.", "example": "9876543" }, "flag": { "type": "string", "nullable": true, "description": "Flag state ISO code.", "example": "DK" }, "vesselType": { "type": "string", "nullable": true, "example": "Bulk Carrier" }, "mmsi": { "type": "string", "nullable": true, "description": "Maritime Mobile Service Identity.", "example": "219000123" }, "callSign": { "type": "string", "nullable": true, "example": "OWAB2" }, "grossTonnage": { "type": "number", "nullable": true, "example": 32000 }, "deadweightTonnage": { "type": "number", "nullable": true, "example": 55000 }, "builtYear": { "type": "integer", "nullable": true, "example": 2018 }, "status": { "type": "string", "enum": ["ACTIVE", "AT_PORT", "DECOMMISSIONED"], "example": "ACTIVE" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "_count": { "type": "object", "properties": { "calls": { "type": "integer", "description": "Active vessel call count." } } } } }, "CreateVesselInput": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Vessel name." }, "imo": { "type": "string", "pattern": "^\\d{7}$", "description": "7-digit IMO number." }, "captain": { "type": "string", "maxLength": 100, "description": "Captain name (creates a CAPTAIN contact)." }, "email": { "type": "string", "format": "email", "description": "Captain email." }, "phone": { "type": "string", "maxLength": 50, "description": "Captain phone." } } }, "CustomsManifest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "vesselId": { "type": "string", "format": "uuid" }, "callId": { "type": "string", "format": "uuid", "nullable": true }, "reference": { "type": "string", "description": "Official customs reference number.", "example": "MIO-2026-0042" }, "type": { "type": "string", "enum": ["IMPORT", "EXPORT", "TRANSIT"] }, "status": { "type": "string", "enum": ["DRAFT", "SUBMITTED", "UNDER_REVIEW", "APPROVED", "RELEASED", "REJECTED", "CLOSED"] }, "declarantName": { "type": "string", "nullable": true, "example": "Nordic Customs Brokers A/S" }, "declarantRef": { "type": "string", "nullable": true, "example": "NCB-REF-8821" }, "portOfEntry": { "type": "string", "nullable": true, "example": "DKCPH" }, "portOfExit": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CreateCustomsManifestInput": { "type": "object", "required": ["vesselId", "reference", "type"], "properties": { "vesselId": { "type": "string", "format": "uuid" }, "callId": { "type": "string", "format": "uuid", "nullable": true }, "reference": { "type": "string", "minLength": 1, "maxLength": 200 }, "type": { "type": "string", "enum": ["IMPORT", "EXPORT", "TRANSIT"] }, "declarantName": { "type": "string", "maxLength": 300, "nullable": true }, "declarantRef": { "type": "string", "maxLength": 200, "nullable": true }, "portOfEntry": { "type": "string", "maxLength": 200, "nullable": true }, "portOfExit": { "type": "string", "maxLength": 200, "nullable": true }, "notes": { "type": "string", "maxLength": 5000, "nullable": true } } }, "TransitionCustomsManifestInput": { "type": "object", "required": ["toStatus"], "properties": { "toStatus": { "type": "string", "enum": ["DRAFT", "SUBMITTED", "UNDER_REVIEW", "APPROVED", "RELEASED", "REJECTED", "CLOSED"] }, "rejectionReason": { "type": "string", "maxLength": 2000, "description": "Required when transitioning to REJECTED." } } }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri", "example": "https://your-app.com/webhooks/seapillar" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Subscribed event types.", "example": ["parcel.status_changed", "manifest.released"] }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "_count": { "type": "object", "properties": { "deliveries": { "type": "integer", "description": "Total deliveries sent to this endpoint." } } } } }, "CreateWebhookInput": { "type": "object", "required": ["url", "events", "secret"], "properties": { "url": { "type": "string", "format": "uri", "description": "HTTPS endpoint URL." }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 20, "description": "Event types to subscribe to. Available: parcel.status_changed, parcel.confirmed, manifest.released, call.completed." }, "secret": { "type": "string", "minLength": 16, "maxLength": 256, "description": "Shared secret for HMAC-SHA256 signature verification." } } }, "SearchResult": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": ["parcel", "vessel"], "description": "Entity type." }, "title": { "type": "string", "description": "Primary display text." }, "subtitle": { "type": "string", "nullable": true, "description": "Secondary display text." }, "url": { "type": "string", "description": "Relative URL to the entity detail page." } } }, "GDN": { "type": "object", "description": "Goods Delivery Note document.", "properties": { "gdnNumber": { "type": "string", "description": "Unique GDN identifier.", "example": "GDN-A1B2C3D4-20260410-E5F6A7" }, "generatedAt": { "type": "string", "format": "date-time" }, "organization": { "type": "object", "nullable": true, "properties": { "name": { "type": "string" } } }, "vessel": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "imo": { "type": "string", "nullable": true } } }, "parcel": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "description": { "type": "string" }, "supplierName": { "type": "string", "nullable": true }, "quantity": { "type": "integer" }, "weight": { "type": "number", "nullable": true }, "direction": { "type": "string", "enum": ["INBOUND", "OUTBOUND", "BONDED"] }, "customsRef": { "type": "string", "nullable": true }, "trackingRef": { "type": "string", "nullable": true }, "currentStatus": { "type": "string" } } }, "timeline": { "type": "object", "properties": { "expected": { "type": "string", "format": "date-time" }, "received": { "type": "string", "format": "date-time", "nullable": true }, "stored": { "type": "string", "format": "date-time", "nullable": true }, "staged": { "type": "string", "format": "date-time", "nullable": true }, "loaded": { "type": "string", "format": "date-time", "nullable": true }, "captainConfirmed": { "type": "string", "format": "date-time", "nullable": true }, "closed": { "type": "string", "format": "date-time", "nullable": true } } }, "captainConfirmation": { "type": "object", "nullable": true, "properties": { "confirmedAt": { "type": "string", "format": "date-time" }, "confirmedBy": { "type": "string" }, "method": { "type": "string" }, "signatureHash": { "type": "string", "nullable": true }, "integrityVerified": { "type": "boolean" } } }, "custodyChain": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "nullable": true }, "to": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "by": { "type": "string" }, "comment": { "type": "string", "nullable": true } } } }, "digitalSignature": { "type": "object", "nullable": true, "description": "ECDSA digital signature for document integrity verification.", "properties": { "algorithm": { "type": "string", "example": "ECDSA-P256-SHA256" }, "signature": { "type": "string" }, "publicKey": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "responses": { "ValidationError": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "message": "Validation failed", "code": "VALIDATION_ERROR", "details": { "errors": [ { "field": "description", "message": "String must contain at least 1 character(s)" } ] } }, "meta": { "requestId": "req-xyz", "timestamp": "2026-04-13T10:00:00.000Z" } } } } }, "Unauthorized": { "description": "Authentication required. Provide a valid API key in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "message": "Authentication required", "code": "UNAUTHORIZED" }, "meta": { "requestId": "req-xyz", "timestamp": "2026-04-13T10:00:00.000Z" } } } } }, "Forbidden": { "description": "Insufficient permissions for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "message": "Access denied", "code": "FORBIDDEN" }, "meta": { "requestId": "req-xyz", "timestamp": "2026-04-13T10:00:00.000Z" } } } } }, "NotFound": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "message": "Resource not found", "code": "NOT_FOUND" }, "meta": { "requestId": "req-xyz", "timestamp": "2026-04-13T10:00:00.000Z" } } } } }, "Conflict": { "description": "Resource already exists or state conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "message": "Resource already exists", "code": "CONFLICT" }, "meta": { "requestId": "req-xyz", "timestamp": "2026-04-13T10:00:00.000Z" } } } } }, "InternalError": { "description": "Internal server error. Contact support if this persists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "message": "Internal server error", "code": "INTERNAL_ERROR" }, "meta": { "requestId": "req-xyz", "timestamp": "2026-04-13T10:00:00.000Z" } } } } } } } }