EasyPodpis API v1
Pre ostatné Easy aplikácie a systémy zákazníkov.
- Základná adresa:
https://podpis.easytrade.sk/api/v1 - Overenie:
Authorization: Bearer epk_…– token vytvorí správca firmy v Nastavenia a API. - Formát: JSON (
Accept: application/json), čas v ISO 8601. Limit 120 požiadaviek za minútu na token.
Vytvoriť obálku z PDF
POST /envelopes → 201. Súbor pošlite ako file (multipart) alebo file_base64 (JSON).
curl https://podpis.easytrade.sk/api/v1/envelopes \
-H "Authorization: Bearer epk_…" -H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"title": "Zmluva o dielo 2026/15",
"file_base64": "JVBERi0xLjcK…",
"file_name": "zmluva.pdf",
"signing_order": "sequential",
"external_id": "zakazka-15",
"webhook_url": "https://vasa-aplikacia.sk/webhooky/podpis",
"signers": [
{ "name": "Ján Novák", "email": "jan@firma.sk", "phone": "+421905123456", "auth": "sms" },
{ "name": "Eva Malá", "email": "eva@dodavatel.sk", "auth": "email", "delivery": "email" }
],
"fields": [
{ "signer": 0, "type": "signature", "page": 2, "x": 0.12, "y": 0.78 },
{ "signer": 1, "type": "signature", "page": 2, "x": 0.58, "y": 0.78 }
]
}'
| Pole | Popis |
|---|---|
title | názov obálky (povinné) |
message | správa pre podpisujúcich |
signing_order | parallel (predvolené) alebo sequential – poradie podľa signers[].order / poradia v zozname |
signers[] | name, email, phone, order, auth (sms | email | none), delivery (email | sms | none). Pri delivery: none výzvu nepošleme – odkaz signing_url dostanete v odpovedi. |
fields[] | nepovinné. signer = index v signers, type (signature, initials, name, date, text, checkbox), page od 1, x/y ľavý horný roh ako podiel šírky/výšky strany (0–1), voliteľne width, height, required, label. Bez polí sa podpis vloží na podpisovú stranu na konci dokumentu. |
send | true (predvolené) – hneď odoslať; false – ostane koncept, odošlete cez /send |
expires_at, reminder_days | platnosť (dátum) a pripomienky každých N dní |
external_id, metadata | vaše ID a ľubovoľné údaje, vrátia sa v odpovediach aj webhookoch |
Ďalšie volania
GET /envelopes | zoznam (?status=, ?external_id=, ?limit=, ?page=) |
GET /envelopes/{id} | stav obálky a podpisujúcich vrátane signing_url |
POST /envelopes/{id}/send | odoslať koncept |
POST /envelopes/{id}/remind | pripomenúť nepodpísaným |
POST /envelopes/{id}/cancel | zrušiť (reason) |
GET /envelopes/{id}/document | podpísané zapečatené PDF (?type=original – pôvodné) |
GET /envelopes/{id}/audit | auditný záznam |
DELETE /envelopes/{id} | zmazať koncept |
GET /templates | šablóny firmy s rolami |
POST /templates/{id}/envelopes | obálka zo šablóny – signers v poradí rolí šablóny, polia sú už rozmiestnené |
Stavy
Obálka: draft, sent, completed, declined, expired, cancelled. Podpisujúci: waiting (čaká na poradie), sent, opened, signed, declined.
Webhooky
POST JSON na webhook_url obálky, inak na webhook firmy. Udalosti: envelope.sent, recipient.signed, envelope.completed, envelope.declined, envelope.expired, envelope.cancelled.
{
"id": "6f1c…",
"event": "envelope.completed",
"created_at": "2026-11-16T14:05:11+01:00",
"data": { "envelope": { "id": "…", "status": "completed", "signed_document": { "sha256": "…", "url": "…" }, … } }
}
Podpis – hlavička X-EasyPodpis-Signature: t=1763298311,v1=5d41…, kde v1 = HMAC-SHA256(tajomstvo, t + "." + telo). Tajomstvo nájdete v nastaveniach. Overte podpis aj čas (±5 min), spracujte udalosť idempotentne podľa id a odpovedzte 2xx do 8 s; inak opakujeme po 1 min, 5 min, 30 min, 2 h a 12 h.
[$t, $v1] = [null, null];
foreach (explode(',', $request->header('X-EasyPodpis-Signature')) as $part) {
[$k, $v] = explode('=', $part, 2) + [1 => null];
$k === 't' ? $t = $v : ($k === 'v1' ? $v1 = $v : null);
}
$ok = $t && abs(time() - (int) $t) < 300
&& hash_equals(hash_hmac('sha256', $t.'.'.$request->getContent(), $secret), (string) $v1);
Chyby
{ "error": { "code": "validation_failed", "message": "…", "fields": { "signers.0.phone": ["…"] } } }
401 unauthorized, 404 not_found, 409 invalid_state / not_ready, 422 validation_failed, 429 – prekročený limit.