Průvodci

Kredit

Zůstatek, historie pohybů a daňové doklady čteš přes API i MCP. Platba kartou - jednorázová i automatická - vždy vede přes odkaz na Stripe Checkout, který dokončí člověk; API samo nikdy kartu nestrhne. Totéž platí pro volitelný měsíční paušál.

Peníze bez DPH, haléře, jazyk popisu

Všechny částky v tomhle API jsou celá čísla v HALÉŘÍCH a bez DPH - volai je plátce DPH, ale DPH se počítá až při dobíjení kreditu kartou (přehled na /cenik). Popisy pohybů (GET /v1/credit/ledger) skládá API anglicky z typu pohybu - uložená česká poznámka ven nejde nikdy, ani v jiném poli.

Zůstatek, výdrž a upozornění

GET /v1/balance vrací aktuální zůstatek plus dva doplňkové výpočty ADITIVNĚ (existující klienti, kteří čtou jen balanceHal/balanceCzk/currency, se nerozbijí): runway (dailyAverageHal - průměrná denní útrata z poslední doby, runwayDays - kolik dní kredit při tomhle tempu vydrží, null když se nedá spočítat) a notice - stejné upozornění, jaké vidíš na /prehled v portálu, null když žádné není. Osm možných tvarů notice: {kind:"unknown"} (nedost dat k odhadu), {kind:"empty"} (nulový zůstatek), {kind:"number_fee",feeHal,dueAt} (do 3 dnů je splatný měsíční poplatek za hlasová nebo SMS čísla a zůstatek na něj nestačí; feeHal je součet všech takových poplatků, dueAt nejdřívější splatnost; při zapnutém automatickém dobíjení se nevrací), {kind:"runway",days} (kredit dojde v days dnech při současném tempu) a čtyři tvary jen u účtu s měsíčním paušálem: {kind:"subscription_exhausted_topup",renewsAt} (měsíční kredit tohoto období je vyčerpaný a paušál běží v režimu dokupovat, další útrata jde z dobitého kreditu; renewsAt je konec období v ms, kdy se připíše nový měsíční kredit), {kind:"subscription_cap_reached",renewsAt} (měsíční kredit je vyčerpaný, paušál běží se stropem a dobitý kredit nic nepokryje, placené akce stojí do renewsAt nebo do ručního dobití) a {kind:"subscription_past_due"} (obnova paušálu neprošla, uloženou kartu se nepodařilo strhnout; obnovu zaplatíš v portálu nebo vyměníš kartu) a {kind:"subscription_runway",renewsAt,runsOutAt} (zůstatek dojde dřív, než se v renewsAt připíše nový měsíční kredit; runsOutAt je odhad v ms, kdy dojde, z opatrného tempa paušálu, stejného jako výhled měsíčního kreditu na kartě paušálu v portálu: nejvyšší z průměru za 28 dní (jen při úplné historii kreditu), průměru provozu za posledních 7 pražských dní bez poplatků za čísla a průměru od začátku období (až po jeho prvním týdnu); runway dál počítá s průměrem za 28 dní; předplatiteli se vrací místo runway a při zapnutém automatickém dobíjení se nevrací). U účtu s měsíčním paušálem nese odpověď navíc subscription (stav paušálu, jinak null) a topupBalanceHal (jen dobitý kredit); balanceHal zůstává součtem měsíčního a dobitého kreditu, viz kapitola Měsíční paušál.

Historie pohybů

GET /v1/credit/ledger?limit - nejnovější pohyby první, BEZ kurzoru (jen limit, 1-200, výchozí 50) - starší pohyby než těch nejnovějších 200 přes API nedosáhneš, celou historii má portál /kredit a daňové doklady. Každý záznam nese type (bonus, topup, call_out, call_in, sms, number_fee, agent, refund, admin, setup_revision - kolo úprav objednávky Na klíč nad rámec balíčku, subscription_grant - připsání měsíčního kreditu z paušálu a subscription_expire - propadnutí jeho nevyužitého zbytku), amountHal (kladné přičtení, záporné odečtení), grossHal (částka s DPH u dobití kartou, jinak null) a anglický description složený z typu - u number_fee navíc s číslem, kterého se poplatek týká. U útrat krytých měsíčním kreditem je navíc pole fromSubscriptionHal - část útraty, kterou pokryl měsíční kredit; u ostatních pohybů chybí. Doplněk SMS číslo se v historii ukáže jako number_fee (první období při koupi i každá obnova po 30 dnech) a sms (odeslání ze SMS čísla, sazba za segment je v ceníku); když operátor SMS ze SMS čísla dodatečně odmítne, kredit se vrátí záznamem refund.

