📫 Documents API

Early‑Access API

🚧 Heads‑up! This is our next‑generation API and it’s still under active development.
We’re shipping improvements fast, which means endpoints, payloads, and error codes may change without notice until we reach General Availability (GA).

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!

Base URL: https://api.dockflow.com/v3

---

Quick start

# 1. Fetch available document types
curl https://api.dockflow.com/v3/downstream/documents/types # not authorization required for this endpoint

# 2. Upload a document (replace the `<…>` values)
curl -X POST https://api.dockflow.com/v3/downstream/documents \
     -H "Authorization: Authorization <API‑token>" \
     -H "Content-Type: application/json" \
     -d '{ ... see JSON example below ...}'

---

Endpoints

Method	Path	Purpose
GET	/downstream/documents/types	List supported business document types (e.g. INV, POD, …).
POST	/downstream/documents	Upload a new document to a Tradeflow.
GET	/downstream/documents/{tradeflow_reference}	List every document already attached to a Tradeflow.
PATCH	/downstream/documents/{id}	Update the filename, business type or container link of a single document.
DELETE	/downstream/documents/{id}	Permanently remove a document.

---

1 · List business document types  GET /types

Returns an array of objects:

[
  {
    "type": "INV",
    "description": "Commercial invoice"
  },
  {
    "type": "POD",
    "description": "Proof of delivery"
  }
]

---

2 · Create a document  POST /downstream/documents

Request body

Field	Type	Required	Notes
tradeflow_reference	string	✔︎	Your own reference (PO / SO / BL / …).
document_extension	string	✔︎	One of pdf, doc, docx, xls, xlsx.
document_payload_base64	string(base64)	✔︎	The raw file encoded with Base‑64.
document_filename	string	–	Friendly file name shown in Dockflow.
document_type	string	–	Must match one of /types (INV, POD, …).
container_reference	string	–	ISO 6346 container number to link to.

Example request (Invoice PDF)

{
  "tradeflow_reference": "PO4564268",
  "document_extension": "pdf",
  "document_filename": "Invoice 4564268",
  "document_type": "INV",
  "container_reference": "ABCD1234567",
  "document_payload_base64": "JVBERi0xLjQgCjEgMCBvYmog..."
}

Successful response 202 Accepted

{
  "id": 123456789,
  "tradeflow_reference": "PO4564268",
  "document_type": "INV",
  "filename": "Invoice 4564268.pdf",
  "filetype": "pdf",
  "container_reference": "ABCD1234567",
  "created_at": "2025‑05‑05T14:22:07Z"
}

(The payload itself is not returned.)

---

3 · List Tradeflow documents  GET /{tradeflow_reference}

curl https://api.dockflow.com/v3/downstream/documents/PO4564268

Returns an array of the same objects as above.

---

4 · Update a document  PATCH /{id}

Request body can contain any of:

{
  "document_filename": "New name.pdf",
  "document_type": "POD",
  "container_reference": "EFGH7654321"
}

---

5 · Delete a document  DELETE /{id}

Irreversible.

curl -X DELETE https://api.dockflow.com/v3/downstream/documents/dfdoc_0f93d2e9

204 No Content on success.

---

Validation rules

• document_extension must be one of pdf|doc|docx|xls|xlsx.
• document_payload_base64 must be valid Base‑64.
• tradeflow_reference has to exist on your Dockflow entity.
• document_type must match one of the 3-char codes from the /types endpoint, or must be empty.

The backend will respond with 400 Bad Request and a meaningful error if any rule fails.

---

Common errors

Status	When it happens
400	Invalid JSON, missing required fields, or bad Base‑64.
401	Missing/invalid API token.
404	Tradeflow or document not found.
415	Unsupported document_extension.