Anleitungen

Guthaben

Kontostand, Buchungsverlauf und Steuerbelege lesen Sie sowohl über die API als auch über MCP. Die Zahlung per Karte - einmalig oder automatisch - läuft immer über einen Stripe-Checkout-Link, den ein Mensch abschließt; die API selbst belastet nie von sich aus eine Karte. Dasselbe gilt für das optionale Monatspaket.

Geld ohne MwSt., Heller, Sprache der Beschreibungen

Jeder Betrag in dieser API ist eine ganze Zahl in HELLERN und ohne MwSt. - volai ist umsatzsteuerpflichtig, die MwSt. wird aber erst beim Aufladen des Guthabens per Karte berechnet (Übersicht unter /cenik). Die Beschreibungen der Buchungen (GET /v1/credit/ledger) setzt die API auf Englisch aus dem Buchungstyp zusammen - die gespeicherte tschechische Notiz wird nie nach außen gegeben, auch nicht in einem anderen Feld.

Kontostand, Reichweite und Hinweise

GET /v1/balance liefert den aktuellen Kontostand plus zwei zusätzliche Berechnungen ADDITIV (bestehende Clients, die nur balanceHal/balanceCzk/currency lesen, funktionieren weiter): runway (dailyAverageHal - die durchschnittlichen Tagesausgaben der letzten Zeit, runwayDays - wie viele Tage das Guthaben bei diesem Tempo reicht, null, wenn es sich nicht berechnen lässt) und notice - denselben Hinweis, den Sie auf der Übersichtsseite des Portals (/prehled) sehen, null, wenn es keinen gibt. Acht mögliche Formen von notice: {kind:"unknown"} (zu wenig Daten für eine Schätzung), {kind:"empty"} (Kontostand null), {kind:"number_fee",feeHal,dueAt} (innerhalb von 3 Tagen wird eine monatliche Gebühr für Sprach- oder Mobilnummern fällig und der Kontostand deckt sie nicht; feeHal ist die Summe aller solcher Gebühren, dueAt die früheste Fälligkeit; bei eingeschalteter automatischer Aufladung wird er nicht geliefert), {kind:"runway",days} (das Guthaben ist bei aktuellem Tempo in days Tagen aufgebraucht) und vier Formen nur bei einem Konto mit Monatspaket: {kind:"subscription_exhausted_topup",renewsAt} (das Monatsguthaben dieses Zeitraums ist aufgebraucht und das Paket läuft im Modus Nachkaufen, weitere Nutzung wird aus aufgeladenem Guthaben bezahlt; renewsAt ist das Ende des Zeitraums in ms, wenn das nächste Monatsguthaben gutgeschrieben wird), {kind:"subscription_cap_reached",renewsAt} (das Monatsguthaben ist aufgebraucht, das Paket läuft mit Obergrenze und aufgeladenes Guthaben deckt nichts ab, kostenpflichtige Aktionen stehen bis renewsAt oder bis zur manuellen Aufladung still) und {kind:"subscription_past_due"} (die Verlängerung des Pakets ist fehlgeschlagen, die gespeicherte Karte konnte nicht belastet werden; bezahlen Sie die Verlängerung im Portal oder tauschen Sie die Karte) und {kind:"subscription_runway",renewsAt,runsOutAt} (der Kontostand ist aufgebraucht, bevor zum nächsten renewsAt das neue Monatsguthaben kommt; runsOutAt ist die Schätzung in ms, aus dem vorsichtigen Tempo des Pakets, dasselbe wie der Ausblick auf das Monatsguthaben auf der Paketkarte im Portal: der höchste Wert aus dem 28-Tage-Durchschnitt (nur bei lückenloser Guthabenhistorie), dem Durchschnittsverbrauch der letzten 7 Prager Tage ohne Nummerngebühren und dem Durchschnitt seit Beginn des Zeitraums (nach dessen erster Woche); runway behält den 28-Tage-Durchschnitt; ein Abonnent erhält diese Form anstelle von runway, und nichts, solange die automatische Aufladung eingeschaltet ist). renewsAt ist in ms (Epoche), derselbe Zeitpunkt wie subscription.periodEnd in derselben Antwort, wo er als ISO-8601-String steht; das Format keines der beiden Felder ändert sich. Bei einem Paket, das nach dem bezahlten Zeitraum enden soll, tragen subscription_exhausted_topup, subscription_cap_reached und subscription_runway zusätzlich cancelAtPeriodEnd: true: Es folgt keine Verlängerung, renewsAt ist das Ende des Pakets, und es wird kein neues Monatsguthaben gutgeschrieben (mit der Obergrenze können Sie dann nur durch Aufladen weitermachen); ohne Kündigung steht das Feld nicht im Hinweis. Bei einem Konto mit Monatspaket enthält die Antwort außerdem subscription (den Paketstatus, sonst null) und topupBalanceHal (nur aufgeladenes Guthaben); balanceHal bleibt die Summe aus Monats- und aufgeladenem Guthaben, siehe das Kapitel Monatspaket.

