Przewodniki

Saldo

Stan salda, historię operacji i dokumenty podatkowe można odczytać przez API i przez MCP. Płatność kartą, zarówno jednorazowa, jak i automatyczna, zawsze przebiega przez link do Stripe Checkout, który kończy człowiek; samo API nigdy nie obciąży karty. To samo dotyczy opcjonalnego abonamentu miesięcznego.

Kwoty bez VAT, halerze, język opisów

Wszystkie kwoty w tym API to liczby całkowite w HALERZACH i bez VAT. volai jest płatnikiem VAT, ale VAT jest naliczany dopiero przy doładowaniu salda kartą (zestawienie na /cenik). Opisy operacji (GET /v1/credit/ledger) API składa po angielsku na podstawie typu operacji; zapisana czeska notatka nigdy nie jest wysyłana na zewnątrz, także w żadnym innym polu.

Saldo, wystarczalność i powiadomienia

GET /v1/balance zwraca aktualne saldo oraz dwa dodatkowe wyliczenia ADDYTYWNIE (istniejący klienci, którzy czytają tylko balanceHal/balanceCzk/currency, nie przestaną działać): runway (dailyAverageHal - średnia dzienna wydatków z ostatniego okresu, runwayDays - na ile dni wystarczy saldo w tym tempie, null, gdy nie da się policzyć) oraz notice - to samo powiadomienie, które widać na stronie /prehled w portalu, null, gdy go nie ma. Osiem możliwych kształtów notice: {kind:"unknown"} (za mało danych do oszacowania), {kind:"empty"} (saldo zerowe), {kind:"number_fee",feeHal,dueAt} (w ciągu 3 dni upływa termin miesięcznej opłaty za numery głosowe lub numery komórkowe, a saldo jej nie pokrywa; feeHal to suma wszystkich takich opłat, dueAt najwcześniejszy termin; przy włączonym automatycznym doładowaniu nie jest zwracane), {kind:"runway",days} (saldo skończy się za days dni przy obecnym tempie) oraz cztery kształty tylko dla konta z abonamentem miesięcznym: {kind:"subscription_exhausted_topup",renewsAt} (miesięczne saldo z tego okresu zostało wykorzystane, a abonament działa w trybie dokupowania, więc dalsze wydatki idą z doładowanego salda; renewsAt to koniec okresu w ms, kiedy zostanie dopisane nowe saldo miesięczne), {kind:"subscription_cap_reached",renewsAt} (saldo miesięczne zostało wykorzystane, abonament działa z limitem, a doładowane saldo niczego nie pokrywa, więc płatne czynności są wstrzymane do renewsAt lub do ręcznego doładowania) oraz {kind:"subscription_past_due"} (odnowienie abonamentu nie powiodło się, zapisanej karty nie udało się obciążyć; odnowienie można opłacić w portalu lub wymienić kartę) oraz {kind:"subscription_runway",renewsAt,runsOutAt} (saldo skończy się, zanim w renewsAt zostanie dopisane nowe saldo miesięczne; runsOutAt to szacunek w ms, wyliczony z ostrożnego tempa abonamentu, takiego samego jak prognoza salda miesięcznego na karcie abonamentu w portalu: najwyższa z wartości - średnia z 28 dni (tylko przy pełnej historii salda), średnia ruchu z ostatnich 7 dni praskich bez opłat za numery oraz średnia od początku okresu (dopiero po jego pierwszym tygodniu); runway nadal liczy ze średniej z 28 dni; abonentowi jest zwracane zamiast runway, a przy włączonym automatycznym doładowaniu nie jest zwracane). renewsAt jest w ms (epoch), czyli to ten sam moment co subscription.periodEnd w tej samej odpowiedzi, gdzie jest ciągiem ISO 8601; format żadnego z tych pól się nie zmienia. W przypadku abonamentu wypowiedzianego na koniec okresu subscription_exhausted_topup, subscription_cap_reached i subscription_runway zawierają dodatkowo cancelAtPeriodEnd: true: odnowienie nie nastąpi, renewsAt jest końcem abonamentu i nowe saldo miesięczne nie zostanie dopisane (przy limicie można wtedy kontynuować tylko po doładowaniu); bez wypowiedzenia tego pola w powiadomieniu nie ma. W przypadku konta z abonamentem miesięcznym odpowiedź zawiera dodatkowo subscription (stan abonamentu, w przeciwnym razie null) oraz topupBalanceHal (tylko saldo doładowane); balanceHal pozostaje sumą salda miesięcznego i doładowanego, zob. rozdział Abonament miesięczny.

