Ako nastaviť opakovanú fakturáciu predplatného

Predplatné, paušál za podporu alebo mesačný prenájom — zakaždým rovnaká faktúra, len s iným mesiacom v texte. Pohoda sama osebe opakované fakturovanie neumí (žiadny recurring endpoint v API neexistuje), ale keďže faktúru zapíšete jedným volaním, stačí ho spúšťať podľa vlastného rozvrhu — cronom, naplánovanou úlohou alebo frontou vo vašej aplikácii.

Princíp

Faktúru vystavujete úplne rovnako ako v návode Ako vystaviť faktúru z vlastnej aplikácie — len volaním, ktoré si naplánujete na pravidelný termín, napríklad prvý deň v mesiaci:

curl -X PUT https://api.apios.cz/api/v1/invoice \
  -H "X-AUTH-TOKEN: VAS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: predplatne-zakaznik-25-2026-11" \
  -d '{
    "customer_id": 25,
    "text": "Fakturujeme vám předplatné Standard za listopad 2026",
    "date_due": "2026-11-15",
    "payment": "příkazem",
    "invoice_items": [
      { "name": "Předplatné Standard", "qty": 1, "unit": "měs", "price": 1500, "vat_rate": "high" }
    ]
  }'

To isté volanie nájdete v dokumentácii so všetkými parametrami a môžete si ho tam rovno vyskúšať:

customer_id odkazuje na zákazníka v adresári Pohody, takže všetky jeho faktúry zostanú prepojené — ako založiť zákazníka, popisuje Ako hľadať a zakladať zákazníkov v adresári.

Kľúč, ktorý chráni pred duplicitou

Naplánovaná úloha sa môže spustiť dvakrát — výpadok, reštart, ručné dobehnutie po chybe. Preto do Idempotency-Key zakódujte zákazníka aj fakturované obdobie, nie náhodnú hodnotu:

predplatne-{ID zákazníka}-{rok}-{mesiac}

Keď sa úloha spustí druhýkrát s rovnakým kľúčom, Pohoda faktúru znova nezaloží a vráti 409 Conflict — druhá faktúra za rovnaký mesiac tak nevznikne. Princíp podrobne popisuje Ako zabrániť dvojitému zápisu dokladu do Pohody.

Keď sa predplatné v priebehu mesiaca zmení

Zákazník upgradoval tarif v polovici mesiaca alebo pridal službu navyše? Do ďalšieho behu úlohy stačí načítať aktuálne položky (cenu, počet) z vášho systému predplatných a poslať ich v rovnakej požiadavke — faktúru netvoríte ručne, len sa menia vstupné dáta.

Ak je potrebné opraviť už vystavenú faktúru (zlá cena, zabudnutá položka), nevytvárajte novú s rovnakým kľúčom — namiesto toho použite opravný doklad podľa Ako opraviť alebo stornovať vystavenú faktúru.

Vlastná číselná rada

Aby boli faktúry z automatickej fakturácie na prvý pohľad odlíšiteľné od ručne vystavených, založte im v Pohode vlastnú číselnú radu a jej skratku posielajte v number_series. Zoznam rád vráti GET /api/v1/number-series.

Čo ďalej

• Ako poslať zákazníkovi faktúru ako PDF a priložiť ju k faktúre automaticky.
• Ako označiť faktúru za zaplatenú po platbe kartou, hneď ako predplatné zaplatí.