Πώς παίρνω API key και στέλνω το πρώτο SMS με curl και PHP

Το API του iSend στέλνει SMS από οποιοδήποτε δικό σας σύστημα με μία κλήση HTTP. Η πιστοποίηση γίνεται με API Token που δημιουργείτε στο μενού Developers της πλατφόρμας και στέλνετε ως Bearer token στην επικεφαλίδα Authorization. Η αποστολή είναι ένα POST στη διεύθυνση https://sms.isend.gr/api/http/sms/send με σώμα JSON που περιέχει τον παραλήπτη, τον αποστολέα και το μήνυμα. Η απάντηση επιστρέφει το αναγνωριστικό του μηνύματος, με το οποίο ελέγχετε αργότερα την κατάσταση παράδοσης.

Πώς παίρνετε το API Token

1. Συνδεθείτε στην πλατφόρμα και ανοίξτε το μενού Developers.
2. Στην κάρτα API Token πατήστε το κουμπί εμφάνισης και μετά Αντιγραφή. Αποθηκεύστε το στις ρυθμίσεις του συστήματός σας, όχι σε αρχείο που βλέπουν άλλοι.
3. Αν το χάσετε ή υποψιάζεστε ότι διέρρευσε, πατήστε Αναδημιουργία token. Το νέο εμφανίζεται μία φορά, αντιγράψτε το αμέσως. Το παλιό παύει να ισχύει.

Το token δίνει πρόσβαση σε όλο τον λογαριασμό σας: αποστολές, επαφές, υπόλοιπο. Δεν το βάζετε ποτέ σε κώδικα που τρέχει στον browser του επισκέπτη ή σε εφαρμογή κινητού. Οι κλήσεις γίνονται από τον δικό σας server.

Η κλήση αποστολής

POST https://sms.isend.gr/api/http/sms/send
Authorization: Bearer ΤΟ_API_TOKEN_ΣΑΣ
Content-Type: application/json
Accept: application/json

Παράδειγμα με curl

curl -X POST https://sms.isend.gr/api/http/sms/send \
  -H "Authorization: Bearer ΤΟ_API_TOKEN_ΣΑΣ" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "recipient": "306912345678",
    "sender_id": "MyShop",
    "message": "Η ΠΑΡΑΓΓΕΛΙΑ 1042 ΕΦΥΓΕ ΣΗΜΕΡΑ. ΠΑΡΑΔΟΣΗ ΑΥΡΙΟ.",
    "transactional": true
  }'

Παράδειγμα σε PHP

<?php
$payload = [
    'recipient'     => '306912345678',
    'sender_id'     => 'MyShop',
    'message'       => 'Η ΠΑΡΑΓΓΕΛΙΑ 1042 ΕΦΥΓΕ ΣΗΜΕΡΑ. ΠΑΡΑΔΟΣΗ ΑΥΡΙΟ.',
    'transactional' => true,
];

$ch = curl_init('https://sms.isend.gr/api/http/sms/send');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('ISEND_API_TOKEN'),
        'Content-Type: application/json',
        'Accept: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode($payload, JSON_UNESCAPED_UNICODE),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

if (($response['status'] ?? '') === 'success') {
    $uid = $response['data']['uid'];   // κρατήστε το για έλεγχο κατάστασης
} else {
    error_log('iSend: ' . ($response['message'] ?? 'unknown error'));
}

Το token διαβάζεται από μεταβλητή περιβάλλοντος, όχι από το ίδιο το αρχείο. Σε WordPress ή Laravel το βάζετε στο αρχείο ρυθμίσεων του project.

Η απάντηση

Επιτυχής αποστολή:

{
  "status": "success",
  "data": {
    "uid": "6415907d0d7a6",
    "to": "306912345678",
    "from": "MyShop",
    "message": "Η ΠΑΡΑΓΓΕΛΙΑ 1042 ΕΦΥΓΕ ΣΗΜΕΡΑ. ΠΑΡΑΔΟΣΗ ΑΥΡΙΟ.",
    "cost": 1,
    "sms_count": 1,
    "status": "Sent"
  },
  "message": "Sent"
}

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

Σφάλμα:

{"status": "error", "message": "The recipient field is required."}

Τα συνηθισμένα σφάλματα είναι λάθος ή ληγμένο token, κενό ή λάθος πεδίο, Sender ID που δεν είναι ενεργό στον λογαριασμό, και ανεπαρκές υπόλοιπο. Το κείμενο στο message λέει ποιο από αυτά.