Buchungsverlauf

GET /v1/credit/ledger?limit - neueste zuerst, OHNE Cursor (nur limit, 1-200, Standard 50) - es gibt überhaupt keinen Cursor, über die API sind also nur die neuesten 200 Buchungen erreichbar; die Portalseite /kredit und die Steuerbelege enthalten den vollständigen Verlauf. Jeder Eintrag enthält type (bonus, topup, call_out, call_in, sms, number_fee, agent, refund, admin, setup_revision - eine zusätzliche Korrekturrunde bei einer Einrichtung schlüsselfertig über den Umfang des Pakets hinaus, subscription_grant - die Gutschrift des Monatsguthabens des Pakets und subscription_expire - der Verfall seines ungenutzten Rests), amountHal (positiv für eine Gutschrift, negativ für eine Belastung), grossHal (der Betrag inkl. MwSt. bei einer Aufladung per Karte, sonst null) und eine englische description, die aus dem Typ zusammengesetzt wird - bei number_fee auch mit der Nummer, für die die Gebühr anfällt. Eine Belastung, die vom Monatsguthaben gedeckt wurde, enthält außerdem fromSubscriptionHal - den Teil der Belastung, den das Monatsguthaben bezahlt hat; andere Buchungen haben dieses Feld nicht. Die Mobilnummer als Zusatzoption erscheint im Verlauf als number_fee (die erste Periode beim Kauf der Nummer und jede Verlängerung nach 30 Tagen) und sms (eine von einer Mobilnummer gesendete Nachricht, zum Tarif pro Segment auf der Preisseite); lehnt der Netzbetreiber eine von einer Mobilnummer gesendete SMS später ab, kommt das Guthaben als Eintrag refund zurück.

Aufladung per Karte

POST /v1/credit/topup {amountCzk} liefert {checkoutUrl} - einen Stripe-Checkout-Link, den ein MENSCH im Browser öffnet. Es wird nichts belastet, bis er die Zahlung selbst abschließt. Eine vollständige Rechnungsadresse (PUT /v1/account/billing) ist VOR dem Aufruf erforderlich - ohne sie lässt sich kein gültiger Steuerbeleg ausstellen (billing_address_required). Unterstützt Idempotency-Key - nach einem Timeout sicher wiederholbar, ohne zwei Zahlungen zu erzeugen.

Automatische Aufladung

Über die API lässt sich die automatische Aufladung nur LESEN, AUSSCHALTEN und ihr SCHWELLENWERT ändern - das Einschalten und das Ändern des BETRAGS laufen ausschließlich über Stripe Checkout, nie über einen direkten Schreibzugriff.

Lesen und Ausschalten

GET /v1/credit/auto-topup liefert {enabled, thresholdHal, amountHal, card: {brand, last4} | null, spentThisMonthHal, monthlyCapHal, disabledReason} - OHNE die Kartennummer, nur mit Marke und den letzten vier Ziffern. PATCH {enabled: false} schaltet sie sofort aus, PATCH {thresholdHal} ändert nur den Schwellenwert (er muss einer der angebotenen Werte und niedriger als der gespeicherte Betrag sein, sonst würde der Kontostand direkt nach einer Aufladung wieder unter den Schwellenwert fallen).

