Životní cyklus dokumentu (API)

Každý dokument v Signi prochází stavy. Podle stavu poznáte, co se s dokumentem děje a co s ním v tu chvíli jde dělat.

Přehled stavů

Jak stavy navazují

1. Dokument založíte přes API — buď rovnou k podpisu (pending), nebo jako rozpracovaný (draft), když v JSON pokynech nastavíte "state": "draft".
2. U dokumentů s vyplňovacími poli může podpisu předcházet doplnění údajů protistranou (waiting_for_answers).
3. Ve stavu pending podepisují jednotlivé strany.
4. Končí se jedním ze tří stavů: completed, rejected, nebo expired.

Jak stav zjistit

Dotazem na detail dokumentu:

curl -H "x-api-key: VAS_API_KLIC" https://api.signi.com/api/v1/contract/ID_DOKUMENTU

V odpovědi je stav v poli state:

{ "contract_id": "1234567", "contract_name": "…", "state": "pending", "creator": { "email": "…" } }

Pohodlnější je nechat si změny hlásit automaticky webhookem — Signi zavolá vaši aplikaci při přechodu dokumentu do stavu pending, completed, rejected nebo expired. Podrobně v článku Webhooky — automatická hlášení změn stavu dokumentu.

Dohledání dokumentu podle interního čísla

Když znáte jen své interní číslo dokumentu (pole number při založení), ID dokumentu dohledáte:

curl -H "x-api-key: VAS_API_KLIC" \
  "https://api.signi.com/api/v1/contract/id?number=OBJ-2026-001"

[ { "contractId": 1234567 } ]

• Hledá se přesná shoda čísla (včetně velikosti písmen) v rámci workspace vašeho klíče; když se nic nenajde, vrátí se prázdné pole [].
• Číslo není unikátní — při opakovaném použití přijde více položek. Obálka s přílohami vrátí i ID příloh.
• Vrací i smazané dokumenty — stav si ověřte dotazem na detail.
• Speciální znaky v čísle zakódujte do URL (/ → %2F, mezera → %20).

S vráceným contractId pak pracujete běžně: detail, stažení PDF atd.

Co dalšího detail vrací

ℹ️ Novinka — dostupné na produkci koncem října 2026.

• pending_expiration_date — do kdy jde dokument podepsat (RFC3339 s offsetem, např. 2026-10-02T23:59:59+02:00). Dokud dokument nepřejde do pending, vrací null.
• is_archived — true = PDF je v důvěryhodném archivu; stažení pak vrací archivní kopii (u dávkové archivace ZIP), jen PDF získáte přes ?ignoreArchive=true.
• note — poznámka z Interního nastavení dokumentu jako Markdown (vlastní odkaz je v ní jako MD odkaz); bez poznámky null.

Na co si dát pozor

• PDF s podpisy jde stáhnout až ve stavu completed — dřív dostanete dokument bez podpisů.
• Mazání dokumentů má podle stavu omezení — podrobnosti v článku Zrušení a smazání dokumentu.

Kam dál

• Webhooky — automatická hlášení změn stavu dokumentu
• Kdo už podepsal — stav jednotlivých podepisujících
• Zrušení a smazání dokumentu
• Quickstart — první dokument k podpisu přes API