Historia operacji

GET /v1/credit/ledger?limit - najnowsze operacje na początku, BEZ kursora (tylko limit, 1-200, domyślnie 50). Operacji starszych niż 200 najnowszych nie można pobrać przez API; pełną historię ma portal /kredit oraz dokumenty podatkowe. Każdy wpis zawiera type (bonus, topup, call_out, call_in, sms, number_fee, agent, refund, admin, setup_revision - runda poprawek zamówienia pod klucz ponad zakres pakietu, subscription_grant - dopisanie salda miesięcznego z abonamentu oraz subscription_expire - wygaśnięcie jego niewykorzystanej reszty), amountHal (wartość dodatnia to uznanie, ujemna to obciążenie), grossHal (kwota z VAT przy doładowaniu kartą, w pozostałych przypadkach null) oraz angielski description złożony z typu - przy number_fee dodatkowo z numerem, którego dotyczy opłata. Przy wydatkach pokrytych saldem miesięcznym jest dodatkowo pole fromSubscriptionHal - część wydatku, którą pokryło saldo miesięczne; przy pozostałych operacjach go nie ma. Dodatek numer komórkowy pojawia się w historii jako number_fee (pierwszy okres przy zakupie i każde odnowienie po 30 dniach) oraz sms (wysłanie z numeru komórkowego, stawka za segment jest w cenniku); gdy operator później odrzuci SMS wysłany z numeru komórkowego, saldo wraca wpisem refund.

Doładowanie kartą

POST /v1/credit/topup {amountCzk} zwraca {checkoutUrl} - link do Stripe Checkout, który otwiera CZŁOWIEK w przeglądarce. Nic nie zostanie obciążone, dopóki sam nie dokończy płatności. Kompletny adres do faktury (PUT /v1/account/billing) musi być podany PRZED wywołaniem - bez niego nie można wystawić prawidłowego dokumentu podatkowego (billing_address_required). Obsługuje Idempotency-Key - można bezpiecznie powtórzyć po przekroczeniu czasu, bez ryzyka dwóch płatności.

Automatyczne doładowanie

Przez API automatyczne doładowanie można tylko ODCZYTAĆ, WYŁĄCZYĆ i zmienić PRÓG - włączenie i zmiana KWOTY przebiegają wyłącznie przez Stripe Checkout, nigdy przez bezpośredni zapis.

Odczyt i wyłączenie

GET /v1/credit/auto-topup zwraca {enabled, thresholdHal, amountHal, card: {brand, last4} | null, spentThisMonthHal, monthlyCapHal, disabledReason} - BEZ numeru karty, tylko marka i ostatnie cztery cyfry. PATCH {enabled: false} wyłącza natychmiast, PATCH {thresholdHal} zmienia wyłącznie próg (musi pochodzić z oferowanego zestawu i być niższy niż zapisana kwota, w przeciwnym razie po doładowaniu saldo od razu znów spadłoby poniżej progu).

Włączenie i zmiana kwoty

POST /v1/credit/auto-topup/setup {thresholdHal, amountHal} zwraca {checkoutUrl} - po zakończeniu Checkout NATYCHMIAST zostaje pobrane amountHal jako pierwsze doładowanie i dopiero wtedy karta zostaje zapisana na przyszłe automatyczne doładowania. Działa także z kartą zapisaną wcześniej - to jedyny sposób, aby włączyć automatyczne doładowanie lub zmienić jego kwotę. Po zakończeniu Checkout przeglądarka wraca na CZESKĄ stronę portalu (/kredit?automat=zapnuto), także w przypadku klienta anglojęzycznego - to znana luka, nie błąd w Państwa integracji.

Karta

