Documentação técnica

API REST idempotente, SDKs oficiais, OpenAPI 3.1

Autenticação Bearer, retries automáticos nos SDKs, webhooks assinados por HMAC SHA-256 e schema versionado. Feito para quem precisa entrar em produção esta semana — não no próximo trimestre.

Autenticação

Bearer token + escopos finos

Todas as chamadas à API exigem um token no header Authorization: Bearer …. Você cria tokens separados por ambiente (prod, staging, sandbox), por escopo (messages:send,templates:manage,analytics:read), e com TTL configurável. Rotação de chave sem downtime via overlap de 24 horas.

Tokens por ambiente e escopo
Rotação com overlap de 24h sem downtime
Rate-limit isolado por token
Audit log de cada chamada no dashboard

curl https://api.ccx.co/v1/messages \
  -H "Authorization: Bearer $CCX_API_KEY" \
  -H "Content-Type: application/json"

Enviar mensagem

`POST` /v1/messages

Envia uma mensagem individual via WhatsApp, SMS ou e-mail. Use template para mensagens HSM (necessário para iniciar conversa) ou text / media / interactive dentro de uma janela de 24h. Sempre idempotente: envie a mesma idempotency_key e a CCX garante entrega única.

Idempotência por chave (janela de 7 dias)
Fallback cross-channel automático
Priority: low / default / high / critical
Scheduled send com timezone
Validação server-side do template

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 em massa

`POST` /v1/broadcasts

Dispara um broadcast para um segmento pré-calculado. Controle fino de vazão, prioridade por tenant, agendamento e retries por destinatário. O status fica disponível em streaming via GET /v1/broadcasts/:id/events (SSE).

Rate-limit por minuto configurável
Pause/resume sem perder contexto
Smart batching: 500 destinatários por job, idempotente
Dry-run para validar custo 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 assinados por HMAC SHA-256

Cada evento sai do seu tenant com assinatura HMAC verificável no header CCX-Signature. Redelivery automático com backoff exponencial de até 24h, ordenação garantida por message_id, e replay manual via dashboard para qualquer janela dos últimos 30 dias.

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

# Exemplo de payload recebido no seu 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" }
}

Limits & SLAs

Transparente sobre o que a API pode entregar

Rate-limits

• Send API: 6.000 req/min por token (Pro) · 50.000 req/min (Enterprise)
• Burst até 1.200 req/s em janelas curtas
• Headers X-RateLimit-Remaining / X-RateLimit-Reset em todas as respostas
• Throttling suave: nunca retornamos 429 sem warning antes

Idempotência

• idempotency_key obrigatório em POST /messages e /broadcasts
• Janela de 7 dias — retorna a mesma resposta cacheada
• Chave UUID v4, ULID ou custom (máx 128 chars)
• Replays não são contabilizados em volume

Latências e SLA

• p50 envio: 38ms · p99 ingest: <200ms
• Entrega à Meta Cloud API: p99 < 500ms
• Webhooks outbound: p99 < 2s após evento
• Uptime mensal: 99,9% (Business) · 99,95% (Enterprise)

SDKs oficiais

Mesma API, múltiplas linguagens

SDKs gerados do mesmo OpenAPI 3.1. Retries exponenciais, telemetry plugável, tipagem forte e testes de contrato em CI para 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

Pronto para escrever o primeiro curl?

Crie uma conta sandbox em 2 minutos. Tokens gratuitos, sem cartão, sem fidelidade.

Ativar sandbox Ver preços