API fakturácia pre SaaS: idempotencia, webhooky a opakované faktúry

Test a live kľúč od začiatku

Faktero rozlišuje testovací a ostrý kľúč a je to vidieť už z jeho tvaru. Vývoj a skúšanie robte testovacím; ostrý patrí len do produkcie. Kľúč sa posiela v hlavičke Authorization ako Bearer token a jeho hodnotu vidíte jediný raz — pri vytvorení.

Idempotencia cez external_id

Každá požiadavka na vystavenie faktúry môže niesť vaše vlastné external_id — napríklad identifikátor predplatného alebo objednávky. Keď to isté external_id príde druhý raz, Faktero nevystaví novú faktúru, ale vráti tú pôvodnú. Vďaka tomu je bezpečné volanie zopakovať po timeoute alebo po páde procesu, čo je presne tá situácia, v ktorej duplicity vznikajú.

Čo si ustrážiť na svojej strane

• external_id musí byť stabilné — nie náhodné pri každom pokuse
• Odpoveď si uložte aj s číslom faktúry, nech ho neskôr netreba dohľadávať
• Sieťovú chybu berte ako „neviem, či prešlo“, nie ako neúspech, a volanie zopakujte

Webhooky namiesto opakovaného dopytovania

Stav faktúry nezisťujte v cykle. Faktero pošle na váš endpoint udalosť, keď faktúra vznikne, keď je odoslaná, keď je zaplatená a keď je stornovaná. Doručenia sa evidujú aj s HTTP odpoveďou vašej strany, takže sa dá dohľadať, čo prešlo a čo nie.

Kedy API vôbec nepotrebujete

Ak fakturujete každý mesiac tú istú sumu tým istým zákazníkom, opakované faktúry to vyriešia bez jediného riadku kódu — šablóna sa vystaví a odošle sama. API má zmysel vtedy, keď suma alebo položky závisia od toho, čo sa udialo vo vašom produkte.