Einschalten und Betrag ändern

POST /v1/credit/auto-topup/setup {thresholdHal, amountHal} liefert {checkoutUrl} - mit dem Abschluss des Checkouts wird SOFORT amountHal als erste Aufladung belastet, und erst dadurch wird die Karte für künftige automatische Aufladungen gespeichert. Das funktioniert auch mit einer bereits früher gespeicherten Karte - es ist der einzige Weg, die automatische Aufladung einzuschalten oder ihren Betrag zu ändern. Nach dem Checkout landet der Browser auch bei einem deutschsprachigen Kunden auf der TSCHECHISCHEN Portalseite (/kredit?automat=zapnuto) - eine bekannte Lücke, kein Fehler Ihrer Integration.

Karte

POST /v1/credit/auto-topup/card liefert einen Checkout-Link (Einrichtungsmodus, es wird nichts belastet) zum Austausch der gespeicherten Karte. DELETE /v1/credit/auto-topup/card trennt die Karte SOFORT - die gesamte Konfiguration wird gelöscht (Schwellenwert und Betrag eingeschlossen), nicht nur die Karte; erneutes Einschalten geht nur über .../setup, das sofort eine erste Aufladung belastet. Nach dem Checkout landet der Browser unabhängig von der Sprache des Kontos auf der TSCHECHISCHEN Portalseite (/kredit?karta=zmenena) - dieselbe bekannte Lücke wie oben.

Obergrenzen

Zwei UNABHÄNGIGE Obergrenzen: höchstens 10.000 CZK gutgeschriebener Betrag pro Kalendermonat und höchstens 4 Aufladungen pro Kalender-TAG - egal, wie oft der Kontostand unter den Schwellenwert fällt. Wird eine davon überschritten, schaltet sich die automatische Aufladung automatisch aus (disabledReason monthly_cap oder daily_cap); spentThisMonthHal/monthlyCapHal in der Antwort zeigen, wie viel von der Monatsgrenze noch übrig ist.

MCP: get_auto_topup (lesen) und disable_auto_topup (ausschalten) - Einschalten, Betrag ändern und Karte sind aus demselben Grund wie enabled: true in REST oben nicht in MCP enthalten.

Monatliches Ausgabenlimit

Eine optionale Absicherung gegen eine unerwartet hohe Rechnung: Sie legen fest, wie viel Anrufe, SMS und der Sprachagent in einem Kalendermonat (Prager Zeit) kosten dürfen. Die Funktion ist nur bei einem Konto aktiv, das ein Limit gesetzt hat; ohne Limit ändert sich nichts, und die Monatsausgaben werden lediglich mitgezählt.

GET /v1/account/spend-cap liefert {spendCap: {enabled, capHal, warnShare, inboundAboveCap, month, monthSpendHal, remainingHal, reached, updatedAt}}. Ohne Limit ist enabled gleich false und die Limitfelder sind null, monthSpendHal erhalten Sie aber immer. Beträge sind in ganzen Hellern ohne MwSt. angegeben.

PUT /v1/account/spend-cap {capHal, warnShare?, inboundAboveCap?} setzt oder ändert das Limit: capHal ist in ganzen Hellern von 5.000 (50 CZK) bis 100.000.000 (1.000.000 CZK) anzugeben, warnShare ist der Anteil des Limits von 0,5 bis 0,99 (Standard 0,8), bei dem die Warn-E-Mail gesendet wird, und inboundAboveCap: true lässt die Agenten eingehende Anrufe auch oberhalb des Limits annehmen (Standard false; bei einer Änderung ohne das Feld bleibt der gespeicherte Wert erhalten). DELETE /v1/account/spend-cap entfernt das Limit; das Entfernen eines nicht gesetzten Limits ist unproblematisch.

