Referencia de API

Base: https://sms.001.com.mx/api/v1

Autenticación: Authorization: Bearer sk_... (API key) o Authorization: Bearer at_... (token JWT).

Todas las respuestas son JSON. En error devolvemos { "error": "mensaje" } con código HTTP apropiado.

Enviar mensaje

POST /api/v1/send

{
  "channel": "sms",            // sms | mms | whatsapp | data
  "phoneNumbers": ["+5215555555555"],
  "message": "Hola mundo",
  "mediaUrls": ["https://..."],  // requerido si channel=mms
  "simNumber": 1,              // 1-3 (Android dual-SIM)
  "priority": 0,               // -128, 0, 100, 127. >=100 salta rate limits
  "ttl": 300,                  // segundos — expira si no se envía
  "validUntil": "2026-01-01T00:00:00Z",
  "withDeliveryReport": true,
  "isEncrypted": false,
  "externalId": "tu-id-unico",  // idempotencia
  "deviceId": "cm..."          // opcional: forzar dispositivo específico
}

Respuesta:

{
  "id": "cmxxx...",
  "state": "processing",
  "priority": 0,
  "recipients": [
    { "phoneNumber": "+5215555555555", "state": "processing" }
  ],
  "createdAt": "2026-04-24T...",
  "updatedAt": "2026-04-24T..."
}

Consultar mensajes

GET /api/v1/messages?limit=50&cursor=cm...&direction=out&state=delivered
GET /api/v1/messages/{id}

Inbox (mensajes recibidos)

GET /api/v1/inbox?limit=50&deviceId=cm...

Conversaciones (hilos)

GET  /api/conversations
GET  /api/conversations/{id}
GET  /api/conversations/{id}/messages
POST /api/conversations/{id}/send       { "message": "..." }
POST /api/conversations/{id}/read

Dispositivos

GET    /api/devices
POST   /api/devices/android             { "name": "..." }
POST   /api/devices/whatsapp            { "name": "..." }
GET    /api/devices/{id}/settings
PATCH  /api/devices/{id}/settings       { "simSelectionMode": "RoundRobin", "limitPeriod": "PerMinute", "limitValue": 30, ... }
GET    /api/devices/{id}/logs?level=error
DELETE /api/devices/{id}

Webhooks

GET    /api/webhooks
GET    /api/webhooks/events              # eventos disponibles
POST   /api/webhooks                     { "url": "...", "events": ["sms:received"], "deviceId": null, "format": "native" }
PATCH  /api/webhooks/{id}
DELETE /api/webhooks/{id}

Eventos: sms:received, sms:sent, sms:delivered, sms:failed, mms:received, mms:downloaded, whatsapp:received, whatsapp:sent, whatsapp:delivered, whatsapp:failed, system:ping, device:online, device:offline.

Cada webhook tiene un secret. Firmamos el body con HMAC-SHA256:

x-smsgw-signature: <hex hmac>
x-smsgw-event: sms:received
x-smsgw-format: native

Llaves API y JWT

POST   /api/keys                { "name": "..." }  -> crea llave (solo se muestra una vez)
DELETE /api/keys/{id}

POST   /api/auth/token          # genera par access/refresh (requiere sesión)
POST   /api/auth/token/refresh  { "refreshToken": "rt_..." }

Cuotas y uso

GET /api/billing                # plan, uso, período actual