Οδηγοί

Υπόλοιπο

Το υπόλοιπο, το ιστορικό κινήσεων και τα φορολογικά παραστατικά τα διαβάζετε τόσο μέσω API όσο και μέσω MCP. Η πληρωμή με κάρτα - εφάπαξ ή αυτόματη - περνά πάντα από σύνδεσμο του Stripe Checkout, τον οποίο ολοκληρώνει άνθρωπος· το API από μόνο του δεν χρεώνει ποτέ κάρτα. Το ίδιο ισχύει και για το προαιρετικό μηνιαίο πακέτο.

Χρήματα χωρίς ΦΠΑ, haléře, γλώσσα των περιγραφών

Όλα τα ποσά σε αυτό το API είναι ακέραιοι αριθμοί σε εκατοστά της κορώνας (haléře) και χωρίς ΦΠΑ - το volai υπόκειται σε ΦΠΑ, αλλά ο ΦΠΑ υπολογίζεται μόνο κατά τη φόρτιση υπολοίπου με κάρτα (επισκόπηση στο /cenik). Τις περιγραφές των κινήσεων (GET /v1/credit/ledger) τις συνθέτει το API στα αγγλικά από τον τύπο της κίνησης - η αποθηκευμένη τσεχική σημείωση δεν βγαίνει ποτέ προς τα έξω, ούτε σε άλλο πεδίο.

Υπόλοιπο, αυτονομία και ειδοποιήσεις

Το GET /v1/balance επιστρέφει το τρέχον υπόλοιπο και δύο επιπλέον υπολογισμούς ΠΡΟΣΘΕΤΙΚΑ (οι υπάρχοντες πελάτες που διαβάζουν μόνο balanceHal/balanceCzk/currency δεν χαλούν): runway (dailyAverageHal - μέση ημερήσια δαπάνη της τελευταίας περιόδου, runwayDays - πόσες ημέρες θα φτάσει το υπόλοιπο με αυτόν τον ρυθμό, null όταν δεν μπορεί να υπολογιστεί) και notice - την ίδια ειδοποίηση που βλέπετε στο /prehled στην πύλη, null όταν δεν υπάρχει καμία. Οκτώ πιθανές μορφές του notice: {kind:"unknown"} (ανεπαρκή δεδομένα για εκτίμηση), {kind:"empty"} (μηδενικό υπόλοιπο), {kind:"number_fee",feeHal,dueAt} (εντός 3 ημερών λήγει η μηνιαία χρέωση για φωνητικούς ή κινητούς αριθμούς και το υπόλοιπο δεν επαρκεί· το feeHal είναι το άθροισμα όλων αυτών των χρεώσεων, το dueAt η πιο πρώιμη λήξη· δεν επιστρέφεται όταν η αυτόματη φόρτιση είναι ενεργή), {kind:"runway",days} (το υπόλοιπο τελειώνει σε days ημέρες με τον τρέχοντα ρυθμό) και τέσσερις μορφές μόνο για λογαριασμό με μηνιαίο πακέτο: {kind:"subscription_exhausted_topup",renewsAt} (το μηνιαίο υπόλοιπο αυτής της περιόδου εξαντλήθηκε και το πακέτο λειτουργεί σε λειτουργία συμπληρωματικής φόρτισης, η επόμενη δαπάνη πηγαίνει από το φορτισμένο υπόλοιπο· το renewsAt είναι το τέλος της περιόδου σε ms, όταν πιστώνεται νέο μηνιαίο υπόλοιπο), {kind:"subscription_cap_reached",renewsAt} (το μηνιαίο υπόλοιπο εξαντλήθηκε, το πακέτο λειτουργεί με όριο και το φορτισμένο υπόλοιπο δεν καλύπτει τίποτα, οι πληρωμένες ενέργειες σταματούν μέχρι το renewsAt ή μέχρι χειροκίνητη φόρτιση) και {kind:"subscription_past_due"} (η ανανέωση του πακέτου δεν πέρασε, η αποθηκευμένη κάρτα δεν μπόρεσε να χρεωθεί· την ανανέωση την πληρώνετε στην πύλη ή αλλάζετε κάρτα) και {kind:"subscription_runway",renewsAt,runsOutAt} (το υπόλοιπο τελειώνει πριν πιστωθεί νέο μηνιαίο υπόλοιπο στο renewsAt· το runsOutAt είναι εκτίμηση σε ms για το πότε θα τελειώσει, με τον συντηρητικό ρυθμό του πακέτου, τον ίδιο με την πρόβλεψη του μηνιαίου υπολοίπου στην κάρτα του πακέτου στην πύλη: το υψηλότερο από τον μέσο όρο 28 ημερών (μόνο με πλήρες ιστορικό υπολοίπου), τον μέσο όρο της κίνησης των τελευταίων 7 ημερών της Πράγας χωρίς χρεώσεις αριθμών και τον μέσο όρο από την αρχή της περιόδου (μόνο μετά την πρώτη της εβδομάδα)· το runway συνεχίζει να υπολογίζει με τον μέσο όρο 28 ημερών· σε συνδρομητή επιστρέφεται στη θέση του runway και δεν επιστρέφεται όταν η αυτόματη φόρτιση είναι ενεργή). Το renewsAt είναι σε ms (epoch), δηλαδή η ίδια χρονική στιγμή με το subscription.periodEnd στην ίδια απάντηση, όπου είναι συμβολοσειρά ISO 8601· η μορφή κανενός από τα δύο πεδίων δεν αλλάζει. Σε πακέτο που ακυρώθηκε για το τέλος της περιόδου, τα subscription_exhausted_topup, subscription_cap_reached και subscription_runway φέρουν επιπλέον cancelAtPeriodEnd: true: δεν θα γίνει ανανέωση, το renewsAt είναι το τέλος του πακέτου και νέο μηνιαίο υπόλοιπο δεν θα πιστωθεί (με όριο μπορείτε τότε να συνεχίσετε μόνο με φόρτιση)· χωρίς ακύρωση το πεδίο δεν υπάρχει στην ειδοποίηση. Σε λογαριασμό με μηνιαίο πακέτο η απάντηση φέρει επιπλέον subscription (κατάσταση του πακέτου, αλλιώς null) και topupBalanceHal (μόνο το φορτισμένο υπόλοιπο)· το balanceHal παραμένει άθροισμα μηνιαίου και φορτισμένου υπολοίπου, βλ. κεφάλαιο Μηνιαίο πακέτο.

