Integrare API

Endpoint-uri API

Trimite mesaje prin REST API:

POST /api/v1/integrations/messages/send
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{"channel": "sms", "to": "+40712345678", "body": "Your OTP: 123456"}

// Returns HTTP 201 with status "queued" — delivery is async.
// Poll GET /api/v1/integrations/messages/{id}/status or use webhooks.

Webhooks

Primeste actualizari de livrare in timp real:

• Notificare la trimiterea mesajului
• Confirmare de livrare (DLR)
• Alerte de bounce / failure
• Notificari pentru mesaje inbound

Status de livrare (livrat vs. acceptat)

Atentie: status "sent" inseamna doar ca operatorul a acceptat mesajul — NU ca a ajuns la telefon. Statusul real de livrare vine de la operator dupa cateva secunde sau minute. Pentru rezultatul corect foloseste campurile delivery_status (delivered | failed | pending | cancelled) si delivery_confirmed.

Push (recomandat)

Aboneaza-te la webhook-urile message.delivered / message.failed. Iti trimitem statusul real in momentul in care il primim de la operator — nu trebuie sa interoghezi nimic.

POST /api/v1/integrations/webhooks
X-API-Key: YOUR_API_KEY

{"delivery_profile": "sms_only"}
// subscribes to message.sent, message.delivered, message.failed

// Webhook we send you when the carrier confirms:
{
  "event": "message.delivered",
  "data": {
    "id": 12345,
    "channel": "sms",
    "to": "+40712345678",
    "status": "delivered",
    "delivery_status": "delivered",   // delivered | failed | pending | cancelled
    "delivery_confirmed": true,
    "delivered_at": "2026-07-30T10:15:03Z"
  }
}

Polling

Sau interogheaza oricand statusul curent al unui mesaj:

GET /api/v1/integrations/messages/{id}/status
X-API-Key: YOUR_API_KEY

// Response
{
  "id": 12345,
  "status": "sent",
  "delivery_status": "pending",       // still waiting on the carrier DLR
  "delivery_confirmed": false
}

Formatul numerelor de telefon

Pentru SMS, WhatsApp, Viber și RCS, câmpul "to" trebuie să conțină un număr de telefon valid. Formatul internațional E.164 este recomandat, dar acceptăm și formatele locale românești și le normalizăm automat.

• +40740123456 — format internațional, recomandat
• 0740123456 — format local românesc, normalizat automat
• 0040740123456 — prefix internațional cu 00, normalizat automat

Ce respingem

Numerele care nu pot fi o destinație reală sunt respinse cu 422 în momentul cererii, nu acceptate și eșuate ulterior. De exemplu +6840242000 (prefix de țară inexistent) sau +4074012345 (o cifră lipsă pentru România). Aceste numere nu ajung niciodată la operator și nu sunt taxate.

Într-o trimitere în lot, un număr invalid este raportat individual cu error_code INVALID_DESTINATION și nu oprește restul destinatarilor valizi.

Autentificare

Autentifica request-urile API cu cheia ta API:

X-API-Key: YOUR_API_KEY