API – Samofakturace (§ 28/6 ZDPH)

Poslední aktualizace: 28. 5. 2026 · verze 1

Toto API umožňuje externí marketplace platformě vystavovat daňové doklady jménem svých dodavatelů v režimu samofakturace dle § 28 odst. 6 zákona o DPH. Pod jedním účtem platformy ve FakturID lze spravovat desítky až stovky nezávislých dodavatelů (subjektů) – každý s vlastním IČO, DIČ, statusem plátce DPH a vlastní číselnou řadou.

Právní rámec: Platforma vystavuje doklady jménem dodavatele na základě jeho písemného zmocnění dle § 28 odst. 6 ZDPH. Na každém dokladu se objevuje povinná klauzule. Za daňovou správnost údajů (zejména status plátce DPH) odpovídá dodavatel, nikoli FakturID ani platforma.

Pro běžnou externí fakturaci (token-autentizované vystavení faktury pod jediným účtem) viz API – centrální fakturace. Samofakturace je rozšířený scénář pro marketplace platformy s mnoha nezávislými prodejci.

Jak to funguje

Pod jedním uživatelským účtem ve FakturID (účet platformy) existuje libovolný počet samostatných fakturačních subjektů – každý reprezentuje jednoho dodavatele.

Upsert dodavatele s každým voláním. Žádné samostatné registrační volání. V payloadu pošlete plné údaje dodavatele včetně IČO a statusu DPH; FakturID najde nebo založí subjekt pod účtem vaší platformy (klíče (platforma, external_supplier_id) primárně, (platforma, IČO) jako fallback).
Vlastní číselná řada per dodavatel. Každý subjekt dodavatele nese vlastní counter ve formátu FSB-{YYYY}-{NNNN}. Atomické přidělení čísla je pojištěné UNIQUE indexem – žádné kolize napříč souběžnými requesty.
DPH dle dodavatele. Status is_vat_payer v payloadu rozhoduje: plátce → DPH se rozpočítá z brutto ceny (default 21 %); neplátce → doklad bez DPH, sazba vždy 0 %.
Uplatněná záloha z kreditů. Pole advance_applied sníží částku k úhradě – bez vlivu na DPH základ. Vhodné pro modely, kde si zákazník platformy dobíjí nedaňové kredity (store credit bez DPH historie).
Zmrazené PDF + SHA256. Po vystavení FakturID vyrenderuje PDF, uloží jeho immutable kopii na disk, vypočte SHA256 a vrátí veřejný link. Edit z UI je zakázán → neměnnost.

Autentizace

Každý požadavek musí obsahovat HTTP hlavičku s přístupovým tokenem platformy:

X-Fakturid-Token: VAS_PLATFORM_TOKEN

Token vydává administrátor FakturID ve Správě API tokenů; je přiřazený k uživatelskému účtu vaší platformy a má vyplněný source_app (identifikátor vaší platformy) pro evidenci původu.
Token bez přiřazeného uživatele (centrální) tento endpoint nepřijme – samofakturace vyžaduje účet platformy jako kontejner pro subjekty dodavatelů.
Token se porovnává v konstantním čase; při nesouladu vrací API 403 forbidden.

Token je tajný klíč. Ukládejte jej výhradně na straně serveru, nikdy ne do klientského kódu. Komunikujte vždy přes HTTPS.

Endpoint

POST https://fakturid.cz/api/self_billing_invoice.php

Tělo požadavku se odesílá jako JSON s hlavičkou Content-Type: application/json.

Struktura požadavku

Kořenový objekt JSON:

