🧪 UAT / test environment

Base URL

https://uat.dockflow.com/v3

UAT mirrors the production API surface.
The only difference is authentication and the optional mock‑tracking features described below.

Environment	Host	Required key prefix
Production	`api.dockflow.com`	`prod_…`
UAT (sandbox)	`uat.dockflow.com`	`uat_…`

Production keys are rejected on UAT, and vice versa (403 Token environment … does not match host …).

UAT data lives in a separate UAT organisation that Dockflow creates for you the first time an API key is created. A uat_ key reads and writes only that organisation, so nothing you send in UAT reaches your production account. Create UAT keys in the API Console by choosing the UAT environment.

What UAT is

UAT is a separate organisation, not a separate platform. The first token created for your organisation (production or UAT) automatically creates a companion organisation named <Your organisation> (UAT), and everything a uat_… token writes lands there instead of in your live organisation. Your live organisation is granted access to it, so the same login can open it from the organisation switcher in the Dockflow app and in the API Console.

That design has two consequences worth planning for:

You can see your test data in the product. Switch to the (UAT) organisation and the tradeflows you posted appear exactly as production tradeflows do, with the same screens and exports — see Working in the UAT organisation.
It runs on live infrastructure. Container tracking, carrier lookups and terminal integrations behave as they do for any organisation: post a real container number and Dockflow will really go and track it. Notifications and upstream delivery for the UAT organisation are live too — anything you subscribe a user to there will actually be sent.

Use mock tracking when you want a predictable journey instead of whatever a real container happens to be doing.

Differences from production

Behaviour	Production	UAT
Token prefix / host	`prod_…` on `api.dockflow.com`	`uat_…` on `uat.dockflow.com`
`mock_tracking`	Ignored	Generates a synthetic journey
`customer_name` and `partners[]`	Create organisations and tradeflow links	Ignored — no organisation is created or linked
Bulk delete `DELETE /downstream/tradeflows/*`	Requires `?confirm=PRODUCTION`	Allowed without confirmation

Everything else — validation, response shapes, upstream payloads, documents — is the same code path as production.

Working in the UAT organisation

Find the right organisation

The sandbox is the organisation whose name ends in (UAT). A live organisation may itself be named after a test environment, so the suffix rather than the word is what separates them: Acme UAT is a live organisation, Acme UAT (UAT) is its sandbox. Anything posted with a uat_… token lands in the (UAT) one and is visible nowhere else.

To open it, go to Settings ▸ Partners in the Dockflow app, pick the organisation ending in (UAT), and log in to it. If it is missing from the list or the login is greyed out, mail [email protected] — access is granted per user.

After a `202`

POST /downstream/tradeflows answers {"status": "queued"} and finishes the work afterwards, so a tradeflow shows up in the app a moment later rather than instantly. queued means accepted.

If nothing has appeared after a minute, check which organisation you are looking at before re-sending — a payload that was accepted but is "missing" is almost always being looked for in the live organisation instead of the (UAT) one.

Build against a real message

Once a tradeflow exists in the UAT organisation, open it and use Download ▸ Download V3 API on the tradeflow header. The file is produced by the same renderer as the Upstream API, so you can replay it into your own consumer — from Postman or a test — and build your processing without waiting for Dockflow to push anything.

One difference to allow for: the download always contains all five blocks, including vessels, while a webhook message carries only events, locations, containers and shipment. Do not make vessels a required field on the strength of the downloaded sample.

Mock tracking

When posting a tradeflow to /downstream/tradeflows in UAT, include the field mock_tracking and Dockflow generates events that simulate real‑world progress.

Basic format

{
  "tradeflow_reference": "PO4564268",
  "port_of_loading": "BEANR",
  "port_of_discharge": "USLAX",

  "mock_tracking": {
    "scenario": "ocean_basic"
  }
}

Property	Type	Default	Description
`scenario`	`string`	–	Selects the event template (table below).

An unknown scenario name is ignored: the tradeflow is created, but no mock events are added.

Inputs it uses

Field	If you omit it
`port_of_loading` / `port_of_discharge` (5‑char UN/LOCODE)	The events for that side of the journey are not generated
`container_reference`	A random existing container is picked, so events still appear
`actual_time_of_departure` / `estimated_time_of_departure`	Departure is set to yesterday
`estimated_time_of_arrival` / `actual_time_of_arrival`	Arrival is set to 30 days from now

Predefined scenarios

Code	Events that will be generated
`ocean_basic`	Actual, at the port of loading: gate out empty (departure − 3d), gate in full (− 2d), loaded on vessel (− 1d). Predicted, at the port of discharge: vessel arrival (arrival), unloaded from vessel (+ 1d), gate out full (+ 2d), empty equipment returned (+ 7d).

Additional scenarios may be added in future versions.

To see what this scenario looks like on the wire before importing anything, use Send test on a webhook destination: it sends an ocean_basic record straight to your endpoint (see Upstream › Webhook delivery).

Custom events

For full control, send your own events array (see Tradeflows API). If both events and mock_tracking.scenario are present, your own events are kept and the mock sequence is appended after them.

Usage example

curl -X POST https://uat.dockflow.com/v3/downstream/tradeflows \
     -H "Authorization: uat_acme-logistics_Zk3n1c0Q2m9..." \
     -H "Content-Type: application/json" \
     -d '{
           "tradeflow_reference": "PO4564268",
           "port_of_loading": "BEANR",
           "port_of_discharge": "USLAX",
           "mock_tracking": { "scenario": "ocean_basic" }
         }'

Response (202 Accepted):

{
  "status": "queued",
  "tradeflows": [{ "tradeflow_reference": "PO4564268", "warnings": [] }]
}

Posting is asynchronous: the tradeflow and its events are processed after the 202, so poll GET /v3/upstream?since=… (or open the (UAT) organisation in the app) to see the result.

Cleaning up

There is no automatic wipe — UAT data stays until you remove it. To start from a clean sheet:

DELETE https://uat.dockflow.com/v3/downstream/tradeflows/*

That deactivates every tradeflow in your UAT organisation; add ?hard=true to delete them permanently. Unlike production, no confirm parameter is needed.

UAT webhooks: configure a destination on your UAT organisation in the API Console to receive UAT updates (see Upstream › Webhook delivery).

Use UAT to validate integrations safely before switching to production. For questions about tokens or mock scenarios, contact Dockflow support.

Base URL​

What UAT is​

Differences from production​

Working in the UAT organisation​

Find the right organisation​

After a 202​

Build against a real message​

Mock tracking​

Basic format​

Inputs it uses​

Predefined scenarios​

Custom events​

Usage example​

Cleaning up​