Documentación técnica

API REST idempotente, SDKs oficiales, OpenAPI 3.1

Autenticación Bearer, reintentos automáticos en los SDKs, webhooks firmados con HMAC SHA-256 y schema versionado. Hecho para equipos que necesitan entrar en producción esta semana — no el próximo trimestre.

Autenticación

Bearer token + scopes granulares

Todas las llamadas a la API requieren un token en el header Authorization: Bearer …. Creas tokens separados por entorno (prod, staging, sandbox), por scope (messages:send,templates:manage,analytics:read), con TTL configurable. Rotación de clave con overlap de 24 horas, sin downtime.

Tokens por entorno y scope
Rotación con overlap de 24h sin downtime
Rate-limit aislado por token
Audit log de cada llamada en el dashboard

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 email. Usa template para mensajes HSM (requerido para iniciar la conversación) o text / media / interactive dentro de la ventana de 24h. Siempre idempotente: envía la misma idempotency_key y CCX garantiza entrega única.

Idempotencia por clave (ventana de 7 días)
Fallback cross-channel automático
Priority: low / default / high / critical
Scheduled send con timezone
Validación server-side de la plantilla

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"
  }'

Broadcast masivo

`POST` /v1/broadcasts

Dispara un broadcast a un segmento precalculado. Control fino de tasa, prioridad por tenant, agendamiento y reintentos por destinatario. El estado queda disponible vía streaming en GET /v1/broadcasts/:id/events (SSE).

Rate-limit por minuto configurable
Pause/resume sin perder contexto
Smart batching: 500 destinatarios por job, idempotente
Dry-run para previsualizar el costo

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 con HMAC SHA-256

Cada evento sale de tu tenant con una firma HMAC verificable en el header CCX-Signature. Redelivery automático con backoff exponencial hasta 24h, orden garantizado por message_id, y replay manual desde el dashboard para cualquier ventana de los últimos 30 días.

message.queuedmessage.sentmessage.deliveredmessage.readmessage.failedmessage.replybroadcast.progressbroadcast.completedtemplate.approvedtemplate.rejected

# Ejemplo de payload entregado a tu endpoint 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.16, "currency": "BRL" }
}

Límites & SLAs

Transparentes sobre lo que la API puede entregar

Rate-limits

• Send API: 6.000 req/min por token (Pro) · 50.000 req/min (Enterprise)
• Burst hasta 1.200 req/s en ventanas cortas
• Headers X-RateLimit-Remaining / X-RateLimit-Reset en todas las respuestas
• Throttling suave: nunca devolvemos 429 sin warning previo

Idempotencia

• idempotency_key requerido en POST /messages y /broadcasts
• Ventana de 7 días — devuelve la respuesta cacheada
• Clave UUID v4, ULID o custom (máx 128 chars)
• Los replays no cuentan contra el volumen

Latencias y SLA

• p50 envío: 38ms · p99 ingest: <200ms
• Entrega a Meta Cloud API: p99 < 500ms
• Webhooks outbound: p99 < 2s tras evento
• Uptime mensual: 99,9% (Business) · 99,95% (Enterprise)

SDKs oficiales

Misma API, múltiples lenguajes

SDKs generados desde el mismo OpenAPI 3.1. Reintentos exponenciales, telemetry enchufable, tipado fuerte y tests de contrato en CI en cada release.

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 sandbox Ver precios