📫 Documents API

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

---

Quick start

# 1. Fetch available document types
curl https://api.dockflow.com/v3/downstream/documents/types \
  -H "Authorization: Bearer prod_acme-logistics_kJ8sV3nQ..."

# 2. Upload a document (replace the `<…>` values)
curl -X POST https://api.dockflow.com/v3/downstream/documents \
     -H "Authorization: Bearer <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	✔︎	An allowed extension (see "Validation rules").
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 \
     -H "Authorization: Bearer <API‑token>"

Successful response 200 OK

{
  "data": [
    {
      "id": 123456789,
      "name": "2025-05-05t14_22_07_00_00_invoice_4564268_inv_tf_789_123456789_v1.pdf",
      "filetype": "pdf",
      "input_name": "Invoice 4564268",
      "version": 0,
      "document_type": {
        "name": "INV",
        "description": "Commercial invoice"
      },
      "metadata": null,
      "created_at": "2025-05-05T14:22:07+00:00",
      "updated_at": "2025-05-05T14:22:07+00:00"
    }
  ],
  "tradeflow_reference": "PO4564268",
  "count": 1
}

Field	Type	Description
data	array	Array of document objects.
id	integer	Unique document identifier.
name	string	Generated filename (includes timestamp, type, ID).
filetype	string	File extension (pdf, doc, etc.).
input_name	string|null	Original filename provided during upload.
version	integer	Document version (starts at 0).
document_type	object|null	Document type with name and description.
metadata	object|null	Custom metadata (JSON).
created_at	string	ISO 8601 timestamp.
updated_at	string	ISO 8601 timestamp.
count	integer	Total number of documents returned.

---

4 · Update a document PATCH /{id}

Request body can contain any of:

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

Returns 200 OK with the updated document, in the same shape as an item of the list in §3.

• An unknown document_type is ignored and the type is left unchanged.
• An unknown container_reference unlinks the document from any container.

---

5 · Delete a document DELETE /{id}

Irreversible.

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

204 No Content on success.

---

Validation rules

• tradeflow_reference and document_extension are required.
• document_extension must be one of pdf|doc|docx|xls|xlsx|jpg|jpeg|png|gif|bmp|tif|tiff|svg|webp (lower case).
• document_payload_base64 is required and must be valid Base‑64.
• tradeflow_reference has to exist on your Dockflow entity.
• document_type should be one of the codes from the /types endpoint. An unknown or missing value is not rejected; the document is stored without a business type.
• An unknown container_reference is accepted and the document is stored without a container link.

The backend responds with 400 Bad Request and a message if any of the first four rules fails.

---

Common errors

Status	When it happens
400	Invalid JSON, missing required fields, bad Base‑64, unsupported document_extension, or on POST a tradeflow_reference that does not exist on your entity; also Token format invalid.
401	Missing or malformed Authorization header, or unknown token.
403	Token environment does not match the host (prod_ vs uat_), or the token is revoked.
404	GET: tradeflow not found. PATCH / DELETE: document not found, or not on one of your tradeflows.
500	The document could not be created, updated or deleted.