Ιστορικό κινήσεων

GET /v1/credit/ledger?limit - πρώτες οι πιο πρόσφατες κινήσεις, ΧΩΡΙΣ δρομέα (μόνο limit, 1-200, προεπιλογή 50) - παλαιότερες κινήσεις από τις 200 πιο πρόσφατες δεν φτάνετε μέσω API, το πλήρες ιστορικό το έχει η πύλη στο /kredit και τα φορολογικά παραστατικά. Κάθε εγγραφή φέρει type (bonus, topup, call_out, call_in, sms, number_fee, agent, refund, admin, setup_revision - γύρος διορθώσεων παραγγελίας Με το κλειδί στο χέρι πέρα από το πακέτο, subscription_grant - πίστωση μηνιαίου υπολοίπου από το πακέτο και subscription_expire - λήξη του αχρησιμοποίητου υπολοίπου του), amountHal (θετικό = πίστωση, αρνητικό = χρέωση), grossHal (ποσό με ΦΠΑ σε φόρτιση με κάρτα, αλλιώς null) και αγγλικό description συντεθειμένο από τον τύπο - στο number_fee επιπλέον με τον αριθμό στον οποίο αναφέρεται η χρέωση. Σε δαπάνες που καλύφθηκαν από μηνιαίο υπόλοιπο υπάρχει επιπλέον το πεδίο fromSubscriptionHal - το μέρος της δαπάνης που κάλυψε το μηνιαίο υπόλοιπο· στις άλλες κινήσεις λείπει. Το πρόσθετο «αριθμός κινητού» εμφανίζεται στο ιστορικό ως number_fee (πρώτη περίοδος κατά την αγορά και κάθε ανανέωση μετά από 30 ημέρες) και sms (αποστολή από τον κινητό αριθμό, η χρέωση ανά τμήμα βρίσκεται στον τιμοκατάλογο)· όταν ο πάροχος απορρίψει εκ των υστέρων SMS από τον κινητό αριθμό, το υπόλοιπο επιστρέφεται με εγγραφή refund.

Φόρτιση με κάρτα

Το POST /v1/credit/topup {amountCzk} επιστρέφει {checkoutUrl} - σύνδεσμο Stripe Checkout, τον οποίο ανοίγει ΕΝΑΣ ΑΝΘΡΩΠΟΣ στο πρόγραμμα περιήγησης. Τίποτα δεν χρεώνεται μέχρι να ολοκληρώσει ο ίδιος την πληρωμή. Η διεύθυνση τιμολόγησης (PUT /v1/account/billing) πρέπει να είναι πλήρης ΠΡΙΝ την κλήση - χωρίς αυτήν δεν μπορεί να εκδοθεί έγκυρο φορολογικό παραστατικό (billing_address_required). Υποστηρίζει Idempotency-Key - είναι ασφαλές να επαναληφθεί μετά από timeout χωρίς να δημιουργηθούν δύο πληρωμές.

Αυτόματη φόρτιση

Μέσω API η αυτόματη φόρτιση μπορεί μόνο να ΔΙΑΒΑΣΤΕΙ, να ΑΠΕΝΕΡΓΟΠΟΙΗΘΕΙ και να αλλάξει το ΟΡΙΟ ενεργοποίησης - η ενεργοποίηση και η αλλαγή του ΠΟΣΟΥ γίνονται αποκλειστικά μέσω Stripe Checkout, ποτέ με άμεση εγγραφή.

Ανάγνωση και απενεργοποίηση

