🔽 Downstream API - send to 🌐

Early‑Access API

🚧 Heads‑up! This is our next‑generation API and it’s still under active development.

How you can help

1. Try it out in non‑production environments first.
2. Report issues or request features by mailing [email protected]

Thank you for partnering with us to shape the future of our platform!

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": ["ABCD1234567","EFGH7654321"],
  "container_references_complete": true,

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

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

  // Partner shortcuts
  "customer_name": "Fruit Maker EXIM International",

  "partners": [
    { "name": "Best Forwarder BV", "role": "forwarder" }
  ],
  "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",

  // 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
    }
  ]
}

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"
        }
      ]
    }
  ]
}

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.

---

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.

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 properties.

---

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.
500 Internal Server Error	Unexpected error during processing.

---

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