POST /v1/credit/auto-topup/card zwraca link do Checkout (tryb wymiany karty, nic nie jest pobierane) służący do wymiany zapisanej karty. DELETE /v1/credit/auto-topup/card odłącza kartę NATYCHMIAST - usuwana jest cała konfiguracja (próg i kwota), nie tylko karta; ponowne włączenie jest możliwe wyłącznie przez .../setup, który od razu pobiera pierwsze doładowanie. Po zakończeniu Checkout przeglądarka wraca na CZESKĄ stronę portalu (/kredit?karta=zmenena) niezależnie od języka konta - ta sama znana luka co wyżej.

Limity

Dwa NIEZALEŻNE limity: najwyżej 10 000 CZK doładowanego salda w miesiącu kalendarzowym oraz najwyżej 4 doładowania w DNIU KALENDARZOWYM - bez względu na to, ile razy saldo spadnie poniżej progu. Przekroczenie któregokolwiek z nich samo wyłącza automatyczne doładowanie (disabledReason monthly_cap, odpowiednio daily_cap); spentThisMonthHal/monthlyCapHal w odpowiedzi pokazują, ile zostało z limitu miesięcznego.

MCP: get_auto_topup (odczyt) i disable_auto_topup (wyłączenie) - włączenia, zmiany kwoty ani karty w MCP nie ma, z tego samego powodu co enabled: true w REST powyżej.

Miesięczny limit wydatków

Opcjonalne zabezpieczenie przed niespodziewanie wysokim rachunkiem: samodzielnie ustawia się, ile mogą kosztować połączenia, SMS-y i agent głosowy w miesiącu kalendarzowym (według czasu w Pradze). Funkcja jest włączona tylko na koncie, które ustawiło limit; bez niego nic się nie zmienia, a wydatki miesiąca są jedynie liczone.

GET /v1/account/spend-cap zwraca {spendCap: {enabled, capHal, warnShare, inboundAboveCap, month, monthSpendHal, remainingHal, reached, updatedAt}}. Bez limitu enabled ma wartość false, a pola limitu są null, natomiast monthSpendHal otrzymuje się zawsze. Kwoty są w pełnych halerzach bez VAT.

PUT /v1/account/spend-cap {capHal, warnShare?, inboundAboveCap?} ustawia lub zmienia limit: capHal w pełnych halerzach od 5 000 (50 CZK) do 100 000 000 (1 000 000 CZK), warnShare to część limitu od 0,5 do 0,99 (domyślnie 0,8), po której zostanie wysłany e-mail z ostrzeżeniem, a inboundAboveCap: true pozwala agentom nadal odbierać połączenia przychodzące także powyżej limitu (domyślnie false; przy zmianie bez tego pola obowiązuje zapisana wartość). DELETE /v1/account/spend-cap usuwa limit; usunięcie nieistniejącego limitu nie jest błędem.

Po osiągnięciu limitu nowe połączenia wychodzące, dzwonienie na numer, połączenia próbne i SMS-y są odrzucane z kodem spend_cap_reached (HTTP 402), nic nie jest naliczane, a ponawianie nie pomoże, dopóki nie skończy się miesiąc albo nie zostanie podniesiony lub usunięty limit. Połączenie przychodzące do agenta kończy się po jednym zdaniu i nic nie kosztuje, chyba że inboundAboveCap: true. E-mail przychodzi po osiągnięciu warnShare i po osiągnięciu limitu, każdy najwyżej raz w miesiącu.

Czego limit NIE zatrzyma: połączeń, które właśnie trwają (cena jest pobierana po połączeniu, więc miesiąc może się skończyć powyżej limitu o ich cenę, tak samo jak przy połączeniach zaksięgowanych po północy), przekierowań bez agenta oraz opłat za numery, rundy poprawek Pod klucz i abonamentu miesięcznego, które nie wliczają się do limitu. W przypadku konta z abonamentem do wydatków wlicza się także to, co pokryło saldo miesięczne. Numer we Własnej centrali SIP z inboundAboveCap: true pozostaje w proxy SIP, więc limit nie zatrzyma połączeń wychodzących z centrali.

MCP: get_spend_cap, set_spend_cap i clear_spend_cap wywołują tę samą usługę co REST i portal (sekcja Miesięczny limit wydatków w Saldzie). set_spend_cap ma powtórzyć klientowi kwotę przed zapisem i po nim.

