API dokumentace

Fakturační API pro napojení webů. Web pošle objednávku, systém vystaví fakturu v jednotné číselné řadě, vrátí odkazy (veřejná faktura, PDF, QR platba) a po zaplacení může web zpětně notifikovat webhookem.

Base URL: https://pay.ucetio.cz
Formát: JSON, UTF‑8
Autentizace: API klíč webu v hlavičce

1. Autentizace

Každý web má vlastní API klíč. Posílá se v hlavičce:

Authorization: Bearer VAS_API_KLIC

Alternativně X-Api-Key: VAS_API_KLIC. Klíč ti předá správce systému (generuje se při založení webu a zobrazí se jen jednou — ulož ho bezpečně, ne do veřejného kódu nebo gitu).

2. Vytvoření faktury

POST /api/invoices

Tělo požadavku

{
  "order_id": "OBJ-2026-12345",
  "currency": "CZK",
  "due_days": 14,
  "customer": {
    "name": "Jan Novák",
    "street": "Dlouhá 5",
    "city": "Praha 1",
    "zip": "110 00",
    "country": "Česká republika",
    "ico": "12345678",
    "dic": "CZ12345678",
    "email": "jan.novak@email.cz"
  },
  "items": [
    { "description": "Premium zápis — 12 měsíců", "quantity": 1, "unit": "ks", "unit_price": 990, "vat_rate": 0 }
  ],
  "note": "Děkujeme za objednávku."
}

Pole požadavku

Pole	Typ	Povinné	Popis
`order_id`	string	ne	ID objednávky na webu. Idempotence — stejné `order_id` vrátí původní fakturu.
`currency`	string	ne	Měna, výchozí CZK.
`due_days`	int	ne	Splatnost ve dnech, výchozí 14.
`customer.name`	string	ano*	Jméno / název odběratele.
`customer.street/city/zip/country`	string	ne	Adresa odběratele.
`customer.ico / dic`	string	ne	IČO / DIČ.
`customer.email`	string	ne	Pošle se na něj faktura a potvrzení o platbě.
`items[].description`	string	ano	Název / popis položky.
`items[].quantity`	number	ne	Množství, výchozí 1.
`items[].unit`	string	ne	Jednotka, výchozí ks.
`items[].unit_price`	number	ano	Cena za jednotku (u neplátce koncová, u plátce bez DPH).
`items[].vat_rate`	number	ne	Sazba DPH v %, uplatní se jen u plátce DPH.
`note`	string	ne	Poznámka na fakturu.

* customer.name je povinné, pokud web nemá „jméno doplnit z platby" (weby typu naprivat.net, kde jméno doplní příchozí platba z banky).

Úspěšná odpověď (HTTP 201)

{
  "ok": true,
  "invoice_id": 42,
  "number": "260042",
  "variable_symbol": "260042",
  "total": 990,
  "currency": "CZK",
  "status": "issued",
  "issue_date": "2026-06-26",
  "due_date": "2026-07-10",
  "public_url": "https://pay.ucetio.cz/faktura/42/",
  "pdf_url": "https://pay.ucetio.cz/faktura/42//pdf",
  "qr_url": "https://pay.ucetio.cz/qr/42/.png"
}

Doporučení: po vytvoření přesměruj zákazníka na public_url — uvidí fakturu i QR platbu.

3. Stav faktury

GET /api/invoices/{invoice_id}

{
  "ok": true, "invoice_id": 42, "number": "260042",
  "status": "issued", "total": 990,
  "paid_at": null, "paid_amount": null,
  "public_url": "https://pay.ucetio.cz/faktura/42/"
}

status: issued (vystaveno), paid (zaplaceno), cancelled (stornováno).

4. Číselná řada a VS

Jednotná číselná řada sdílená všemi weby ve formátu RRNNNN (RR = rok, NNNN = pořadí v roce), např. 260042. Číslo je zároveň variabilní symbol pro párování platby.

5. Webhook — notifikace o zaplacení

Má‑li web vyplněnou Webhook URL, systém po spárování platby pošle:

POST https://tvuj-web.cz/webhook/platba
Content-Type: application/json
X-Event: invoice.paid
X-Signature: sha256=<hmac>

{
  "event": "invoice.paid", "invoice_id": 42, "number": "260042",
  "variable_symbol": "260042", "total": 990, "currency": "CZK",
  "paid_at": "2026-06-26 09:15:00", "external_order_id": "OBJ-2026-12345",
  "customer_name": "Jan Novák", "site": "seokatalog",
  "timestamp": "2026-06-26T09:16:00+02:00"
}

Ověření podpisu

X-Signature = sha256= + HMAC‑SHA256 těla podepsané webhook secretem webu (v administraci v detailu webu).

$payload = file_get_contents('php://input');
$secret  = 'WEBHOOK_SECRET_TOHOTO_WEBU';
$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_SIGNATURE'] ?? '')) {
    http_response_code(403); exit('Neplatný podpis');
}
$data = json_decode($payload, true);
// $data['external_order_id'] → spáruj s objednávkou, označ zaplaceno
http_response_code(200);

6. Chybové stavy

HTTP	Význam
401	Neplatný / chybějící API klíč.
422	Chyba validace — tělo obsahuje `error` a `details`.
429	Příliš mnoho požadavků (limit 60 / min z jedné IP).
500	Chyba serveru.

7. Příklad (PHP)

$ch = curl_init('https://pay.ucetio.cz/api/invoices');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Authorization: Bearer VAS_API_KLIC'],
    CURLOPT_POSTFIELDS => json_encode([
        'order_id' => 'OBJ-1',
        'customer' => ['name' => 'Jan Novák', 'email' => 'jan@email.cz'],
        'items' => [['description' => 'Zápis', 'unit_price' => 990]],
    ], JSON_UNESCAPED_UNICODE),
]);
$data = json_decode(curl_exec($ch), true);
if ($data['ok'] ?? false) { header('Location: ' . $data['public_url']); exit; }

Příklad (curl)

curl -X POST https://pay.ucetio.cz/api/invoices \
  -H "Authorization: Bearer VAS_API_KLIC" \
  -H "Content-Type: application/json" \
  -d '{"order_id":"OBJ-1","customer":{"name":"Jan Novák","email":"jan@email.cz"},
       "items":[{"description":"Zápis","unit_price":990}]}'

8. Poznámky

Idempotence: vždy posílej order_id — zabrání duplicitě při opakovaném odeslání.
DPH: dodavatel je nyní neplátce — unit_price je koncová cena, vat_rate se ignoruje.
E‑mail: s customer.email dostane zákazník fakturu i potvrzení o platbě.
Bezpečnost: API klíč i webhook secret drž v tajnosti, komunikace přes HTTPS.

Verze: červen 2026 · Kontakt: info@ucetio.cz