Uma referência única para todos os canais
A NexxiSend nasce como API: o console é apenas um cliente dela. A Universal Messaging API já está publicada em /api/public/v1/messages, autenticada pelas chaves emitidas no console e com escopos por chave. O envio só sai de verdade quando o provedor do canal tem credencial ativa no cofre.
Quickstart
- 1Crie um workspace e gere uma API key com escopo restrito.
- 2Envie a primeira mensagem no sandbox, sem custo e sem envio real.
- 3Assine os webhooks de status e reconcilie custo por tentativa.
- 4Ative providers reais quando as credenciais estiverem no vault.
Autenticação
Bearer token por workspace, com escopos por recurso. Chaves de provider ficam no backend, nunca no cliente.
Authorization: Bearer nxs_live_•••••••curl -X POST https://nexxisend.com.br/api/public/v1/messages \
-H "Authorization: Bearer $NEXXI_API_KEY" \
-H "Idempotency-Key: ord_92f4c1" \
-H "Content-Type: application/json" \
-d '{
"channel": "sms",
"to": "+5511999999999",
"country": "BR",
"sms": { "body": "Seu código é 481920" },
"metadata": { "order_id": "92f4c1" }
}'Resposta 202
{
"data": {
"id": "6f1c...",
"channel": "sms",
"status": "sent",
"to": "+55119****9999",
"provider": "twilio",
"route": { "policy": "balanced", "reason": "menor custo por entrega" },
"attempts": [
{ "number": 1, "provider": "twilio", "status": "sent", "latency_ms": 412 }
],
"error": null,
"idempotent_replay": false,
"created_at": "2026-03-14T18:22:41Z"
}
}Endpoints planejados
Recursos previsíveis, erros tipados, paginação por cursor e idempotência por chave em toda operação de escrita.
- POST/api/public/v1/messagesEnvio unificado SMS, WhatsApp e e-mail, com NexxiRoute, fallback e idempotência.
- GET/api/public/v1/messages?id={id}Situação atual, tentativas por provedor e timeline de eventos.
- POST/api/public/sms-dlrRecebimento de DLR do provedor de SMS, autenticado por token.
- POST/api/public/email-eventsEntrega, bounce e reclamação de e-mail, autenticados por token.
- POST/api/public/whatsapp-webhookStatus e mensagens recebidas do WhatsApp, autenticados por token.
Webhooks
Eventos assinados com HMAC, reentrega com backoff e ordem por mensagem. Cada payload carrega provider, tentativa, custo e motivo de falha — base do FinOps e do audit trail.
message.queued
Aceita e enfileirada; idempotência já resolvida.
message.routed
Canal e provider escolhidos, com motivo da decisão.
attempt.failed
Tentativa falhou; fallback avaliado.
message.delivered
Entrega confirmada pelo provider.
message.read
Leitura, quando o canal reporta.
contact.opted_out
Opt-out registrado e supressão aplicada.
Idempotência
Reenvie a mesma requisição com a mesma Idempotency-Key sem risco de duplicar envio ou cobrança. O fallback nunca reentrega uma mensagem já confirmada como entregue.
Erros tipados
- 401invalid_api_keyChave ausente, revogada ou expirada.
- 403insufficient_scopeChave sem o escopo messages:send ou messages:read.
- 400idempotency_key_requiredHeader Idempotency-Key ausente ou curto demais.
- 409consent_requiredDestino sem consentimento ativo ou em supressão.
- 422validation_errorPayload inválido para o canal informado.
- 503provider_unavailableNenhum provedor elegível com credencial ativa.
Boas práticas
- Valide a assinatura antes de processar o payload.
- Responda 2xx rápido e processe de forma assíncrona.
- Trate eventos como at-least-once e deduplique por event id.
- Nunca exponha API keys no frontend.
SDKs e sandbox
SDKs para Node, Python, PHP e Go estão planejados sobre a mesma Universal Messaging API, junto de um sandbox com providers simulados. Status atual: em construção — nada aqui simula uma integração já ativa.