Sobald das Limit erreicht ist, werden neue ausgehende Anrufe, Rings, Testanrufe und SMS mit spend_cap_reached (HTTP 402) abgelehnt, es wird nichts belastet, und eine Wiederholung hilft nicht, bis der Monat endet oder Sie das Limit erhöhen oder entfernen. Ein eingehender Agentenanruf endet nach einem Satz und kostet nichts, sofern inboundAboveCap nicht true ist. Eine E-Mail wird gesendet, wenn warnShare erreicht ist und wenn das Limit erreicht ist, jeweils höchstens einmal im Monat.

Was das Limit NICHT stoppt: bereits laufende Anrufe (der Preis wird nach dem Anruf belastet, der Monat kann also um deren Preis über dem Limit enden, ebenso durch Anrufe, die nach Mitternacht verbucht werden), Weiterleitung ohne Agent sowie Nummerngebühren, die Runde Schlüsselfertig und das Monatspaket, die alle nicht auf das Limit angerechnet werden. Bei einem Konto mit Monatspaket zählen auch Ausgaben mit, die das Monatsguthaben gedeckt hat. Eine Nummer im Modus Eigene SIP-Telefonanlage mit inboundAboveCap: true bleibt im SIP-Proxy, das Limit stoppt also keine ausgehenden Anrufe der Telefonanlage.

MCP: get_spend_cap, set_spend_cap und clear_spend_cap rufen denselben Dienst auf wie REST und das Portal (der Abschnitt Monatliches Ausgabenlimit im Guthaben). set_spend_cap lässt den Agenten den Betrag dem Kunden vor und nach dem Speichern wiederholen.

Monatspaket

Ein optionales Abonnement: Jeden Monat wird der Preis der gewählten Stufe von der gespeicherten Karte abgebucht und ein Monatsguthaben in CZK gutgeschrieben, das zur Standardpreisliste verbraucht wird. Tarife und die sekundengenaue Abrechnung ändern sich nicht, das Paket ist eine Ebene darüber. Es gibt drei Stufen, und tier ist ihr Preis in CZK ohne MwSt.: "490", "990" und "1990"; Preis und Guthaben jeder Stufe liefert GET /v1/subscription im Feld tiers.

Zwei Arten von Guthaben

Monatsguthaben stammt aus dem Paket, verfällt am Ende des Zeitraums und ist nicht erstattungsfähig. Aufgeladenes Guthaben (Aufladungen, Willkommensbonus, Korrekturen) verfällt nicht und ist wie bisher erstattungsfähig. Der Kontostand - balanceHal in GET /v1/balance, im Portal und in jeder Schranke (Mindestbetrag für einen Anruf, Schuldengrenze, Warnungen) - ist die Summe beider Arten. Das aufgeladene Guthaben allein steht in topupBalanceHal, das verbleibende Monatsguthaben in subscription.monthlyRemainingHal. Eine Schuld kann nur im aufgeladenen Guthaben entstehen.

Reihenfolge des Verbrauchs

Jede Belastung wird zuerst aus dem Monatsguthaben und der Rest aus aufgeladenem Guthaben bezahlt - Anrufe sekundengenau, der Agent, Gebühren für Nummern und Mobilnummern, SMS, Torrufe und ausgehende Aufgabenanrufe. Die Aufteilung erfolgt atomar und wird im Buchungsverlauf festgehalten: Eine vom Monatsguthaben gedeckte Belastung trägt fromSubscriptionHal (den Teil, den das Monatsguthaben bezahlt hat). Korrekturen durch den Inhaber (admin, auch negative) und die Erstattung für eine nicht gesendete SMS (refund) betreffen nur das aufgeladene Guthaben.

Zeitraum und Gutschrift