Dobití kartou

POST /v1/credit/topup {amountCzk} vrátí {checkoutUrl} - Stripe Checkout odkaz, který otevře ČLOVĚK v prohlížeči. Nic se nestrhne, dokud platbu sám nedokončí. Fakturační adresa (PUT /v1/account/billing) musí být kompletní PŘED voláním - bez ní nejde vystavit platný daňový doklad (billing_address_required). Podporuje Idempotency-Key - bezpečné zopakovat po timeoutu, aniž by vznikly dvě platby.

Automatické dobíjení

Přes API jde automatické dobíjení jen ČÍST, VYPNOUT a změnit PRÁH - zapnutí a změna ČÁSTKY jde výhradně přes Stripe Checkout, nikdy přímým zápisem.

Čtení a vypnutí

GET /v1/credit/auto-topup vrací {enabled, thresholdHal, amountHal, card: {brand, last4} | null, spentThisMonthHal, monthlyCapHal, disabledReason} - BEZ čísla karty, jen značka a poslední čtyřčíslí. PATCH {enabled: false} vypne okamžitě, PATCH {thresholdHal} změní jen práh (musí být z nabízené řady a nižší než uložená částka, jinak se po dobití zůstatek hned znovu propadne pod práh).

Zapnutí a změna částky

POST /v1/credit/auto-topup/setup {thresholdHal, amountHal} vrátí {checkoutUrl} - po dokončení Checkoutu se OKAMŽITĚ strhne amountHal jako první dobití a teprve tím se uloží karta pro budoucí automatická dobití. Funguje i s kartou už uloženou z dřívějška - je to jediná cesta, jak automatické dobíjení zapnout nebo mu změnit částku. Po dokončení Checkoutu se prohlížeč vrátí na ČESKOU stránku portálu (/kredit?automat=zapnuto) i anglicky mluvícímu zákazníkovi - známá mezera, ne chyba tvé integrace.

Karta

POST /v1/credit/auto-topup/card vrátí Checkout odkaz (režim výměny karty, nic se nestrhne) na výměnu uložené karty. DELETE /v1/credit/auto-topup/card odpojí kartu OKAMŽITĚ - smaže se celá konfigurace (práh i částka), ne jen karta; další zapnutí jde jen znovu přes .../setup, který rovnou strhne první dobití. Po dokončení Checkoutu se prohlížeč vrátí na ČESKOU stránku portálu (/kredit?karta=zmenena) bez ohledu na jazyk účtu - stejná známá mezera jako výše.

Stropy

Dva NEZÁVISLÉ stropy: nejvýš 10 000 Kč připsaného kreditu za kalendářní měsíc, a nejvýš 4 dobití za KALENDÁŘNÍ DEN - bez ohledu na to, kolikrát práh klesne pod hranici. Překročení kteréhokoli automatické dobíjení samo vypne (disabledReason monthly_cap, respektive daily_cap); spentThisMonthHal/monthlyCapHal v odpovědi ukazují, kolik z měsíčního stropu zbývá.

MCP: get_auto_topup (čtení) a disable_auto_topup (vypnutí) - zapnutí, změna částky ani karta v MCP nejsou, ze stejného důvodu jako enabled: true v REST výš.

Měsíční paušál

Volitelné předplatné: každý měsíc se z uložené karty strhne cena zvoleného stupně a připíše se měsíční kredit v Kč, který se utrácí za běžný ceník. Sazby ani účtování po vteřinách se tím nemění, paušál je vrstva nad nimi. Stupně jsou tři a tier je jejich cena v Kč bez DPH: "490", "990" a "1990"; ceny a kredit každého stupně vrací GET /v1/subscription v poli tiers.

Dva druhy kreditu

