REST API · JSON · Bearer token

Fakturácia cez API, jednoducho a spoľahlivo.

Vystavujte predfaktúry, faktúry aj dobropisy, používajte vlastné číselné rady, evidujte úhrady a odošlite zákazníkovi hotové PDF cez jedno univerzálne API.

Base URL API v1

https://api.dokly.sk/api/v1

24API endpointov

120/minLimit na API kľúč

PDFGenerované automaticky

01 — Prístup

API kľúč a oddelenie dát

Prístupové údaje dostanete od správcu služby. Každý API kľúč patrí jednej organizácii, preto odpovede obsahujú iba jej číselné rady, doklady a úhrady.

API kľúč je tajný údaj. Používajte ho iba na serveri vašej aplikácie a nikdy ho nevkladajte do verejného frontendu ani do URL.

02 — Bezpečnosť

Autentifikácia

Každá požiadavka pod /api/v1 vyžaduje Bearer token a JSON hlavičky.

Accept: application/json
Content-Type: application/json
Authorization: Bearer dokly_xxxxxxxxxxxxxxxxx

03 — Číslovanie

Číselné rady

Jedna organizácia môže mať samostatný rad pre každý projekt. {RRRR} vloží celý rok, {RR} dvojciferný rok a počet N určuje počet číslic poradového čísla.

GET/api/v1/number-seriesZoznam radov

POST/api/v1/number-seriesNový rad

{
  "code": "project-invoice",
  "name": "Projektové faktúry",
  "document_type": "invoice",
  "format": "{RR}BK{NNNN}",
  "reset_annually": true
}

04 — Adresár

Odberatelia

Adresár je voliteľný. Odberateľa môžete spravovať cez API a pri vystavení dokladu poslať iba jeho customer_id.

GET/api/v1/customersZoznam a vyhľadávanie

POST/api/v1/customersNový odberateľ

GET · PATCH · DELETE/api/v1/customers/{customer_id}Detail a správa

{
  "name": "Klient, s. r. o.",
  "company_id": "12345678",
  "email": "faktury@klient.sk",
  "address_line_1": "Hlavná 10",
  "city": "Bratislava",
  "postal_code": "811 01",
  "country_code": "SK"
}

05 — Fakturácia

Doklady

Doklad môže byť predfaktúra, faktúra alebo dobropis. Sumy posielajte ako reťazce, napríklad "39.00".

GET/api/v1/documentsZoznam a filtre

GET/api/v1/documents/{document_id}Detail dokladu

POST/api/v1/documentsVystavenie dokladu

{
  "type": "invoice",
  "number_series_code": "project-invoice",
  "external_id": "subscription-1278",
  "buyer": {
    "name": "Klient, s. r. o.",
    "email": "faktury@klient.sk",
    "address_line_1": "Hlavná 10",
    "city": "Bratislava",
    "postal_code": "811 01",
    "country_code": "SK"
  },
  "currency": "EUR",
  "issue_date": "2026-08-22",
  "due_date": "2026-09-05",
  "items": [{
    "name": "Mesačné predplatné",
    "quantity": "1",
    "unit": "ks",
    "unit_price": "39.00",
    "tax_rate": "23"
  }]
}

POST/api/v1/documents/{proforma_id}/convertPredfaktúra → faktúra

Faktúra obsahuje source_document_id aj čitateľné source_document_number pôvodnej predfaktúry.

POST/api/v1/documents/{invoice_id}/credit-noteÚplný alebo čiastočný dobropis

Použite samostatný rad typu credit_note. Položky pošlite kladne; API vytvorí záporný doklad a nedovolí prekročiť sumu faktúry.

POST/api/v1/documents/{document_id}/cancelStorno so zachovaním čísla

DELETE/api/v1/documents/{document_id}Nevratné vymazanie

Číslo sa neuvoľní a v číselnom rade zostane medzera.

Namiesto objektu buyer môžete poslať customer_id. Ručne zadaný odberateľ sa uloží automaticky; existujúci sa podľa IČO, prípadne e-mailu, iba prepojí bez duplicity. Doklad si vždy ponechá historickú snímku údajov.

Idempotencia: rovnaký external_id vráti existujúci doklad a nespotrebuje nové číslo.

06 — Spracovanie

Úhrady, PDF a e-mail

Úhrada môže byť čiastočná alebo úplná. Stav a zostávajúca suma sa prepočítajú automaticky.

POST/api/v1/documents/{document_id}/paymentsEvidencia úhrady

GET/api/v1/documents/{document_id}/pdfStiahnutie PDF

POST/api/v1/documents/{document_id}/sendOdoslanie e-mailom

{
  "amount": "47.97",
  "paid_at": "2026-08-22T10:30:00+02:00",
  "method": "bank_transfer",
  "external_id": "payment-9821"
}

07 — Udalosti

Webhooky

Dokly upozorní vašu aplikáciu na úhradu alebo zmenu dokladu bez pravidelného kontrolovania API. Hlavná udalosť payment.recorded obsahuje platbu, aktuálny stav aj zostávajúcu sumu.

GET · POST/api/v1/webhooksZoznam a vytvorenie

GET · PATCH · DELETE/api/v1/webhooks/{webhook_id}Detail a správa

GET/api/v1/webhooks/{webhook_id}/deliveriesHistória doručení

{
  "name": "Produkcia",
  "url": "https://moja-aplikacia.sk/webhooks/dokly",
  "events": ["payment.recorded", "document.created"],
  "is_active": true
}

Udalosť	Význam
payment.recorded	Nová čiastočná alebo úplná úhrada.
document.created	Nová predfaktúra, faktúra alebo dobropis.
document.cancelled	Storno dokladu.
document.deleted	Nevratné vymazanie dokladu.
document.converted	Konverzia predfaktúry na faktúru.
document.email_queued	E-mail bol zaradený na odoslanie.

Bezpečnosť: webhook má vlastný secret zobrazený iba pri vytvorení. Podpis v X-Dokly-Signature je HMAC SHA-256 z <timestamp>.<raw_body>. Overte aj X-Dokly-Timestamp a udalosti spracujte idempotentne podľa ID doručenia.

$body = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_DOKLY_TIMESTAMP'];
$expected = 'sha256='.hash_hmac('sha256', $timestamp.'.'.$body, $secret);

if (abs(time() - (int) $timestamp) > 300 || ! hash_equals($expected, $_SERVER['HTTP_X_DOKLY_SIGNATURE'])) {
    http_response_code(401);
    exit;
}

Payload obsahuje id, event, created_at, organization_id a objekt data. Endpoint musí do 10 sekúnd vrátiť 2xx. Pri chybe Dokly skúsi doručenie znova po 1, 5 a 30 minútach.

08 — Referencia

Stavy a chybové odpovede

Úspešné odpovede vracajú dáta v objekte data. Pri chybe použite HTTP stav a objekt errors na spracovanie konkrétnych polí.

Stav dokladu	Význam
issued	Vystavený a zatiaľ neuhradený.
partially_paid	Čiastočne uhradený.
paid	Plne uhradený.
overdue	Neuhradený po splatnosti.
converted	Predfaktúra prevedená na faktúru.
cancelled	Zrušený doklad.

HTTP	Význam
200	Požiadavka bola úspešne spracovaná.
202	Požiadavka na asynchrónne odoslanie e-mailu bola prijatá.
401	Chýbajúci, neplatný alebo zrušený API kľúč.
404	Doklad nepatrí organizácii alebo neexistuje.
422	Validačná chyba s detailmi v objekte `errors`.
429	Prekročený limit 120 požiadaviek za minútu.