Desarrolladores

Documentación

Envía SMS y RCS por la API HTTP o por SMPP, sigue el estado de cada mensaje y recibe las actualizaciones en tu sistema.

Primeros pasos API de SMS RCS Webhooks SMPP Errores

Primeros pasos

Crea tu cuenta y agrega saldo por PIX o USDT.
En el panel, en Conexiones API / SMPP, registra las IP de tus servidores. Solo esas direcciones pueden usar la API y el SMPP.
Genera tus credenciales: el token de la API y el usuario y la contraseña del SMPP. Se muestran una sola vez; guárdalas en un lugar seguro.
Consulta tus SID (remitentes) en el panel o con GET /api/v1/routes.

Autenticación

Todas las llamadas usan HTTPS y el token en el encabezado Authorization:

Authorization: Bearer TOKEN
Content-Type: application/json

Nunca pongas el token en aplicaciones, páginas web o repositorios públicos. Si sospechas una filtración, genera nuevas credenciales en el panel: las anteriores dejan de funcionar al instante.

La dirección base de la API se informa en el panel, junto con las credenciales.

API de SMS

POST/api/v1/messages

Envía un mensaje.

Campo	Obligatorio	Descripción
`sid`	sí	El SID (remitente) de tu cuenta.
`to`	sí	Número de destino. Para Brasil, con o sin el 55 (5511999990000 o 11999990000).
`text`	sí	Texto del mensaje.
`reference`	no	Tu identificador (hasta 128 caracteres). Reenviar la misma referencia no duplica el envío.
`channel`	no	sms (predeterminado) o rcs.

curl -X POST https://[API]/api/v1/messages \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sid":"SID","to":"5511999990000","text":"Tu código es 482913","reference":"pedido-1001"}'

Respuesta:

{ "id": "dx1234567", "status": "queued", "amount": 45000, "currency": "BRL" }

El campo amount es el valor cobrado en millonésimas de la moneda (45000 = BRL 0,045).

Se aceptan mensajes largos: Diamond X divide el texto y el teléfono lo muestra todo junto, como un solo mensaje. Cada parte tiene hasta 153 caracteres sin acentos (o 67 con acentos o emojis), con un límite de 20 partes. Se cobra por parte; un mensaje de hasta 160 caracteres (o 70 con acentos) es una sola parte.

GET/api/v1/messages/{id}

Consulta el estado de un mensaje.

{ "id": "dx1234567", "status": "delivered", "phone": "5511999990000", "channel": "sms",
  "created_at": "…", "updated_at": "…", "delivered_at": "…" }

Status	Significado
`queued`	En la cola de Diamond X.
`sent`	Aceptado por el operador, esperando confirmación.
`delivered`	Entregado en el teléfono.
`undelivered`	El operador no pudo entregarlo.
`failed`	Falló o fue rechazado.
`unknown`	Sin confirmación final del operador.

GET/api/v1/routes

Lista los SID activos de tu cuenta, con canal (sms o rcs), país, precio y moneda.

GET/api/v1/balance

Muestra el saldo disponible, el saldo reservado para envíos en curso y la moneda de la cuenta.

RCS

Con un SID de RCS habilitado en tu cuenta, usa el mismo endpoint de envío con "channel": "rcs":

{"sid":"SID_RCS","to":"5511999990000","text":"¡Tu compra salió para entrega!","channel":"rcs"}

El mensaje llega con el nombre, el logo y el sello de verificación de tu marca. Tarjetas, carrusel y botones, y el registro del agente de tu marca, están en la guía de RCS dentro del panel.

Webhooks

Registra en el panel una URL HTTPS de tu sistema para recibir las actualizaciones de estado de los mensajes, sin consultar la API.

Cada llamada se firma con HMAC-SHA256 en el encabezado X-DiamondX-Signature, usando el secreto que aparece en el panel. Valida la firma antes de procesar.
Responde con HTTP 2xx. Si tu sistema está caído, Diamond X vuelve a intentarlo.
Usa el id o tu reference para relacionar el evento con el envío.

SMPP

Protocolo SMPP 3.4, con binds transmitter, receiver o transceiver.
Hasta 3 conexiones por cuenta, cada una con su propio usuario y contraseña.
Informes de entrega (DLR) por deliver_sm, siempre que se soliciten en registered_delivery.
Mensajes largos: envía las partes con UDH o SAR; llegan juntas al teléfono.
Acceso permitido solo desde las IP registradas en el panel.
La dirección, el puerto, el usuario (system_id) y la contraseña aparecen en el panel, en Conexiones API / SMPP, después de iniciar sesión.

Errores

Los errores devuelven el código HTTP y un mensaje en el campo error.

Código	Cuándo ocurre
`400`	Campo inválido o ausente, número no válido para el país del SID o SID no activo en la cuenta.
`401`	Token ausente o inválido.
`403`	Acceso no permitido: IP no registrada, cuenta inactiva o SID no habilitado.
`404`	Mensaje no encontrado.

¿Dudas con la integración? Habla con el soporte técnico: WhatsApp · site@diamondx.app