Abonament miesięczny

Opcjonalna subskrypcja: co miesiąc z zapisanej karty pobierana jest cena wybranego poziomu i dopisywane jest saldo miesięczne w CZK, które wydaje się według zwykłego cennika. Stawki ani naliczanie za sekundy się przez to nie zmieniają, abonament jest warstwą nad nimi. Poziomy są trzy, a tier to ich cena w CZK bez VAT: "490", "990" i "1990"; ceny i saldo każdego poziomu zwraca GET /v1/subscription w polu tiers.

Dwa rodzaje salda

Saldo miesięczne pochodzi z abonamentu, na koniec okresu wygasa i nie podlega zwrotowi. Saldo doładowane (doładowania, bonus powitalny, korekty) nie wygasa i podlega zwrotowi jak dotychczas. Stan konta - balanceHal w GET /v1/balance, w portalu i we wszystkich bramkach (minimum na połączenie, limit zadłużenia, ostrzeżenia) - to suma obu rodzajów. Samo saldo doładowane jest w topupBalanceHal, pozostałe saldo miesięczne w subscription.monthlyRemainingHal. Zadłużenie może powstać tylko w saldzie doładowanym.

Kolejność wydatków

Każdy wydatek idzie najpierw z salda miesięcznego, a reszta z doładowanego - połączenia naliczane za sekundy, agent, opłaty za numery i numery komórkowe, SMS-y, dzwonienie na numer i wychodzące zadania. Podział jest atomowy i zapisany w księdze: wydatek pokryty saldem miesięcznym zawiera fromSubscriptionHal (część pokrytą saldem miesięcznym). Korekty właściciela (admin, także ujemne) i zwrot za niewysłany SMS (refund) dotyczą wyłącznie salda doładowanego.

Okres i dopisanie

Okres trwa jeden miesiąc od udanego pobrania (31. 1. daje 28. 2.). Saldo miesięczne jest dopisywane dopiero po potwierdzonej płatności wpisem subscription_grant, a dopisanie jest idempotentne według identyfikatora płatności. Jeśli konto ma w tej chwili zadłużenie w saldzie doładowanym, jest ono najpierw spłacane z nowego salda miesięcznego, aby saldo doładowane nie pozostało ujemne.

Wygaśnięcie

Niewykorzystana reszta salda miesięcznego wygasa w dniu odnowienia (wpis subscription_expire z kwotą ujemną), przy zakończeniu subskrypcji lub przez automatyczne zabezpieczenie, gdy okres zakończył się ponad 36 godzin temu bez odnowienia. Jeśli pobranie się nie powiedzie, reszta już wygasła i nowe saldo nie zostaje dopisane; do czasu opłacenia konto działa wyłącznie na saldzie doładowanym.

Wybór po wyczerpaniu

Przy włączaniu trzeba obowiązkowo wybrać exhaustionMode, bez wartości domyślnej. topup: po wyczerpaniu salda miesięcznego z zapisanej karty dokupywane jest saldo doładowane - to dzisiejsze automatyczne doładowanie z tymi samymi limitami i e-mailami. cap (limit): nic nie jest dokupywane, połączenia wychodzące, SMS-y i zakupy numerów są odrzucane błędem subscription_cap_reached (HTTP 402), a gdy saldo spadnie poniżej zera, zatrzymują się także połączenia przychodzące, przekierowanie i dostęp przez SIP (zatrzymanie przy zerze; wznowienie po doładowaniu lub z nowym miesięcznym saldem). Z limitem nie można włączyć automatycznego doładowania (subscription_cap_active); przełączenie na limit je wyłącza. Najwięcej, ile miesięcznie zapłaci się z limitem, to cena abonamentu.

Zmiana poziomu, wypowiedzenie, wznowienie

Zmiana poziomu (w górę i w dół) obowiązuje od następnego okresu, bez wyrównania. Wypowiedzenie to cancelAtPeriodEnd: true: saldo obowiązuje do końca okresu, potem wygasa, a stan to canceled; do końca okresu wypowiedzenie można cofnąć. Przez REST ani MCP nie można podnieść poziomu, wznowić wypowiedzianego abonamentu ani przełączyć na dokupowanie z karty - te kroki zwiększają lub ponownie włączają cykliczne pobieranie, dlatego zwracają subscription_confirmation_required z confirmUrl, który człowiek otwiera i potwierdza w portalu (ważny 24 godziny).