Ein Zeitraum dauert einen Monat ab der erfolgreichen Belastung (der 31. Januar ergibt den 28. Februar). Das Monatsguthaben wird erst nach Bestätigung der Zahlung mit einem Eintrag subscription_grant gutgeschrieben, und die Gutschrift ist über die Zahlungs-ID idempotent. Hat das Konto zu diesem Zeitpunkt eine Schuld im aufgeladenen Guthaben, wird sie zuerst aus dem neuen Monatsguthaben beglichen, damit das aufgeladene Guthaben nicht negativ bleibt.

Verfall

Der ungenutzte Rest des Monatsguthabens verfällt am Tag der Verlängerung (ein Eintrag subscription_expire mit negativem Betrag), wenn das Abonnement endet, oder durch eine automatische Sicherheitsprüfung, wenn ein Zeitraum vor mehr als 36 Stunden ohne Verlängerung endete. Scheitert die Belastung, ist der Rest bereits verfallen und es wird kein neues Guthaben gutgeschrieben; bis zur Zahlung läuft das Konto nur mit aufgeladenem Guthaben.

Auswahl nach Aufbrauchen

Das Einschalten des Pakets erfordert einen exhaustionMode, ohne Standardwert. topup: Ist das Monatsguthaben aufgebraucht, wird aufgeladenes Guthaben von der gespeicherten Karte nachgekauft - es ist die heutige automatische Aufladung mit denselben Limits und E-Mails. cap: Es wird nichts nachgekauft, ausgehende Anrufe, SMS und Nummernkäufe werden mit subscription_cap_reached (HTTP 402) abgelehnt, und bei einem Kontostand unter null stoppen auch eingehende Anrufe, Weiterleitung und SIP-Zugang (Stopp bei null; nach dem Aufladen oder mit dem neuen Monatsguthaben läuft alles wieder an). Die automatische Aufladung lässt sich mit einer Obergrenze nicht einschalten (subscription_cap_active); der Wechsel zur Obergrenze schaltet sie aus. Mehr als der Preis des Pakets zahlen Sie mit Obergrenze in einem Monat nicht.

Stufe wechseln, kündigen, erneuern

Ein Stufenwechsel (nach oben oder unten) gilt ab dem nächsten Zeitraum, ohne Verrechnung. Kündigen bedeutet cancelAtPeriodEnd: true: Das Guthaben bleibt bis zum Ende des Zeitraums gültig, verfällt dann, und der Status wird canceled; eine Kündigung lässt sich bis zum Ende des Zeitraums zurücknehmen. Über REST und MCP können Sie die Stufe nicht erhöhen, ein gekündigtes Paket nicht erneuern und nicht auf Nachkauf von der Karte umstellen - diese Schritte erhöhen oder starten wiederkehrende Belastungen neu und liefern deshalb subscription_confirmation_required mit einer confirmUrl, die ein Mensch im Portal öffnet und bestätigt (24 Stunden gültig).

Empfehlung vor der Verlängerung

Drei Tage vor der Verlängerung (spätestens einen Tag vorher) kommt eine E-Mail, aber nur, wenn bei Ihren bisherigen Ausgaben die sekundengenaue Zahlung oder eine niedrigere Stufe günstiger wäre. Es gilt dieselbe Regel wie bei der Empfehlung in der Verlängerungs-E-Mail und im Portal: Eine andere Variante muss mindestens 50 CZK und 5 % günstiger ausfallen. Die Schätzung für den ganzen Zeitraum nimmt den höheren Wert aus dem Tempo seit Beginn des Zeitraums und in den letzten 7 Tagen und liegt nie unter den Ausgaben der letzten 30 Tage, auf deren Basis das Portal berät; die Zeilen Stufe und Paket kündigen sagen deshalb nach dem Klick nie, dass Ihre Stufe passt. Die E-Mail nennt Datum und Uhrzeit der Verlängerung genau und kommt höchstens einmal pro Zeitraum, nie bei einem zum Ende des Zeitraums gekündigten Paket, mit einer geplanten Stufenänderung, ohne gespeicherte Karte oder bei ausstehender Zahlung. Ihr Button öffnet im Portal direkt die Zeile Paket kündigen (/kredit?pausal=zrusit) oder die Zeile Stufe (/kredit?pausal=stupen). Die Verlängerungs-E-Mail berät danach erneut anhand der tatsächlichen Ausgaben des ganzen Zeitraums, die Empfehlung kann also anders ausfallen.

