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.

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í. Čtyři možné tvary notice: {kind:"unknown"} (nedost dat k odhadu), {kind:"empty"} (nulový zůstatek), {kind:"number_fee",feeHal,dueAt} (blíží se měsíční poplatek za číslo) a {kind:"runway",days} (kredit dojde v days dnech při současném tempu).

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), 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á.

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ýš.

Daňové doklady

Doklad vzniká automaticky při každém dobití kreditu kartou (jednorázovém i automatickém) - žá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.

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á).
• 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.