Podpowiedź przed odnowieniem

Trzy dni przed odnowieniem (najpóźniej dzień wcześniej) przychodzi e-mail, ale tylko wtedy, gdy przy dotychczasowych wydatkach taniej wyszłoby płacenie za sekundy lub niższy poziom. Obowiązuje ta sama zasada co przy podpowiedzi w e-mailu o odnowieniu i w portalu: inna droga musi wyjść taniej o co najmniej 50 CZK i 5 %. Szacunek na cały okres bierze wyższe z temp od początku okresu i z ostatnich 7 dni i nigdy nie jest niższy niż wydatki z ostatnich 30 dni, z których doradza portal; wiersze Poziom i Wypowiedzenie dlatego po kliknięciu nie powiedzą, że poziom pasuje. E-mail podaje dokładną datę i godzinę odnowienia i przychodzi najwyżej raz na okres, nigdy w przypadku abonamentu wypowiedzianego na koniec okresu, z zaplanowaną zmianą poziomu, bez zapisanej karty ani oczekującego na płatność. Przycisk w nim otwiera w portalu od razu wiersz Wypowiedzenie (/kredit?pausal=zrusit) lub Poziom (/kredit?pausal=stupen). E-mail o odnowieniu radzi potem ponownie na podstawie rzeczywistych wydatków z całego okresu, więc podpowiedź może wyjść inaczej.

Nieopłacone odnowienie

Pobranie z zapisanej karty jest próbowane w dniu odnowienia, po 2 i po 4 dniach. Po pierwszym niepowodzeniu stan to past_due, przychodzi e-mail z linkiem do płatności ręcznej i do zmiany karty, a saldo miesięczne wynosi 0; link do płatności ręcznej zwraca POST /v1/subscription/pay. Po trzecim niepowodzeniu abonament się kończy (canceled), a saldo doładowane i konto działają dalej.

VAT i dokumenty

Ceny są bez VAT. Reżim VAT jest odczytywany przed każdym pobraniem, więc płatnik z innego państwa UE z zweryfikowanym numerem VAT płaci bez czeskiego VAT (odwrotne obciążenie), a dokument to odzwierciedla. Dokument podatkowy za każdy opłacony okres wystawia volai samodzielnie (podstawą opodatkowania jest cena poziomu, nie dopisane saldo) i można go znaleźć w GET /v1/billing/documents.

Związek z bonusem i pierwszym doładowaniem

Włączenie abonamentu liczy się jako pierwsza płatność: odblokowuje SMS-y ze wspólnego nadawcy, przekierowanie, drugi numer, numer komórkowy i kartę automatycznego doładowania tak samo jak doładowanie. Bonus powitalny pozostaje saldem doładowanym.

Zwroty

Saldo miesięczne nie podlega zwrotowi i wygasa; saldo doładowane podlega zwrotowi jak dotychczas. Wypowiedzenie abonamentu nie daje prawa do proporcjonalnej części opłaconego okresu. Zwrot płatności za abonament (reklamacja, pomyłka) załatwia ręcznie właściciel volai, przez API ani MCP nie jest to możliwe.

Abonament w REST i MCP

Pieniądze ruszają się tylko wtedy, gdy człowiek jest przy karcie. Włączenie abonamentu i płatność ręczna zwracają wyłącznie link do Stripe Checkout i nigdy nie obciążają karty bezpośrednio; podniesienie poziomu, wznowienie abonamentu ustawionego na koniec okresu i przełączenie na dokupowanie z karty wymagają potwierdzenia zalogowanego człowieka w portalu.