Pole	Typ	Povinné	Popis
`supplier`	object	ano	Dodavatel, jehož jménem se doklad vystavuje (viz tabulka níže).
`customer`	object	ano	Odběratel – koncový zákazník (viz tabulka níže).
`items`	array	ano	Pole položek faktury. Pro samofakturaci se podporuje libovolný počet položek.
`self_billing`	object	doporučeno	Metadata samofakturace – jen `platform_name` (název vaší platformy do povinné klauzule).
`advance_applied`	number	ne	Částka uplatněná z kreditů zákazníka (snižuje „K úhradě"; bez vlivu na DPH základ – viz Uplatněné zálohy).
`external_ref`	string	doporučeno	Vaše jednoznačná reference (ID objednávky / rezervace). Spolu se `source_app` tokenu zajišťuje idempotenci.
`currency`	string	ne	Měna. Povolené: `CZK`, `EUR`, `USD`. Výchozí `CZK`.
`note`	string	ne	Poznámka na faktuře.

Objekt supplier (dodavatel):

Pole	Typ	Povinné	Popis
`name`	string	ano	Obchodní jméno dodavatele (firma nebo OSVČ).
`ico`	string	ano	IČO dodavatele. Primární klíč pro upsert subjektu pod účtem platformy.
`external_supplier_id`	string	doporučeno	Vaše interní ID dodavatele ve vaší databázi (např. `user_id`). Záložní klíč pro upsert – pokud dodavatel změní IČO, zachová si stejný subjekt ve FakturID. Důrazně doporučeno posílat vždy.
`dic`	string	ne	DIČ (povinné u plátců DPH).
`is_vat_payer`	bool	doporučeno	`true`/`false` – status plátce DPH. Rozhoduje o sazbě DPH na dokladu (viz DPH logika).
`street`	string	ne	Ulice a číslo popisné.
`city`	string	ne	Město.
`zip`	string	ne	PSČ.
`country_code`	string	ne	Kód země (ISO). Výchozí `CZ`.
`email`	string	ne	E-mail dodavatele.
`phone`	string	ne	Telefon.
`bank_account_number`	string	ne	Číslo bankovního účtu dodavatele (pro QR platbu).
`bank_code`	string	ne	Kód banky.
`bank_account_prefix`	string	ne	Předčíslí účtu.

Objekt customer (odběratel):

Pole	Typ	Povinné	Popis
`name`	string	ano	Jméno / název odběratele.
`ico`	string	ne	IČO odběratele (B2B).
`dic`	string	ne	DIČ odběratele.
`street`	string	ne	Ulice a č.p.
`city`	string	ne	Město.
`zip`	string	ne	PSČ.
`country_code`	string	ne	Kód země. Výchozí `CZ`.
`email`	string	ne	E-mail.

Položka v items[]:

Pole	Typ	Povinné	Popis
`description`	string	ano	Popis položky (poskytnutá služba, zboží, doprava…).
`quantity`	number	ano	Množství. Musí být > 0.
`unit_price`	number	ano	Cena za jednotku. Plátce DPH: brutto vč. DPH – systém rozpočítá základ + DPH. Neplátce: rovnou základ (DPH 0).
`vat_rate`	int	ne	Sazba DPH v %. Použije se jen u plátce. Výchozí `21`. U neplátce se vždy přepíše na 0.
`unit`	string	ne	Jednotka (ks, hod…). Výchozí `ks`.

Objekt self_billing:

Pole	Typ	Povinné	Popis
`platform_name`	string	doporučeno	Název vaší platformy (např. `Acme Marketplace s.r.o.`). Vstupuje do povinné klauzule na PDF: „Fakturováno platformou {platform_name} na základě zmocnění dle § 28 odst. 6 ZDPH."

DPH logika

Sazba DPH na dokladu se řídí statusem dodavatele, ne odběratele:

Plátce DPH (supplier.is_vat_payer = true): unit_price je cena včetně DPH. Systém z brutto rozpočítá základ a DPH ve výši item.vat_rate (default 21 %).
Neplátce DPH (supplier.is_vat_payer = false nebo neuvedeno): doklad je bez DPH. unit_price je rovnou základ, sazba se vždy přepíše na 0 % – neplátce DPH ze zákona nemůže DPH účtovat.

Za správnost statusu plátce DPH odpovídá dodavatel a jeho zmocnění vůči platformě. FakturID údaj přebírá tak, jak ho API předá.

Uplatněné zálohy z kreditů

Pole advance_applied umožňuje odečíst částku, kterou zákazník už uhradil formou kreditů (např. dobitím na platformě). Systém pracuje s modelem store credit bez DPH historie:

Kredity se na platformě dobíjejí bez vystavení zálohového daňového dokladu (ZDD). Vhodné pro neplátce DPH (platforma).
DPH se počítá z plné částky služby – záloha DPH základ ani DPH částku nesnižuje.
Na dokladu se zobrazí samostatný řádek „Uplatněná záloha z kreditů: –X Kč", který sníží „K úhradě" na rozdíl mezi celkovou cenou s DPH a uplatněnou zálohou.
Pokud advance_applied ≥ total_with_vat, „K úhradě" je 0 a doklad se uloží se statusem paid.

Pozor – nemíchat s § 37a ZDPH. Pokud byste v budoucnu spustili vystavování zálohových daňových dokladů (ZDD), kredity by získaly DPH historii a tento jednoduchý model už nestačí – budeme muset zavést samostatný režim zúčtování záloh s DPH. Dejte vědět.

Idempotence

Stejný požadavek se stejnou kombinací source_app (z tokenu) + external_ref nevytvoří duplicitní doklad. API vrátí již existující fakturu s příznakem "duplicate": true.

Vždy posílejte stabilní external_ref (např. ID rezervace) – ošetříte tím opakované odeslání po timeoutu.

Struktura odpovědi

Při úspěchu vrací API HTTP 200 a JSON:

{
    "ok": true,
    "invoice_id": "4821",
    "number": "FSB-2026-0007",
    "subject_id": "152",
    "total_with_vat": 6050,
    "advance_applied": 6050,
    "to_pay": 0,
    "pdf_url": "https://fakturid.cz/api/invoice_pdf.php?id=4821&t=...",
    "archive_sha256": "8a4b…3f"
}

Pole	Typ	Popis
`ok`	bool	`true` při úspěchu.
`invoice_id`	string	Interní ID dokladu ve FakturID.
`number`	string	Přidělené číslo z FSB řady dodavatele.
`subject_id`	string	ID subjektu dodavatele, pod kterým doklad vznikl (užitečné pro audit).
`total_with_vat`	number	Celková fakturovaná částka vč. DPH (plné plnění).
`advance_applied`	number	Uplatněná záloha z kreditů (po ořezání na max `total_with_vat`).
`to_pay`	number	Skutečná částka k úhradě (`total_with_vat − advance_applied`; min 0).
`pdf_url`	string	Podepsaný veřejný odkaz na PDF (HMAC-SHA256). Otevírá zmrazenou kopii z archivu.
`archive_sha256`	string	SHA256 archivovaného PDF (hex). Důkaz neměnnosti – uložte si na své straně pro audit.
`duplicate`	bool	Přítomno a `true` u idempotentního zásahu (vrácena existující faktura).

Návratové kódy a chyby

Při chybě API vrací odpovídající HTTP kód a JSON ve tvaru { "ok": false, "error": "..." }.

HTTP	`error`	Význam a řešení
403	`forbidden`	Chybný / chybějící token, nebo token nemá přiřazený účet platformy. Zkontrolujte hlavičku a nastavení tokenu v adminu FakturID.
400	`bad_request`	Neplatné JSON tělo. Ověřte `Content-Type: application/json` a strukturu těla.
400	`invalid_supplier`	Chybí `supplier` nebo některé z povinných polí (`name`, `ico`).
400	`invalid_customer`	Chybí `customer.name`.
400	`no_items`	Pole `items` je prázdné nebo chybí.
400	`invalid_amount`	Některá položka má `quantity` nebo `unit_price` ≤ 0.
500	`subject_failed`	Nepodařilo se založit / aktualizovat subjekt dodavatele (typicky DB chyba). Opakujte; pokud přetrvává, kontaktujte provozovatele.
500	`subject_not_found`	Konzistentní chyba mezi upsertem a čtením (raritní souběh). Opakujte.
500	`sequence_contention`	Nepodařilo se přidělit číslo z řady kvůli souběhu po několika pokusech. Opakujte.
500	`insert_failed`	Chyba při zápisu faktury do DB. Opakujte; pokud přetrvává, kontaktujte provozovatele.

Archív a neměnnost

Po úspěšném vystavení FakturID:

Vyrenderuje PDF obsahující všechny náležitosti dle § 29 ZDPH + povinnou klauzuli § 28/6.
Zmrazí PDF na disk do archivu (data/archive/fsb/YYYY/MM/) a vypočte SHA256 jeho bytes.
Veřejný PDF link v pdf_url servíruje právě tuto archivní kopii – ne re-render. Bytes jsou identické s tím, co jste dostali při vystavení.
Edit z UI je zakázán. Doklad nelze upravit přes rozhraní FakturID; případné námitky dodavatele řeší vaše platforma.
Retence 10 let dle § 35 odst. 2 ZDPH. Archiv má mimo-deploy zálohu.

archive_sha256 v odpovědi si uložte na své straně – kdykoliv můžete proti aktuálnímu obsahu archivovaného PDF ověřit, že nedošlo k manipulaci.

Příklady

cURL

curl -X POST https://fakturid.cz/api/self_billing_invoice.php \
  -H "Content-Type: application/json" \
  -H "X-Fakturid-Token: VAS_PLATFORM_TOKEN" \
  -d '{
    "self_billing": { "platform_name": "Acme Marketplace s.r.o." },
    "external_ref": "ORDER-2026-1042",
    "supplier": {
      "name": "Acme Konzulting s.r.o.",
      "ico": "12345678",
      "external_supplier_id": "user_872",
      "dic": "CZ12345678",
      "is_vat_payer": true,
      "street": "Dlouhá 5",
      "city": "Praha",
      "zip": "11000",
      "bank_account_number": "1234567890",
      "bank_code": "0100"
    },
    "customer": {
      "name": "Jana Nováková",
      "street": "Veselá 12",
      "city": "Brno",
      "zip": "60200",
      "email": "jana@example.cz"
    },
    "items": [
      { "description": "Konzultační služba – květen 2026", "quantity": 1, "unit_price": 6050, "vat_rate": 21 }
    ],
    "advance_applied": 6050
  }'

