Cheia API SMS: cum trimiți primul mesaj în 10 minute

Ce obții la final

Un cont SMS prepay activ, o cheie API și primul mesaj livrat pe un telefon din România, la tariful unic pe segment, fără abonament și fără minim lunar. Dacă nu scrii cod, sari direct la ultima secțiune: campaniile din portal fac același lucru din browser.

Ai nevoie de: o firmă cu CUI (contul se face pe firmă), un card pentru prima încărcare și, pentru partea cu API, un server sau o aplicație care poate face cereri HTTP (orice limbaj; și n8n, Make sau Zapier merg).

Pasul 1 — contul și prima încărcare

•Intră pe voxbee.ro/start și creează contul firmei (CUI, date de facturare, cam două minute).
•În portal, deschide SMS și încarcă credit cu cardul (de la 5 €). Prima încărcare activează contul SMS; factura vine automat pe e-mail.
•Expeditorul (Sender ID) e propus din numele firmei: maximum 11 litere și cifre, fără diacritice. Îl poți schimba sau poți cere alți expeditori din portal.

De ce prepay? Plătești doar ce trimiți, creditul nu expiră, iar când soldul scade sub 20 €, 5 € și 0 € primești e-mail. Fără credit trimiterea se oprește; nimic nu se facturează în plus.

Pasul 2 — cheia API

Tot din Portal → SMS, secțiunea Chei API: dai un nume cheii (de exemplu productie sau n8n) și o creezi. Cheia începe cu vxs_ și se afișează o singură dată: copiaz-o atunci în locul în care o păstrezi (variabile de mediu, seiful de parole al aplicației). Dacă o pierzi, o revoci și faci alta; poți avea până la 5 chei active.

Portalul SMS: chei API, webhook-uri și secretul de semnare

Două setări merită făcute din prima:

•IP-uri permise: restrângi cheile la IP-ul static al serverului tău. Implicit se poate trimite de pe orice IP.
•Webhook pentru statusul livrării: un URL HTTPS al tău, pe care platforma îl cheamă la fiecare livrare sau eșec, cu semnătură HMAC (verifici că mesajul vine de la noi). Detaliile sunt în documentația API.

Pasul 3 — primul SMS

Un singur apel POST pe https://smshub.voxbee.ro/api/v1/messages, cu cheia în antetul Authorization. Numărul poate fi scris +40722…, 0040722… sau 0722…; textul poate avea diacritice (atunci un segment are 70 de caractere în loc de 160).

curl -s https://smshub.voxbee.ro/api/v1/messages \
  -H "Authorization: Bearer vxs_CHEIA_TA" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: comanda-12345" \
  -d '{"to":"+40722000000","from":"FIRMATA","text":"Comanda 12345 e gata de ridicare. Multumim!","ref":"comanda-12345"}'

Răspunsul vine imediat (202 Accepted) și îți spune, pentru fiecare destinatar, dacă mesajul a fost acceptat, câte segmente are și cât costă:

{
  "messages": [
    {
      "to": "40722000000",
      "status": "accepted",
      "id": "01a1…",
      "segments": 1,
      "encoding": "gsm7",
      "price": { "amount": "0.040000", "currency": "EUR" }
    }
  ]
}

Același apel în Node.js:

const r = await fetch('https://smshub.voxbee.ro/api/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SMS_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'comanda-12345',
  },
  body: JSON.stringify({
    to: '+40722000000',
    from: 'FIRMATA',
    text: 'Comanda 12345 e gata de ridicare. Multumim!',
    ref: 'comanda-12345',
  }),
})
const data = await r.json()
console.log(data.messages[0].status, data.messages[0].id)

Și în PHP:

$ch = curl_init('https://smshub.voxbee.ro/api/v1/messages');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('SMS_API_KEY'),
    'Content-Type: application/json',
    'Idempotency-Key: comanda-12345',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'to' => '+40722000000', 'from' => 'FIRMATA',
    'text' => 'Comanda 12345 e gata de ridicare. Multumim!', 'ref' => 'comanda-12345',
  ]),
]);
$data = json_decode(curl_exec($ch), true);
echo $data['messages'][0]['status'];

Trei detalii care te scutesc de bătăi de cap:

•Idempotency-Key: dacă aplicația ta reîncearcă apelul (timeout, repornire), același mesaj nu pleacă de două ori.
•ref: referința ta (id de comandă, de programare); o vezi în portal și o poți căuta prin API.
•Până la 100 de destinatari într-un singur apel, cu același text; răspunsul e per destinatar.

Pasul 4 — statusul de livrare

Fiecare mesaj trece prin stările acceptat → trimis → livrat (sau nelivrat / expirat, cu motivul). Le vezi în trei locuri:

•în portal, la Mesaje, cu rețeaua reală a destinatarului (inclusiv numerele portate), segmentele și prețul;
•prin API: GET /api/v1/messages/{id} sau GET /api/v1/messages?ref=comanda-12345;
•pe webhook, dacă l-ai setat: primești evenimentul semnat, cu reîncercări automate timp de 24 de ore dacă serverul tău nu răspunde.

Soldul curent: GET /api/v1/account/balance. Consumul pe zi și pe lună, cu export pentru contabilitate, e în portal.

Fără cod: campanii din portal

Dacă vrei să trimiți o promoție sau un reminder la o listă de clienți, nu ai nevoie de cheie API. În portal (butonul Campanii SMS):

•Contacte — urci un fișier CSV sau Excel; prima linie dă numele coloanelor, telefonul e recunoscut automat. Primești raportul: câte rânduri sunt valide, invalide, duplicate sau dezabonate.
•Campanie nouă — alegi lista și expeditorul, scrii mesajul cu variabile din fișier ({{prenume}}, {{comanda}}…), opțional ora de pornire și fereastra zilnică.
•Estimează — platforma calculează segmentele și rețeaua fiecărui destinatar și îți arată costul total. Campania pornește doar dacă ai credit pentru toate mesajele plus o mică rezervă; dacă soldul se termină pe parcurs, se oprește și reia singură după reîncărcare.
•Pornește și urmărești progresul: trimise, livrate, respinse, săriți; raportul per destinatar se descarcă în CSV.

Campanie în portal: destinatari, cost estimat, sold necesar, previzualizarea mesajelor personalizate

Pentru un mesaj către câțiva destinatari, pagina Mesaj nou face același lucru fără listă:

Mesaj nou din portal: destinatari, expeditor, text

Înainte să trimiți la clienți

•Consimțământ: pentru mesaje comerciale ai nevoie de acordul prealabil al destinatarilor (Legea nr. 506/2004 și GDPR). Mesajele tranzacționale (confirmări, coduri, remindere pentru o programare făcută de client) nu sunt marketing.
•Dezabonări: ține lista de opt-out în portal; cei de acolo nu primesc nimic din campanii, oricâte liste ai urca.
•Expeditorul: numele firmei, recognoscibil; nu folosi nume generice.
•Orele: nu trimite promoții noaptea; în portal poți seta o fereastră zilnică de trimitere.

Ai întrebări sau vrei un expeditor dedicat? Scrie-ne sau deschide un tichet din portal. Tarifele și întrebările frecvente sunt pe pagina SMS prin API.