• GET /v1/subscription - stan abonamentu (subscription lub null), katalog poziomów tiers (id, priceHal, creditHal), topupBalanceHal, available (można włączyć nowy abonament: oferta jest włączona i żaden abonament nie działa), recommendation (najtańszy sposób płacenia za wydatki z ostatnich 30 dni oraz steady, czyli czy wydatki mają charakter ciągły, a nie jednorazowego szczytu; null bez oferty lub bez 30 dni historii) oraz previousPeriod (poprzedni okres z tymi samymi liczbami co e-mail o odnowieniu: usedHal z creditHal, usedPercent, wydatki ponad saldo miesięczne overHal i wygasła reszta expiredHal; tylko przy aktywnym abonamencie, null w pierwszym okresie i gdy wydatków nie da się udowodnić historią).
• POST /v1/subscription/checkout {tier, exhaustionMode, consumerConsent?} - zwraca {checkoutUrl} do Stripe Checkout, po którego zakończeniu abonament się rozpoczyna. exhaustionMode (topup lub cap) jest wymagany; konsument bez numeru firmy musi wysłać consumerConsent: true (w przeciwnym razie consumer_consent_required). Adres do faktury musi być kompletny (billing_address_required). Obsługuje Idempotency-Key.
• PATCH /v1/subscription {tier?, cancelAtPeriodEnd?, exhaustionMode?} - obniżenie poziomu, wypowiedzenie (cancelAtPeriodEnd: true) i przełączenie na limit (exhaustionMode: "cap") zostają wykonane i zwracają {subscription}. Podniesienie poziomu, wznowienie abonamentu ustawionego na koniec okresu (cancelAtPeriodEnd: false) i exhaustionMode: "topup" niczego nie zmieniają i zwracają 409 subscription_confirmation_required z confirmUrl.
• POST /v1/subscription/pay - tylko w stanie past_due; zwraca {checkoutUrl} do ręcznego opłacenia odnowienia. Obsługuje Idempotency-Key.
• POST /v1/subscription/card - zwraca {checkoutUrl} do wymiany zapisanej karty abonamentu, nic nie jest pobierane. Obsługuje Idempotency-Key.
• GET /v1/balance zawiera dodatkowo subscription (ten sam kształt co wyżej, w przeciwnym razie null) oraz topupBalanceHal.

MCP: get_subscription (odczyt), create_subscription_link (link do włączenia), update_subscription i cancel_subscription (obniżenie poziomu, wypowiedzenie, limit; podniesienie, wznowienie i dokupowanie zwracają confirmUrl ze zdaniem, że musi to potwierdzić człowiek w portalu) oraz create_subscription_payment_link (płatność ręczna). Wymiany karty w MCP nie ma, z tego samego powodu co przy automatycznym doładowaniu: stąd nic nie jest pobierane.

Dokumenty podatkowe

Dokument powstaje automatycznie przy doładowaniu salda kartą (jednorazowym i automatycznym), przy opłaceniu uruchomienia Pod klucz oraz jako dokument korygujący przy zwrocie za uruchomienie - żadnego ręcznego kroku, żadnego wystawiania przez API.

GET /v1/billing/documents?limit&before - najnowsze na początku, kursor before (Unix ms, wyłączny) to nextBefore z poprzedniej strony. Magazyn danych nigdy nie zwróci więcej niż 100 rekordów na jedno wywołanie, nawet jeśli limit żąda więcej.

GET /v1/billing/documents/{id} zwraca {id, number, issuedAt, taxableAt, netHal, vatHal, grossHal, vatRatePercent, reverseCharge, description, customer, paymentRef, pdfUrl} - reverseCharge: true w przypadku płatników z innego państwa UE ze zweryfikowanym numerem VAT (VIES), którzy płacą bez czeskiego VAT. Pole kind jest zawsze wypełnione - "invoice" przy zwykłym dokumencie (także przy dokumentach wystawionych przed wprowadzeniem pola), "credit_note" przy dokumencie korygującym - powstaje automatycznie, gdy właściciel zwraca cenę uruchomienia anulowanego zamówienia Pod klucz, jest numerowany własną serią OD... i zawiera dodatkowo correctsNumber (numer korygowanego dokumentu) oraz correctionReason (powód zwrotu); kwoty netHal/vatHal/grossHal są także przy korekcie DODATNIE, znak minus dodaje dopiero PDF.

