Começando com a API Nexus

Este guia irá orientá-lo através dos primeiros passos para integrar a API Nexus em sua aplicação. Em menos de 5 minutos, você estará enviando suas primeiras mensagens.

Pré-requisitos

Antes de começar, certifique-se de ter:

• Uma conta ativa na plataforma Nexus
• Saldo disponível para envio de mensagens
• Conhecimento básico de requisições HTTP/REST
• Ferramenta para testar APIs (Postman, Insomnia, cURL, etc.)

1. Obter sua API Key

A API Key é necessária para autenticar suas requisições. Para gerar uma nova chave:

1. Acesse o painel da Nexus em app.nexuscomunicacao.com.br
2. Faça login com suas credenciais
3. Navegue até Configurações → API Keys
4. Clique em "Gerar Nova API Key"
5. Copie e armazene a chave em local seguro

Sua API Key terá o formato:

nxc_live_abc123def456ghi789jkl012mno345pqr678

2. Fazer sua Primeira Requisição

Todas as requisições à API devem incluir o header de autenticação:

X-API-KEY: sua_api_key_aqui

Exemplo com cURL

curl -X GET "https://app.nexuscomunicacao.com.br/api/v1/integration/balance" \
  -H "X-API-KEY: nxc_live_abc123..."

Exemplo com JavaScript (Fetch)

fetch('https://app.nexuscomunicacao.com.br/api/v1/integration/balance', {
  method: 'GET',
  headers: {
    'X-API-KEY': 'nxc_live_abc123...'
  }
})
.then(response => response.json())
.then(data => console.log(data));

3. Consultar Saldo Disponível

Antes de enviar mensagens, verifique o saldo disponível em sua conta:

Resposta de Sucesso (200 OK)

{
  "balance": 1250.50
}

4. Listar Rotas Disponíveis

Consulte as rotas de envio habilitadas em sua conta e seus respectivos preços:

Resposta de Sucesso (200 OK)

[
  {
    "id": "6584a9b1c2d3e4f5a6b7c8d9",
    "name": "Rota SMS Premium",
    "type": "SMS"
  },
  {
    "id": "6584a9b1c2d3e4f5a6b7c8e0",
    "name": "Rota RCS Marketing",
    "type": "RCS"
  },
  {
    "id": "6584a9b1c2d3e4f5a6b7c8e1",
    "name": "Rota WhatsApp Business",
    "type": "WHATSAPP"
  }
]

5. Enviar sua Primeira Mensagem

Agora você está pronto para enviar sua primeira mensagem através da API:

Parâmetros da Requisição

Exemplo de Requisição

{
  "to": "5511999999999",
  "message": "Olá! Esta é sua primeira mensagem via API Nexus.",
  "type": "SMS",
  "callbackUrl": "https://sua-aplicacao.com/webhook/status"
}

Exemplo com cURL

curl -X POST "https://app.nexuscomunicacao.com.br/api/v1/integration/send" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: nxc_live_abc123..." \
  -d '{
    "to": "5511999999999",
    "message": "Olá! Esta é sua primeira mensagem via API Nexus.",
    "routeId": "6584a9b1c2d3e4f5a6b7c8d9",
    "type": "SMS"
  }'

Resposta de Sucesso (200 OK)

{
  "message": "Requisição recebida com sucesso. A campanha foi enviada para análise e processamento.",
  "details": {
    "campaignId": "6584b123c2d3e4f5a6b7c999",
    "status": "UNDER_APPROVAL",
    "type": "SMS",
    "routeName": "Rota SMS Premium",
    "content": "Olá! Esta é sua primeira mensagem via API Nexus.",
    "recipients": 1,
    "cost": {
      "perUnit": 0.08,
      "total": 0.08,
      "currency": "BRL"
    }
  }
}

6. Verificar Status da Campanha

Após enviar uma mensagem, você pode consultar suas estatísticas de entrega:

Resposta de Sucesso (200 OK)

{
  "sent": 1,
  "delivered": 1,
  "failed": 0,
  "pending": 0,
  "contacts": [
    {
      "phone": "5511999999999",
      "status": "DELIVERED",
      "updatedAt": "2026-01-20T10:30:00.000Z"
    }
  ]
}

Boas Práticas

1. Segurança

• Nunca exponha sua API Key no código front-end ou repositórios públicos
• Use variáveis de ambiente para armazenar credenciais
• Implemente rate limiting em sua aplicação
• Valide e sanitize todos os inputs antes de enviar

2. Performance

• Use envio em lote para múltiplos destinatários (até 1000 por vez)
• Implemente retry com backoff exponencial para falhas temporárias
• Cache resultados de consultas de rotas e saldo quando apropriado
• Use webhooks ao invés de polling para atualizações de status

3. Tratamento de Erros

• Sempre verifique o código de status HTTP da resposta
• Implemente tratamento específico para cada tipo de erro
• Log todas as respostas de erro para debugging
• Notifique usuários sobre falhas de forma clara e acionável

4. Monitoramento

• Configure alertas para saldo baixo
• Monitore taxas de entrega e falhas
• Acompanhe tempo de resposta da API
• Mantenha logs de todas as requisições importantes