Spouštějte podepisování z vlastních systémů

Ověření

Klíč posílejte v každém požadavku jako bearer token. Klíče patří organizaci; kdykoli je zneplatníte v Nastavení → API. Klíč nikdy nedávejte do kódu v prohlížeči.

curl -X POST https://doxio.pro/api/v1/templates/TEMPLATE_ID/runs \
  -H "Authorization: Bearer $DOXIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-2026-0001" \
  -d '{
    "recipients": { "client": { "email": "jana@example.com", "name": "Jana Nováková", "locale": "cs" } },
    "prefill": { "contract_no": "2026-0001" },
    "external_id": "ORDER-2026-0001"
  }'

Endpointy

https://doxio.pro/api/v1

• GET /templates

  Seznam aktivních šablon s pozicemi a poli

• GET /templates/{id}

  Jedna šablona

• POST /templates/{id}/runs

  Spustí podepisování ze šablony

• GET /runs

  Seznam spuštění (50 na stránku, filtr podle external_id a stavu)

• GET /runs/{id}

  Jedno spuštění se stavem každého podepisujícího

• POST /runs/{id}/cancel

  Zruší spuštění: všechny otevřené odkazy k podpisu přestanou fungovat

• GET /runs/{id}/signed.pdf

  Stáhne podepsané PDF dokončeného spuštění

• GET /runs/{id}/certificate.pdf

  Stáhne samostatný certifikát (jen v režimu samostatného certifikátu)

curl https://doxio.pro/api/v1/runs/RUN_ID \
  -H "Authorization: Bearer $DOXIO_API_KEY"

curl -o signed.pdf https://doxio.pro/api/v1/runs/RUN_ID/signed.pdf \
  -H "Authorization: Bearer $DOXIO_API_KEY"

Chyby

Chyby jsou JSON: kód chyby a u neplatného vstupu issues, případně field_errors, když data neodpovídají šabloně. Každá odpověď je označená no-store.

• 400 invalid_input
• 400 invalid_json
• 400 invalid_idempotency_key
• 400 invalid_cursor
• 401 unauthorized
• 402 plan_required
• 402 billing_inactive
• 403 forbidden
• 404 not_found
• 409 org_signature_not_configured
• 409 mandate_required
• 409 quota_exceeded
• 409 template_unavailable
• 409 idempotency_in_progress
• 409 idempotency_conflict
• 409 run_completed
• 409 run_completing
• 409 run_not_cancellable
• 413 payload_too_large
• 415 unsupported_media_type
• 422 invalid_fields
• 429 rate_limited
• 500 internal_error

Idempotence

Při spuštění posílejte hlavičku Idempotency-Key. Stejný požadavek se stejným klíčem do 24 hodin vrátí původní spuštění (200) místo založení druhého; stejný klíč s jiným tělem odmítne odpověď 409 idempotency_conflict.

Webhooky

V Nastavení → API přidejte https endpoint. DOXIO pošle JSON událost s aktuálním stavem spuštění; neúspěšná doručení opakuje po 1 min, 5 min, 30 min, 2 h, 12 h a 24 h. Endpoint, který selže 50× za sebou, se vypne a vlastník dostane e-mail.

Události

run.signer_signed

Někdo podepsal (včetně automatického podpisu organizace).

run.completed

Podepsali všichni; podepsané PDF je připravené.

run.declined

Někdo odmítl; spuštění skončilo.

run.cancelled

Spuštění bylo zrušeno přes API.

run.expired

Odkaz podepisujícího vypršel, podepisování se samo nedokončí.

run.org_signature_failed

Automatický podpis organizace se nepodařilo připojit; DOXIO to denně zkouší znovu.

POST /your/webhook HTTP/1.1
Content-Type: application/json
User-Agent: doxio-webhooks/1
X-Doxio-Event: run.completed
X-Doxio-Delivery: 7b0c…            (unique per delivery — deduplicate on it)
X-Doxio-Timestamp: 1790000000      (unix seconds)
X-Doxio-Signature: v1=<hex HMAC-SHA256(secret, timestamp + "." + body)>

Ověření webhooku

Spočítejte HMAC-SHA256 z časového razítka, tečky a surového těla požadavku s tajným klíčem endpointu, porovnejte ho v konstantním čase s hodnotou v1 z X-Doxio-Signature a odmítněte razítka starší než 5 minut. Duplicity poznáte podle X-Doxio-Delivery.

const { createHmac, timingSafeEqual } = require("node:crypto");

// rawBody: the request body exactly as received (a string, BEFORE JSON.parse).
function verifyDoxioWebhook(rawBody, headers, secret, nowMs = Date.now()) {
  const timestamp = String(headers["x-doxio-timestamp"] ?? "");
  if (!/^\d+$/.test(timestamp) || Math.abs(nowMs / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac("sha256", secret).update(timestamp + "." + rawBody).digest();
  return String(headers["x-doxio-signature"] ?? "")
    .split(",")
    .some((part) => {
      const match = /^\s*v1=([0-9a-f]{64})\s*$/.exec(part);
      return match !== null && timingSafeEqual(Buffer.from(match[1], "hex"), expected);
    });
}

Vzorový výpočet

secret    = whk_test_secret_0123456789abcdefghijklmnopqrstu
timestamp = 1790000000
body      = {"id":"evt_1","type":"run.completed","created_at":"2026-09-28T12:00:00.000Z","data":{"run":{"id":"r1"}}}
signature = v1=54849a4be185576b3f3670eb41e9005d41f751baa60c65028ebf4e4af63a5a01

Limity

• 120 požadavků za minutu na klíč a 600 za minutu na organizaci (429 s Retry-After).
• Těla požadavků do 256 KB, jen JSON.
• Nejvýše 10 aktivních klíčů a 5 webhooků na organizaci.
• Záznamy o doručení se uchovávají 30 dní. Webhooky nikdy neobsahují soubory.