Έλεγχος κατάστασης και υπολοίπου

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

GET https://sms.isend.gr/api/http/sms/{uid}
Authorization: Bearer ΤΟ_API_TOKEN_ΣΑΣ

Η απάντηση περιέχει το customer_status με τις ίδιες τιμές που βλέπετε στις Αναφορές: Sent, Delivered, Undelivered, Failed, Expired, Rejected. Το άρθρο για τις καταστάσεις παράδοσης εξηγεί την καθεμία. Για μηνύματα που καταλήγουν σε αποτυχία οι μονάδες επιστρέφονται αυτόματα.

Το υπόλοιπο μονάδων του λογαριασμού:

GET https://sms.isend.gr/api/http/balance
Authorization: Bearer ΤΟ_API_TOKEN_ΣΑΣ

Χρήσιμο για να ειδοποιείται το σύστημά σας πριν τελειώσουν οι μονάδες.

Τι άλλο κάνει το API

Με το ίδιο token διαχειρίζεστε επαφές και ομάδες, για παράδειγμα προσθέτετε έναν νέο πελάτη σε ομάδα τη στιγμή που εγγράφεται στο σύστημά σας. Το άρθρο για τις ομάδες επαφών έχει την κλήση. Η πλήρης τεκμηρίωση, με όλα τα endpoints για επαφές, ομάδες, καμπάνιες, πρότυπα και αναφορές, βρίσκεται μέσα στην πλατφόρμα, στο μενού Developers, με παραδείγματα που περιέχουν ήδη τη δική σας διεύθυνση.

Πέντε κανόνες για σωστή ενσωμάτωση

• Στείλτε τα μηνύματα συναλλαγής με transactional: true και τα διαφημιστικά χωρίς. Το διαφημιστικό περιεχόμενο με την ένδειξη συναλλαγής παραβιάζει τη συγκατάθεση των διαγραμμένων παραληπτών.
• Κρατήστε το uid κάθε αποστολής στη βάση σας, ώστε να μπορείτε να ελέγξετε τι παραδόθηκε.
• Μην ξαναστέλνετε αυτόματα σε αποτυχία χωρίς να δείτε την αιτία. Ένας λάθος αριθμός αποτυγχάνει κάθε φορά.
• Το όριο είναι 30 κλήσεις αποστολής το λεπτό ανά token. Για πολλούς παραλήπτες με το ίδιο μήνυμα, βάλτε τους αριθμούς με κόμμα σε μία κλήση αντί για μία κλήση ανά αριθμό.
• Για διαφημιστικά μηνύματα, προσθέστε πρώτα τον παραλήπτη ως επαφή σε ομάδα και μετά στείλτε. Έτσι το μήνυμα παίρνει τον σύνδεσμο διαγραφής STOP και η πλατφόρμα σέβεται όσους έχουν ήδη διαγραφεί.
• Δοκιμάστε πρώτα στο δικό σας κινητό. Ο δοκιμαστικός λογαριασμός με τα 50 SMS καλύπτει μια πλήρη ενσωμάτωση.

Συχνές ερωτήσεις

Χρεώνεται η κλήση αν το μήνυμα δεν σταλεί;

Όχι. Χρεώνονται μόνο τα μηνύματα που παραδίδονται στο δίκτυο, και όσα καταλήξουν σε κατάσταση αποτυχίας επιστρέφουν τις μονάδες τους αυτόματα. Κλήση που απορρίπτεται για λάθος πεδίο ή λάθος token δεν χρεώνει τίποτα.

Μπορώ να στείλω σε πολλούς αριθμούς με μία κλήση;

Ναι. Βάλτε τους αριθμούς στο πεδίο recipient χωρισμένους με κόμμα. Η πλατφόρμα δημιουργεί καμπάνια και στέλνει σε όλους το ίδιο μήνυμα. Για διαφορετικό κείμενο ανά παραλήπτη, κάντε ξεχωριστές κλήσεις ή χρησιμοποιήστε ετικέτες προσωποποίησης για επαφές που υπάρχουν στις λίστες σας.

Σε ποια γλώσσα προγραμματισμού δουλεύει;

Σε οποιαδήποτε κάνει κλήσεις HTTPS με JSON: PHP, Python, Node.js, C#, Java, ή ακόμη και ένα εργαλείο αυτοματισμού όπως το Make ή το n8n. Το μόνο που χρειάζεται είναι η επικεφαλίδα Authorization με το token και το σώμα JSON.