Oppaat
Saldo
Saldon, tapahtumahistorian ja laskut voi lukea sekä API:n että MCP:n kautta. Korttimaksu - kertaluonteinen tai automaattinen - kulkee aina Stripe Checkout -linkin kautta, jonka ihminen viimeistelee; API ei koskaan veloita korttia omin päin. Sama koskee valinnaista kuukausipakettia.
Rahat ilman ALV:tä, haléř, kuvausten kieli
Kaikki tämän API:n summat ovat kokonaislukuja haléř-yksikköinä ja ilman ALV:tä - volai on ALV-velvollinen, mutta ALV lasketaan vasta kun saldoa ladataan kortilla (yleiskatsaus sivulla /cenik). Tapahtumien kuvaukset (GET /v1/credit/ledger) API muodostaa englanniksi tapahtuman tyypin perusteella - tallennettu tšekinkielinen merkintä ei poistu järjestelmästä koskaan, ei myöskään missään muussa kentässä.
Markkinat ja valuutat
Jokaisella tilillä on markkina-alue, maa, jossa se maksaa. Saldo pidetään aina haléř-yksikköinä (Tšekissä 1 krediitti = 1 CZK), ja API palauttaa kaikki summat kentissä *Hal haléř-yksikköinä. Tšekin ulkopuolinen tili ostaa saldoa kortilla oman markkina-alueensa valuutassa, ja portaali näyttää sen saldon krediiteissä likimääräisellä muunnoksella, kun taas latausmäärät ovat tarkkoja tilin valuutassa. Markkina-alue valitaan rekisteröitymisen yhteydessä. Latausmäärät on pyöristetty tilin valuutassa (ilman ALV:tä) ja lisättävä saldo noudattaa valuuttakurssia tarkasti; alla oleva taulukko luodaan tarjonnasta. Tällä hetkellä tarjolla ovat nämä markkina-alueet ja valuutat:
- Alankomaat
EUR - Australia
AUD - Belgia
EUR - Bulgaria
EUR - Islanti
ISK - Iso-Britannia
GBP - Itävalta
EUR - Kanada
CAD - Kreikka
EUR - Kroatia
EUR - Latvia
EUR - Portugali
EUR - Puola
PLN - Romania
RON - Ruotsi
SEK - Slovakia
EUR - Slovenia
EUR - Suomi
EUR - Sveitsi
CHF - Tanska
DKK - Tšekki
CZK - Uusi-Seelanti
NZD - Viro
EUR
Pyöristetyt latausmäärät ja suositellut automaattisen latauksen arvot valuutoittain, valuutan kokonaisina yksikköinä, ilman ALV:tä:
| Valuutta | Latausmäärät | Automaattisen latauksen kynnykset | Oma summa (alku, loppu, askel) |
|---|---|---|---|
| CZK | 200 / 500 / 1 000 / 2 000 | 100 / 200 / 500 | 100 - 20 000 (1) |
| EUR | 10 / 20 / 50 / 100 | 5 / 10 / 20 | 5 - 1 000 (1) |
| PLN | 50 / 100 / 200 / 500 | 20 / 50 / 100 | 20 - 5 000 (1) |
| GBP | 10 / 20 / 50 / 100 | 5 / 10 / 20 | 5 - 1 000 (1) |
| DKK | 50 / 100 / 200 / 500 | 20 / 50 / 100 | 20 - 5 000 (1) |
| CHF | 10 / 20 / 50 / 100 | 5 / 10 / 20 | 5 - 1 000 (1) |
| RON | 50 / 100 / 200 / 500 | 20 / 50 / 100 | 20 - 5 000 (1) |
| SEK | 100 / 200 / 500 / 1 000 | 50 / 100 / 200 | 50 - 10 000 (1) |
| CAD | 10 / 20 / 50 / 100 | 5 / 10 / 20 | 5 - 1 000 (1) |
| ISK | 1 000 / 2 000 / 5 000 / 10 000 | 500 / 1 000 / 2 000 | 500 - 100 000 (100) |
| AUD | 10 / 20 / 50 / 100 | 5 / 10 / 20 | 5 - 1 000 (1) |
| NZD | 20 / 50 / 100 / 200 | 10 / 20 / 50 | 10 - 2 000 (1) |
Saldo, riittävyys ja ilmoitus
GET /v1/balance palauttaa nykyisen saldon sekä kaksi täydentävää laskelmaa LISÄKSI (olemassa olevat clientit, jotka lukevat vain balanceHal/balanceCzk/currency, eivät rikkoudu): runway (dailyAverageHal - keskimääräinen päivittäinen kulutus viime ajalta, runwayDays - kuinka monta päivää saldo riittää tällä vauhdilla, null kun sitä ei voi laskea) ja notice - sama ilmoitus, joka näytetään portaalin sivulla /prehled, null kun ilmoitusta ei ole. notice voi olla kahdeksassa muodossa: {kind:"unknown"} (liian vähän dataa arvioon), {kind:"empty"} (saldo on nolla), {kind:"number_fee",feeHal,dueAt} (3 päivän sisällä erääntyy puhe- tai matkapuhelinnumeron kuukausimaksu, eikä saldo riitä siihen; feeHal on kaikkien tällaisten maksujen summa, dueAt aikaisin eräpäivä; ei palauteta, kun automaattinen lataus on päällä), {kind:"runway",days} (saldo loppuu days päivän kuluttua nykyisellä vauhdilla) sekä neljä muotoa vain kuukausipaketin tileille: {kind:"subscription_exhausted_topup",renewsAt} (jakson kuukausisaldo on kulutettu ja paketti toimii latausmoodissa, joten jatkuva kulutus otetaan ladatusta saldosta; renewsAt on jakson loppu millisekunteina, jolloin uusi kuukausisaldo hyvitetään), {kind:"subscription_cap_reached",renewsAt} (kuukausisaldo on kulutettu, paketti toimii katolla eikä ladattu saldo kata mitään, maksulliset toiminnot pysäytetään kunnes renewsAt tai käsin tehtyyn lataukseen asti) ja {kind:"subscription_past_due"} (paketin uusiminen ei onnistunut, tallennettua korttia ei voitu veloittaa; uusimisen maksat portaalissa tai vaihdat kortin) ja {kind:"subscription_runway",renewsAt,runsOutAt} (saldo loppuu ennen kuin uusi kuukausisaldo hyvitetään ajankohtana renewsAt; runsOutAt on millisekunteina annettu arvio loppumisesta paketin varovaisen vauhdin pohjalta, sama kuin kuukausisaldon ennuste portaalin pakettikortissa: suurin arvo seuraavista - 28 päivän keskiarvo (vain täydellä saldohistorialla), viimeisten 7 päivän käyttökulutuksen keskiarvo Prahan ajassa ilman numeromaksuja sekä keskiarvo jakson alusta (vasta sen ensimmäisen viikon jälkeen); runway laskee edelleen 28 päivän keskiarvolla; palautetaan runway-kentän sijaan paketin tilaajalle, eikä palauteta kun automaattinen lataus on päällä). renewsAt on millisekunteina (epoch), eli sama ajankohta kuin subscription.periodEnd samassa vastauksessa, jossa se on ISO 8601 -merkkijono; kummankaan kentän muoto ei muutu. Jakson lopussa päättyvällä paketilla subscription_exhausted_topup, subscription_cap_reached ja subscription_runway sisältävät lisäksi cancelAtPeriodEnd: true: uusimista ei tule, renewsAt on paketin loppu eikä uutta kuukausisaldoa hyvitetä (katolla jatkaminen onnistuu silloin vain lataamalla); ilman irtisanomista kenttää ei ole ilmoituksessa. Mukana on myös topup = {currency, amounts: [{amount, creditHal}], defaultAmount, custom: {min, max, step}}: tarjous pyöristetyillä latausmäärillä tilin valuutassa (topup.currency; ylimmän tason currency ilmaisee edelleen kentän balanceCzk yksikön). Kuukausipaketin tilillä vastaus sisältää lisäksi subscription (paketin tila, muuten null) ja topupBalanceHal (vain ladattu saldo); balanceHal on edelleen kuukausisaldon ja ladatun saldon summa, ks. luku Kuukausipaketti.
Tapahtumahistoria
GET /v1/credit/ledger?limit - uusimmat tapahtumat ensin, ILMAN kursoria (vain limit, 1-200, oletus 50) - vanhempia tapahtumia kuin 200 viimeisintä ei saa API:n kautta, koko historia on portaalissa osoitteessa /kredit ja laskuissa. Jokaisella kirjauksella on type (bonus, topup, call_out, call_in, sms, number_fee, agent, refund, admin, setup_revision - muutoskierros avaimet käteen -tilauksessa paketin lisäksi, subscription_grant - kuukausisaldon hyvitys paketista ja subscription_expire - sen käyttämättömän osan raukeaminen), amountHal (positiivinen lisäys, negatiivinen veloitus), grossHal (summa ALV mukaan lukien kortilla ladattaessa, muuten null) ja tyypistä muodostettu englanninkielinen description - number_fee-kirjauksessa lisäksi numero, jota maksu koskee. Kulutukselle, jonka kuukausisaldo on kattanut, on lisäksi kenttä fromSubscriptionHal - se osa kulutuksesta, jonka kuukausisaldo kattoi; muissa tapahtumissa sitä ei ole. Lisäosa matkapuhelinnumero näkyy historiassa tyyppeinä number_fee (ensimmäinen jakso oston yhteydessä ja jokainen uusiminen 30 päivän välein) ja sms (lähetykset matkapuhelinnumerosta, segmenttikohtainen hinta on hinnastossa); jos operaattori hylkää tekstiviestin matkapuhelinnumerosta jälkikäteen, saldo palautetaan kirjauksella refund.
Saldon lataus kortilla
POST /v1/credit/topup {amount, currency} palauttaa {checkoutUrl, currency, amount, creditHal, totalMinor} - Stripe Checkout -linkin, jonka IHMINEN avaa selaimessa. amount on pyöristetty summa tilin valuutan kokonaisina yksikköinä, ilman ALV:tä (tarjous on topup vastauksesta GET /v1/balance, tai mikä tahansa muu kokonaissumma kentän topup.custom rajoissa ja askeleella); currency on oltava tilin valuutta, muuten invalid_amount. creditHal on lisättävä saldo ja totalMinor on veloitus ALV mukaan lukien valuutan pienimmässä yksikössä (ISK satasosina kruunusta, eli 1 000 ISK on 100000). Vanhempi muoto {amountCzk} (kokonaisia krediittejä) toimii muuttumattomana kaikilla tileillä; CZK:n ulkopuolella se palauttaa amount: null, koska summa tilin valuutassa ei ole tasaluku. Lähetä täsmälleen toinen kahdesta muodosta. Mitään ei veloiteta ennen kuin maksaja on itse viimeistellyt maksun. Laskutusosoitteen (PUT /v1/account/billing) on oltava täydellinen ENNEN kutsua - ilman sitä pätevää laskua ei voi antaa (billing_address_required). Tukee otsaketta Idempotency-Key - toisto aikakatkaisun jälkeen on turvallista ilman kahta maksua.
Automaattinen lataus
API:n kautta automaattista latausta voi vain LUKEA, SAMMUTTAA ja muuttaa KYNNYSTÄ - päälle kytkeminen ja SUMMAN muuttaminen kulkee yksinomaan Stripe Checkoutin kautta, ei koskaan suoralla kirjoituksella.
Miksi ei pelkkä ”enabled: true”
Kun kortti on jo tallennettu, paljas {"enabled": true} käynnistäisi veloitukset ILMAN ihmistä kortin ääressä - juuri sen, mitä halutaan välttää (määrittely ”Raha liikkuu vain kun ihminen on kortin ääressä”). Siksi PATCH /v1/credit/auto-topup hylkää sekä enabled: true että amountHal omalla viestillään, ei yleisellä virheellä tuntemattomasta kentästä.
Lukeminen ja sammuttaminen
GET /v1/credit/auto-topup palauttaa {autoTopup: {enabled, thresholdHal, amountHal, card: {brand, last4} | null, spentThisMonthHal, monthlyCapHal, disabledReason}, options}, jossa options = {currency, thresholds: [{amount, thresholdHal}], amounts: [{amount, amountHal}], defaultThreshold, defaultAmount} ovat suositellut pyöristetyt arvot tilin valuutassa (thresholdHal ja amountHal ovat eteenpäin lähetettäviä haléř-yksikköjä saldosta; defaultThreshold ja defaultAmount ovat valuuttayksikköinä). Kortti on ILMAN korttinumeroa, vain merkki ja neljä viimeistä numeroa. PATCH {enabled: false} sammuttaa heti, PATCH {thresholdHal} muuttaa vain kynnystä (arvo joukosta options.thresholds tai yksi vanhoista tšekkiläisistä arvoista, aina pienempi kuin tallennettu summa, muuten saldo jää latauksen jälkeen heti uudelleen kynnyksen alle).
Päälle kytkeminen ja summan muuttaminen
POST /v1/credit/auto-topup/setup {thresholdHal, amountHal} (arvot kentästä options; vanhat tšekkiläiset arvot hyväksytään edelleen kaikilla tileillä) palauttaa {checkoutUrl} - kun Checkout on viimeistelty, amountHal veloitetaan HETI ensimmäisenä latauksena, ja vasta silloin kortti tallennetaan tuleviin automaattisiin latauksiin. Toimii myös aiemmin tallennetulla kortilla - se on ainoa tapa kytkeä automaattinen lataus päälle tai muuttaa summaa. Kun Checkout on viimeistelty, selain palaa portaalin TŠEKINKIELISELLE sivulle (/kredit?automat=zapnuto) myös englanninkieliselle asiakkaalle - tunnettu puute, ei virhe integraatiossasi.
Kortti
POST /v1/credit/auto-topup/card palauttaa Checkout-linkin (kortinvaihtotila, mitään ei veloiteta) tallennetun kortin vaihtamiseksi. DELETE /v1/credit/auto-topup/card irrottaa kortin HETI - koko asetus poistuu (sekä kynnys että summa), ei vain kortti; seuraava päälle kytkeminen onnistuu vain uudelleen kautta .../setup, joka veloittaa ensimmäisen latauksen heti. Kun Checkout on viimeistelty, selain palaa portaalin TŠEKINKIELISELLE sivulle (/kredit?karta=zmenena) tilin kielestä riippumatta - sama tunnettu puute kuin yllä.
Katot
Kaksi ERILLISTÄ kattoa: enintään 10 000 CZK hyvitettyä saldoa kalenterikuukaudessa ja enintään 4 latausta KALENTERIPÄIVÄSSÄ - riippumatta siitä, kuinka monta kertaa kynnys alitetaan. Jos kumpi tahansa ylittyy, automaattinen lataus sammuttaa itsensä (disabledReason monthly_cap tai daily_cap); vastauksen spentThisMonthHal/monthlyCapHal näyttävät, kuinka paljon kuukausikatosta on jäljellä.
MCP: get_auto_topup (lukeminen) ja disable_auto_topup (sammuttaminen) - päälle kytkeminen, summan muuttaminen ja kortti eivät ole MCP:ssä, samasta syystä kuin enabled: true RESTissä yllä.
Kuukausittainen kulutuskatto
Valinnainen suoja yllättävän suurta laskua vastaan: asetat itse, kuinka paljon puhelut, tekstiviestit ja puheagentti saavat maksaa kalenterikuukaudessa (Prahan ajan mukaan). Toiminto on päällä vain tilillä, jolle katto on asetettu; ilman kattoa mikään ei muutu ja kuukauden kulutus vain lasketaan.
GET /v1/account/spend-cap palauttaa {spendCap: {enabled, capHal, warnShare, inboundAboveCap, month, monthSpendHal, remainingHal, reached, updatedAt}}. Ilman kattoa enabled: false ja kattokentät ovat null, mutta monthSpendHal saat aina. Summat ovat kokonaisina haléř-yksikköinä ilman ALV:tä.
PUT /v1/account/spend-cap {capHal, warnShare?, inboundAboveCap?} asettaa tai muuttaa katon: capHal on kokonaisina haléř-yksikköinä väliltä 5 000 (50 CZK) - 100 000 000 (1 000 000 CZK), warnShare on katon osuus 0,5 - 0,99 (oletus 0,8), jolloin varoitussähköposti lähetetään, ja inboundAboveCap: true sallii agenttien jatkaa saapuvien puhelujen vastaanottoa katon ylittymisen jälkeenkin (oletus false, muutettaessa ilman kenttää pätee tallennettu arvo). DELETE /v1/account/spend-cap poistaa katon; olemattoman katon poistaminen on sallittu.
Kun katto on saavutettu, uudet lähtevät puhelut, soitot, testipuhelut ja tekstiviestit hylätään koodilla spend_cap_reached (HTTP 402), mitään ei veloiteta eikä uusi yritys auta ennen kuin kuukausi päättyy tai kattoa nostetaan tai se poistetaan. Saapuva puhelu agentille päättyy yhden lauseen jälkeen eikä maksa mitään, ellei inboundAboveCap: true ole asetettu. Sähköposti lähetetään, kun warnShare saavutetaan ja kun katto saavutetaan, aina enintään kerran kuukaudessa.
Mitä katto EI pysäytä: parhaillaan käynnissä olevat puhelut (hinta veloitetaan vasta puhelun jälkeen, joten kuukausi voi päättyä niiden hinnan ylittäessä katon, samoin kuin keskiyön jälkeen kirjautuvilla puheluilla), vastaajaton soitonsiirto sekä numeromaksut, avaimet käteen -tilauksen muutoskierros ja kuukausipaketti, joita ei lasketa kattoon. Paketin tilillä kulutukseen lasketaan mukaan myös se, minkä kuukausisaldo kattoi. Numero Oma SIP-vaihde -ratkaisussa asetuksella inboundAboveCap: true pysyy SIP-proxyssä, joten katto ei pysäytä vaihteen lähteviä puheluja.
MCP: get_spend_cap, set_spend_cap ja clear_spend_cap kutsuvat samaa palvelua kuin REST ja portaali (osio Kuukausittainen kulutuskatto luvussa Saldo). set_spend_cap toistaa summan asiakkaalle sekä ennen kirjoitusta että sen jälkeen.
Kuukausipaketti
Valinnainen tilaus: joka kuukausi valitun tason hinta veloitetaan tallennetulta kortilta ja tilille hyvitetään kuukausisaldo CZK:na, joka kulutetaan tavallisen hinnaston mukaan. Hinnat ja sekuntikohtainen veloitus eivät muutu, paketti on kerros niiden päällä. Tasoja on kolme ja tier on niiden hinta CZK:na ilman ALV:tä: "490", "990" ja "1990"; kunkin tason hinnat ja saldo palauttaa GET /v1/subscription kentässä tiers.
Kun tarjous ei ole saatavilla
Pakettitarjouksen voi sammuttaa käytössä kaikille tileille tai vain joillekin. Kun se on sammutettu tilillesi, GET /v1/subscription palauttaa available: false ja päälle kytkeminen päättyy virheeseen pausal_unavailable (404). Jo päällä oleva paketti pysyy voimassa, vaikka tarjous sammutetaan.
Kahdenlaista saldoa
Kuukausisaldo tulee paketista, raukeaa jakson lopussa eikä sitä palauteta. Ladattu saldo (lataus, tervetulobonus, korjaus) ei raukea ja on palautettavissa kuten ennenkin. Tilin saldo - balanceHal kutsussa GET /v1/balance, portaalissa ja kaikissa esteissä (puhelujen vähimmäissumma, velkaraja, varoitus) - on molempien summa. Pelkkä ladattu saldo on kentässä topupBalanceHal, jäljellä oleva kuukausisaldo kentässä subscription.monthlyRemainingHal. Velkaa voi syntyä vain ladattuun saldoon.
Kulutuksen järjestys
Jokainen kulutus otetaan ensin kuukausisaldosta ja loppu ladatusta saldosta - sekuntikohtaiset puhelut, agentti, numeroiden ja matkapuhelinnumeroiden maksut, tekstiviestit, soitot ja lähtevät tiedot. Jako on atominen ja kirjataan pääkirjaan: kulutuksella, jonka kuukausisaldo on kattanut, on fromSubscriptionHal (osa, jonka kuukausisaldo kattoi). Omistajan korjaukset (admin, myös negatiiviset) ja lähettämättömän tekstiviestin palautus (refund) koskevat vain ladattua saldoa.
Jakso ja hyvitys
Jakso kestää kuukauden onnistuneesta veloituksesta (31.1. antaa 28.2.). Kuukausisaldo hyvitetään vasta vahvistetun maksun jälkeen kirjauksella subscription_grant, ja hyvitys on idempotentti maksun tunnisteen mukaan. Jos tilillä on silloin velkaa ladatussa saldossa, se maksetaan ensin uudesta kuukausisaldosta, jotta ladattu saldo ei jää negatiiviseksi.
Raukeaminen
Kuukausisaldon käyttämätön osa raukeaa uusimispäivänä (kirjaus subscription_expire negatiivisella summalla), kun tilaus päättyy tai automaattisella varmistuksella, kun jakso päättyi yli 36 tuntia sitten ilman uusimista. Jos veloitus ei onnistu, jäännös on jo rauennut eikä uutta saldoa hyvitetä; maksuun asti tili toimii vain ladatulla saldolla.
Valinta saldon kuluttua loppuun
Päälle kytkettäessä on valittava exhaustionMode, ilman oletusta. topup: kun kuukausisaldo on kulutettu, ladattua saldoa täydennetään tallennetulta kortilta - se on nykyinen automaattinen lataus samoine rajoineen ja sähköposteineen. cap (katto): mitään ei ladata, lähtevät puhelut, tekstiviestit ja numero-ostot hylätään virheellä subscription_cap_reached (HTTP 402), ja kun saldo on alle nollan, pysäytetään myös saapuvat puhelut, soitonsiirto ja SIP-yhteys (pysäytys nollassa, palautuu latauksen tai uuden kuukausisaldon jälkeen). Katon kanssa automaattista latausta ei voi kytkeä päälle (subscription_cap_active); katolle vaihtaminen sammuttaa sen. Katon kanssa maksat kuukaudessa enintään paketin hinnan.
Tason vaihto, irtisanominen, jatkaminen
Tason vaihto (ylös- ja alaspäin) tulee voimaan seuraavasta jaksosta, ilman tasausta. Irtisanominen on cancelAtPeriodEnd: true: saldo on voimassa jakson loppuun, raukeaa sitten ja tilaksi tulee canceled; jakson loppuun asti irtisanomisen voi perua. REST:n ja MCP:n kautta ei voi nostaa tasoa, jatkaa irtisanottua pakettia tai vaihtaa korttilataukseen - nämä vaiheet lisäävät tai käynnistävät uudelleen toistuvat veloitukset, joten ne palauttavat subscription_confirmation_required ja confirmUrl-osoitteen, jonka ihminen avaa ja vahvistaa portaalissa (voimassa 24 tuntia).
Neuvo ennen uusimista
Kolme päivää ennen uusimista (viimeistään edellisenä päivänä) lähetetään sähköposti, mutta vain jos tähänastisella kulutuksella olisi edullisempaa maksaa sekunneittain tai ottaa alempi taso. Sama sääntö pätee kuin uusimissähköpostin ja portaalin neuvossa: toisen vaihtoehdon on oltava vähintään 50 CZK ja 5 % edullisempi. Koko jakson arvio ottaa suuremman vauhdeista jakson alusta ja viimeisiltä 7 päivältä eikä ole koskaan pienempi kuin viimeisten 30 päivän kulutus, jonka perusteella portaali neuvoo; rivit Taso ja Irtisanominen eivät siksi väitä napsautuksen jälkeen, että taso sopii. Sähköposti ilmoittaa uusimisen tarkan päivän ja kellonajan ja lähetetään enintään kerran jaksossa, ei koskaan jakson lopussa irtisanotulle paketille, suunnitellun tasonvaihdon yhteydessä, ilman tallennettua korttia tai maksua odottavalle. Sen painike avaa portaalissa suoraan rivin Irtisanominen (/kredit?pausal=zrusit) tai Taso (/kredit?pausal=stupen). Uusimissähköposti neuvoo sen jälkeen uudelleen koko jakson todellisen kulutuksen perusteella, joten neuvo voi olla toinen.
Maksamaton uusiminen
Veloitus tallennetulta kortilta yritetään uusimispäivänä, 2 ja 4 päivän kuluttua. Ensimmäisen epäonnistumisen jälkeen tila on past_due, lähetetään sähköposti, jossa on linkki käsin maksamiseen ja kortin vaihtoon, ja kuukausisaldo on 0; käsin tehtävän maksun palauttaa POST /v1/subscription/pay. Kolmannen epäonnistumisen jälkeen paketti päättyy (canceled), ladattu saldo ja tili toimivat edelleen.
ALV ja laskut
Hinnat ovat ilman ALV:tä. ALV-järjestelmä luetaan ennen jokaista veloitusta, joten toisen EU-maan maksaja vahvistetulla ALV-tunnuksella maksaa ilman Tšekin ALV:tä (käänteinen verovelvollisuus) ja lasku heijastaa sitä. Jokaisesta maksetusta jaksosta volai antaa laskun itse (veron peruste on tason hinta, ei hyvitetty saldo) ja löydät sen kutsulla GET /v1/billing/documents.
Suhde bonukseen ja ensimmäiseen lataukseen
Paketin päälle kytkeminen lasketaan ensimmäiseksi maksuksi: se avaa yhteisen lähettäjän tekstiviestit, soitonsiirron, toisen numeron, lisäosan matkapuhelinnumero ja automaattisen latauksen kortin samoin kuin lataus. Tervetulobonus pysyy ladattuna saldona.
Palautus
Kuukausisaldoa ei palauteta ja se raukeaa; ladattu saldo on palautettavissa kuten ennenkin. Paketin irtisanominen ei anna oikeutta maksetun jakson suhteelliseen osuuteen. Pakettimaksun palautuksen (reklamaatio, erehdys) hoitaa volain omistaja käsin, se ei onnistu API:n tai MCP:n kautta.
Paketti RESTissä ja MCP:ssä
Raha liikkuu vain kun ihminen on kortin ääressä. Paketin päälle kytkeminen ja käsin tehtävä maksu palauttavat vain Stripe Checkout -linkin eivätkä koskaan veloita korttia suoraan; tason nosto, jakson lopussa päättyväksi asetetun paketin jatkaminen ja vaihto korttilataukseen vaativat kirjautuneen ihmisen vahvistuksen portaalissa.
GET /v1/subscription- paketin tila (subscriptiontainull), tasoluettelotiers(id,priceHal,creditHal),topupBalanceHal,available(uuden paketin voi kytkeä päälle: tarjous on päällä eikä pakettia ole käynnissä),recommendation(edullisin tie viimeisten 30 päivän kulutukselle jasteady, jos kulutus on pysyvää eikä vain kertapiikki;nullilman tarjousta tai ilman 30 päivän historiaa) japreviousPeriod(edellinen jakso samoilla luvuilla kuin uusimissähköpostissa:usedHal/creditHal,usedPercent, kuukausisaldon ylittävä kulutusoverHalja rauennut jäännösexpiredHal; vain aktiiviselle paketille,nullensimmäisessä jaksossa ja kun kulutusta ei voi todentaa historiasta).POST /v1/subscription/checkout {tier, exhaustionMode, consumerConsent?}- palauttaa{checkoutUrl}Stripe Checkoutiin, ja kun se on viimeistelty, paketti alkaa.exhaustionMode(topuptaicap) on pakollinen; kuluttajan ilman IČO-tunnusta on lähetettäväconsumerConsent: true(muutenconsumer_consent_required). Laskutusosoitteen on oltava täydellinen (billing_address_required). Tukee otsakettaIdempotency-Key.PATCH /v1/subscription {tier?, cancelAtPeriodEnd?, exhaustionMode?}- tason lasku, irtisanominen (cancelAtPeriodEnd: true) ja vaihto katolle (exhaustionMode: "cap") suoritetaan ja palautetaan{subscription}. Tason nosto, jakson lopussa päättyväksi asetetun paketin jatkaminen (cancelAtPeriodEnd: false) jaexhaustionMode: "topup"eivät muuta mitään ja palauttavat 409subscription_confirmation_requiredjaconfirmUrl.POST /v1/subscription/pay- vain tilassapast_due; palauttaa{checkoutUrl}uusimisen käsin maksamiseen. Tukee otsakettaIdempotency-Key.POST /v1/subscription/card- palauttaa{checkoutUrl}paketin tallennetun kortin vaihtoon, mitään ei veloiteta. Tukee otsakettaIdempotency-Key.GET /v1/balancesisältää lisäksisubscription(sama muoto kuin yllä, muutennull) jatopupBalanceHal.
MCP: get_subscription (lukeminen), create_subscription_link (linkki päälle kytkemiseen), update_subscription ja cancel_subscription (tason lasku, irtisanominen, katto; nosto, jatkaminen ja korttilataus palauttavat confirmUrl-osoitteen ja lauseen siitä, että ihmisen on vahvistettava se portaalissa) ja create_subscription_payment_link (käsin tehtävä maksu). Kortin vaihto ei ole MCP:ssä, samasta syystä kuin automaattisessa latauksessa: täältä ei veloiteta mitään.
Laskut
Lasku syntyy automaattisesti, kun saldoa ladataan kortilla (sekä kertaluonteisesti että automaattisesti), kun maksetaan avaimet käteen -tilauksen aloitusmaksu ja hyvityslaskuna, kun aloitusmaksu palautetaan - ei käsin tehtävää vaihetta, ei antamista API:n kautta.
GET /v1/billing/documents?limit&before - uusimmat ensin, kursori before (Unix ms, eksklusiivinen) on edellisen sivun nextBefore. Tallennus ei itse palauta koskaan yli 100 kirjausta kutsua kohden, vaikka limit pyytäisi enemmän.
GET /v1/billing/documents/{id} palauttaa {id, number, issuedAt, taxableAt, netHal, vatHal, grossHal, vatRatePercent, reverseCharge, description, customer, paymentRef, pdfUrl} - reverseCharge: true toisen EU-maan maksajalle vahvistetulla ALV-tunnuksella (VIES), joka maksaa ilman Tšekin ALV:tä. Kenttä kind on aina täytetty - "invoice" tavalliselle laskulle (myös ennen kentän käyttöönottoa annetuille laskuille), "credit_note" hyvityslaskulle - se syntyy automaattisesti, kun omistaja palauttaa aloitusmaksun keskeytetyssä avaimet käteen -tilauksessa, numeroidaan omassa sarjassaan OD... ja sisältää lisäksi correctsNumber (oikaistun laskun numero) ja correctionReason (palautuksen syy); summat netHal/vatHal/grossHal ovat POSITIIVISIA myös hyvityslaskulle, miinusmerkin lisää vasta PDF.
GET /v1/billing/documents/{id}/pdf lataa saman laskun muodossa application/pdf - se muodostetaan tuoreena jokaisella latauksella eikä sitä tallenneta. Vieras tai olematon id antaa saman virheen (invoice_not_found) molemmissa endpointeissa, jotta vastauksesta ei voi päätellä vieraan laskun olemassaoloa.
MCP: list_billing_documents ja get_billing_document ovat samaa muotoa kuin REST. PDF on vain RESTissä - MCP:ssä ei ole binäärikanavaa tiedostonsiirtoon.
Virheet
ledger_unavailable- Tapahtumahistoriaa ja saldoa ei voi tällä hetkellä lukea - yritä hetken kuluttua uudelleen.invalid_amount- Latausmäärää ei ole tarjouksessa (topupkutsussaGET /v1/balance, tai oma summa kentäntopup.customvälin tai askeleen ulkopuolella), automaattisen latauksen kynnys tai summa ei ole kentästäoptionseikä vanhoista tšekkiläisistä arvoista, taicurrencyei ole tilin valuutta.billing_address_required- Laskutusosoite puuttuu tai on puutteellinen - täydennä se portaalissa (/nastaveni) ennen latausta, muuten pätevää laskua ei voi antaa.stripe_not_configured- Maksut on sammutettu tässä volai-ajossa - ei koske nimenomaan pyyntöäsi.stripe_error- Stripe hylkäsi maksuistunnon luomisen - yritä hetken kuluttua uudelleen.autotopup_not_configured- Automaattinen lataus ei ole koskaan mennyt läpi kutsun.../setupkautta - ei ole mitään sammutettavaa, muutettavaa eikä korttia vaihdettavaksi.invoice_not_found- Tilillä ei ole laskua tälläid:llä (tai se kuuluu toiselle tilille - vastaus on sama).spend_cap_reached- Asettamasi kuukausittainen kulutuskatto on saavutettu: uudet lähtevät puhelut ja tekstiviestit hylätään eikä mitään veloiteta. Kattoa nostat tai poistat kutsullaPUTtaiDELETE /v1/account/spend-cap, muuten se on voimassa kuukauden loppuun (keskiyöhön Prahan aikaa).subscription_cap_reached- Paketin katto: sekä kuukausisaldo että ladattu saldo on kulutettu ja tili on valinnut katon. Lähtevät puhelut, tekstiviestit ja numero-ostot hylätään (HTTP 402) seuraavaan uusimiseen tai käsin tehtyyn lataukseen asti.subscription_exists- Tilillä on jo paketti; tason vaihto, irtisanominen ja valinta saldon kuluttua loppuun kulkevat kutsunPATCH /v1/subscriptionkautta.subscription_missing- Tilillä ei ole aktiivista pakettia, jota voisi muuttaa, irtisanoa tai maksaa käsin.subscription_canceled- Paketti on jo päättynyt (tilacanceled): sitä ei voi muuttaa, irtisanoa eikä maksaa käsin. Uuden kytket päälle kutsullaPOST /v1/subscription/checkout.subscription_confirmation_required- Tason noston, jakson lopussa päättyväksi asetetun paketin jatkamisen ja korttilatauksen vahvistaa vain ihminen portaalissa - vastauksessa onconfirmUrleikä mikään ole muuttunut.consumer_consent_required- Kuluttajan ilman IČO-tunnusta on päälle kytkettäessä vahvistettava nimenomainen pyyntö aloittaa suoritus ennen peruuttamisajan päättymistä (consumerConsent: true).pausal_unavailable- Pakettitarjous on tällä hetkellä sammutettu tälle tilille.invalid_tier- Taso, joka paketilla jo on, kun muuta ei ole suunniteltu (taso, johon paketti on jo vaihtumassa, ei ole virhe ja lasketaan suoritetuksi, joten samaPATCH /v1/subscriptionvoidaan lähettää uudelleen katkoksen jälkeen; poikkeus on paluu nykyiseen tasoon, joka peruu suunnitellun vaihdon: toistettaessa ei ole enää mitään peruttavaa); tuntematon arvo muu kuin"490","990","1990"päättyy virheeseenvalidation.subscription_cap_active- Katon kanssa automaattista latausta ei voi kytkeä päälle; vaihda ensin portaalissa valinta saldon kuluttua loppuun arvoontopup.validation- Erityisesti kutsullePATCH /v1/credit/auto-topup: yritys kytkeä päälle (enabled: true) tai muuttaaamountHalsuoraan - käytä sen sijaanPOST .../setup.
Täydellinen virhetaulukko jokaiselle endpointille on osiossa Saldo REST API -referenssissä.
Liittyvää
MCP-palvelin
Yhdistä Claude Code, Codex CLI, Codex desktop, Cursor ja muut tekoälyeditorit.
REST API
Täydellinen kuvaus jokaisesta päätepisteestä: numerot, puhelut, tekstiviestit, tekstiviestien matkapuhelinnumerot, agentit ja niiden luonnokset, työkalut, tallenteet, webhookit, soittokieltolista, välitys, tili, tehtävät, saldo, asiakirjat, kalenterit ja integraatiot.
Tehtävät
Lähtevät kampanjat: luonti, vastaanottajien CSV-tuonti, käynnistys, keskeytys ja täsmäytys, budjetti ja soittoikkuna.