Το GET /v1/credit/auto-topup επιστρέφει {enabled, thresholdHal, amountHal, card: {brand, last4} | null, spentThisMonthHal, monthlyCapHal, disabledReason} - ΧΩΡΙΣ αριθμό κάρτας, μόνο μάρκα και τα τελευταία τέσσερα ψηφία. Το PATCH {enabled: false} απενεργοποιεί άμεσα, το PATCH {thresholdHal} αλλάζει μόνο το όριο (πρέπει να ανήκει στην προσφερόμενη σειρά και να είναι χαμηλότερο από το αποθηκευμένο ποσό, αλλιώς μετά τη φόρτιση το υπόλοιπο θα έπεφτε αμέσως ξανά κάτω από το όριο).

Ενεργοποίηση και αλλαγή ποσού

Το POST /v1/credit/auto-topup/setup {thresholdHal, amountHal} επιστρέφει {checkoutUrl} - μετά την ολοκλήρωση του Checkout χρεώνεται ΑΜΕΣΩΣ το amountHal ως πρώτη φόρτιση και μόνο τότε αποθηκεύεται η κάρτα για μελλοντικές αυτόματες φορτίσεις. Λειτουργεί και με κάρτα που έχει ήδη αποθηκευτεί παλαιότερα - είναι ο μοναδικός τρόπος να ενεργοποιήσετε την αυτόματη φόρτιση ή να αλλάξετε το ποσό της. Μετά την ολοκλήρωση του Checkout το πρόγραμμα περιήγησης επιστρέφει στην ΤΣΕΧΙΚΗ σελίδα της πύλης (/kredit?automat=zapnuto) ακόμη και σε πελάτη που μιλά αγγλικά - γνωστό κενό, όχι σφάλμα της δικής σας ενσωμάτωσης.

Κάρτα

Το POST /v1/credit/auto-topup/card επιστρέφει σύνδεσμο Checkout (λειτουργία αλλαγής κάρτας, τίποτα δεν χρεώνεται) για την αλλαγή της αποθηκευμένης κάρτας. Το DELETE /v1/credit/auto-topup/card αποσυνδέει την κάρτα ΑΜΕΣΩΣ - διαγράφεται ολόκληρη η ρύθμιση (όριο και ποσό), όχι μόνο η κάρτα· η επόμενη ενεργοποίηση γίνεται μόνο ξανά μέσω .../setup, που χρεώνει αμέσως την πρώτη φόρτιση. Μετά την ολοκλήρωση του Checkout το πρόγραμμα περιήγησης επιστρέφει στην ΤΣΕΧΙΚΗ σελίδα της πύλης (/kredit?karta=zmenena) ανεξάρτητα από τη γλώσσα του λογαριασμού - το ίδιο γνωστό κενό όπως παραπάνω.

Όρια

Δύο ΑΝΕΞΑΡΤΗΤΑ όρια: το πολύ 10 000 CZK πιστωμένου υπολοίπου ανά ημερολογιακό μήνα και το πολύ 4 φορτίσεις ανά ΗΜΕΡΟΛΟΓΙΑΚΗ ΗΜΕΡΑ - όσες φορές κι αν πέσει το όριο ενεργοποίησης. Η υπέρβαση οποιουδήποτε απενεργοποιεί αυτόματα την αυτόματη φόρτιση (disabledReason monthly_cap, αντίστοιχα daily_cap)· τα spentThisMonthHal/monthlyCapHal στην απάντηση δείχνουν πόσο από το μηνιαίο όριο απομένει.

MCP: get_auto_topup (ανάγνωση) και disable_auto_topup (απενεργοποίηση) - ενεργοποίηση, αλλαγή ποσού και κάρτα δεν υπάρχουν στο MCP, για τον ίδιο λόγο όπως το enabled: true στο REST παραπάνω.

Μηνιαίο όριο δαπανών

Προαιρετική δικλίδα ασφαλείας απέναντι σε απροσδόκητα υψηλό λογαριασμό: ορίζετε μόνοι σας πόσο μπορούν να κοστίσουν οι κλήσεις, τα SMS και ο φωνητικός πράκτορας μέσα σε έναν ημερολογιακό μήνα (με ώρα Πράγας). Η λειτουργία είναι ενεργή μόνο σε λογαριασμό που έχει ορίσει όριο· χωρίς αυτό δεν αλλάζει τίποτα και η δαπάνη του μήνα απλώς μετριέται.

Το GET /v1/account/spend-cap επιστρέφει {spendCap: {enabled, capHal, warnShare, inboundAboveCap, month, monthSpendHal, remainingHal, reached, updatedAt}}. Χωρίς όριο το enabled είναι false και τα πεδία του ορίου είναι null, ενώ το monthSpendHal το λαμβάνετε πάντα. Τα ποσά είναι σε ακέραια εκατοστά της κορώνας (haléře) χωρίς ΦΠΑ.

Το PUT /v1/account/spend-cap {capHal, warnShare?, inboundAboveCap?} ορίζει ή αλλάζει το όριο: το capHal είναι σε ακέραια εκατοστά της κορώνας από 5 000 (50 CZK) έως 100 000 000 (1 000 000 CZK), το warnShare είναι το ποσοστό του ορίου από 0,5 έως 0,99 (προεπιλογή 0,8) στο οποίο στέλνεται email προειδοποίησης, και το inboundAboveCap: true αφήνει τους πράκτορες να συνεχίζουν να δέχονται εισερχόμενες κλήσεις και πάνω από το όριο (προεπιλογή false, σε αλλαγή χωρίς το πεδίο ισχύει η αποθηκευμένη τιμή). Το DELETE /v1/account/spend-cap καταργεί το όριο· η κατάργηση ανύπαρκτου ορίου είναι εντάξει.

