Τεκμηρίωση API Veloxiom
Πλήρης τεκμηρίωση REST API για την πλατφόρμα διαχείρισης ISP Veloxiom. Διαχειριστείτε πελάτες, χρεώσεις, δίκτυο και integrations μέσω κώδικα.
Ενότητες API
🔐 Πιστοποίηση
Το Veloxiom εκθέτει δύο διαφορετικές επιφάνειες. Επιλέξτε τη σωστή για την ενσωμάτωσή σας:
- <b>REST API v1</b> — το δημόσιο, προγραμματιστικό API στο <code>/api/v1.php</code>. Αυθεντικοποίηση με scoped <b>API token</b> (Bearer). Αυτό πρέπει να χρησιμοποιούν τα integrations.
- <b>Ενέργειες Panel / Mobile</b> — τα action-based endpoints στο <code>/mikrotik/process.php</code> που χρησιμοποιεί εσωτερικά το admin panel και οι mobile εφαρμογές. Απαιτούν authenticated admin <b>session cookie</b> (ή mobile token) + CSRF — <b>δεν</b> είναι Bearer API.
API Tokens (REST API v1)
Δημιουργήστε scoped tokens στο panel από Admin → API & Webhooks. Κάθε token εμφανίζεται μία φορά (αποθηκεύεται μόνο SHA-256 hash), φέρει scopes ανά module, μπορεί να έχει λήξη και να ανακληθεί. Το token είναι tenant-scoped — βλέπει μόνο τα δεδομένα του tenant του.
Scopes Token
Κάθε token δίνει πρόσβαση ανά module σε επίπεδο none / view / write (write συνεπάγεται view). Κάθε endpoint απαιτεί συγκεκριμένο scope· ανεπαρκές scope επιστρέφει HTTP 403.
| Ενότητα scope | Δίνει πρόσβαση σε |
|---|---|
| customers | Πελάτες / συνδρομητές |
| plans | Πλάνα υπηρεσιών |
| billing | Τιμολόγια & χρέωση |
| routers | Δικτυακές συσκευές / routers |
| monitoring | Δεδομένα monitoring (διαβάζει και routers) |
| crm | Tickets & μηνύματα (write για αποστολή) |
2FA (Αυθεντικοποίηση Δύο Παραγόντων)
🔌 REST API v1 (Token)
Το δημόσιο read-first REST API. Στείλτε GET με ?resource=<name> και Bearer token. Οι απαντήσεις είναι JSON με πεδίο ok· οι λίστες επιστρέφουν επίσης count και data. Όλα τα queries χρησιμοποιούν prepared statements και δεν εκθέτουν ποτέ passwords ή router secrets.
Πόροι Ανάγνωσης (GET)
Μεταβολές (POST)
Κοινές Παράμετροι Query
| Παράμετρος | Τύπος | Περιγραφή |
|---|---|---|
| resource / r | string | Όνομα πόρου (δες λίστα) |
| limit | int | Μέγεθος σελίδας, 1–500 (default 100) |
| offset | int | Offset για σελιδοποίηση (default 0) |
| q | string | Αναζήτηση κειμένου (customers/invoices/tickets) |
Σφάλματα
| HTTP | Σώμα | Σημασία |
|---|---|---|
| 401 | {"ok":false,"error":"unauthorized"} | Λείπει/άκυρο/ανακληθέν/ληγμένο token |
| 403 | {"ok":false,"error":"insufficient_scope","need":"module:level"} | Το token δεν έχει το απαιτούμενο scope |
| 404 | {"ok":false,"error":"unknown_resource"} | Άγνωστος πόρος |
| 400 | {"ok":false,"error":"unknown_action"} | Άγνωστη POST action / λείπει param |
| 429 | {"ok":false,"error":"rate_limited"} | Υπέρβαση ορίου (120 req/min ανά token) |
Envelope, Pagination & Request IDs
| Πεδίο | Περιγραφή |
|---|---|
ok | Πάντα παρόν. true σε επιτυχία, false σε σφάλμα. |
data | Το payload (πίνακας για λίστες, object για μονό πόρο). |
count | Πλήθος γραμμών στην τρέχουσα απάντηση. |
pagination | limit, offset, total, has_more, next_offset — για λίστες. |
meta.request_id | Μοναδικό id κλήσης· επιστρέφεται και ως header X-Request-Id. |
Errors stay flat for backward compatibility ({ok:false,error:"…"}). Send envelope=2 for a structured error: {ok:false,error:{code,message,details},meta:{request_id}}. Validation failures return 422. Callers still using ?token=… receive Deprecation/Sunset headers — prefer Authorization: Bearer or X-Api-Token.
Τιμές πεδίων
invoice.status | unpaid · paid · partial · overdue · cancelled |
message.channel | sms · viber · whatsapp |
Μηχανική Τεκμηρίωση (OpenAPI)
api/v1.php?resource=openapi returns an OpenAPI 3.0.3 document for your tenant — load it into Postman, Insomnia or a client generator.
👥 Πελάτες / Συνδρομητές (action μέσω session panel/mobile)
Διαχείριση συνδρομητών ISP — δημιουργία, επεξεργασία, διαγραφή και έλεγχος κατάστασης υπηρεσίας.
Παράμετροι Πελάτη
| Παράμετρος | Τύπος | Περιγραφή |
|---|---|---|
| username | string | PPPoE/DHCP username (μοναδικό) |
| password | string | PPPoE password |
| fullname | string | Πλήρες όνομα πελάτη |
string | Email διεύθυνση | |
| phone | string | Τηλέφωνο |
| plan | string | Όνομα πλάνου υπηρεσίας |
| address | string | Διεύθυνση εγκατάστασης |
| afm | string | ΑΦΜ για χρέωση |
| static_ip | string | Static IP ανάθεση (προαιρετικό) |
| mac_address | string | MAC address για DHCP binding |
📋 Πακέτα Υπηρεσιών
Δημιουργία και διαχείριση πλάνων υπηρεσιών internet με ταχύτητες, τιμολόγηση και πολιτικές FUP.
Παράμετροι Πλάνου
| Παράμετρος | Τύπος | Περιγραφή |
|---|---|---|
| name | string | Όνομα πλάνου (π.χ. 'FTTH 100Mbps') |
| download | string | Ταχύτητα download (π.χ. '100M') |
| upload | string | Ταχύτητα upload (π.χ. '10M') |
| price | float | Μηνιαία τιμή (EUR) |
| burst_limit | string | MikroTik burst limit |
| burst_threshold | string | Burst threshold |
| burst_time | string | Διάρκεια burst |
| priority | int | Προτεραιότητα queue (1-8) |
💰 Τιμολόγηση & Παραστατικά
Αυτοματοποιημένη μηχανή χρέωσης με δημιουργία τιμολογίων, παρακολούθηση κατάστασης και batch λειτουργίες.
💳 Πληρωμές
Επεξεργασία πληρωμών μέσω πολλαπλών gateways — DIAS τραπεζικό, Revolut, Stripe, Viva Wallet, PayPal.
Υποστηριζόμενα Payment Gateways
| Πάροχος πληρωμών | Τύπος | Περιγραφή |
|---|---|---|
| DIAS | bank | Ελληνικό τραπεζικό σύστημα (κωδικοί RF) |
| Revolut | online | Online πληρωμές κάρτας μέσω Revolut Business |
| Stripe | online | Διεθνείς πληρωμές κάρτας & subscriptions |
| Viva Wallet | online | Ελληνικές/EU πληρωμές κάρτας |
| PayPal | online | PayPal πληρωμές |
📄 Ηλεκτρονική Τιμολόγηση (ΑΑΔΕ / myDATA)
Υποβολή τιμολογίων ηλεκτρονικά στο ΑΑΔΕ myDATA. Υποστηρίζει πολλαπλούς παρόχους ηλ. τιμολόγησης.
Υποστηριζόμενοι Πάροχοι Ηλ. Τιμολόγησης
| Πάροχος | Κατάσταση | Περιγραφή |
|---|---|---|
| myDATA (AADE) | active | Απευθείας υποβολή ΑΑΔΕ API |
| Elorus | active | Elorus ERP & πλατφόρμα ηλ. τιμολόγησης |
| IMPACT | coming soon | IMPACT πάροχος ηλ. τιμολόγησης |
| Primer (Cosmos) | coming soon | Primer/Cosmos ηλ. τιμολόγηση |
| Retail@Link | coming soon | Retail@Link ηλ. τιμολόγηση |
| Edpsoft | coming soon | Edpsoft ηλ. τιμολόγηση |
📡 RADIUS / PPPoE / DHCP
Ενσωμάτωση FreeRADIUS για PPPoE και DHCP authentication, CoA (Change of Authorization) και διαχείριση sessions.
Το PPPoE/DHCP authentication είναι πλήρως ενεργό. Οι παρακάτω on-demand ενέργειες session/CoA είναι στο roadmap και δεν εκτίθενται ακόμη ως HTTP actions.
🔧 Routers MikroTik
Διαχείριση MikroTik RouterOS συσκευών — προσθήκη, ρύθμιση, παρακολούθηση και εκτέλεση API εντολών.
Παράμετροι Router
| Παράμετρος | Τύπος | Περιγραφή |
|---|---|---|
| ip | string | IP διεύθυνση διαχείρισης router |
| name | string | Εμφανιζόμενο όνομα router |
| user | string | RouterOS API username |
| pass | string | RouterOS API password |
| radius_ip | string | RADIUS NAS IP (default: management IP) |
| radius_secret | string | RADIUS shared secret |
🌐 Ρυθμίσεις Δικτύου
🗺️ Τοπολογία & Χάρτες
Οπτικοποίηση τοπολογίας δικτύου με 2D/3D χάρτες. Υποστηρίζει πολλαπλά monitoring backends.
Υποστηριζόμενα Monitoring Backends
| Backend | Πρωτόκολλο | Περιγραφή |
|---|---|---|
| LibreNMS | REST API | Open-source network monitoring |
| Observium | REST API | Network monitoring platform |
| Zabbix | JSON-RPC | Enterprise monitoring solution |
| MikroTik | RouterOS API | Direct router SNMP/API polling |
📦 Απογραφή Συσκευών (IPAM)
Διαχείριση IP Addresses και inventory δικτυακών συσκευών με workflows έγκρισης.
📊 Εποπτεία SNMP
Real-time παρακολούθηση δικτύου μέσω SNMP. Συλλογή bandwidth, latency και interface metrics από routers και switches.
Το monitoring τρέχει μέσω προγραμματισμένων collectors και Grafana dashboards. Οι παρακάτω on-demand ενέργειες είναι στο roadmap και δεν εκτίθενται ακόμη ως HTTP actions.
📞 VoIP / Τηλεφωνία (MOR)
MOR/M2 τηλεφωνική ενσωμάτωση — διαχείριση SIP trunks, CDR records, tariffs, balance management και VoIP billing.
🔒 WireGuard VPN
🎫 Υποστήριξη / Αιτήματα
Σύστημα tickets υποστήριξης πελατών με ανάθεση, προτεραιότητες και παρακολούθηση κατάστασης.
🤖 Βοηθός AI
🔔 Ειδοποιήσεις
Multi-channel σύστημα ειδοποιήσεων — Telegram, Email, Push notifications.
👤 Διαχείριση Διαχειριστών
🏢 Πολλαπλοί Πάροχοι
Multi-tenant αρχιτεκτονική — κάθε tenant είναι μια απομονωμένη ISP instance με δική του βάση, domain, branding και ρυθμίσεις.
Η δημιουργία tenant είναι super-admin ενέργεια από το control panel· εκτελεί όλο το pipeline (βάση, schema, RADIUS, WireGuard/NPM, captive portal) εσωτερικά με rollback σε αποτυχία.
⚙️ Ρυθμίσεις Συστήματος
🔗 Webhooks
Λήψη real-time ειδοποιήσεων όταν συμβαίνουν events. Ρυθμίστε outbound webhooks στο panel από Admin → API & Webhooks. Το signing secret (whsec_…) εμφανίζεται μία φορά.
Διαθέσιμα Events
| Γεγονός | Περιγραφή |
|---|---|
| message.received | Ελήφθη εισερχόμενο μήνυμα (SMS/άλλο κανάλι) |
| message.sent | Στάλθηκε εξερχόμενο μήνυμα (π.χ. μέσω API send_message) |
| ping | Δοκιμαστικό event από το admin UI |
| * | Εγγραφή σε όλα τα τρέχοντα και μελλοντικά events |
Επιπλέον business events (customer.*, invoice.*, ticket.*, router.*) είναι στο roadmap και δεν εκπέμπονται ακόμη.
Παράδοση & Υπογραφή
Κάθε παράδοση είναι HTTPS POST με JSON body. Επαληθεύστε τη γνησιότητα με την HMAC-SHA256 υπογραφή πάνω στο ακατέργαστο σώμα, με το webhook secret σας.
🏗️ Διασυνδέσεις ERP
Σύνδεση Veloxiom με το ERP σύστημά σας για συγχρονισμένη χρέωση, δεδομένα πελατών και οικονομικές αναφορές.
| ERP | Κατάσταση | Τύπος Ενσωμάτωσης |
|---|---|---|
| Elorus | active | Πλήρης συγχρονισμός — τιμολόγια, πελάτες, πληρωμές |
| SoftOne | coming soon | REST API integration |
| Epsilon Net | coming soon | REST API integration |
| Entersoft | coming soon | REST API integration |
| Galaxy / Real | coming soon | REST API integration |
| QuickBooks Online | beta | OAuth2 — πελάτες, τιμολόγια, πληρωμές μέσω ουράς συγχρονισμού |
| Xero | beta | OAuth2 — πελάτες, τιμολόγια, πληρωμές μέσω ουράς συγχρονισμού |
| 1C:Enterprise | beta | OData — πελάτες, τιμολόγια, πληρωμές μέσω ουράς συγχρονισμού |
📨 Μορφή Απάντησης
Όλα τα API responses επιστρέφουν JSON. Επιτυχείς λειτουργίες περιλαμβάνουν ok: true.
⏱️ Όρια Κλήσεων
| Εύρος | Όριο | Παράθυρο |
|---|---|---|
| REST API v1 token | 120 requests | ανά λεπτό, ανά token (HTTP 429 σε υπέρβαση) |
Χρειάζεστε Βοήθεια;
Για υποστήριξη API και βοήθεια custom integrations, επικοινωνήστε μέσω της