Nicht bezahlte Verlängerung

Die Belastung der gespeicherten Karte wird am Tag der Verlängerung, nach 2 Tagen und nach 4 Tagen versucht. Nach dem ersten Fehlschlag ist der Status past_due, eine E-Mail enthält einen Link zur manuellen Zahlung und zum Kartenwechsel, und das Monatsguthaben ist 0; POST /v1/subscription/pay liefert den Link zur manuellen Zahlung. Nach dem dritten Fehlschlag endet das Paket (canceled), und aufgeladenes Guthaben sowie das Konto funktionieren weiter.

MwSt. und Steuerbelege

Die Preise verstehen sich ohne MwSt. Die MwSt.-Regelung wird vor jeder Belastung gelesen, ein Zahler aus einem anderen EU-Land mit geprüfter USt-IdNr. zahlt daher ohne tschechische MwSt. (Reverse-Charge), und der Beleg bildet das ab. volai stellt selbst für jeden bezahlten Zeitraum einen Steuerbeleg aus (die Bemessungsgrundlage ist der Preis der Stufe, nicht das gutgeschriebene Guthaben), und Sie finden ihn in GET /v1/billing/documents.

Verhältnis zum Bonus und zur ersten Aufladung

Das Einschalten des Pakets zählt als erste Zahlung: Es schaltet SMS vom gemeinsamen Absender, Weiterleitung, eine zweite Nummer, eine Mobilnummer und die Karte für die automatische Aufladung frei, genau wie eine Aufladung. Der Willkommensbonus bleibt aufgeladenes Guthaben.

Erstattungen

Monatsguthaben ist nicht erstattungsfähig und verfällt; aufgeladenes Guthaben ist wie bisher erstattungsfähig. Die Kündigung des Pakets begründet keinen Anspruch auf einen anteiligen Teil des bezahlten Zeitraums. Die Erstattung einer Paketzahlung (Reklamation, Irrtum) erledigt der volai-Inhaber manuell, nicht über API oder MCP.

Das Paket über REST und MCP

Geld bewegt sich nur, wenn ein Mensch an der Karte sitzt. Das Einschalten des Pakets und die manuelle Zahlung liefern nur einen Stripe-Checkout-Link und belasten die Karte nie direkt; das Erhöhen der Stufe, das Fortsetzen eines zum Ende vorgesehenen Pakets und der Wechsel zum Nachkauf von der Karte erfordern die Bestätigung eines angemeldeten Menschen im Portal.

• GET /v1/subscription - der Paketstatus (subscription oder null), der Stufenkatalog tiers (id, priceHal, creditHal), topupBalanceHal, available (ein neues Paket kann gestartet werden: Das Angebot ist an und es läuft kein Paket), recommendation (der günstigste Weg, die Ausgaben der letzten 30 Tage zu bezahlen, und steady, ob die Ausgaben fortlaufend und keine einmalige Spitze sind; null ohne Angebot oder ohne 30 Tage Historie) und previousPeriod (der letzte Zeitraum mit denselben Zahlen wie die Verlängerungs-E-Mail: usedHal von creditHal, usedPercent, Ausgaben über das Monatsguthaben hinaus overHal und Verfallenes expiredHal; nur solange das Paket aktiv ist, null im ersten Zeitraum und wenn die Guthabenhistorie die Nutzung nicht belegen kann).
• POST /v1/subscription/checkout {tier, exhaustionMode, consumerConsent?} - liefert ein {checkoutUrl} für Stripe Checkout; das Paket startet nach dessen Abschluss. exhaustionMode (topup oder cap) ist erforderlich; ein Verbraucher ohne Firmenidentifikationsnummer muss consumerConsent: true senden (sonst consumer_consent_required). Die Rechnungsadresse muss vollständig sein (billing_address_required). Unterstützt Idempotency-Key.
• PATCH /v1/subscription {tier?, cancelAtPeriodEnd?, exhaustionMode?} - Stufe senken, kündigen (cancelAtPeriodEnd: true) und auf die Obergrenze wechseln (exhaustionMode: "cap") werden angewendet und liefern {subscription}. Stufe erhöhen, ein zum Ende vorgesehenes Paket fortsetzen (cancelAtPeriodEnd: false) und exhaustionMode: "topup" ändern nichts und liefern 409 subscription_confirmation_required mit einer confirmUrl.
• POST /v1/subscription/pay - nur im Status past_due; liefert ein {checkoutUrl} zur manuellen Zahlung der Verlängerung. Unterstützt Idempotency-Key.
• POST /v1/subscription/card - liefert ein {checkoutUrl} zum Austausch der gespeicherten Karte des Pakets, es wird nichts belastet. Unterstützt Idempotency-Key.
• GET /v1/balance enthält außerdem subscription (gleiche Struktur wie oben, sonst null) und topupBalanceHal.

