📫 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 # no 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	✔︎	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: Authorization <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"
}

---

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

• document_extension must be one of pdf|doc|docx|xls|xlsx|jpg|jpeg|png|gif|bmp|tif|tiff|svg|webp.
• 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, bad Base‑64, or unsupported document_extension.
401	Missing/invalid API token.
404	Tradeflow or document not found.