SMS API για προγραμματιστές

Ενημερώθηκε: 27 Οκτωβρίου 2026

Συνδέστε το e-shop, το CRM ή το σύστημα κρατήσεών σας με ένα απλό JSON API πάνω από HTTPS. Στέλνετε SMS με μία κλήση και μαθαίνετε αν παραδόθηκαν χωρίς να στήσετε webhook, χωρίς δημόσιο URL και χωρίς στατική IP.

Δημιουργία λογαριασμού · Πλήρης τεκμηρίωση στα αγγλικά

Ξεκινήστε σε τρία βήματα

1. Φτιάξτε λογαριασμό και μπείτε στη σελίδα API του panel. Δημιουργήστε ένα κλειδί. Εμφανίζεται μία μόνο φορά, γι' αυτό αποθηκεύστε το αμέσως.
2. Στείλτε ένα SMS με την κλήση που ακολουθεί.
3. Διαβάστε τις αναφορές παράδοσης από το /v1/reports.

curl -X POST https://api.isms.gr/v1/messages \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sender": "MyShop", "to": ["306900000000"], "text": "Your order is on its way", "client_ref": "order-1042"}'

Ταυτοποίηση και δικαιώματα

Κάθε αίτημα στέλνει το κλειδί στο header Authorization: Bearer <key>. Όλα τα αιτήματα γίνονται με HTTPS.

Κάθε κλειδί έχει μόνο τα δικαιώματα που του δώσατε:

Έτσι δίνετε σε κάθε σύστημα μόνο ό,τι χρειάζεται, π.χ. σε ένα εργαλείο αναφορών μόνο read. Μπορείτε προαιρετικά να περιορίσετε ένα κλειδί σε συγκεκριμένες IP, αλλά δεν είναι απαραίτητο. Ένα κλειδί ανακαλείται αμέσως από το panel και από εκείνη τη στιγμή απαντά 401. Έχετε έως 10 ενεργά κλειδιά.

Αποστολή: POST /v1/messages

Αν ένας αριθμός είναι άκυρος ή χωρίς κωδικό χώρας, απορρίπτεται όλη η αίτηση και δεν στέλνεται ούτε χρεώνεται τίποτα. Η χρέωση γίνεται όταν το μήνυμα γίνει δεκτό, από το υπόλοιπο του λογαριασμού σας.

Παράδειγμα απάντησης:

{
  "id": "KN-7K3M9-Q2XPD",
  "client_ref": "order-1042",
  "status": "queued",
  "created_at": "2026-10-12T08:20:30Z",
  "scheduled_at": null,
  "cost": "0.03572",
  "recipients": 1,
  "counts": {"queued": 1, "sent": 0, "delivered": 0, "failed": 0, "unknown": 0, "blocked": 0},
  "duplicate": false
}

Τα χρήματα επιστρέφονται πάντα ως κείμενο (string), σε ευρώ, και οι ώρες σε UTC.

Ασφαλείς επαναλήψεις με client_ref

Αν ένα αίτημα λήξει χωρίς απάντηση και δεν ξέρετε αν έφτασε, στείλτε το ξανά με το ίδιο client_ref. Δεν φεύγει δεύτερο SMS και δεν χρεώνεστε ξανά: παίρνετε πίσω το αρχικό μήνυμα με "duplicate": true. Το client_ref θυμόμαστε για πάντα.

Αναφορές παράδοσης χωρίς webhook

Εσείς ρωτάτε και εμείς σας δίνουμε μόνο ό,τι δεν έχετε ήδη πάρει. Γι' αυτό δεν χρειάζεστε δημόσιο URL ούτε στατική IP.

curl "https://api.isms.gr/v1/reports?limit=500" \
  -H "Authorization: Bearer YOUR_KEY"

{
  "reports": [
    {"message_id": "KN-7K3M9-Q2XPD", "client_ref": "order-1042", "mobile": "306900000000",
     "status": "delivered", "reason": null, "at": "2026-10-12T08:20:36Z"}
  ],
  "count": 1,
  "ack": "tVEgYU10LopOB6biUNbftQ",
  "next_poll_after": 5
}

Πώς δουλεύει ο κύκλος:

1. Η κλήση επιστρέφει ένα πακέτο αναφορών και ένα ack.
2. Αφού αποθηκεύσετε το πακέτο, καλείτε ξανά με ?ack=<το ack>. Αυτό το επιβεβαιώνει και φέρνει το επόμενο.
3. Αν το σύστημά σας έπεσε πριν αποθηκεύσει, δεν στέλνετε ack και παίρνετε το ίδιο πακέτο ξανά. Τίποτα δεν χάνεται.
4. Όταν δεν υπάρχει τίποτα νέο, η λίστα είναι άδεια και το next_poll_after λέει σε πόσα δευτερόλεπτα να ξαναρωτήσετε.

Κάθε SMS δίνει μία αναφορά με την τελική του κατάσταση, όχι τρεις ενδιάμεσες. Χρειάζεται δικαίωμα read.

Καταστάσεις παραληπτών

Για κάθε μήνυμα ξεχωριστά, μπορείτε να ρωτήσετε GET /v1/messages/{id} ή GET /v1/messages?client_ref=....

Λίστα αποκλεισμού από το σύστημά σας

Οι αριθμοί της λίστας αποκλεισμού δεν λαμβάνουν μηνύματα και δεν χρεώνονται. Όταν ένας πελάτης σας απαντήσει STOP, μπορείτε να τον προσθέσετε αυτόματα (δικαίωμα blacklist):

curl -X POST https://api.isms.gr/v1/blacklist \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": ["306900000000", "306900000001"]}'

Υπάρχουν επίσης GET /v1/blacklist (λίστα ή έλεγχος ενός αριθμού) και DELETE /v1/blacklist/{mobile}.

Υπόλοιπο

curl https://api.isms.gr/v1/credits -H "Authorization: Bearer YOUR_KEY"

{"credits": "12.34000", "currency": "EUR"}

Όρια

• 120 αιτήματα ανά λεπτό ανά κλειδί.
• Αναφορές: τουλάχιστον 5 δευτερόλεπτα ανάμεσα σε δύο κλήσεις.
• Έως 1.000 αριθμοί ανά αποστολή και έως 1 MB ανά αίτημα.
• Αν ξεπεράσετε τα όρια παίρνετε 429 με Retry-After. Ένα κλειδί που τα ξεπερνά συνεχώς σταματά για 15 λεπτά. Αν ακολουθείτε το Retry-After και το next_poll_after, δεν θα το δείτε ποτέ.

Σφάλματα

Κάθε σφάλμα είναι JSON, με σταθερό κωδικό που δεν αλλάζει:

{"error": "insufficient_balance", "message": "..."}

Η πλήρης τεκμηρίωση, με όλα τα πεδία και τις λεπτομέρειες, είναι δημόσια στα αγγλικά: my.isms.gr/docs/api. Για απορίες, επικοινωνήστε μαζί μας.