MCP: get_subscription (lesen), create_subscription_link (ein Link zum Einschalten), update_subscription und cancel_subscription (Stufe senken, kündigen, Obergrenze; Erhöhen, Erneuern und Nachkauf von der Karte liefern eine confirmUrl mit dem Hinweis, dass ein Mensch sie im Portal bestätigen muss) und create_subscription_payment_link (manuelle Zahlung). Einen Kartentausch gibt es in MCP nicht, aus demselben Grund wie bei der automatischen Aufladung: Von hier wird nichts belastet.

Steuerbelege

Ein Beleg wird automatisch ausgestellt bei einer Aufladung des Guthabens per Karte (einmalig oder automatisch), bei der Zahlung für eine Einrichtung schlüsselfertig und als Korrekturbeleg bei der Erstattung einer Einrichtung - ohne manuellen Schritt, ohne Ausstellung über die API.

GET /v1/billing/documents?limit&before - neueste zuerst, der Cursor before (Unix-ms, exklusiv) ist das nextBefore der vorherigen Seite. Der zugrunde liegende Speicher liefert nie mehr als 100 Datensätze pro Aufruf, auch wenn limit mehr anfordert.

GET /v1/billing/documents/{id} liefert {id, number, issuedAt, taxableAt, netHal, vatHal, grossHal, vatRatePercent, reverseCharge, description, customer, paymentRef, pdfUrl} - reverseCharge: true bei Zahlern aus einem anderen EU-Land mit einer per VIES geprüften USt-IdNr., die ohne tschechische MwSt. zahlen. Das Feld kind ist immer gefüllt - "invoice" für einen regulären Beleg (auch für solche, die vor Einführung des Felds ausgestellt wurden), "credit_note" für einen Korrekturbeleg - automatisch ausgestellt, wenn der Gründer die Gebühr einer stornierten Einrichtung schlüsselfertig erstattet, nummeriert in einer eigenen Serie OD..., mit zusätzlichem correctsNumber (die Nummer des ursprünglichen Belegs) und correctionReason (warum erstattet wurde); netHal/vatHal/grossHal sind auch bei einer Gutschrift POSITIV, das Minuszeichen wird nur auf dem PDF ergänzt.

GET /v1/billing/documents/{id}/pdf lädt denselben Beleg als application/pdf herunter - er wird bei jedem Download neu erzeugt, nicht gespeichert. Eine fremde oder fehlende id meldet an beiden Endpunkten denselben Fehler (invoice_not_found), die Antwort verrät also nicht, dass der Beleg eines anderen existiert.

MCP: list_billing_documents und get_billing_document haben dieselbe Struktur wie REST. Das PDF gibt es nur über REST - MCP hat keinen Binärkanal zur Übertragung einer Datei.

Fehler

