🔽 Downstream API - send to 🌐

Endpoints

Method	Path	Description
POST	/downstream/tradeflows	Create a tradeflow or update an existing one. Accepts a single object or an array.
DELETE	/downstream/tradeflows/{tradeflow_reference}	Deactivate a tradeflow. ?hard=true → permanently delete.

---

1 · Create / update tradeflows POST /downstream/tradeflows

Payload format

A single JSON object or an array of objects.

{
  "tradeflow_reference": "PO4564268", // required

  // Tracking references — string OR array
  "container_reference": [
    {
      "reference": "ABCD1234567",
      "custom_properties": {
        "requires_inspection": true,
        "quality_check_date": "2025-05-01"
      }
    },
    {
      "reference": "EFGH7654321",
      "custom_properties": {
        "requires_inspection": true,
        "quality_check_date": "2025-05-01"
      }
    }
  ],
  "container_references_complete": true,

  "bill_of_lading_reference": "ANR00001010",
  "booking_reference": ["94512540", "94512888"],

  // Tradeflow status
  "active": true, // default = true

  // Carrier name
  "carrier_name": "Maersk", // optional
  "carrier_scac": "MAEU", // optional

  // Partner shortcuts
  "customer_name": "Fruit Maker EXIM International",
  "customer_reference": "PO_12345_CUST", // optional
  "partners": [
    {
      "name": "Best Forwarder BV",
      "role": "forwarder",
      "reference": "PO_4564268"
    }
  ],
  "partners_complete": false,

  // Voyage metadata
  "port_of_loading": "BEANR",
  "port_of_discharge": "USLAX",

  "estimated_time_of_departure": "2025-05-14T12:00:00Z",
  // or - when vessel has already departed
  "actual_time_of_departure": "2025-05-14T12:00:00Z",

  "estimated_time_of_arrival": "2025-06-06T22:00:00Z",
  // or - when vessel has already arrived
  "actual_time_of_arrival": "2025-06-06T22:00:00Z",

  "vessel": "Maersk SOPHIE",
  "incoterms": "FOB",
  "references": {
    "house_bill_of_lading": "hbl_123456789", // optional house bill of lading reference
    "delivery_location": "Factory yard 12345", // optional, string of the delivery location
    "delivery_event_date": "2021-08-24T15:00:25+00:00" // optional, ISO-date of delivery
  },

  // Optional self-defined events
  "events": [
    {
      "message": "delivery at client",
      "container_reference": "ABCD1234567",
      "location_name": "BEANR", // also accepts string-addresses
      "event_date": "2025-05-12T08:34:00Z",
      "actual": true // whether the event already happened – or is scheduled
    }
  ],

  // NEW · Arbitrary key-value pairs defined by you
  "custom_references": {
    "invoice_number": "INV-12345",
    "priority": 2,
    "quality_check_date": "2025-05-01",
    "requires_inspection": true
  }
}

custom_references — what & why

Field	Type	Description
custom_references	object	A free-form dictionary whose keys are fully user-defined. Each value may be a string, number, boolean, or ISO-8601 date. Use it for anything that doesn’t fit the prescribed schema (e.g. internal IDs, workflow flags, etc.).

• Nested objects or arrays inside custom_references are not allowed (hard-fail).
• Keys are case-sensitive UTF-8 strings (≤ 255 chars).
• Duplicate keys in the object are rejected (409 Conflict).

Complete-list flags

Flag	Applies to	Effect when true
container_references_complete	container_reference[]	Containers not listed are removed.
bill_of_lading_references_complete	bill_of_lading_reference[]	Same logic.
booking_references_complete	booking_reference[]	Same logic.
partners_complete	partners[]	Partners not listed are removed.

If a _complete flag is omitted, the list is merged instead of replaced.

Partner input

• customer_name — quick way to add one partner with role customer.
• partners — full array that supports multiple roles and references. Both inputs may be combined.

Response 202 Accepted

Processing is asynchronous. The response lists queued items and any warnings:

{
  "status": "queued",
  "tradeflows": [
    {
      "tradeflow_reference": "PO4564268",
      "created": false,
      "warnings": [
        {
          "path": "[0].container_reference[1]",
          "message": "EFGH7654321 does not match ISO 6346 and was ignored"
        },
        {
          "path": "[0].custom_references.quality_check_date",
          "message": "Date must be ISO-8601; received \"20250501\""
        }
      ]
    }
  ]
}

Warnings indicate values that were ignored without blocking the request (soft-fail).

---

2 · Remove tradeflows DELETE /downstream/tradeflows/{tradeflow_reference}

Action	How
Deactivate (preferred)	DELETE /downstream/tradeflows/PO4564268 — same effect as posting "active": false.
Permanent delete	DELETE /downstream/tradeflows/PO4564268?hard=true

Returns 204 No Content on success.

UAT entity filtering

When using * as the tradeflow_reference, the system will only target tradeflows belonging to entities that are UAT environments (where is_uat_for_entity_id is not null). This allows you to perform bulk operations on UAT entities without affecting production data.

Example:

DELETE /downstream/tradeflows/*

This will deactivate all tradeflows for UAT entities only.

---

Validation rules

Hard-fail (request rejected — 400 Bad Request):

• Payload must be JSON object or array.

• tradeflow_reference missing or longer than 255 characters.

• Date fields not ISO-8601 (YYYY-MM-DDTHH:MM:SSZ) or YYYYMMDD.

• port_of_loading / port_of_discharge not a 2-letter ISO country code or 5-character UN/LOCODE.

• custom_references:

  • Contains nested array/object values.
  • A value is not string/number/boolean/date.
  • Total number of keys > 50.

Soft-fail (processed but returned as warnings):

• container_reference not matching ^[A-Z]{4}[0-9]{7}$.
• Empty strings or null values inside array fields.
• Unknown top-level properties (outside custom_references).

---

Error codes

Status	Meaning
400 Bad Request	Validation failed (hard-fail rules).
401 Unauthorized	Missing or invalid Authorization token.
404 Not Found	Tradeflow not found on delete.
409 Conflict	Same tradeflow_reference appears twice in one payload. Duplicate key inside custom_references.
500 Internal Server Error	Unexpected error during processing.

---

Questions or feedback? Create an issue in the public repository or contact Dockflow support.