Měsíční kredit pochází z paušálu, na konci období propadá a je nevratný. Dobitý kredit (dobití, uvítací bonus, korekce) nevyprší a je vratný jako dosud. Zůstatek účtu - balanceHal v GET /v1/balance, v portálu i ve všech bránách (minimum pro hovor, limit dluhu, varování) - je součet obou druhů. Samotný dobitý kredit je v topupBalanceHal, zbývající měsíční kredit v subscription.monthlyRemainingHal. Dluh může vzniknout jen v dobitém kreditu.

Pořadí útraty

Každá útrata jde nejdřív z měsíčního kreditu a zbytek z dobitého - hovory po vteřinách, agent, poplatky za čísla a SMS čísla, SMS, prozvonění i odchozí úkoly. Rozdělení je atomické a zapsané v ledgeru: útrata krytá měsíčním kreditem nese fromSubscriptionHal (část, kterou pokryl měsíční kredit). Korekce majitele (admin, i záporná) a vrácení za neodeslanou SMS (refund) se týkají jen dobitého kreditu.

Období a připsání

Období trvá jeden měsíc od úspěšného stržení (31. 1. dává 28. 2.). Měsíční kredit se připíše až po potvrzené platbě záznamem subscription_grant a připsání je idempotentní podle id platby. Má-li účet v tu chvíli dluh v dobitém kreditu, uhradí se nejdřív z nového měsíčního kreditu, aby dobitý kredit nezůstal záporný.

Propadnutí

Nevyužitý zbytek měsíčního kreditu propadá v den obnovy (záznam subscription_expire se zápornou částkou), při skončení předplatného, nebo automatickou pojistkou, když období skončilo před víc než 36 hodinami bez obnovy. Neprojde-li stržení, zbytek už propadl a nový kredit se nepřipíše; do zaplacení běží účet jen na dobitém kreditu.

Volba po vyčerpání

Při zapnutí se povinně volí exhaustionMode, bez předvolby. topup: po vyčerpání měsíčního kreditu se z uložené karty dokupuje dobitý kredit - je to dnešní automatické dobíjení se stejnými limity a e-maily. cap (strop): nic se nedokupuje, příchozí hovory se zvedají ještě do dluhu 50 Kč, odchozí hovory, SMS a nákupy čísel se odmítnou chybou subscription_cap_reached (HTTP 402). Se stropem nejde zapnout automatické dobíjení (subscription_cap_active); přepnutí na strop ho vypne. Nejvíc, co za měsíc se stropem zaplatíš, je cena paušálu.

Změna stupně, zrušení, obnovení

Změna stupně (nahoru i dolů) platí od dalšího období, bez dorovnání. Zrušení je cancelAtPeriodEnd: true: kredit platí do konce období, pak propadne a stav je canceled; do konce období jde zrušení vzít zpět. Přes REST ani MCP nejde zvýšit stupeň, obnovit zrušený paušál ani přepnout na dokupování z karty - tyhle kroky zvyšují nebo znovu zapínají opakované strhávání, proto vrátí subscription_confirmation_required s confirmUrl, který člověk otevře a potvrdí v portálu (platí 24 hodin).

Rada před obnovou

Tři dny před obnovou (nejpozději den předem) přijde e-mail, ale jen když by ti při dosavadní útratě vyšlo levněji platit po vteřinách nebo nižší stupeň. Platí stejné pravidlo jako rada v e-mailu o obnově a v portálu: jiná cesta musí vyjít aspoň o 50 Kč a 5 % levněji. Odhad na celé období bere vyšší z temp od začátku období a za posledních 7 dní a nikdy není nižší než útrata za posledních 30 dní, ze které radí portál; řádky Stupeň a Zrušení proto po kliknutí neřeknou, že stupeň sedí. E-mail uvede přesné datum a čas obnovy a přijde nejvýš jednou za období, nikdy u paušálu zrušeného ke konci období, s naplánovanou změnou stupně, bez uložené karty ani čekajícího na platbu. Tlačítko v něm otevře v portálu rovnou řádek Zrušení (/kredit?pausal=zrusit) nebo Stupeň (/kredit?pausal=stupen). E-mail o obnově pak radí znovu ze skutečné útraty celého období, takže rada může vyjít i jinak.

Nezaplacená obnova

