OpenAPI Specification
openapi: 3.1.0
info:
title: Wove External Authentication Shipments API
version: 1.0.0
description: "# Wove External API Documentation\n\nThe Wove External API allows you to programmatically access document processing, shipment management, and validation capabilities.\n\n## Features\n\n- **OAuth 2.0 Authentication**: Secure client credentials flow\n- **Rate Limiting**: Configurable per-client rate limits\n- **Document Processing**: Upload, validate, and merge shipping documents\n- **Shipment Management**: Create and manage shipment records with validation and merge operations\n- **Webhooks**: Get notified of document processing events (extraction, validation, merge)\n- **Comprehensive Error Handling**: Detailed error responses with troubleshooting information\n\n## Getting Started\n\n1. **Create OAuth Client**: Contact your account manager to create OAuth credentials\n2. **Get Access Token**: Use client credentials flow to obtain bearer token\n3. **Make API Calls**: Include bearer token in Authorization header\n4. **Handle Rate Limits**: Monitor rate limit headers in responses\n\n## Authentication\n\nAll API endpoints require OAuth 2.0 authentication using the client credentials flow.\n\n### Getting an Access Token\n\n```bash\ncurl -X POST https://api.wove.com/api/v1/external/auth/token \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"grant_type\": \"client_credentials\",\n \"client_id\": \"your_client_id\",\n \"client_secret\": \"your_client_secret\"\n }'\n```\n\n### Using the Access Token\n\nInclude the access token in the Authorization header:\n\n```bash\ncurl -H \"Authorization: Bearer your_access_token\" \\\n https://api.wove.com/api/v1/external/shipments\n```\n\n## Rate Limiting\n\nAll endpoints are subject to rate limiting based on your OAuth client configuration:\n\n- **Per-minute limit**: Default 60 requests/minute\n- **Daily limit**: Default 10,000 requests/day\n\nRate limit information is included in response headers:\n- `X-RateLimit-Limit-Minute`: Your per-minute limit\n- `X-RateLimit-Remaining-Minute`: Remaining requests this minute\n- `X-RateLimit-Reset-Minute`: When the minute window resets\n- `X-RateLimit-Limit-Day`: Your daily limit\n- `X-RateLimit-Remaining-Day`: Remaining requests today\n- `X-RateLimit-Reset-Day`: When the daily window resets\n\n## Webhook Security\n\nAll webhook payloads are signed using HMAC-SHA256 for verification:\n\n```javascript\n// Verify webhook signature\nconst crypto = require('crypto');\nconst signature = request.headers['x-wove-signature'];\nconst payload = JSON.stringify(request.body);\nconst expectedSignature = crypto\n .createHmac('sha256', your_webhook_secret)\n .update(payload)\n .digest('hex');\n\nconst isValid = crypto.timingSafeEqual(\n Buffer.from(signature),\n Buffer.from(expectedSignature)\n);\n```\n\nHeaders included with every webhook:\n- `X-Wove-Signature`: HMAC-SHA256 signature of the payload\n- `X-Wove-Event`: Event type (e.g., \"extraction.completed\")\n- `X-Wove-Timestamp`: ISO timestamp when the webhook was sent\n\n## Error Handling\n\nAll errors follow a consistent format:\n\n```json\n{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"One or more documents not found or access denied\",\n \"details\": {\n \"field\": \"documentIds\",\n \"value\": [\"invalid_id\"]\n }\n }\n}\n```\n\n### Error Codes\n\n- `VALIDATION_ERROR` - Invalid request parameters or data validation failure\n- `AUTHENTICATION_ERROR` - Invalid or expired credentials\n- `AUTHORIZATION_ERROR` - Insufficient permissions for the requested operation\n- `NOT_FOUND` - Requested resource not found\n- `RATE_LIMIT_ERROR` - Too many requests, rate limit exceeded\n- `INTERNAL_ERROR` - Internal server error\n\nSee the common error responses in the components section for detailed examples.\n"
contact:
name: Wove API Support
email: api-support@wove.com
url: https://docs.wove.com
license:
name: Proprietary
url: https://wove.com/terms
servers:
- url: https://api.wove.com
description: Production server
- url: https://staging-api.wove.com
description: Staging server
- url: http://localhost:4000
description: Development server
security:
- bearerAuth: []
tags:
- name: Shipments
description: Shipment management operations
paths:
/api/v1/external/shipments:
get:
tags:
- Shipments
summary: List shipments
description: 'Retrieve a paginated list of shipments for your organization.
Results are ordered by creation date (newest first).
'
security:
- bearerAuth: []
parameters:
- name: page
in: query
schema:
type: integer
minimum: 1
default: 1
description: Page number for pagination
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 20
description: Number of items per page
- name: status
in: query
schema:
type: string
enum:
- draft
- booked
- pending
- in_transit
- delivered
- cancelled
description: Filter by shipment status
- name: shipmentType
in: query
schema:
type: string
enum:
- FCL
- LCL
- Air
description: Filter by shipment type
- name: search
in: query
schema:
type: string
description: Search shipments by name or ID
responses:
'200':
description: Shipments retrieved successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ShipmentSummary'
pagination:
type: object
properties:
page:
type: integer
example: 1
limit:
type: integer
example: 20
total:
type: integer
example: 150
totalPages:
type: integer
example: 8
hasNext:
type: boolean
example: true
hasPrev:
type: boolean
example: false
post:
tags:
- Shipments
summary: Create shipment
description: Create a new shipment in draft status.
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateShipmentRequest'
responses:
'201':
description: Shipment created successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
$ref: '#/components/schemas/ShipmentDetails'
'400':
description: Invalid request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/v1/external/shipments/{shipmentId}:
get:
tags:
- Shipments
summary: Get shipment details
description: Retrieve detailed information about a specific shipment.
security:
- bearerAuth: []
parameters:
- name: shipmentId
in: path
required: true
schema:
type: string
description: Unique shipment identifier
responses:
'200':
description: Shipment details retrieved successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
$ref: '#/components/schemas/ShipmentDetails'
'404':
description: Shipment not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
put:
tags:
- Shipments
summary: Update shipment
description: Update an existing shipment's details.
security:
- bearerAuth: []
parameters:
- name: shipmentId
in: path
required: true
schema:
type: string
description: Unique shipment identifier
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateShipmentRequest'
responses:
'200':
description: 'Shipment updated successfully
'
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
$ref: '#/components/schemas/ShipmentDetails'
'404':
description: Shipment not found
delete:
tags:
- Shipments
summary: Delete shipment
description: Delete a shipment and all associated data.
security:
- bearerAuth: []
parameters:
- name: shipmentId
in: path
required: true
schema:
type: string
description: Unique shipment identifier
responses:
'204':
description: Shipment deleted successfully
'404':
description: Shipment not found
/api/v1/external/shipments/{shipmentId}/details:
get:
tags:
- Shipments
summary: Get detailed shipment information
description: Retrieve comprehensive shipment details including items and containers.
security:
- bearerAuth: []
parameters:
- name: shipmentId
in: path
required: true
schema:
type: string
description: Unique shipment identifier
responses:
'200':
description: Detailed shipment information retrieved successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: object
properties:
shipment:
$ref: '#/components/schemas/ShipmentDetails'
items:
type: array
items:
$ref: '#/components/schemas/ShipmentItem'
containers:
type: array
items:
$ref: '#/components/schemas/Container'
'404':
description: Shipment not found
put:
tags:
- Shipments
summary: Update shipment information
description: "Update shipment-level details only. \nTo update containers, packages, or items, use the respective CRUD endpoints:\n- Containers: PUT /shipments/{shipmentId}/containers/{containerId}\n- Packages: PUT /shipments/{shipmentId}/packages/{packageId}\n- Items: PUT /shipments/{shipmentId}/items/{itemId}\n"
security:
- bearerAuth: []
parameters:
- name: shipmentId
in: path
required: true
schema:
type: string
description: Unique shipment identifier
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateShipmentDetailsRequest'
responses:
'200':
description: Shipment details updated successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
$ref: '#/components/schemas/ShipmentDetails'
message:
type: string
'400':
description: Invalid request parameters
'404':
description: Shipment not found
/api/v1/external/shipments/{shipmentId}/events:
get:
tags:
- Shipments
summary: Get shipment events
description: Retrieve chronological events and milestones for a shipment.
security:
- bearerAuth: []
parameters:
- name: shipmentId
in: path
required: true
schema:
type: string
description: Unique shipment identifier
responses:
'200':
description: Shipment events retrieved successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: object
properties:
events:
type: array
items:
$ref: '#/components/schemas/ShipmentEvent'
'404':
description: Shipment not found
/api/v1/external/shipments/{shipmentId}/validation-items:
get:
tags:
- Shipments
summary: Get validation items
description: Retrieve all validation items for a shipment with optional filtering.
security:
- bearerAuth: []
parameters:
- name: shipmentId
in: path
required: true
schema:
type: string
description: Unique shipment identifier
- name: status
in: query
schema:
type: string
description: Filter by validation item status
- name: actionStatus
in: query
schema:
type: string
enum:
- PENDING
- ACCEPTED
- IGNORED
- OVERRIDDEN
description: Filter by validation item action status
responses:
'200':
description: Validation items retrieved successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: array
items:
$ref: '#/components/schemas/ValidationItem'
'404':
description: Shipment not found
/api/v1/external/shipments/{shipmentId}/validation-items/{itemId}:
put:
tags:
- Shipments
summary: Update validation item
description: Update the action status and details of a validation item.
security:
- bearerAuth: []
parameters:
- name: shipmentId
in: path
required: true
schema:
type: string
description: Unique shipment identifier
- name: itemId
in: path
required: true
schema:
type: string
description: Unique validation item identifier
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateValidationItemRequest'
responses:
'200':
description: Validation item updated successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
example: Validation item updated successfully
'400':
description: Invalid request
'404':
description: Validation item or shipment not found
/api/v1/external/shipments/{shipmentId}/validation-items/bulk-update:
post:
tags:
- Shipments
summary: Bulk update validation items
description: Update multiple validation items at once with the same action.
security:
- bearerAuth: []
parameters:
- name: shipmentId
in: path
required: true
schema:
type: string
description: Unique shipment identifier
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
itemIds:
type: array
items:
type: string
minItems: 1
maxItems: 100
description: Array of validation item IDs to update
actionStatus:
type: string
enum:
- ACCEPTED
- IGNORED
- OVERRIDDEN
description: Action to apply to all items
actionReason:
type: string
description: Optional reason explaining the action
required:
- itemIds
- actionStatus
responses:
'200':
description: Validation items updated successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: object
nullable: true
message:
type: string
example: 5 validation items updated successfully
'400':
description: Invalid request
'404':
description: Shipment not found
/api/v1/external/shipments/{shipmentId}/jobs:
get:
tags:
- Shipments
summary: Get shipment jobs
description: Retrieve all background jobs (extraction, validation, merge) for a shipment.
security:
- bearerAuth: []
parameters:
- name: shipmentId
in: path
required: true
schema:
type: string
description: Unique shipment identifier
responses:
'200':
description: Jobs retrieved successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: object
properties:
jobs:
type: object
properties:
crossValidation:
type: array
items:
$ref: '#/components/schemas/CrossValidationJob'
merge:
type: array
items:
$ref: '#/components/schemas/MergeJob'
'404':
description: Shipment not found
/api/v1/external/shipments/{shipmentId}/containers:
get:
tags:
- Shipments
summary: List containers
description: Retrieve all containers for a specific shipment.
security:
- bearerAuth: []
parameters:
- name: shipmentId
in: path
required: true
schema:
type: string
description: Unique shipment identifier
responses:
'200':
description: Containers retrieved successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: object
properties:
containers:
type: array
items:
$ref: '#/components/schemas/ShipmentContainer'
'404':
description: Shipment not found
post:
tags:
- Shipments
summary: Create container
description: Add a new container to a shipment.
security:
- bearerAuth: []
parameters:
- name: shipmentId
in: path
required: true
schema:
type: string
description: Unique shipment identifier
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateContainerRequest'
responses:
'201':
description: Container created successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
$ref: '#/components/schemas/ShipmentContainer'
message:
type: string
'400':
description: Invalid request data
'404':
description: Shipment not found
/api/v1/external/shipments/{shipmentId}/containers/{containerId}:
put:
tags:
- Shipments
summary: Update container
description: Update an existing container's details.
security:
- bearerAuth: []
parameters:
- name: shipmentId
in: path
required: true
schema:
type: string
description: Unique shipment identifier
- name: containerId
in: path
required: true
schema:
type: string
description: Unique container identifier
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateContainerRequest'
responses:
'200':
description: Container updated successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
$ref: '#/components/schemas/ShipmentContainer'
message:
type: string
'400':
description: Invalid request data
'404':
description: Container or shipment not found
delete:
tags:
- Shipments
summary: Delete container
description: Remove a container from a shipment. Associated packages will become loose packages.
security:
- bearerAuth: []
parameters:
- name: shipmentId
in: path
required: true
schema:
type: string
description: Unique shipment identifier
- name: containerId
in: path
required: true
schema:
type: string
description: Unique container identifier
responses:
'200':
description: Container deleted successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: object
properties:
success:
type: boolean
message:
type: string
'404':
description: Container or shipment not found
/api/v1/external/shipments/{shipmentId}/packages:
get:
tags:
- Shipments
summary: List packages
description: Retrieve all packages for a specific shipment, optionally filtered by container.
security:
- bearerAuth: []
parameters:
- name: shipmentId
in: path
required: true
schema:
type: string
description: Unique shipment identifier
- name: containerId
in: query
required: false
schema:
type: string
nullable: true
description: Filter packages by container ID (use 'null' for loose packages)
responses:
'200':
description: Packages retrieved successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: object
properties:
packages:
type: array
items:
$ref: '#/components/schemas/ShipmentPackage'
'404':
description: Shipment not found
post:
tags:
- Shipments
summary: Create package
description: Add a new package to a shipment (either in a container or as a loose package).
security:
- bearerAuth: []
parameters:
- name: shipmentId
in: path
required: true
schema:
type: string
description: Unique shipment identifier
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePackageRequest'
responses:
'201':
description: Package created successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
$ref: '#/components/schemas/ShipmentPackage'
message:
type: string
'400':
description: Invalid request data
'404':
description: Shipment not found
/api/v1/external/shipments/{shipmentId}/packages/{packageId}:
put:
tags:
- Shipments
summary: Update package
description: Update an existing package's details.
security:
- bearerAuth: []
parameters:
- name: shipmentId
in: path
required: true
schema:
type: string
description: Unique shipment identifier
- name: packageId
in: path
required: true
schema:
type: string
description: Unique package identifier
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePackageRequest'
responses:
'200':
description: Package updated successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
$ref: '#/components/schemas/ShipmentPackage'
message:
type: string
'400':
description: Invalid request data
'404':
description: Package or shipment not found
delete:
tags:
- Shipments
summary: Delete package
description: Remove a package from a shipment. Associated items will be deleted.
security:
- bearerAuth: []
parameters:
- name: shipmentId
in: path
required: true
schema:
type: string
description: Unique shipment identifier
- name: packageId
in: path
required: true
schema:
type: string
description: Unique package identifier
responses:
'200':
description: Package deleted successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: object
properties:
success:
type: boolean
message:
type: string
'404':
description: Package or shipment not found
/api/v1/external/shipments/{shipmentId}/packages/{packageId}/move:
post:
tags:
- Shipments
summary: Move package
description: Move a package to a different container or make it a loose package.
security:
- bearerAuth: []
parameters:
- name: shipmentId
in: path
required: true
schema:
type: string
description: Unique shipment identifier
- name: packageId
in: path
required: true
schema:
type: string
description: Unique package identifier
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
containerId:
type: string
nullable: true
description: Target container ID (null to make it a loose package)
required:
- containerId
responses:
'200':
description: Package moved successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
'400':
description: Invalid request data
'404':
description: Package, container, or shipment not found
/api/v1/external/shipments/{shipmentId}/items:
get:
tags:
- Shipments
summary: List items
description: Retrieve all items for a specific shipment, optionally filtered by package.
security:
- bearerAuth: []
parameters:
- name: shipmentId
in: path
required: true
schema:
type: string
description: Unique shipment identifier
- name: packageId
in: query
required: false
schema:
type: string
description: Filter items by package ID
responses:
'200':
description: Items retrieved successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/ShipmentItem'
'404':
description: Shipment not found
post:
tags:
- Shipments
summary: Create item
description: Add a new item to a package.
security:
- bearerAuth: []
parameters:
- name: shipmentId
in: path
required: true
schema:
type: string
description: Unique shipment identifier
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateItemRequest'
responses:
'201':
description: Item created successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
$ref: '#/components/schemas/ShipmentItem'
message:
type: string
'400':
description: Invalid request data
'404':
description: Shipment or package not found
/api/v1/external/shipments/{shipmentId}/items/{itemId}:
put:
tags:
- Shipments
summary: Update item
description: Update an existing item's details.
security:
- bearerAuth: []
parameters:
- name: shipmentId
# --- truncated at 32 KB (66 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/wove/refs/heads/main/openapi/wove-shipments-api-openapi.yml