api.ccxmessages.com/v1 · operativa

Una API para seis canales. Sin SDK obligatorio.

REST con JSON, autenticación Bearer, idempotencia por clave y webhooks firmados. Cambiar de canal es cambiar un campo — el resto del contrato sigue igual.

Abrir el playgroundReferencia completa
curl -X POST https://api.ccxmessages.com/v1/messages \
-H "Authorization: Bearer $CCX_KEY" \
-H "Idempotency-Key: pedido-9921" \
-H "Content-Type: application/json" \
-d '{
"channel": "whatsapp",
"to": "+5541998124410",
"template": "pedido_enviado_v3",
"variables": { "nome": "Marina", "pedido": "9921" },
"fallback": ["sms", "push"]
}'
202 Accepted{ "id": "msg_9f21ac", "status": "queued" }118 ms
64
endpoints REST documentados
600/min
límite por defecto por clave de API
118 ms
latencia p95 en el envío
99,9%
SLA contractual de la API
Principios de la API

Contratos estables, comportamiento previsible.

Sin campo mágico por canal, sin endpoint que cambia de forma sin aviso. Los cambios que rompen el contrato solo llegan en una nueva versión mayor, con 12 meses de solapamiento y changelog público.

Changelog y versionadoProbar en el playground
Un contrato, seis canales

El mismo payload envía WhatsApp, email, SMS, RCS, push e Instagram. Cambiar de canal es cambiar un campo.

Idempotencia nativa

La cabecera Idempotency-Key elimina el envío duplicado en los reintentos, con respuesta idéntica durante 24 horas.

Webhooks firmados

HMAC SHA-256, tolerancia de 5 minutos y reintentos con backoff exponencial durante hasta 24 horas.

Coste en la respuesta

Cada envío devuelve el precio aplicado, el tramo de volumen y el saldo del monedero — sin conciliación posterior.

Referencia

Los endpoints que usas el primer día.

Son 64 rutas en total. Estas seis cubren envío, consulta, lote, plantilla, monedero y webhook — lo suficiente para poner la primera operación en producción.

Ver los 64 endpoints
POST/v1/messages

Envía un mensaje en cualquier canal. El campo channel decide la ruta; el resto del contrato es idéntico.

Parámetros
channelstringobligatoriowhatsapp · sms · email · push · instagram
tostringobligatorioTeléfono E.164, email o id del usuario, según el canal.
templatestringcondicionalObligatorio fuera de la ventana de 24h en WhatsApp.
variablesobjectopcionalVariables nombradas de la plantilla, validadas antes del envío.
fallbackarrayopcionalCanales alternativos si el principal no entrega.
Probar ahora
01Webhooks

Cada evento llega firmado y con reintento.

Firma HMAC SHA-256 en la cabecera, tolerancia de 5 minutos en el timestamp y reintentos con backoff exponencial durante hasta 24 horas. El panel guarda el cuerpo de cada intento durante 30 días.

01Ping antes de activarLa URL tiene que responder 200 en la validación — nada se activa a ciegas.
02Reintento exponencial30s, 2min, 10min, 1h y 6h hasta completar 24 horas de intentos.
03Cuerpo auditableCabeceras y payload de cada intento guardados y reenviables desde el panel.
Configurar un webhook
Eventos firmadosHMAC SHA-256
message.queuedmessage.sentmessage.deliveredmessage.readmessage.failedmessage.receivedtemplate.approvedtemplate.rejectedwallet.low_balanceai.interaction
30 sPrimer reintento tras un fallo o un timeout
2 – 10 minSegundo y tercer intento, con backoff
1 h – 6 hÚltimos intentos hasta completar 24 horas
02Reenvío con trazabilidad

Un fallo no es el punto final.

Un mensaje en cola o con fallo puede corregirse y reprocesarse. El original se archiva y se genera uno nuevo que referencia al anterior — toda la cadena queda auditable, sin mensajes huérfanos ni envíos duplicados.

01Referencia explícitaEl mensaje nuevo lleva replaces con el id del original.
02Cobro justoLo rechazado por el proveedor o cancelado antes del envío no se cobra.
03Reenvío por lotesPOST /v1/messages/bulk-resend con corrección del lote y aceptación parcial.
Ver en el panel de mensajes
Cadena de reprocesamiento
msg_9f21acFalloRechazado por el proveedor: variable de la plantilla fuera del formato esperado.error: invalid_template_variable
msg_9f21acArchivadoEl original se conserva tal cual — nada se sobrescribe ni se borra.archived_at: 14:07:22Z
msg_a4d70eNuevoCorriges el contenido y la plataforma genera un mensaje nuevo, ya con la referencia al anterior.replaces: msg_9f21ac
msg_a4d70eEntregadoEl historial del contacto muestra los dos, enlazados — sin mensajes huérfanos ni duplicados.

Un mensaje rechazado por el proveedor no se cobra. El reenvío es un mensaje nuevo y se tarifa con normalidad.

03Fallback de canal

Orquestación de canal sin código tuyo.

Declara la cadena en el envío y la plataforma prueba el canal siguiente cuando el anterior no entrega en el plazo definido. Recibes el webhook de cada intento y pagas solo lo que se envió de verdad.

01Plazo configurablefallback_after acepta minutos u horas por mensaje.
02Sin estado en tu ladoLa plataforma controla la cola, el plazo y el orden de los intentos.
03Coste por intento realCada canal activado se cobra según su propia tabla.
Ver la tabla por canal
Cadena declarada en el envíofallback_after: 4h
01WhatsAppcanal principal
02SMSsin lectura en 4 horas
03Pushúltimo intento
"fallback": ["sms", "push"]
Operación

Límites, autenticación y errores — publicados.

Nada de límites que se descubren en producción. Cada código de error tiene un code estable, un mensaje legible y la acción recomendada en la documentación.

Autenticación y límites
AutenticaciónCabecera Authorization: Bearer con la clave de la organizaciónBearer
Claves de pruebaPrefijo ccx_test_ · monedero sandbox, sin descontar saldo realilimitadas
Envío unitarioPor clave de API, con ráfaga de 100 solicitudes600/min
Envío por lotesCada lote admite hasta 5.000 mensajes30/min
Errores previsibles
400invalid_phoneNúmero fuera del estándar E.164 o inexistente
402insufficient_fundsSaldo del monedero insuficiente para el envío
409window_closedFuera de la ventana de 24h: usa una plantilla aprobada
429rate_limitedLímite por minuto superado · consulta Retry-After
Herramientas

Lo que ya viene listo para integrar.

Dudas técnicas

Lo que pregunta el equipo de ingeniería.

¿Necesitas más detalle? La referencia tiene ejemplos en cinco lenguajes para cada ruta.

Envía la cabecera Idempotency-Key con un identificador tuyo (el número del pedido, por ejemplo). Las repeticiones de la misma clave en 24 horas devuelven la respuesta original, con el mismo id de mensaje, sin duplicar el envío ni el cobro. Es el mecanismo recomendado para el reintento automático.

Empieza hoy con R$ 50 de crédito de prueba.

Monedero sandbox activado al crear la cuenta, número de prueba de WhatsApp y onboarding guiado. Sin tarjeta, sin contrato.

Reservar una demoCrear cuenta gratisRespuesta comercial en menos de 2 horas laborables
CCX
Plataforma CPaaS brasileña. WhatsApp, email, SMS, RCS, push e Instagram en una única integración.
Todos los sistemas operando
© 2026 CCX Digital Solutions LTDA · CNPJ 24.329.191/0001-06 · BrasilTérminos de usoPrivacidadSeguridadChangelog