eIDAS elektronický podpis API Certyneo Developers

curl https://api.certyneo.com/v1/envelopes \ -H "Authorization: Bearer $CERTYNEO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "Contrat de prestation", "documents": [{"file_url": "https://your.app/contract.pdf"}], "recipients": [{"email": "client@example.com", "name": "Jane Doe"}], "webhook_url": "https://your.app/webhooks/sign" }'

import Certyneo from '@certyneo/sdk'; const client = new Certyneo({ apiKey: process.env.CERTYNEO_API_KEY }); const envelope = await client.envelopes.create({ title: 'Contrat de prestation', documents: [{ file_url: 'https://your.app/contract.pdf' }], recipients: [{ email: 'client@example.com', name: 'Jane Doe' }], }); console.log(envelope.sign_url); // ready to share with the signer

Webhooku — reagujte v reálnom čase

Šesť udalostí (envelope.sent, viewed, signed, completed, declined, expired) s overiteľným podpisom HMAC a automatickými pokusmi.

envelope.completed

{
  "event": "envelope.completed",
  "envelope_id": "env_3a2f...",
  "signed_at": "2026-05-25T14:32:18Z",
  "evidence_url": "https://api.certyneo.com/v1/envelopes/env_3a2f.../audit-trail.pdf",
  "signers": [
    { "email": "client@example.com", "signed": true, "ip": "82.x.x.x" }
  ]
}

Podpis HMAC SHA-256 každej užitočnosti — overte pravosť na strane servera.

Automatický pokus v prípade zlyhania: 5 pokusov za 24 hodín s exponenciálnym oneskorením.

Konzultovateľný záznam udalostí z dashboardu: vidzte každý pokus, vrátený stav HTTP, telo.

URL webhooku konfigurovateľná podľa obálky (prepísanie) alebo globálna v projekte.

Prečo vyhradené API pre elektronický podpis?

Integrácia elektronického podpisu do vášho produktu nie je triviálna. Potrebujete záruky na právnu zhodu (eIDAS), technickú spoľahlivosť (webhouku, ktoré naozaj prídu) a zvrchovanosť údajov (európsky hosting, aby ste sa vyhnuli Cloud Act). API Certyneo pokrýva všetky tri.

Navrhnuté vývojármi a pre vývojárov, dodržiava moderné konvencie REST: stránkovanie založené na kurzore, kľúče idempotentnosti, verzovanie pomocou URL, OpenAPI 3.1 na automatické generovanie vašich klientov. Bez SOAP, bez XML, bez prekvapení.

Zhoda s eIDAS vysvetlená pre vývojárov

Nariadenie eIDAS definuje tri úrovne podpisu: jednoduchý (SES), pokročilý (AES) a kvalifikovaný (QES). API Certyneo umožňuje zvoliť si úroveň na obálku prostredníctvom poľa `signature_level`. Predvolená hodnota je AES (postačujúca pre 95 % prípadov B2B). QES je dostupná pre akty vyžadujúce prísnu právnu ekvivalenciu s manuálnym písomným podpisom (notárske akty, verejné obstarávania).

Na technickej strane AES vyžaduje silné overenie signatára (OTP prostredníctvom SMS štandardne, video KYC ako voliteľnú) a časovanú stopu auditu. QES pridáva kvalifikovaný certifikát vystavený kvalifikovaným TSP EÚ. To všetko spravuje API — zavoláte koncový bod, my sa postaráme o zvyšok.

Odporúčaná architektúra integrácie

Najčastejší vzor integrácie nasleduje tento tok:

Váš backend zavolá POST /v1/envelopes na vytvorenie obálky a dostane sign_url, ktorý predstaví používateľovi.
Presmerujete používateľa na sign_url alebo ho vložíte do iframu (s vaším brandingom cez plán Pro).
Po dokončení podpisu Certyneo zavolá váš webhook s udalosťou envelope.completed.
Aktualizujete svoju databázu a upozorníte používateľa (e-mail, in-app atď.).

Bezplatné neobmedzené pieskovisko

Prostredie pieskoviska je bezplatné a neobmedzené. Všetky produkčné funkcie sú dostupné, okrem toho, že podpisy nemajú právnu hodnotu (PDF je označený SANDBOX). Praktické pre automatizované testy, ukážky klientov, lokálny vývoj. Kľúče pieskoviska sa líšia od produkčných kľúčov, úplná izolácia medzi nimi.

Migrácia z DocuSign alebo Yousign

Ak už máte integráciu DocuSign alebo Yousign, mapovanie API je priame: obálky → obálky, príjemcovia → príjemcovia, webhouku statúsu → webhouku statúsu. Náš návod migrácie zdokumentuje ekvivalencie koncový bod za koncovým bodom. Počítajte s 1 až 3 dňami na kompletnú migráciu, oveľa menej, ak používate interný wrapper.

Často kladené otázky — API

Aký je limit rýchlosti API?

1 000 požiadaviek za minútu štandardne, zvýšiteľné na požiadavku pre vysoké použitie (továrne, multi-tenant platformy). Hlavička X-RateLimit-Remaining v každej odpovedi indikuje zvyšnú kvótu. V prípade prekročenia API vracia 429 s Retry-After.

Koľko stojí API?

Pieskovisko je bezplatné a neobmedzené. Produkcia funguje na základe platby za podpis (od 0,40 € za podpis AES s degresivitou pri obieme), bez minimálneho predplatného. Plán Enterprise zahŕňa posilnené SLA, IP whitelisting a vyhradený technický účet.

Existuje SLA?

99,95 % dostupnosti pri plánoch Business a Enterprise (maximálny výpadok 4 hodiny ročne). Verejná stránka stavu s históriou incidentov: status.certyneo.com. Plán Enterprise zahŕňa automatický úver v prípade nedodržania SLA.

Akú autentifikáciu používate?

Bearer token (kľúč API) v hlavičke Authorization. Kľúče sú rotovateľné z dashboardu s okamžitým odvolaním. Pre integrácie OAuth (multi-tenant platforma) ponúkame OAuth 2.0 Client Credentials v pláne Enterprise.

Ako overiť podpis HMAC webhooku?

Každý webhook obsahuje hlavičku X-Certyneo-Signature obsahujúcu HMAC SHA-256 užitočnosti, podpísanú vašou tajnou hodnotou webhooku. Na strane servera prepočítajte HMAC a porovnajte v konštantnom čase (porovnanie bezpečné voči času). Oficiálny SDK to automaticky robí prostredníctvom webhook.verify(payload, signature, secret).

Sú SDK open source?

Áno. SDK Node, Python a Ruby sú na GitHube pod licenciou MIT. Môžete ich fork, prispieť alebo jednoducho auditovať. Binárne súbory sú publikované na npm, PyPI a RubyGems pod menným priestorom @certyneo / certyneo.

Môžem testovať bez registrácie?

Áno, prostredníctvom interaktívnych príkladov v dokumentácii API: /developers/playground. Požiadavky sa tu spúšťajú na zdieľanej sandbox inštancii bez potreby kľúča. Na seriózne použitie si vytvorte bezplatný vývojársky účet (neobmedzený sandbox).

E-Signature API pre vývojárov

REST + OpenAPI 3.1

Spoľahlivé webhooku

Natívna zhoda s eIDAS

Latenčnosť < 200 ms

Spustenie za 5 minút