API Dokumentace

Programové rozhraní pro vytváření požadavků na elektronický podpis dokumentů bankovní identitou.

1. Jak to funguje

1. Odešlete PDF dokument s pozicemi podpisů a emaily podepisujících.
2. API vrátí platební údaje (účet, VS, QR kód). Zadavateli odešleme email s údaji k platbě.
3. Po připsání platby automaticky rozešleme podepisujícím osobám výzvu k podpisu emailem.
4. Každá podepisující osoba se podepíše přes svou bankovní identitu.
5. Po podpisu všemi účastníky obdrží všichni finální PDF s podpisy.

2. Autentizace

Každý požadavek musí obsahovat HTTP hlavičku Authorization s platným API klíčem:

Authorization: Bearer VAS_API_KLIC

Pro získání API klíče nás kontaktujte na info@signuj.cz.

3. Endpoint

Typ obsahu: multipart/form-data (kvůli nahrávání PDF souboru).

4. Parametry

5. Formát podpisů

Parametr signatures je JSON pole objektů. Každý objekt definuje jeden podpis:

[
  {
    "email": "jan.novak@firma.cz",
    "page":  1,
    "rect": {
      "x": 50,
      "y": 100,
      "w": 190,
      "h": 50
    }
  },
  {
    "email": "petra.svobodova@firma.cz",
    "page":  2,
    "rect": {
      "x": 300,
      "y": 680,
      "w": 190,
      "h": 50
    }
  }
]

6. Odpověď

Úspěšná odpověď 200

{
  "ok": true,
  "id": "a1b2c3d4e5f6a1b2c3d4e5f6",
  "status": "new",
  "signatures_count": 2,
  "price": {
    "per_signature_czk": 9,
    "total_czk": 18
  },
  "payment": {
    "account": "2102763112/2010",
    "iban": "CZ6320100000002102763112",
    "bic": "FIOBCZPP",
    "variable_symbol": "7712345678",
    "amount_czk": 18,
    "message": "Signuj.cz a1b2c3d4e5f6a1b2c3d4e5f6",
    "qr_url": "https://api.paylibo.com/..."
  },
  "ready_url": "https://signuj.cz/ready.php?id=a1b2c3d4e5f6a1b2c3d4e5f6",
  "status_url": "https://signuj.cz/sign_status.php?id=a1b2c3d4e5f6a1b2c3d4e5f6"
}

7. Chybové stavy

Chybová odpověď vždy vrací JSON:

{
  "ok": false,
  "error": "Popis chyby v češtině"
}

8. Příklady

cURL

# Odeslání dokumentu s jedním podpisem
curl -X POST https://signuj.cz/api/v1/sign \
  -H "Authorization: Bearer VAS_API_KLIC" \
  -F "pdf=@smlouva.pdf" \
  -F 'signatures=[{"email":"jan@firma.cz","page":1,"rect":{"x":50,"y":100,"w":190,"h":50}}]' \
  -F "email=zadavatel@firma.cz" \
  -F "company=Firma s.r.o." \
  -F "ic=12345678"Kopírovat

cURL — dva podpisy na různých stranách

curl -X POST https://signuj.cz/api/v1/sign \
  -H "Authorization: Bearer VAS_API_KLIC" \
  -F "pdf=@smlouva.pdf" \
  -F 'signatures=[
    {"email":"jan@firma.cz","page":3,"rect":{"x":50,"y":100,"w":190,"h":50}},
    {"email":"petra@firma.cz","page":3,"rect":{"x":300,"y":100,"w":190,"h":50}}
  ]' \
  -F "email=admin@firma.cz" \
  -F "pdf_name=Nájemní smlouva 2026"Kopírovat

PHP

// PHP s cURL
$ch = curl_init('https://signuj.cz/api/v1/sign');

$signatures = json_encode([
    [
        'email' => 'jan@firma.cz',
        'page'  => 1,
        'rect'  => ['x' => 50, 'y' => 100, 'w' => 190, 'h' => 50],
    ],
]);

curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer VAS_API_KLIC'],
    CURLOPT_POSTFIELDS     => [
        'pdf'        => new CURLFile('/cesta/k/smlouva.pdf', 'application/pdf'),
        'signatures' => $signatures,
        'email'      => 'zadavatel@firma.cz',
        'company'    => 'Firma s.r.o.',
    ],
]);

$response = curl_exec($ch);
$data = json_decode($response, true);

if ($data['ok']) {
    echo "ID: " . $data['id'] . "\n";
    echo "Cena: " . $data['price']['total_czk'] . " Kč\n";
    echo "VS: " . $data['payment']['variable_symbol'] . "\n";
}Kopírovat

JavaScript (Node.js)

const fs = require('fs');

const form = new FormData();
form.append('pdf', fs.createReadStream('smlouva.pdf'));
form.append('email', 'zadavatel@firma.cz');
form.append('signatures', JSON.stringify([
  { email: 'jan@firma.cz', page: 1, rect: { x: 50, y: 100, w: 190, h: 50 } }
]));

const res = await fetch('https://signuj.cz/api/v1/sign', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer VAS_API_KLIC' },
  body: form,
});

const data = await res.json();
console.log(data);Kopírovat

Python

import requests, json

signatures = json.dumps([
    {"email": "jan@firma.cz", "page": 1,
     "rect": {"x": 50, "y": 100, "w": 190, "h": 50}}
])

resp = requests.post(
    "https://signuj.cz/api/v1/sign",
    headers={"Authorization": "Bearer VAS_API_KLIC"},
    files={"pdf": open("smlouva.pdf", "rb")},
    data={
        "signatures": signatures,
        "email": "zadavatel@firma.cz",
    },
)

data = resp.json()
print(data)Kopírovat

9. Životní cyklus požadavku

Zjištění stavu — status_url

Pro zjištění aktuálního stavu požadavku použijte status_url vrácenou v odpovědi. Vyžaduje autentizaci API klíčem stejně jako ostatní endpointy.

Authorization: Bearer VAS_API_KLIC

Odpověď status endpointu 200

{
  "ok": true,
  "status": "signed",
  "signatures_count": 2,
  "price_czk": 18,
  "signers": [
    {
      "signature_no": 1,
      "email": "jan@firma.cz",
      "status": "signed",
      "signed_at": "2026-03-22 14:30:00"
    },
    {
      "signature_no": 2,
      "email": "petra@firma.cz",
      "status": "signed",
      "signed_at": "2026-03-22 15:12:00"
    }
  ]
}

Chybové stavy status endpointu

Příklady — zjištění stavu

cURL

curl -H "Authorization: Bearer VAS_API_KLIC" \
  https://signuj.cz/sign_status.php?id=a1b2c3d4e5f6a1b2c3d4e5f6Kopírovat

PHP

// Zjištění stavu požadavku
$id = 'a1b2c3d4e5f6a1b2c3d4e5f6';

$ch = curl_init('https://signuj.cz/sign_status.php?id=' . urlencode($id));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer VAS_API_KLIC'],
]);

$response = curl_exec($ch);
$data = json_decode($response, true);

if ($data['ok'] && $data['status'] === 'signed') {
    echo "Dokument je kompletně podepsán.\n";
} else {
    echo "Stav: " . $data['status'] . "\n";
}Kopírovat

JavaScript (Node.js)

const id = 'a1b2c3d4e5f6a1b2c3d4e5f6';

const res = await fetch(
  `https://signuj.cz/sign_status.php?id=${id}`,
  { headers: { 'Authorization': 'Bearer VAS_API_KLIC' } }
);

const data = await res.json();
console.log(data.status);           // "new" | "paid" | "sent" | "signed"
console.log(data.signers);          // detail podepisujícíchKopírovat

Python

import requests

id = "a1b2c3d4e5f6a1b2c3d4e5f6"

resp = requests.get(
    f"https://signuj.cz/sign_status.php?id={id}",
    headers={"Authorization": "Bearer VAS_API_KLIC"},
)

data = resp.json()
print(data["status"])    # "new" | "paid" | "sent" | "signed"
print(data["signers"])   # detail podepisujícíchKopírovat

10. Limity