PHP (cURL)

<?php
$token = 'VAS_PLATFORM_TOKEN';
$payload = [
    'self_billing'    => ['platform_name' => 'Acme Marketplace s.r.o.'],
    'external_ref'    => 'ORDER-2026-1042',
    'supplier' => [
        'name'                 => 'Acme Konzulting s.r.o.',
        'ico'                  => '12345678',
        'external_supplier_id' => 'user_872',
        'dic'                  => 'CZ12345678',
        'is_vat_payer'         => true,
        'street'               => 'Dlouhá 5',
        'city'                 => 'Praha',
        'zip'                  => '11000',
        'bank_account_number'  => '1234567890',
        'bank_code'            => '0100',
    ],
    'customer' => [
        'name'  => 'Jana Nováková',
        'email' => 'jana@example.cz',
    ],
    'items' => [
        ['description' => 'Konzultační služba – květen 2026', 'quantity' => 1, 'unit_price' => 6050, 'vat_rate' => 21],
    ],
    'advance_applied' => 6050,
];

$ch = curl_init('https://fakturid.cz/api/self_billing_invoice.php');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'X-Fakturid-Token: ' . $token,
    ],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
]);
$response = curl_exec($ch);
$status   = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);
if ($status === 200 && !empty($data['ok'])) {
    // Ulož $data['archive_sha256'] pro audit; PDF najdeš na $data['pdf_url'].
    // U neplátce DPH stačí pustit is_vat_payer: false – sazba se sama přepíše na 0.
}

