Visión GeneralCómo FuncionaFuncionesPreciosDocumentaciónCasos de UsoIntegracionesSMSCorreoComenzar
Documentación técnica

API REST idempotente, SDKs oficiales, OpenAPI 3.1

Autenticación Bearer, reintentos automáticos en SDKs, webhooks firmados con HMAC SHA-256 y esquema versionado. Construido para quienes necesitan ir a producción esta semana — no el próximo trimestre.

Autenticación

Token Bearer + alcances de grano fino

Todas las llamadas a API requieren un token en el encabezado Authorization: Bearer …. Usted crea tokens separados por entorno (prod, staging, sandbox), por alcance (messages:send,templates:manage,analytics:read), y con TTL configurable. Rotación de claves sin tiempo de inactividad vía solapamiento de 24 horas.

  • Tokens por entorno y alcance
  • Rotación con solapamiento de 24h sin tiempo de inactividad
  • Límite de velocidad aislado por token
  • Registro de auditoría de cada llamada en el panel
curl https://api.ccx.co/v1/messages \
  -H "Authorization: Bearer $CCX_API_KEY" \
  -H "Content-Type: application/json"
Enviar mensaje

POST /v1/messages

Envía un mensaje individual vía WhatsApp, SMS o correo. Use template para mensajes HSM (requerido para iniciar conversación) o text / media / interactive dentro de una ventana de 24h. Siempre idempotente: envíe el mismo idempotency_key y CCX garantiza entrega única.

  • Idempotencia por clave (ventana de 7 días)
  • Fallback automático entre canales
  • Prioridad: baja / por defecto / alta / crítica
  • Envío programado con zona horaria
  • Validación de plantilla del lado del servidor
curl https://api.ccx.co/v1/messages \
  -H "Authorization: Bearer $CCX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+5511999990000",
    "channel": "whatsapp",
    "template": {
      "name": "order_confirmation",
      "language": "pt_BR",
      "variables": {
        "1": "Maria",
        "2": "#A8492",
        "3": "R$ 349,90"
      }
    },
    "idempotency_key": "ord_A8492"
  }'
Difusión masiva

POST /v1/broadcasts

Dispara una difusión a un segmento precalculado. Control fino de flujo, prioridad por inquilino, programación y reintentos por destinatario. El estado está disponible en transmisión vía GET /v1/broadcasts/:id/events (SSE).

  • Límite de velocidad por minuto configurable
  • Pausa/reanudación sin perder contexto
  • Agrupamiento inteligente: 500 destinatarios por trabajo, idempotente
  • Ensayo en seco para validar costo antes
curl https://api.ccx.co/v1/broadcasts \
  -H "Authorization: Bearer $CCX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Black Friday — Batch 1",
    "template": "black_friday_2026",
    "language": "pt_BR",
    "segment_id": "seg_ZZ11",
    "rate_limit_per_minute": 6000,
    "priority": "high",
    "schedule_at": "2026-11-28T09:00:00-03:00"
  }'
Webhooks

Eventos firmados por HMAC SHA-256

Cada evento sale de su inquilino con firma HMAC verificable en encabezado CCX-Signature. Reentrega automática con retroceso exponencial hasta 24h, ordenamiento garantizado por message_id, y reproducción manual vía panel para cualquier ventana de los últimos 30 días.

message.queuedmessage.sentmessage.deliveredmessage.readmessage.failedmessage.replybroadcast.progressbroadcast.completedtemplate.approvedtemplate.rejected
# Ejemplo de carga útil recibida en su punto final HTTPS:
POST /webhooks/ccx HTTP/1.1
CCX-Signature: t=1745347200,v1=a6f7…
Content-Type: application/json

{
  "event": "message.delivered",
  "message_id": "msg_0xK91A",
  "conversation_id": "cnv_44aa",
  "to": "+5511999990000",
  "template": "order_confirmation",
  "delivered_at": "2026-04-22T14:20:12Z",
  "billable": { "category": "utility", "price": 0.10, "currency": "BRL" }
}
Límites y SLAs

Transparencia sobre lo que la API puede entregar

Límites de velocidad

  • • API de envío: 6.000 req/min por token (Pro) · 50.000 req/min (Empresarial)
  • • Ráfaga hasta 1.200 req/s en ventanas cortas
  • • Encabezados X-RateLimit-Remaining / X-RateLimit-Reset en todas las respuestas
  • • Limitación suave: nunca devuelva 429 sin advertencia previa

Idempotencia

  • • idempotency_key obligatorio en POST /messages y /broadcasts
  • • Ventana de 7 días — devuelve la misma respuesta en caché
  • • Clave UUID v4, ULID o personalizada (máx 128 caracteres)
  • • Las repeticiones no se cuentan en volumen

Latencias y SLA

  • • p50 envío: 38ms · p99 ingestión: <200ms
  • • Entrega a Meta Cloud API: p99 < 500ms
  • • Webhooks salientes: p99 < 2s después del evento
  • • Tiempo de actividad mensual: 99,9% (Negocio) · 99,95% (Empresarial)
SDKs oficiales

Misma API, múltiples lenguajes

SDKs generados desde el mismo OpenAPI 3.1. Reintentos exponenciales, telemetría conectables, tipificación fuerte y pruebas de contrato en CI para cada lanzamiento.

Node.js · TypeScript

@ccxcompany/sdk

npm i @ccxcompany/sdk

Python · Pydantic v2

ccx-sdk

pip install ccx-sdk

PHP 8.2+ · PSR-18

ccxcompany/sdk-php

composer require ccxcompany/sdk

Go 1.22+ · context-aware

github.com/ccxcompany/go

go get github.com/ccxcompany/go

Ruby 3.3+ · Sorbet

ccxcompany/sdk-ruby

gem install ccxcompany-sdk

Java 17+ · Maven Central

com.ccxcompany:sdk

mvn install com.ccxcompany:sdk

¿Listo para escribir el primer curl?

Crea una cuenta sandbox en 2 minutos. Tokens gratis, sin tarjeta, sin lock-in.

Activar sandboxVer precios