{
"openapi": "3.0.3",
"info": {
"title": "Podpisuj.cz API",
"version": "1.0.0",
"description": "REST rozhraní pro napojení elektronických podpisů na vlastní systém (ERP, CRM, HR).\n\n**Účtuje se obálka, tedy jeden dokument**, bez ohledu na počet podepisujících.\nDokument založený přes API spotřebuje jednu obálku ze stejného zůstatku, ze kterého\nčerpá webové rozhraní. **Bez aktivního balíčku obálek API nefunguje** a všechna\nvolání vrací `402 subscription_required`.\n\nKlíč posílejte v hlavičce `X-API-Key`. Patří na server, nikdy do prohlížeče ani do\nmobilní aplikace. Úspěch má vždy tvar `{\"data\": {…}}`, chyba\n`{\"error\": {\"code\": \"…\", \"message\": \"…\"}}` — rozhodujte se podle `code`, ne podle\ntextu zprávy.\n\nPřehled, ceny, popis webhooků a ověření totožnosti: ",
"contact": {
"name": "Podpora Wopro",
"email": "support@wopro.cz",
"url": "https://podpisuj.cz/api/"
}
},
"servers": [
{
"url": "https://podpisuj.cz/api",
"description": "Produkční server"
}
],
"tags": [
{
"name": "Účet",
"description": "Ověření klíče a zůstatek obálek"
},
{
"name": "Dokumenty",
"description": "Zakládání dokumentů k podpisu a sledování jejich stavu"
},
{
"name": "Totožnost",
"description": "Spuštění ověření totožnosti a zjištění výsledku"
}
],
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
],
"paths": {
"/v1/ping": {
"get": {
"tags": [
"Účet"
],
"summary": "Ověření klíče",
"description": "Nejrychlejší způsob, jak zjistit, že klíč funguje a k jaké organizaci patří. Nevyžaduje žádné oprávnění nad rámec platného klíče.",
"responses": {
"200": {
"description": "Klíč je platný",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"organization": {
"type": "string"
},
"plan": {
"type": "object"
},
"envelopes_available": {
"type": "integer"
},
"server_time": {
"type": "string"
}
}
}
}
}
}
}
},
"401": {
"description": "Chyba",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"402": {
"description": "Organizace nemá aktivní balíček obálek",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/balance": {
"get": {
"tags": [
"Účet"
],
"summary": "Zůstatek obálek",
"description": "Kolik obálek zbývá, kdy propadnou a kolik ověření totožnosti jste tento měsíc spotřebovali.\n\nPřed hromadným rozesláním se sem vyplatí podívat, ať vám obálky nedojdou uprostřed dávky. Obálky se sčítají a každá dávka platí 12 měsíců; čerpáme vždy tu, které platnost končí nejdřív.",
"security": [
{
"ApiKeyAuth": []
}
],
"responses": {
"200": {
"description": "Zůstatek",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"envelopes_available": {
"type": "integer"
},
"expires_soonest": {
"type": "string",
"nullable": true
},
"batches": {
"type": "array",
"items": {
"type": "object",
"properties": {
"remaining": {
"type": "integer"
},
"granted_at": {
"type": "string"
},
"expires_at": {
"type": "string"
}
}
}
},
"identity_verifications": {
"type": "object",
"properties": {
"used_this_month": {
"type": "integer"
},
"limit_this_month": {
"type": "integer",
"description": "Dvojnásobek obálek balíčku. Balíček 10 → 20 ověření měsíčně."
}
}
},
"max_signers_per_envelope": {
"type": "integer",
"description": "Podle balíčku. Bez balíčku a u malých balíčků 5, od balíčku 100 výše 100."
}
}
}
}
}
}
}
},
"401": {
"description": "Chyba",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"402": {
"description": "Chyba",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/documents": {
"post": {
"tags": [
"Dokumenty"
],
"summary": "Založit dokument a rozeslat pozvánky",
"description": "Nahraje PDF, přidá podepisující a **rovnou jim rozešle výzvy k podpisu**. Podepisuje se v pořadí, v jakém je uvedete; dokud první nepodepíše, další dokument nevidí.\n\nSpotřebuje **jednu obálku** ze zůstatku organizace. Když obálky nejsou, vrací `402 no_envelopes` — přes API se nikdy nic nepřeklopí do jednorázové platby, protože na ni není kdo klikne.\n\nPozvánky rozesíláme e-mailem sami, takže `sign_url` nemusíte nikam přeposílat.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"signers"
],
"properties": {
"title": {
"type": "string",
"example": "Smlouva o dílo 2026/114"
},
"file_base64": {
"type": "string",
"description": "PDF v base64. Alternativa k `file_url`."
},
"file_url": {
"type": "string",
"description": "https adresa, ze které si PDF stáhneme. Bez přesměrování."
},
"signers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Signer"
},
"description": "Nejvýš tolik osob, kolik dovolí váš balíček."
},
"placements": {
"type": "array",
"description": "Nepovinné umístění podpisů. Bez nich je umístíme na poslední stranu pod sebe.",
"items": {
"type": "object",
"properties": {
"signer": {
"type": "integer",
"description": "Index v poli signers"
},
"page": {
"type": "integer"
},
"x": {
"type": "number"
},
"y": {
"type": "number"
},
"w": {
"type": "number"
},
"h": {
"type": "number"
}
}
}
},
"external_id": {
"type": "string",
"description": "Vaše ID zakázky. Zapíše se do auditní stopy."
}
}
},
"example": {
"title": "Smlouva o dílo 2026/114",
"file_url": "https://vas-system.cz/export/smlouva-114.pdf",
"signers": [
{
"first_name": "Eva",
"last_name": "Dvořáková",
"email": "eva@zakaznik.cz"
}
],
"external_id": "ZAK-2026-114"
}
}
}
},
"responses": {
"201": {
"description": "Dokument",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/Document"
}
}
}
}
}
},
"401": {
"description": "Chyba",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"402": {
"description": "Chybí balíček (`subscription_required`) nebo došly obálky (`no_envelopes`)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "Neplatný vstup: `too_many_signers`, `invalid_document`, `duplicate_signer`",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Chyba",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"get": {
"tags": [
"Dokumenty"
],
"summary": "Výpis dokumentů",
"description": "Dokumenty vaší organizace, nejnovější první. Bez podepisujících — ty vrací detail.",
"parameters": [
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"draft",
"awaiting_payment",
"signing",
"finalizing",
"completed",
"cancelled"
]
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"default": 25,
"maximum": 100
}
},
{
"name": "offset",
"in": "query",
"schema": {
"type": "integer",
"default": 0
}
}
],
"responses": {
"200": {
"description": "Seznam"
},
"401": {
"description": "Chyba",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"402": {
"description": "Chyba",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/documents/{id}": {
"get": {
"tags": [
"Dokumenty"
],
"summary": "Stav dokumentu",
"description": "Detail včetně stavu jednotlivých podepisujících. Když nemáte nastavený webhook, tímhle si stav zjišťujete.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^[0-9A-Fa-f]{32}$"
},
"description": "ID dokumentu, které jste dostali při založení."
}
],
"responses": {
"200": {
"description": "Dokument",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/Document"
}
}
}
}
}
},
"401": {
"description": "Chyba",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Chyba",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/documents/{id}/file": {
"get": {
"tags": [
"Dokumenty"
],
"summary": "Stažení PDF",
"description": "Vrací **binární PDF**, ne JSON. Dokud dokument není hotový, vrací `409 not_ready`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^[0-9A-Fa-f]{32}$"
},
"description": "ID dokumentu, které jste dostali při založení."
},
{
"name": "type",
"in": "query",
"schema": {
"type": "string",
"enum": [
"signed",
"original"
],
"default": "signed"
}
}
],
"responses": {
"200": {
"description": "PDF",
"content": {
"application/pdf": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"409": {
"description": "Dokument ještě není podepsaný",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Chyba",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/documents/{id}/remind": {
"post": {
"tags": [
"Dokumenty"
],
"summary": "Připomenout podpis",
"description": "Znovu pošle výzvu tomu, kdo je na řadě. Připomínka nic nestojí a obálku nespotřebuje.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^[0-9A-Fa-f]{32}$"
},
"description": "ID dokumentu, které jste dostali při založení."
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Nepovinné. Bez něj se připomene tomu, kdo je na řadě."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Odesláno"
},
"409": {
"description": "Chyba",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Chyba",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/documents/{id}/cancel": {
"post": {
"tags": [
"Dokumenty"
],
"summary": "Zrušit dokument",
"description": "Zruší rozpracovaný podpis a lidem, kteří už dostali výzvu, pošle informaci.\n\n**Obálka se nevrací.** Ve chvíli, kdy pozvánky odešly, je vyčerpaná.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^[0-9A-Fa-f]{32}$"
},
"description": "ID dokumentu, které jste dostali při založení."
}
],
"responses": {
"200": {
"description": "Zrušeno"
},
"409": {
"description": "Dokument už je dokončený nebo zrušený",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Chyba",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/identity-verifications": {
"post": {
"tags": [
"Totožnost"
],
"summary": "Spustit ověření totožnosti",
"description": "Založí žádost o ověření totožnosti a vrátí **odkaz, kam člověka pošlete**.\n\n### Jak to celé proběhne\n\n1. Zavoláte tenhle endpoint s e-mailem člověka. Dostanete `verification_url`.\n2. Pošlete ho na ten odkaz (e-mailem, přesměrováním, jakkoli).\n3. Na naší stránce se přihlásí nebo zaregistruje. **Ověření je vázané na účet Wopro**,\n proto tenhle krok nejde přeskočit a proto vám nemůžeme na jedno zavolání ověřit\n kohokoli, kdo o tom neví.\n4. Vyfotí doklad totožnosti a sebe. Kontroluje se živost a shoda obličeje s dokladem.\n5. Vrátíme ho na vaši `return_url`.\n6. Výsledek si zjistíte dotazem na `GET /v1/identity-verifications/{id}`, nebo vám\n přijde webhook `identity.verified`.\n\n### Co je dobré vědět\n\n- **Ověření platí dva roky.** Kdo už ověřený je, projde okamžitě a limit nečerpá.\n- **Odkaz platí 14 dní.**\n- **Neúčtuje se**, ale měsíčně jich smíte spustit nejvýš **dvojnásobek obálek\n svého balíčku** (balíček 10 → 20 ověření). Po vyčerpání vrací `429`.\n- **Fotky dokladu ani selfie neukládáme** na svou infrastrukturu. Zůstávají jen\n údaje přečtené z dokladu a rozhodnutí o ověření.\n- **`return_url` musí být https.** Vaši doménu nelze poslat přímo do ověřovací\n služby (pouští jen adresy z whitelistu), takže se člověk vrací přes podpisuj.cz\n a teprve odtud ho přesměrujeme k vám. Je to bezpečnostní pojistka, ne omezení navíc.\n\n### Proč může přijít `rejected`, i když byl doklad v pořádku\n\nNejčastější důvod není nečitelná fotka, ale **neshoda jména**: jméno na dokladu\nneodpovídá jménu na účtu Wopro. Stává se to po svatbě nebo při překlepu v účtu.\nČlověk to spraví opravou jména v účtu a novým pokusem.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"format": "email"
},
"first_name": {
"type": "string"
},
"last_name": {
"type": "string"
},
"return_url": {
"type": "string",
"description": "https adresa, kam člověka po ověření vrátíme."
},
"external_id": {
"type": "string",
"description": "Vaše ID. Vrátíme ho beze změny."
}
}
},
"example": {
"email": "eva@zakaznik.cz",
"first_name": "Eva",
"last_name": "Dvořáková",
"return_url": "https://vas-system.cz/onboarding/hotovo",
"external_id": "ZAK-1180"
}
}
}
},
"responses": {
"201": {
"description": "Žádost o ověření",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/IdentityVerification"
}
}
}
}
}
},
"401": {
"description": "Chyba",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"402": {
"description": "Chybí aktivní balíček obálek",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "Chyba",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`identity_limit_reached` — vyčerpán měsíční limit ověření",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/identity-verifications/{id}": {
"get": {
"tags": [
"Totožnost"
],
"summary": "Stav ověření totožnosti",
"description": "Vrací aktuální stav. Pokud je žádost ještě otevřená a známe účet, doptáme se rovnou u ověřovací služby, takže dostanete čerstvý výsledek.\n\n**Po návratu člověka na vaši `return_url` si stav vždycky potvrďte tímhle dotazem.** Samotný návrat neznamená, že ověření dopadlo dobře.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^[0-9A-Fa-f]{32}$"
}
}
],
"responses": {
"200": {
"description": "Žádost o ověření",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/IdentityVerification"
}
}
}
}
}
},
"401": {
"description": "Chyba",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Chyba",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"ApiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "X-API-Key",
"description": "Klíč ve tvaru `pps_live__`.\n\nVytvoříte si ho v účtu v sekci **API klíče**. Tajná část se zobrazí jen jednou.\n\nVolání projdou jen tehdy, když má organizace **aktivní balíček obálek**; jinak vrací `402 subscription_required`."
},
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Stejný klíč jako u `X-API-Key`, jen poslaný jako `Authorization: Bearer pps_live_…`. Použijte jedno nebo druhé, ne obojí."
}
},
"schemas": {
"Error": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"example": "no_envelopes",
"description": "Strojově čitelný kód. Rozhodujte se podle něj, ne podle textu."
},
"message": {
"type": "string",
"example": "Došly obálky. Doplňte je změnou balíčku."
}
}
}
}
},
"Signer": {
"type": "object",
"required": [
"first_name",
"last_name",
"email"
],
"properties": {
"id": {
"type": "string",
"readOnly": true,
"example": "88B2C1…"
},
"first_name": {
"type": "string",
"example": "Eva"
},
"last_name": {
"type": "string",
"example": "Dvořáková"
},
"email": {
"type": "string",
"format": "email",
"example": "eva@zakaznik.cz"
},
"is_owner": {
"type": "boolean",
"readOnly": true
},
"status": {
"type": "string",
"readOnly": true,
"enum": [
"waiting",
"notified",
"signed",
"declined"
]
},
"signed_at": {
"type": "string",
"nullable": true,
"readOnly": true
},
"sign_url": {
"type": "string",
"nullable": true,
"readOnly": true,
"description": "Odkaz k podpisu. Pozvánku posíláme e-mailem sami, tohle se hodí, když chcete podpis nabídnout přímo ve svém rozhraní. Vyplněné jen u toho, kdo je na řadě."
}
}
},
"Document": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "3F9A1C…",
"description": "32 hexadecimálních znaků"
},
"title": {
"type": "string",
"example": "Smlouva o dílo 2026/114"
},
"status": {
"type": "string",
"enum": [
"draft",
"awaiting_payment",
"signing",
"finalizing",
"completed",
"cancelled"
],
"description": "Dokument založený přes API jde rovnou do `signing`, protože je zaplacený obálkou."
},
"pages": {
"type": "integer"
},
"created_at": {
"type": "string"
},
"completed_at": {
"type": "string",
"nullable": true
},
"signature_level": {
"type": "string",
"enum": [
"SES",
"AES"
],
"description": "Výsledná úroveň podpisu. Běžně `AES`."
},
"sha256_original": {
"type": "string"
},
"sha256_signed": {
"type": "string",
"nullable": true
},
"audit_url": {
"type": "string",
"nullable": true,
"description": "Veřejná ověřovací stránka. Nese jména podepisujících, proto ji neindexujeme."
},
"signers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Signer"
}
}
}
},
"IdentityVerification": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "A71E…"
},
"status": {
"type": "string",
"enum": [
"pending",
"verified",
"rejected",
"expired"
],
"description": "`pending` — čeká se, až člověk ověření projde.\n`verified` — totožnost ověřena, člověk může podepisovat.\n`rejected` — ověření neprošlo. Nejčastěji nečitelný doklad, selhání kontroly živosti, nebo **jméno na dokladu neodpovídá jménu na účtu**.\n`expired` — odkaz vypršel dřív, než ho člověk otevřel."
},
"email": {
"type": "string",
"format": "email"
},
"first_name": {
"type": "string"
},
"last_name": {
"type": "string"
},
"external_id": {
"type": "string",
"nullable": true,
"description": "Vaše vlastní ID, které jsme dostali při založení a vracíme beze změny."
},
"verification_url": {
"type": "string",
"nullable": true,
"description": "Odkaz, kam člověka pošlete. Platí 14 dní."
},
"created_at": {
"type": "string"
},
"resolved_at": {
"type": "string",
"nullable": true
},
"verified_at": {
"type": "string",
"nullable": true
},
"expires_at": {
"type": "string"
}
}
}
}
}
}