Stržení z uložené karty se zkouší v den obnovy, za 2 a za 4 dny. Po prvním neúspěchu je stav past_due, přijde e-mail s odkazem na ruční platbu a na změnu karty a měsíční kredit je 0; ruční platbu vrací POST /v1/subscription/pay. Po třetím neúspěchu paušál skončí (canceled), dobitý kredit a účet fungují dál.

DPH a doklady

Ceny jsou bez DPH. Režim DPH se čte před každým stržením, takže plátce z jiného státu EU s ověřeným DIČ platí bez české DPH (reverse charge) a doklad to odráží. Daňový doklad za každé zaplacené období vystavuje volai sám (základ daně je cena stupně, ne připsaný kredit) a najdeš ho v GET /v1/billing/documents.

Vztah k bonusu a prvnímu dobití

Zapnutí paušálu se počítá jako první platba: odemyká SMS ze sdíleného odesílatele, přesměrování, druhé číslo, SMS číslo i kartu automatického dobíjení stejně jako dobití. Uvítací bonus zůstává dobitým kreditem.

Vratnost

Měsíční kredit je nevratný a propadá; dobitý kredit je vratný jako dosud. Zrušení paušálu nezakládá nárok na poměrnou část zaplaceného období. Vrácení platby za paušál (reklamace, omyl) řeší majitel volai ručně, přes API ani MCP nejde.

Paušál v REST a MCP

Peníze se hýbou jen s člověkem u karty. Zapnutí paušálu a ruční platba vrací jen odkaz na Stripe Checkout a nikdy nestrhnou kartu přímo; zvýšení stupně, obnovení paušálu nastaveného ke konci období a přepnutí na dokupování z karty vyžadují potvrzení přihlášeného člověka v portálu.

• GET /v1/subscription - stav paušálu (subscription nebo null), katalog stupňů tiers (id, priceHal, creditHal), topupBalanceHal, available, recommendation (nejlevnější cesta pro útratu za posledních 30 dní a steady, jestli útrata trvá, ne jen jednorázová špička; null bez nabídky nebo bez 30 dní historie) a previousPeriod (minulé období se stejnými čísly jako e-mail o obnově: usedHal z creditHal, usedPercent, útrata nad měsíční kredit overHal a propadlý zbytek expiredHal; jen u aktivního paušálu, null v prvním období a když útratu nejde z historie doložit).
• POST /v1/subscription/checkout {tier, exhaustionMode, consumerConsent?} - vrátí {checkoutUrl} na Stripe Checkout, po jehož dokončení paušál začne. exhaustionMode (topup nebo cap) je povinný; spotřebitel bez IČO musí poslat consumerConsent: true (jinak consumer_consent_required). Fakturační adresa musí být kompletní (billing_address_required). Podporuje Idempotency-Key.
• PATCH /v1/subscription {tier?, cancelAtPeriodEnd?, exhaustionMode?} - snížení stupně, zrušení (cancelAtPeriodEnd: true) a přepnutí na strop (exhaustionMode: "cap") provede a vrátí {subscription}. Zvýšení stupně, obnovení paušálu nastaveného ke konci období (cancelAtPeriodEnd: false) a exhaustionMode: "topup" nic nezmění a vrátí 409 subscription_confirmation_required s confirmUrl.
• POST /v1/subscription/pay - jen ve stavu past_due; vrátí {checkoutUrl} na ruční zaplacení obnovy. Podporuje Idempotency-Key.
• POST /v1/subscription/card - vrátí {checkoutUrl} na výměnu uložené karty paušálu, nic se nestrhne. Podporuje Idempotency-Key.
• GET /v1/balance nese navíc subscription (stejný tvar jako výše, jinak null) a topupBalanceHal.

MCP: get_subscription (čtení), create_subscription_link (odkaz na zapnutí), update_subscription a cancel_subscription (snížení stupně, zrušení, strop; zvýšení, obnovení a dokupování vrátí confirmUrl s větou, že to musí potvrdit člověk v portálu) a create_subscription_payment_link (ruční platba). Výměna karty v MCP není, ze stejného důvodu jako u automatického dobíjení: odsud se nic nestrhává.

Daňové doklady

Doklad vzniká automaticky při dobití kreditu kartou (jednorázovém i automatickém), při zaplacení zřízení Na klíč a jako opravný doklad při vrácení zřízení - žádný ruční krok, žádné vystavení přes API.

