📗 Manual Interno 02: Integração com API REST v2/v3 Nvoip & Autenticação OAuth2

🛡️ Sentinel Status

  • Classificação: Manual de Engenharia de Integração de Software
  • Versão da API: Nvoip REST API v2 & v3 (Cloud PBX & Messaging Engine)
  • Protocolos: HTTPS / REST / JSON / OAuth2
  • Ambiente de Autenticação: https://auth.nvoip.com.br/oauth2/token
  • Ambiente de Produção Base: https://api.nvoip.com.br/v2 e https://api.nvoip.com.br/v3

1. Arquitetura de Autenticação OAuth2

A API da Nvoip utiliza o padrão da indústria OAuth 2.0 (RFC 6749) com tokens Bearer de curta duração para garantir a segurança no tráfego de telecomunicações.

1.1. Obtenção do Access Token (Fluxo Client Credentials)

Para autenticar sua aplicação, envie uma requisição POST para o endpoint de autenticação:

curl -X POST "https://auth.nvoip.com.br/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=SEU_CLIENT_ID" \
  -d "client_secret=SEU_CLIENT_SECRET"

Resposta JSON (200 OK):

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "calls sms whatsapp managed-accounts billing"
}

[!TIP] Em chamadas subsequentes, inclua o header: Authorization: Bearer eyJhbGciOiJSUzI1Ni...

2. Módulo de Ligações Telefônicas & Click-to-Call

2.1. Realizar Chamada Direta via API

Inicia uma chamada que primeiro toca no ramal interno ou telefone do atendente e, ao atender, disca imediatamente para o cliente final.

Endpoint: POST /calls/

curl -X POST "https://api.nvoip.com.br/v3/calls/" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "caller": "68105001",
    "called": "11987654321",
    "callerId": "4733690000",
    "record": true,
    "maxDuration": 1800
  }'

Parâmetros:

  • caller: Número do ramal interno Nvoip ou telefone SIP de origem.
  • called: Número de destino com DDD (ex: 11987654321).
  • callerId: Identificador de chamada (bina) exibido para o cliente (DID cadastrado).
  • record: Gravação automática da chamada (true ou false).

2.2. Click-to-Call Web

Permite que um visitante no site insira seu telefone e o sistema conecte operador e cliente instantaneamente:

Endpoint: POST /calls/click-to-call

curl -X POST "https://api.nvoip.com.br/v3/calls/click-to-call" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentExtension": "68105001",
    "customerNumber": "47999887766",
    "tag": "lead-site-artesdosul"
  }'

3. Torpedo de Voz (TTS & URA Reversa com DTMF)

O serviço de Torpedo de Voz permite enviar alertas sonoros sintetizados via Text-to-Speech (TTS) ou capturar dados digitados no teclado telefônico pelo cliente.

3.1. Torpedo de Voz Simples (Mensagem TTS)

Endpoint: POST /torpedo/

curl -X POST "https://api.nvoip.com.br/v3/torpedo/" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "11973741227",
    "callerId": "4733690000",
    "message": "Olá! Seu chamado técnico no suporte Artes do Sul foi concluído com sucesso. Obrigado.",
    "voice": "pt-BR-FranciscaNeural",
    "speed": 1.0
  }'

3.2. Torpedo Interativo com Captura de Dígitos DTMF

Ideal para confirmação de agendamentos, pesquisas de satisfação e autenticação por voz:

Endpoint: POST /torpedo/voice

curl -X POST "https://api.nvoip.com.br/v3/torpedo/voice" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "11973741227",
    "message": "Por favor, avalie nosso atendimento. Digite 1 para excelente ou 2 para regular.",
    "maxDigits": 1,
    "timeout": 8,
    "webhookUrl": "https://meu-endpoint.com/webhook/dtmf-result"
  }'

4. Módulo de SMS Corporativo

4.1. Envio de SMS Avulso ou em Lote

Endpoint: POST /sms

curl -X POST "https://api.nvoip.com.br/v3/sms" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "11987654321",
    "message": "Artes do Sul: Seu projeto foi publicado em https://artesdosul.com. Acesse agora.",
    "flash": false
  }'

5. Módulo de WhatsApp Cloud API Oficial

A Nvoip opera integrada à API oficial da Meta (WhatsApp Business Platform), exigindo o uso de templates homologados (HSM - Highly Structured Messages).

5.1. Contrato Moderno Tipado (recipient e BSUID)

Para máxima segurança e compatibilidade com as regras de privacidade da Meta de 2026, a API suporta envio tanto por número de telefone como por identificador de usuário no negócio (BSUID - Business-Scoped User ID):

Endpoint: POST /wa/sendTemplates

curl -X POST "https://api.nvoip.com.br/v3/wa/sendTemplates" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "templateName": "notificacao_chamado_concluido",
    "language": "pt_BR",
    "recipient": {
      "type": "bsuid",
      "bsuid": "wa.biz.usr.9841804928172901"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Roberto" },
          { "type": "text", "text": "#ADS-2026-1042" }
        ]
      }
    ]
  }'

[!CAUTION] Atenção ao usar BSUID: O identificador BSUID é fornecido diretamente pela Meta. Nunca envie @username e nunca coloque BSUID no campo de telefone. Templates de autenticação OTP que não suportam BSUID retornarão o código estável WHATSAPP_BSUID_AUTH_TEMPLATE_UNSUPPORTED.

6. Consulta de Saldo em Tempo Real

Endpoint: GET /balance

curl -X GET "https://api.nvoip.com.br/v3/balance" \
  -H "Authorization: Bearer SEU_TOKEN"

Resposta:

{
  "balance": 245.80,
  "currency": "BRL",
  "creditLimit": 0.00,
  "autoRechargeEnabled": true
}

7. SDKs Oficiais & Bibliotecas Locais

Os desenvolvedores podem utilizar as implementações já construídas e testadas localmente no ecossistema:

  • Node.js / n8n Node: D:\ai-projects\_nvoip\nvoip-n8n\
  • PHP Client Class: D:\ai-projects\_nvoip\nvoip-php\src\NvoipClient.php
  • Shell Script CLI: D:\ai-projects\_nvoip\nvoip-shell\lib\nvoip.sh
  • Postman Collection v3: D:\ai-projects\_nvoip\nvoip-api-v3.postman_collection.json