GET /v1/billing/documents/{id}/pdf pobiera ten sam dokument jako application/pdf - jest składany od nowa przy każdym pobraniu i nie jest zapisywany. Cudzy lub nieistniejący id zgłasza ten sam błąd (invoice_not_found) w obu endpointach, aby z odpowiedzi nie dało się poznać, że cudzy dokument istnieje.

MCP: list_billing_documents i get_billing_document mają ten sam kształt co REST. PDF jest tylko w REST - MCP nie ma kanału binarnego do przesyłania plików.

Błędy

• ledger_unavailable - Historii operacji ani salda nie udaje się teraz odczytać - proszę spróbować ponownie za chwilę.
• invalid_amount - Kwota doładowania, progu lub automatycznej płatności nie jest jedną z oferowanych stałych wartości.
• billing_address_required - Adres do faktury nie został podany lub jest niekompletny - proszę uzupełnić go w portalu (/nastaveni) przed doładowaniem, inaczej nie można wystawić prawidłowego dokumentu.
• stripe_not_configured - Płatności są wyłączone w tym środowisku volai - nie dotyczy konkretnie Państwa żądania.
• stripe_error - Stripe odmówił utworzenia sesji płatności - proszę spróbować ponownie za chwilę.
• autotopup_not_configured - Automatyczne doładowanie nigdy nie przeszło przez .../setup - nie ma czego wyłączać, zmieniać ani której karty wymieniać.
• invoice_not_found - Dokument z tym id nie istnieje na koncie (albo należy do innego konta - odpowiedź jest taka sama).
• spend_cap_reached - Ustawiony przez Państwa miesięczny limit wydatków został osiągnięty: nowe połączenia wychodzące i SMS-y są odrzucane i nic nie jest naliczane. Limit można podnieść lub usunąć przez PUT albo DELETE /v1/account/spend-cap, w przeciwnym razie obowiązuje do końca miesiąca (do północy w Pradze).
• subscription_cap_reached - Limit abonamentu: saldo miesięczne i doładowane jest wyczerpane, a konto ma wybrany limit. Połączenia wychodzące, SMS-y i zakupy numerów są odrzucane (HTTP 402) do następnego odnowienia lub do ręcznego doładowania.
• subscription_exists - Konto ma już abonament; zmiana poziomu, wypowiedzenie i wybór po wyczerpaniu przebiegają przez PATCH /v1/subscription.
• subscription_missing - Konto nie ma aktywnego abonamentu, który można by zmienić, wypowiedzieć lub opłacić ręcznie.
• subscription_canceled - Abonament już się zakończył (stan canceled): nie można go zmienić, wypowiedzieć ani opłacić ręcznie. Nowy można włączyć przez POST /v1/subscription/checkout.
• subscription_confirmation_required - Podniesienie poziomu, wznowienie abonamentu ustawionego na koniec okresu i dokupowanie z karty potwierdza tylko człowiek w portalu - odpowiedź zawiera confirmUrl i nic się nie zmieniło.
• consumer_consent_required - Konsument bez numeru firmy musi przy włączaniu potwierdzić wyraźną prośbę o rozpoczęcie świadczenia przed upływem terminu na odstąpienie od umowy (consumerConsent: true).
• pausal_unavailable - Oferta abonamentu jest teraz wyłączona dla tego konta.
• invalid_tier - Poziom, który abonament już ma, gdy nie jest zaplanowany żaden inny (poziom, na który abonament już przechodzi, nie jest błędem i jest traktowany jako wykonany, więc to samo PATCH /v1/subscription można wysłać ponownie po awarii; wyjątkiem jest powrót do obecnego poziomu, który anuluje zaplanowaną zmianę: przy powtórzeniu nie ma już czego anulować); nieznana wartość poza "490", "990", "1990" kończy się jako validation.
• subscription_cap_active - Z limitem nie można włączyć automatycznego doładowania; najpierw proszę przełączyć wybór po wyczerpaniu na topup w portalu.
• validation - Konkretnie przy PATCH /v1/credit/auto-topup: próba włączenia (enabled: true) lub zmiany amountHal bezpośrednio - zamiast tego proszę użyć POST .../setup.

Pełną tabelę błędów dla każdego endpointu można znaleźć w sekcji Saldo w dokumentacji REST API.