• ledger_unavailable - Buchungsverlauf oder Kontostand konnten gerade nicht gelesen werden - versuchen Sie es gleich erneut.
• invalid_amount - Der Betrag für Aufladung, Schwellenwert oder automatische Aufladung ist keiner der angebotenen festen Werte.
• billing_address_required - Die Rechnungsadresse fehlt oder ist unvollständig - ergänzen Sie sie vor der Aufladung im Portal (/nastaveni), sonst lässt sich kein gültiger Beleg ausstellen.
• stripe_not_configured - Zahlungen sind für dieses volai-Deployment ausgeschaltet - nicht spezifisch für Ihre Anfrage.
• stripe_error - Stripe hat die Erstellung einer Zahlungssitzung abgelehnt - versuchen Sie es gleich erneut.
• autotopup_not_configured - Die automatische Aufladung hat nie .../setup durchlaufen - es gibt nichts auszuschalten, zu ändern oder dessen Karte zu tauschen.
• invoice_not_found - Auf dem Konto existiert kein Beleg mit dieser id (oder er gehört zu einem anderen Konto - die Antwort ist dieselbe).
• spend_cap_reached - Das von Ihnen gesetzte monatliche Ausgabenlimit ist erreicht: Neue ausgehende Anrufe und SMS werden abgelehnt, und es wird nichts belastet. Erhöhen oder entfernen Sie das Limit mit PUT oder DELETE /v1/account/spend-cap, sonst gilt es bis zum Monatsende (Mitternacht in Prag).
• subscription_cap_reached - Die Obergrenze des Pakets: Monats- und aufgeladenes Guthaben sind beide aufgebraucht, und das Konto hat die Obergrenze gewählt. Ausgehende Anrufe, SMS und Nummernkäufe werden (HTTP 402) bis zur nächsten Verlängerung oder zu einer manuellen Aufladung abgelehnt.
• subscription_exists - Das Konto hat bereits ein Paket; Stufenwechsel, Kündigung und die Auswahl nach Aufbrauchen laufen über PATCH /v1/subscription.
• subscription_missing - Das Konto hat kein aktives Paket, das sich ändern, kündigen oder manuell bezahlen ließe.
• subscription_canceled - Das Paket ist bereits beendet (Status canceled): Es lässt sich nicht mehr ändern, kündigen oder manuell bezahlen. Starten Sie ein neues mit POST /v1/subscription/checkout.
• subscription_confirmation_required - Stufe erhöhen, ein zum Ende vorgesehenes Paket fortsetzen und Nachkauf von der Karte bestätigt nur ein Mensch im Portal - die Antwort enthält eine confirmUrl, und es wurde nichts geändert.
• consumer_consent_required - Ein Verbraucher ohne Firmenidentifikationsnummer muss beim Einschalten des Pakets den ausdrücklichen Wunsch bestätigen, mit der Leistung vor Ablauf der Widerrufsfrist zu beginnen (consumerConsent: true).
• pausal_unavailable - Das Paketangebot ist für dieses Konto derzeit ausgeschaltet.
• invalid_tier - Die Stufe, die das Paket bereits hat, wenn keine andere Stufe geplant ist (eine Stufe, auf die bereits gewechselt wird, ist kein Fehler und gilt als erledigt, sodass dasselbe PATCH /v1/subscription nach einem Ausfall erneut gesendet werden kann; die Ausnahme ist die Rückkehr zur aktuellen Stufe, die die geplante Änderung aufhebt: Bei einer Wiederholung gibt es nichts mehr aufzuheben); ein unbekannter Wert außerhalb von "490", "990", "1990" endet als validation.
• subscription_cap_active - Die automatische Aufladung lässt sich mit einer Obergrenze nicht einschalten; stellen Sie zuerst die Auswahl nach Aufbrauchen im Portal auf topup.
• validation - Speziell bei PATCH /v1/credit/auto-topup: ein Versuch, sie direkt einzuschalten (enabled: true) oder amountHal zu ändern - verwenden Sie stattdessen POST .../setup.

Die vollständige Fehlertabelle für alle Endpunkte steht im Abschnitt Guthaben der REST-API-Referenz.