Příklad pro dodavatele-neplátce DPH (stejný endpoint, jen jiný status dodavatele):

{
  "self_billing": { "platform_name": "Acme Marketplace s.r.o." },
  "external_ref": "ORDER-2026-1043",
  "supplier": {
    "name": "Eva Dvořáková",
    "ico": "87654321",
    "external_supplier_id": "user_415",
    "is_vat_payer": false
  },
  "customer": { "name": "Tomáš Dvořák" },
  "items": [
    { "description": "Grafický návrh – kampaň 2026", "quantity": 1, "unit_price": 8000 }
  ]
}

Výstup: doklad bez DPH (sazba 0 %), celkem 8 000 Kč, k úhradě 8 000 Kč (záloha není uplatněna).

Získání přístupu

Token pro platformu vystavuje administrátor FakturID ve Správě API tokenů. Token musí být přiřazený uživatelskému účtu vaší platformy ve FakturID (slouží jako kontejner pro subjekty dodavatelů) a má vyplněný source_app (identifikátor vaší platformy, např. acme-marketplace) pro evidenci a idempotenci.

O vydání tokenu, založení účtu platformy nebo nahlášení problému s integrací napište na bachurek@gmail.com. Uveďte název platformy, doménu a stručný popis použití.

Před nasazením v produkci je nutné mít k dispozici písemné zmocnění § 28 odst. 6 ZDPH od každého dodavatele, jehož jménem platforma vystavuje doklady. Toto zmocnění je odpovědnost platformy, nikoli FakturID.