POST /v1/shipments
Attach or update the shipment of a deal
Attach or update the shipment of a deal
One shipment per deal: the first call attaches the container / bill of lading, later calls update it. If a container or B/L number is given the container tracker is queried immediately; a tracker failure is returned in warnings and the shipment is still saved. Emits shipment.updated (webhook). Supports Idempotency-Key. Requires scope write:deals.
- Автентифікація: заголовок
Authorization: Bearer rv_live_...(API-ключі та scopes) - Потрібний scope:
write:deals
openapi.json) і подається англійською, як у самому API.Параметри
| Поле | Де | Тип | Обов’язк. | Опис |
|---|---|---|---|---|
idempotency-key | header | string | ні | Makes a retry of this POST safe for 24 hours: the same key and body returns the stored response (Idempotent-Replay: true). |
Тіло запиту
| Поле | Тип | Обов’язк. | Опис |
|---|---|---|---|
dealId | string (uuid) | так | |
mode | "container" | "roro" | "truck" | ні | |
containerNo | string | ні | |
billOfLading | string | ні | |
bookingNo | string | ні | |
carrier | string | ні | |
vessel | string | ні | |
portFrom | string | ні | |
portTo | string | ні | |
warehouse | string | ні | |
etd | string (date-time) | ні | |
eta | string (date-time) | ні | |
trackingProvider | "shipsgo" | "terminal49" | "manual" | ні | |
refresh | boolean | ні |
Відповіді
200
The shipment after the update.
application/json · Схема: Shipment
| Поле | Тип | Обов’язк. | Опис |
|---|---|---|---|
id | string (uuid) | так | |
dealId | string (uuid) | так | |
status | "planned" | "booked" | "loaded" | "in_transit" | "at_port" | "discharged" | "released" | "delivered" | так | |
containerNo | string | null | так | |
billOfLading | string | null | так | |
vessel | string | null | так | |
portFrom | string | null | так | |
portTo | string | null | так | |
etd | string | null | так | ISO 8601 date-time (UTC). |
eta | string | null | так | ISO 8601 date-time (UTC). |
ata | string | null | так | ISO 8601 date-time (UTC). |
events | object[] | так | |
events[].at | string | ні | |
events[].code | string | ні | |
events[].description | string | ні | |
events[].location | string | ні | |
events[].vessel | string | ні | |
lastTrackedAt | string | null | так | ISO 8601 date-time (UTC). |
warnings | string[] | так |
400
Invalid request parameters or body (code validation_error).
application/problem+json · Схема: Problem
401
Missing, malformed, unknown, revoked or expired API key (code unauthorized).
application/problem+json · Схема: Problem
403
The API key lacks the scope required by this endpoint (code insufficient_scope).
application/problem+json · Схема: Problem
404
Not found in this tenant.
application/problem+json · Схема: Problem
409
A request with this Idempotency-Key is still being processed.
application/problem+json · Схема: Problem
422
No container/B/L number, or Idempotency-Key reused.
application/problem+json · Схема: Problem
429
Rate limit exceeded for the tenant plan (code rate_limited). Wait Retry-After seconds.
application/problem+json · Схема: Problem