Dokumentace pro integrátory · verze 1

Docflow API

Pošlete PDF, vyberte šablonu a dostanete hodnoty polí. Ke každé hodnotě patří doslovná citace z dokumentu, číslo strany, jistota modelu a příznak, zda se citace v PDF opravdu našla. Pravidla šablony (součty, IČO, pořadí dat) počítá deterministický kód.

Strojově čitelná specifikace: OpenAPI / Swagger · openapi.json

Přístup

Každý klient dostane vlastní API klíč (dfk_…) s denní kvótou extrakcí. Klíč se posílá v hlavičce Authorization: Bearer <klíč>. Klient vidí jen své dokumenty. Klíč lze kdykoli odvolat a vydat nový. Pokud firma používá i aplikaci Docflow, klíč patří k jejímu pracovnímu prostoru: v API jsou dostupné i šablony, které si firma vytvořila v aplikaci, a extrakce se počítají do její kvóty. Požádat o klíč

Postup v příkladech

1. Nahrání PDF. Se stejným Idempotency-Key a stejným souborem vrátí API původní dokument (200), nevznikne duplikát.

curl -X POST https://docflow-api-yh74.onrender.com/v1/documents \
  -H "Authorization: Bearer $DOCFLOW_KEY" \
  -H "Idempotency-Key: objednavka-OP-2026-0815" \
  -F file=@objednavka.pdf
# 201 {"id": "7VCKELG_m3yoFvtkNJcm4w", "filename": "objednavka.pdf", "page_count": 1, ...}

2. Spuštění vytěžení. Běží na pozadí, odpověď přijde hned se stavem running.

curl -X POST https://docflow-api-yh74.onrender.com/v1/documents/7VCKELG_m3yoFvtkNJcm4w/extract \
  -H "Authorization: Bearer $DOCFLOW_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template_id": "transport_order"}'
# 202 {"id": "3GRKSx9XRhKxqpiu_XjtDQ", "status": "running", ...}

3. Dotazování na výsledek, dokud status není running (stačí každé 2–3 s; jednostránkový dokument trvá obvykle 10–60 s). S webhookem se dotazovat nemusíte, viz Webhooky.

curl https://docflow-api-yh74.onrender.com/v1/extractions/3GRKSx9XRhKxqpiu_XjtDQ \
  -H "Authorization: Bearer $DOCFLOW_KEY"

4. Export. xlsx a json pro každý dokončený výsledek.

curl -o objednavka.xlsx \
  "https://docflow-api-yh74.onrender.com/v1/extractions/3GRKSx9XRhKxqpiu_XjtDQ/export?format=xlsx" \
  -H "Authorization: Bearer $DOCFLOW_KEY"

5. Přijaté faktury do účetnictví. pohoda a money (XML import) fungují jen pro šablonu invoice po lidském schválení a bez chybových nálezů. Schválení s případnými opravami hodnot (klíče polí podle šablony):

curl -X PATCH https://docflow-api-yh74.onrender.com/v1/extractions/<id> \
  -H "Authorization: Bearer $DOCFLOW_KEY" \
  -H "Content-Type: application/json" \
  -d '{"values": {"due_date": "17. 9. 2026"}}'

curl -o faktura-pohoda.xml \
  "https://docflow-api-yh74.onrender.com/v1/extractions/<id>/export?format=pohoda" \
  -H "Authorization: Bearer $DOCFLOW_KEY"

Webhooky

Po domluvě nastavím ke klíči adresu (https://) a předám podpisový klíč whsec_…. Po dokončení každé extrakce pošle Docflow na adresu POST s JSON {"id", "event", "created_at", "data"}, kde data je stejný objekt jako z GET /extractions/{id}. Událost extraction.completed nebo extraction.failed je i v hlavičce Docflow-Event. Odpovězte kódem 2xx do 10 s; jinak se doručení zopakuje po 5 a 30 s. Podpis v hlavičce Docflow-Signature: t=…,v1=… je HMAC-SHA256 řetězce <t>.<tělo požadavku>:

import hashlib, hmac, time

def verify(body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + body, hashlib.sha256)
    fresh = abs(time.time() - int(parts["t"])) < 300  # ochrana proti přehrání
    return fresh and hmac.compare_digest(parts["v1"], expected.hexdigest())

Ukázka odpovědi

Skutečná odpověď na fiktivní objednávku přepravy, zkrácená na dvě pole. value je normalizovaná hodnota (čísla jako čísla, data jako RRRR-MM-DD), raw zápis v dokumentu. status: ok bez nálezů, needs_review s nálezy ke kontrole, approved po schválení, failed při chybě. Pravidlo má výsledek passed, failed nebo skipped (chybí hodnota).

{
  "id": "3GRKSx9XRhKxqpiu_XjtDQ",
  "document_id": "7VCKELG_m3yoFvtkNJcm4w",
  "template_id": "transport_order",
  "status": "ok",
  "model": "qwen/qwen3.6-35b-a3b",
  "created_at": "2026-10-21T14:48:55.223076Z",
  "reviewed_at": null,
  "latency_s": 11.4,
  "fields": [
    {
      "key": "loading_date",
      "label": "Datum nakládky",
      "type": "date",
      "value": "2026-11-04",
      "raw": "4. 11. 2026, 8:00",
      "page": 1,
      "quote": "Datum nakládky: 4. 11. 2026, 8:00",
      "confidence": 1.0,
      "grounded": true,
      "corrected": false
    },
    {
      "key": "weight_kg",
      "label": "Hmotnost (kg)",
      "type": "number",
      "value": 18400.0,
      "raw": "18 400 kg",
      "page": 1,
      "quote": "Hrubá hmotnost: 18 400 kg",
      "confidence": 1.0,
      "grounded": true,
      "corrected": false
    }
  ],
  "issues": [],
  "rules": [
    {
      "type": "date_order",
      "description": "Datum nakládky není po Datum vykládky",
      "fields": ["loading_date", "unloading_date"],
      "result": "passed"
    }
  ]
}

Endpointy

Šablony: invoice (faktura), transport_order (objednávka přepravy / CMR), lease (nájemní smlouva), contract (smlouva), insurance_policy (pojistka). Klíč firmy vidí navíc její vlastní šablony z aplikace (GET /templates). Šablonu na míru doplním po domluvě.

Chyby a limity

Každá chyba má stejný tvar:

{"error": {"code": "quota_exceeded", "message": "Denní kvóta 100 extrakcí je vyčerpaná (UTC)."}}

• PDF nejvýš 20 MB a 50 stran; skeny se čtou OCR.
• Denní kvóta extrakcí je u každého klíče vlastní a počítá se podle dne v UTC.
• Dokumenty z API se nemažou automaticky, smažete je přes DELETE. Nepoužívají se k evaluaci ani tréninku.

Chcete si to nejdřív vyzkoušet bez klíče? Zkušební stránka