GET /v1/billing/documents?limit&before - nejnovější první, kurzor before (Unix ms, exkluzivní) je nextBefore z předchozí stránky. Úložiště samo nikdy nevrátí víc než 100 záznamů na jedno volání, i když limit požaduje víc.

GET /v1/billing/documents/{id} vrací {id, number, issuedAt, taxableAt, netHal, vatHal, grossHal, vatRatePercent, reverseCharge, description, customer, paymentRef, pdfUrl} - reverseCharge: true u plátců z jiného státu EU s ověřeným DIČ (VIES), kteří platí bez české DPH. Pole kind je vždy vyplněné - "invoice" u běžného dokladu (i u dokladů vystavených před zavedením pole), "credit_note" u opravného daňového dokladu - ten vzniká automaticky, když majitel vrátí cenu zřízení u zrušené objednávky Na klíč, čísluje se vlastní řadou OD... a nese navíc correctsNumber (číslo opravovaného dokladu) a correctionReason (důvod vrácení); částky netHal/vatHal/grossHal jsou i u dobropisu KLADNÉ, znaménko mínus dává až PDF.

GET /v1/billing/documents/{id}/pdf stáhne stejný doklad jako application/pdf - sází se čerstvě při každém stažení, neukládá se. Cizí nebo neexistující id hlásí stejnou chybu (invoice_not_found) v obou endpointech, ať z odpovědi nejde poznat, že cizí doklad existuje.

MCP: list_billing_documents a get_billing_document mají stejný tvar jako REST. PDF je jen REST - MCP nemá binární kanál pro přenos souboru.

Chyby

• ledger_unavailable - Historii pohybů ani zůstatek se momentálně nedaří přečíst - zkus to znovu za chvíli.
• invalid_amount - Částka dobití, prahu nebo automatické platby není jedna z nabízených pevných hodnot.
• billing_address_required - Fakturační adresa chybí nebo je neúplná - dopln ji v portálu (/nastaveni) před dobitím, jinak nejde vystavit platný doklad.
• stripe_not_configured - Platby jsou pro tenhle běh volai vypnuté - netýká se konkrétně tvého požadavku.
• stripe_error - Stripe odmítl vytvořit platební relaci - zkus to znovu za chvíli.
• autotopup_not_configured - Automatické dobíjení ještě nikdy neprošlo .../setup - není co vypnout, změnit ani jakou kartu vyměnit.
• invoice_not_found - Doklad s tímhle id na účtu není (nebo patří jinému účtu - odpověď je stejná).
• subscription_cap_reached - Strop paušálu: měsíční i dobitý kredit je vyčerpaný a účet má zvolený strop. Odchozí hovory, SMS a nákupy čísel se odmítají (HTTP 402) do další obnovy nebo do ručního dobití.
• subscription_exists - Účet už paušál má; změna stupně, zrušení a volba po vyčerpání jdou přes PATCH /v1/subscription.
• subscription_missing - Účet nemá aktivní paušál, který by šlo změnit, zrušit nebo zaplatit ručně.
• subscription_canceled - Paušál už skončil (stav canceled): nejde změnit, zrušit ani zaplatit ručně. Nový zapneš přes POST /v1/subscription/checkout.
• subscription_confirmation_required - Zvýšení stupně, obnovení paušálu nastaveného ke konci období a dokupování z karty potvrdí jen člověk v portálu - odpověď nese confirmUrl a nic se nezměnilo.
• consumer_consent_required - Spotřebitel bez IČO musí při zapnutí potvrdit výslovnou žádost o zahájení plnění před uplynutím lhůty pro odstoupení (consumerConsent: true).
• pausal_unavailable - Nabídka paušálu je pro tento účet právě vypnutá.
• invalid_tier - Stupeň, který už paušál má, nebo na který už přechází; neznámá hodnota mimo "490", "990", "1990" skončí jako validation.
• subscription_cap_active - Se stropem nejde zapnout automatické dobíjení; nejdřív přepni volbu po vyčerpání na topup v portálu.
• validation - U PATCH /v1/credit/auto-topup konkrétně: pokus zapnout (enabled: true) nebo změnit amountHal přímo - použij POST .../setup místo toho.

Úplnou tabulku chyb pro každý endpoint najdeš v sekci Kredit v REST API referenci.