Μετά την επίτευξη του ορίου, οι νέες εξερχόμενες κλήσεις, οι κλήσεις-κουδούνισμα, οι δοκιμαστικές κλήσεις και τα SMS απορρίπτονται με κωδικό spend_cap_reached (HTTP 402), τίποτα δεν χρεώνεται και η επανάληψη δεν βοηθά μέχρι να τελειώσει ο μήνας ή να αυξήσετε ή να καταργήσετε το όριο. Η εισερχόμενη κλήση του πράκτορα τελειώνει μετά από μία πρόταση και δεν κοστίζει τίποτα, εκτός αν είναι inboundAboveCap: true. Το email φτάνει όταν επιτευχθεί το warnShare και όταν επιτευχθεί το όριο, το πολύ μία φορά τον μήνα.

Τι το όριο ΔΕΝ σταματά: κλήσεις που τρέχουν αυτή τη στιγμή (η τιμή χρεώνεται μετά την κλήση, γι' αυτό ο μήνας μπορεί να τελειώσει πάνω από το όριο κατά την τιμή τους, όπως και με κλήσεις που λογίστηκαν μετά τα μεσάνυχτα), προώθηση κλήσεων χωρίς πράκτορα και χρεώσεις αριθμών, γύρο διορθώσεων Με το κλειδί στο χέρι και μηνιαίο πακέτο, που δεν προσμετρώνται στο όριο. Σε λογαριασμό με πακέτο στη δαπάνη προσμετράται και ό,τι κάλυψε το μηνιαίο υπόλοιπο. Ένας αριθμός στο Δικό σας τηλεφωνικό κέντρο SIP με inboundAboveCap: true παραμένει στο SIP proxy, οπότε το όριο δεν σταματά τις εξερχόμενες κλήσεις από το τηλεφωνικό κέντρο.

MCP: τα get_spend_cap, set_spend_cap και clear_spend_cap καλούν την ίδια υπηρεσία με το REST και την πύλη (ενότητα Μηνιαίο όριο δαπανών στο Υπόλοιπο). Το set_spend_cap πρέπει να επαναλάβει το ποσό στον πελάτη πριν και μετά την εγγραφή.

Μηνιαίο πακέτο

Προαιρετική συνδρομή: κάθε μήνα χρεώνεται από την αποθηκευμένη κάρτα η τιμή του επιλεγμένου επιπέδου και πιστώνεται μηνιαίο υπόλοιπο σε CZK, που δαπανάται με τον κανονικό τιμοκατάλογο. Οι χρεώσεις και η χρέωση ανά δευτερόλεπτο δεν αλλάζουν, το πακέτο είναι ένα επίπεδο πάνω από αυτές. Τα επίπεδα είναι τρία και το tier είναι η τιμή τους σε CZK χωρίς ΦΠΑ: "490", "990" και "1990"· τις τιμές και το υπόλοιπο κάθε επιπέδου τις επιστρέφει το GET /v1/subscription στο πεδίο tiers.

Δύο είδη υπολοίπου

Το μηνιαίο υπόλοιπο προέρχεται από το πακέτο, λήγει στο τέλος της περιόδου και δεν επιστρέφεται. Το φορτισμένο υπόλοιπο (φόρτιση, μπόνους καλωσορίσματος, διορθώσεις) δεν λήγει και επιστρέφεται όπως μέχρι τώρα. Το υπόλοιπο του λογαριασμού - το balanceHal στο GET /v1/balance, στην πύλη και σε όλες τις πύλες ελέγχου (ελάχιστο για κλήση, όριο οφειλής, προειδοποιήσεις) - είναι το άθροισμα των δύο ειδών. Μόνο το φορτισμένο υπόλοιπο βρίσκεται στο topupBalanceHal, το υπόλοιπο μηνιαίο υπόλοιπο στο subscription.monthlyRemainingHal. Οφειλή μπορεί να δημιουργηθεί μόνο στο φορτισμένο υπόλοιπο.

Σειρά δαπάνης

Κάθε δαπάνη πηγαίνει πρώτα από το μηνιαίο υπόλοιπο και το υπόλοιπο από το φορτισμένο - κλήσεις ανά δευτερόλεπτο, πράκτορας, χρεώσεις αριθμών και κινητών αριθμών, SMS, κλήσεις-κουδούνισμα και εξερχόμενες εργασίες. Η κατανομή είναι ατομική και καταγράφεται στο ledger: δαπάνη που καλύφθηκε από μηνιαίο υπόλοιπο φέρει fromSubscriptionHal (το μέρος που κάλυψε το μηνιαίο υπόλοιπο). Οι διορθώσεις του ιδιοκτήτη (admin, και οι αρνητικές) και η επιστροφή για SMS που δεν στάλθηκε (refund) αφορούν μόνο το φορτισμένο υπόλοιπο.

Περίοδος και πίστωση

Η περίοδος διαρκεί έναν μήνα από την επιτυχή χρέωση (η 31. 1. δίνει 28. 2.). Το μηνιαίο υπόλοιπο πιστώνεται μόνο μετά από επιβεβαιωμένη πληρωμή με εγγραφή subscription_grant και η πίστωση είναι idempotent με βάση το id της πληρωμής. Αν ο λογαριασμός έχει εκείνη τη στιγμή οφειλή στο φορτισμένο υπόλοιπο, αυτή εξοφλείται πρώτα από το νέο μηνιαίο υπόλοιπο, ώστε το φορτισμένο υπόλοιπο να μη μείνει αρνητικό.

Λήξη

Το αχρησιμοποίητο υπόλοιπο του μηνιαίου υπολοίπου λήγει την ημέρα της ανανέωσης (εγγραφή subscription_expire με αρνητικό ποσό), στη λήξη της συνδρομής ή από αυτόματη δικλίδα όταν η περίοδος έληξε πριν από περισσότερες από 36 ώρες χωρίς ανανέωση. Αν η χρέωση αποτύχει, το υπόλοιπο έχει ήδη λήξει και νέο υπόλοιπο δεν πιστώνεται· μέχρι την πληρωμή ο λογαριασμός τρέχει μόνο με φορτισμένο υπόλοιπο.

Επιλογή μετά την εξάντληση

Κατά την ενεργοποίηση επιλέγεται υποχρεωτικά το exhaustionMode, χωρίς προεπιλογή. topup: μετά την εξάντληση του μηνιαίου υπολοίπου αγοράζεται συμπληρωματικά φορτισμένο υπόλοιπο από την αποθηκευμένη κάρτα - είναι η σημερινή αυτόματη φόρτιση με τα ίδια όρια και email. cap (όριο): τίποτα δεν αγοράζεται συμπληρωματικά, οι εξερχόμενες κλήσεις, τα SMS και οι αγορές αριθμών απορρίπτονται με σφάλμα subscription_cap_reached (HTTP 402) και με υπόλοιπο κάτω από το μηδέν σταματούν και οι εισερχόμενες κλήσεις, η προώθηση κλήσεων και η πρόσβαση SIP (διακοπή στο μηδέν, αίρεται μετά τη φόρτιση ή με νέο μηνιαίο υπόλοιπο). Με όριο δεν μπορεί να ενεργοποιηθεί η αυτόματη φόρτιση (subscription_cap_active)· η εναλλαγή σε όριο την απενεργοποιεί. Το πολύ που θα πληρώσετε τον μήνα με όριο είναι η τιμή του πακέτου.

Αλλαγή επιπέδου, ακύρωση, επανενεργοποίηση

Η αλλαγή επιπέδου (προς τα πάνω και προς τα κάτω) ισχύει από την επόμενη περίοδο, χωρίς αναπροσαρμογή. Η ακύρωση είναι cancelAtPeriodEnd: true: το υπόλοιπο ισχύει μέχρι το τέλος της περιόδου, έπειτα λήγει και η κατάσταση γίνεται canceled· μέχρι το τέλος της περιόδου η ακύρωση μπορεί να αναιρεθεί. Μέσω REST ή MCP δεν μπορείτε να αυξήσετε επίπεδο, να επανενεργοποιήσετε ακυρωμένο πακέτο ούτε να εναλλάξετε σε συμπληρωματική φόρτιση από κάρτα - αυτά τα βήματα αυξάνουν ή ξαναενεργοποιούν επαναλαμβανόμενες χρεώσεις, γι' αυτό επιστρέφουν subscription_confirmation_required με confirmUrl, που ο άνθρωπος ανοίγει και επιβεβαιώνει στην πύλη (ισχύει 24 ώρες).

Συμβουλή πριν από την ανανέωση

Τρεις ημέρες πριν από την ανανέωση (το αργότερο μία ημέρα πριν) φτάνει email, αλλά μόνο όταν με τη μέχρι τώρα δαπάνη σας θα ήταν φθηνότερο να πληρώνετε ανά δευτερόλεπτο ή με χαμηλότερο επίπεδο. Ισχύει ο ίδιος κανόνας όπως στη συμβουλή του email ανανέωσης και στην πύλη: η άλλη επιλογή πρέπει να βγαίνει φθηνότερη τουλάχιστον κατά 50 CZK και 5 %. Η εκτίμηση για ολόκληρη την περίοδο παίρνει τον υψηλότερο από τους ρυθμούς από την αρχή της περιόδου και των τελευταίων 7 ημερών και δεν είναι ποτέ χαμηλότερη από τη δαπάνη των τελευταίων 30 ημερών, βάσει της οποίας συμβουλεύει η πύλη· οι γραμμές Επίπεδο και Ακύρωση γι' αυτό δεν θα πουν μετά το κλικ ότι το επίπεδο ταιριάζει. Το email αναφέρει την ακριβή ημερομηνία και ώρα ανανέωσης και φτάνει το πολύ μία φορά ανά περίοδο, ποτέ σε πακέτο ακυρωμένο για το τέλος της περιόδου, με προγραμματισμένη αλλαγή επιπέδου, χωρίς αποθηκευμένη κάρτα ή σε αναμονή πληρωμής. Το κουμπί σε αυτό ανοίγει στην πύλη απευθείας τη γραμμή Ακύρωση (/kredit?pausal=zrusit) ή Επίπεδο (/kredit?pausal=stupen). Το email ανανέωσης συμβουλεύει έπειτα ξανά από την πραγματική δαπάνη ολόκληρης της περιόδου, οπότε η συμβουλή μπορεί να βγει και διαφορετική.

Ανανέωση που δεν πληρώθηκε

Η χρέωση από την αποθηκευμένη κάρτα επιχειρείται την ημέρα ανανέωσης, μετά από 2 και μετά από 4 ημέρες. Μετά την πρώτη αποτυχία η κατάσταση είναι past_due, φτάνει email με σύνδεσμο για χειροκίνητη πληρωμή και για αλλαγή κάρτας και το μηνιαίο υπόλοιπο είναι 0· τη χειροκίνητη πληρωμή την επιστρέφει το POST /v1/subscription/pay. Μετά την τρίτη αποτυχία το πακέτο τελειώνει (canceled), το φορτισμένο υπόλοιπο και ο λογαριασμός συνεχίζουν να λειτουργούν.

ΦΠΑ και παραστατικά

Οι τιμές είναι χωρίς ΦΠΑ. Το καθεστώς ΦΠΑ διαβάζεται πριν από κάθε χρέωση, οπότε υποκείμενος σε φόρο από άλλο κράτος της ΕΕ με επαληθευμένο ΑΦΜ πληρώνει χωρίς τσεχικό ΦΠΑ (reverse charge) και το παραστατικό το αντικατοπτρίζει. Φορολογικό παραστατικό για κάθε πληρωμένη περίοδο εκδίδει το ίδιο το volai (φορολογητέα βάση είναι η τιμή του επιπέδου, όχι το πιστωμένο υπόλοιπο) και θα το βρείτε στο GET /v1/billing/documents.

Σχέση με το μπόνους και την πρώτη φόρτιση

Η ενεργοποίηση του πακέτου προσμετράται ως πρώτη πληρωμή: ξεκλειδώνει SMS από τον κοινόχρηστο αποστολέα, προώθηση κλήσεων, δεύτερο αριθμό, «αριθμός κινητού» και κάρτα αυτόματης φόρτισης όπως η φόρτιση. Το μπόνους καλωσορίσματος παραμένει φορτισμένο υπόλοιπο.

Επιστρεψιμότητα

Το μηνιαίο υπόλοιπο δεν επιστρέφεται και λήγει· το φορτισμένο υπόλοιπο επιστρέφεται όπως μέχρι τώρα. Η ακύρωση του πακέτου δεν δημιουργεί δικαίωμα αναλογικής επιστροφής για την πληρωμένη περίοδο. Την επιστροφή πληρωμής για πακέτο (παράπονο, λάθος) τη χειρίζεται χειροκίνητα ο ιδιοκτήτης του volai, δεν γίνεται μέσω API ή MCP.

Πακέτο στο REST και στο MCP

Τα χρήματα κινούνται μόνο με άνθρωπο μπροστά στην κάρτα. Η ενεργοποίηση του πακέτου και η χειροκίνητη πληρωμή επιστρέφουν μόνο σύνδεσμο Stripe Checkout και δεν χρεώνουν ποτέ απευθείας κάρτα· η αύξηση επιπέδου, η επανενεργοποίηση πακέτου που έχει οριστεί να λήξει και η εναλλαγή σε συμπληρωματική φόρτιση από κάρτα απαιτούν επιβεβαίωση από συνδεδεμένο άνθρωπο στην πύλη.

• GET /v1/subscription - κατάσταση του πακέτου (subscription ή null), κατάλογος επιπέδων tiers (id, priceHal, creditHal), topupBalanceHal, available (μπορεί να ενεργοποιηθεί νέο πακέτο: η προσφορά είναι ενεργή και κανένα πακέτο δεν τρέχει), recommendation (η φθηνότερη επιλογή για τη δαπάνη των τελευταίων 30 ημερών και steady, αν η δαπάνη είναι σταθερή και όχι μεμονωμένη κορύφωση· null χωρίς προσφορά ή χωρίς 30 ημέρες ιστορικού) και previousPeriod (η προηγούμενη περίοδος με τους ίδιους αριθμούς όπως στο email ανανέωσης: usedHal από creditHal, usedPercent, δαπάνη πάνω από το μηνιαίο υπόλοιπο overHal και υπόλοιπο που έληξε expiredHal· μόνο σε ενεργό πακέτο, null στην πρώτη περίοδο και όταν η δαπάνη δεν τεκμηριώνεται από το ιστορικό).
• POST /v1/subscription/checkout {tier, exhaustionMode, consumerConsent?} - επιστρέφει {checkoutUrl} προς το Stripe Checkout, μετά την ολοκλήρωση του οποίου το πακέτο ξεκινά. Το exhaustionMode (topup ή cap) είναι υποχρεωτικό· καταναλωτής χωρίς IČO πρέπει να στείλει consumerConsent: true (αλλιώς consumer_consent_required). Η διεύθυνση τιμολόγησης πρέπει να είναι πλήρης (billing_address_required). Υποστηρίζει Idempotency-Key.
• PATCH /v1/subscription {tier?, cancelAtPeriodEnd?, exhaustionMode?} - η μείωση επιπέδου, η ακύρωση (cancelAtPeriodEnd: true) και η εναλλαγή σε όριο (exhaustionMode: "cap") εκτελούνται και επιστρέφουν {subscription}. Η αύξηση επιπέδου, η επανενεργοποίηση πακέτου που έχει οριστεί να λήξει (cancelAtPeriodEnd: false) και το exhaustionMode: "topup" δεν αλλάζουν τίποτα και επιστρέφουν 409 subscription_confirmation_required με confirmUrl.
• POST /v1/subscription/pay - μόνο στην κατάσταση past_due· επιστρέφει {checkoutUrl} για χειροκίνητη πληρωμή της ανανέωσης. Υποστηρίζει Idempotency-Key.
• POST /v1/subscription/card - επιστρέφει {checkoutUrl} για αλλαγή της αποθηκευμένης κάρτας του πακέτου, τίποτα δεν χρεώνεται. Υποστηρίζει Idempotency-Key.
• Το GET /v1/balance φέρει επιπλέον subscription (ίδια μορφή όπως παραπάνω, αλλιώς null) και topupBalanceHal.

MCP: get_subscription (ανάγνωση), create_subscription_link (σύνδεσμος ενεργοποίησης), update_subscription και cancel_subscription (μείωση επιπέδου, ακύρωση, όριο· η αύξηση, η επανενεργοποίηση και η συμπληρωματική φόρτιση επιστρέφουν confirmUrl με πρόταση ότι πρέπει να τα επιβεβαιώσει άνθρωπος στην πύλη) και create_subscription_payment_link (χειροκίνητη πληρωμή). Αλλαγή κάρτας στο MCP δεν υπάρχει, για τον ίδιο λόγο όπως στην αυτόματη φόρτιση: από εδώ τίποτα δεν χρεώνεται.

Φορολογικά παραστατικά

Το παραστατικό δημιουργείται αυτόματα κατά τη φόρτιση υπολοίπου με κάρτα (εφάπαξ και αυτόματη), κατά την πληρωμή της εγκατάστασης Με το κλειδί στο χέρι και ως διορθωτικό παραστατικό κατά την επιστροφή της εγκατάστασης - κανένα χειροκίνητο βήμα, καμία έκδοση μέσω API.

GET /v1/billing/documents?limit&before - πρώτα τα πιο πρόσφατα, ο δρομέας before (Unix ms, αποκλειστικός) είναι το nextBefore της προηγούμενης σελίδας. Η αποθήκευση από μόνη της δεν επιστρέφει ποτέ περισσότερες από 100 εγγραφές ανά κλήση, ακόμη κι αν το limit ζητά περισσότερες.

Το GET /v1/billing/documents/{id} επιστρέφει {id, number, issuedAt, taxableAt, netHal, vatHal, grossHal, vatRatePercent, reverseCharge, description, customer, paymentRef, pdfUrl} - reverseCharge: true σε υποκείμενους σε φόρο από άλλο κράτος της ΕΕ με επαληθευμένο ΑΦΜ (VIES), που πληρώνουν χωρίς τσεχικό ΦΠΑ. Το πεδίο kind είναι πάντα συμπληρωμένο - "invoice" σε κανονικό παραστατικό (και σε παραστατικά που εκδόθηκαν πριν από την εισαγωγή του πεδίου), "credit_note" σε διορθωτικό φορολογικό παραστατικό - αυτό δημιουργείται αυτόματα όταν ο ιδιοκτήτης επιστρέφει την τιμή της εγκατάστασης σε ακυρωμένη παραγγελία Με το κλειδί στο χέρι, αριθμείται με δική του σειρά OD... και φέρει επιπλέον correctsNumber (αριθμός του διορθούμενου παραστατικού) και correctionReason (λόγος επιστροφής)· τα ποσά netHal/vatHal/grossHal είναι ΘΕΤΙΚΑ και στην πιστωτική σημείωση, το πρόσημο μείον το δίνει μόνο το PDF.

Το GET /v1/billing/documents/{id}/pdf κατεβάζει το ίδιο παραστατικό ως application/pdf - δημιουργείται εκ νέου σε κάθε λήψη, δεν αποθηκεύεται. Ξένο ή ανύπαρκτο id αναφέρει το ίδιο σφάλμα (invoice_not_found) και στα δύο endpoints, ώστε από την απάντηση να μη φαίνεται ότι υπάρχει ξένο παραστατικό.

MCP: τα list_billing_documents και get_billing_document έχουν την ίδια μορφή με το REST. Το PDF υπάρχει μόνο στο REST - το MCP δεν έχει δυαδικό κανάλι για μεταφορά αρχείου.

Σφάλματα

• ledger_unavailable - Το ιστορικό κινήσεων και το υπόλοιπο δεν μπορούν να διαβαστούν αυτή τη στιγμή - δοκιμάστε ξανά σε λίγο.
• invalid_amount - Το ποσό φόρτισης, ορίου ενεργοποίησης ή αυτόματης πληρωμής δεν είναι μία από τις προσφερόμενες σταθερές τιμές.
• billing_address_required - Η διεύθυνση τιμολόγησης λείπει ή είναι ελλιπής - συμπληρώστε την στην πύλη (/nastaveni) πριν από τη φόρτιση, αλλιώς δεν μπορεί να εκδοθεί έγκυρο παραστατικό.
• stripe_not_configured - Οι πληρωμές είναι απενεργοποιημένες για αυτό το περιβάλλον του volai - δεν αφορά συγκεκριμένα το αίτημά σας.
• stripe_error - Το Stripe αρνήθηκε να δημιουργήσει συνεδρία πληρωμής - δοκιμάστε ξανά σε λίγο.
• autotopup_not_configured - Η αυτόματη φόρτιση δεν έχει περάσει ποτέ από το .../setup - δεν υπάρχει τίποτα να απενεργοποιηθεί, να αλλάξει ή κάρτα να αντικατασταθεί.
• invoice_not_found - Παραστατικό με αυτό το id δεν υπάρχει στον λογαριασμό (ή ανήκει σε άλλον λογαριασμό - η απάντηση είναι η ίδια).
• spend_cap_reached - Το μηνιαίο όριο δαπανών που ορίσατε έχει επιτευχθεί: οι νέες εξερχόμενες κλήσεις και τα SMS απορρίπτονται και τίποτα δεν χρεώνεται. Το όριο το αυξάνετε ή το καταργείτε μέσω PUT ή DELETE /v1/account/spend-cap, αλλιώς ισχύει μέχρι το τέλος του μήνα (μέχρι τα μεσάνυχτα στην Πράγα).
• subscription_cap_reached - Όριο πακέτου: το μηνιαίο και το φορτισμένο υπόλοιπο έχουν εξαντληθεί και ο λογαριασμός έχει επιλεγμένο όριο. Οι εξερχόμενες κλήσεις, τα SMS και οι αγορές αριθμών απορρίπτονται (HTTP 402) μέχρι την επόμενη ανανέωση ή τη χειροκίνητη φόρτιση.
• subscription_exists - Ο λογαριασμός έχει ήδη πακέτο· η αλλαγή επιπέδου, η ακύρωση και η επιλογή μετά την εξάντληση γίνονται μέσω PATCH /v1/subscription.
• subscription_missing - Ο λογαριασμός δεν έχει ενεργό πακέτο που θα μπορούσε να αλλάξει, να ακυρωθεί ή να πληρωθεί χειροκίνητα.
• subscription_canceled - Το πακέτο έχει ήδη τελειώσει (κατάσταση canceled): δεν μπορεί να αλλάξει, να ακυρωθεί ή να πληρωθεί χειροκίνητα. Νέο ενεργοποιείτε μέσω POST /v1/subscription/checkout.
• subscription_confirmation_required - Την αύξηση επιπέδου, την επανενεργοποίηση πακέτου που έχει οριστεί να λήξει και τη συμπληρωματική φόρτιση από κάρτα τα επιβεβαιώνει μόνο άνθρωπος στην πύλη - η απάντηση φέρει confirmUrl και τίποτα δεν άλλαξε.
• consumer_consent_required - Ο καταναλωτής χωρίς IČO πρέπει κατά την ενεργοποίηση να επιβεβαιώσει ρητό αίτημα έναρξης παροχής πριν από τη λήξη της προθεσμίας υπαναχώρησης (consumerConsent: true).
• pausal_unavailable - Η προσφορά πακέτου είναι αυτή τη στιγμή απενεργοποιημένη για αυτόν τον λογαριασμό.
• invalid_tier - Το επίπεδο που έχει ήδη το πακέτο όταν δεν έχει προγραμματιστεί κανένα άλλο (επίπεδο στο οποίο ήδη μεταβαίνει δεν είναι σφάλμα και θεωρείται εκτελεσμένο, οπότε το ίδιο PATCH /v1/subscription μπορεί να σταλεί ξανά μετά από διακοπή· εξαίρεση είναι η επιστροφή στο σημερινό επίπεδο, που ακυρώνει την προγραμματισμένη αλλαγή: στην επανάληψη δεν υπάρχει πια τίποτα να ακυρωθεί)· άγνωστη τιμή εκτός των "490", "990", "1990" καταλήγει σε validation.
• subscription_cap_active - Με όριο δεν μπορεί να ενεργοποιηθεί η αυτόματη φόρτιση· πρώτα αλλάξτε στην πύλη την επιλογή μετά την εξάντληση σε topup.
• validation - Συγκεκριμένα στο PATCH /v1/credit/auto-topup: απόπειρα ενεργοποίησης (enabled: true) ή άμεσης αλλαγής του amountHal - χρησιμοποιήστε αντί γι' αυτό το POST .../setup.

Τον πλήρη πίνακα σφαλμάτων για κάθε endpoint θα τον βρείτε στην ενότητα Υπόλοιπο στην αναφορά REST API.