Přeskočit na hlavní obsah

První faktura krok za krokem

Projdeme celý životní cyklus dokladu: najdeme zákazníka, zjistíme bankovní účet, vystavíme fakturu, zaúčtujeme ji, stáhneme PDF a pošleme ji e-mailem. Všechny ukázky počítají s klíčem v proměnné prostředí IUCTO_API_KEY.

Ukázková čísla

ID, čísla dokladů a částky jsou vymyšlené. Endpointy, názvy polí a tvar odpovědí odpovídají referenci.

1. Ověřte klíč​

První dotaz veďte na profil firmy — proč zrovna na něj, rozebírá Začínáme:

curl -s https://online.iucto.cz/api/1.3/company_profile \
  -H "X-Auth-Key: $IUCTO_API_KEY"

Když přijde 401, klíč je neplatný nebo patří jiné firmě.

2. Najděte zákazníka​

Na jednorázové dohledání zákazníka slouží IČO — je to pole, které se v praxi nemění. Kdo adresář průběžně synchronizuje z vlastního systému, páruje místo toho podle external_code, viz Synchronizace adresáře.

curl -s "https://online.iucto.cz/api/1.3/customer?comid=12345679&page=1&pageSize=1" \
  -H "X-Auth-Key: $IUCTO_API_KEY"
{
  "pageCount": 1,
  "page": 1,
  "pageSize": 1,
  "_embedded": {
    "customer": [
      { "id": 785, "name": "ACME s.r.o.", "comid": "12345679", "vat_payer": true, "vatid": "CZ12345679" }
    ]
  }
}

page a pageSize platí jen když přijdou oba — viz Stránkování.

Když zákazník neexistuje, klíč _embedded v odpovědi vůbec není. Založte ho přes POST /customer; u plátce DPH je vatid povinné.

3. Zjistěte ID bankovního účtu​

Při platbě převodem (payment_type: transfer) je bank_account povinný:

curl -s https://online.iucto.cz/api/1.3/bank_account \
  -H "X-Auth-Key: $IUCTO_API_KEY"
tip

ID účtu se nemění — vytáhněte si ho jednou při nasazení integrace a uložte do konfigurace, ne při každé faktuře.

4. Vystavte fakturu​

$invoice = [
    'customer_id'   => 785,
    'date'          => '2026-08-12',
    'date_vat'      => '2026-08-12',
    'maturity_date' => '2026-08-26',
    'currency'      => 'CZK',
    'payment_type'  => 'transfer',
    'bank_account'  => 456,
    'description'   => 'Fakturujeme dle smlouvy č. 2026/114.',
    'items'         => [
        [
            'text'   => 'Konzultace — srpen 2026',
            'amount' => 4,
            'price'  => 1500.00,
            'unit'   => 'h',
            'vat'    => 21,
        ],
    ],
];

$ch = curl_init('https://online.iucto.cz/api/1.3/invoice_issued');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($invoice),
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'X-Auth-Key: ' . getenv('IUCTO_API_KEY'),
    ],
]);

$created = json_decode(curl_exec($ch), true);
echo $created['sequence_code']; // FV20260114

Odpověď 201 obsahuje kompletní detail dokladu včetně dopočítaných částek (price, price_inc_vat, to_be_paid) a vygenerovaného čísla dokladu.

Neplátce DPH

Jste-li neplátce, date_vat neposílejte a u položek posílejte "vat": 0 — sazba je povinné pole i tak. Co všechno u neplátce odpadá, je v Neplátcích DPH.

5. Zaúčtujte​

Zaúčtování je samostatný krok, aby šlo doklad před promítnutím do účetnictví ještě zkontrolovat:

curl -s -X PUT https://online.iucto.cz/api/1.3/invoice_issued/123/account \
  -H "X-Auth-Key: $IUCTO_API_KEY"

Aby operace prošla, musí mít všechny položky vyplněné zaúčtování — jak se zadává, popisuje Zaúčtování položek.

Uzavřené účetní období nebo období DPH skončí chybou 400 s popisem, co brání zaúčtování.

6. Stáhněte PDF​

curl -s https://online.iucto.cz/api/1.3/invoice_issued/123/pdf \
  -H "X-Auth-Key: $IUCTO_API_KEY" \
  -o faktura-FV20260114.pdf

Endpoint vrací binární data, ne JSON — nezapomeňte na -o (nebo CURLOPT_FILE v PHP).

7. Pošlete zákazníkovi​

curl -s -X POST https://online.iucto.cz/api/1.3/invoice_issued/123/email \
  -H "Content-Type: application/json" \
  -H "X-Auth-Key: $IUCTO_API_KEY" \
  -d '{
        "message": "Dobrý den, v příloze posíláme fakturu za srpnové konzultace.",
        "recipient": ["fakturace@acme.cz"],
        "hidden_copy": ["kopie@nasefirma.cz"],
        "attach_pdf": true
      }'
{ "send": true }

Kam dál​