Configurar SMS com Provedor Customizado (HTTP Genérico)

🔧 Provedor Customizado: Conecte qualquer gateway SMS via HTTP. Ideal para operadoras locais, gateways próprios ou APIs específicas.

Este guia mostra como integrar um provedor SMS genérico à Notifica usando requisições HTTP. Funciona com qualquer API REST que aceite JSON.

Quando usar um provedor customizado

Use esta opção quando:

Você tem um gateway SMS próprio (infraestrutura interna)
Usa uma operadora local (TIM, Vivo, Claro com APIs corporativas)
Precisa de um provedor específico não listado nativamente
Quer controle total sobre o formato da requisição

O que você precisa

URL da API do seu provedor SMS
Método de autenticação (header, query param, etc.)
Documentação da API do provedor
Número de teste para validação

Passo 1: Entender a estrutura da API

Antes de configurar, identifique na documentação do seu provedor:

✅ URL base da API
✅ Método HTTP (POST, GET, PUT)
✅ Formato do corpo da requisição (JSON, form-data)
✅ Header de autenticação
✅ Nome dos campos (to, message, sender)
✅ Estrutura da resposta de sucesso/erro

Exemplo de API típica:

POST https://api.operadora.com.br/v1/sms/send
Content-Type: application/json
Authorization: Bearer seu_token_aqui

{
  "numero": "5511987654321",
  "mensagem": "Olá!",
  "remetente": "SuaEmpresa"
}

Passo 2: Criar o provedor na Notifica

Via Dashboard

Acesse Canais → SMS → Adicionar Provedor
Selecione Provedor Customizado (HTTP Genérico)
Preencha os campos:

Nome: Gateway Operadora Local
URL da API: https://api.operadora.com.br/v1/sms/send
Método HTTP: POST
Header de Autenticação: Bearer seu_token_aqui
Sender ID (opcional): SuaEmpresa

Template do Corpo da Requisição

No campo Body Template, use variáveis Liquid:

{
  "numero": "{{to}}",
  "mensagem": "{{message}}",
  "remetente": "{{from}}",
  "referencia": "{{message_id}}"
}

Via API

curl -X POST https://app.usenotifica.com.br/v1/channels/sms/providers \
  -H "Authorization: Bearer nk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gateway Operadora Local",
    "provider_type": "generic",
    "config": {
      "api_url": "https://api.operadora.com.br/v1/sms/send",
      "http_method": "POST",
      "auth_header": "Bearer seu_token_aqui",
      "body_template": "{\"numero\": \"{{to}}\", \"mensagem\": \"{{message}}\", \"remetente\": \"{{from}}\"}",
      "sender_id": "SuaEmpresa",
      "headers": {
        "Content-Type": "application/json"
      }
    }
  }'

Resposta:

{
  "id": "sms_prov_generic_001",
  "name": "Gateway Operadora Local",
  "provider_type": "generic",
  "status": "pending_validation",
  "config": {
    "api_url": "https://api.operadora.com.br/v1/sms/send",
    "http_method": "POST",
    "sender_id": "SuaEmpresa"
  },
  "created_at": "2024-01-15T10:00:00Z"
}

Passo 3: Variáveis do template

Use estas variáveis no seu body template:

Variável	Descrição	Exemplo
`{{to}}`	Número do destinatário	`+5511987654321`
`{{message}}`	Texto da mensagem	`Seu código é: 123456`
`{{from}}`	Remetente/Sender ID	`SuaEmpresa`
`{{message_id}}`	ID único da Notifica	`msg_abc123`

Exemplos de templates

API com campos em português:

{
  "destino": "{{to}}",
  "texto": "{{message}}",
  "origem": "{{from}}"
}

API com formato diferente:

{
  "phone": "{{to}}",
  "content": "{{message}}",
  "sender": "{{from}}",
  "id": "{{message_id}}"
}

API com query params (GET):

https://sms.gateway.com/send?to={{to}}&msg={{message}}&from={{from}}

Passo 4: Mapeamento de resposta

Configure como interpretar a resposta da API:

Via Dashboard

Em Mapeamento de Resposta, defina:

Campo de ID: id
Campo de Status: status
Valor de Sucesso: sent,ok,success
Valor de Falha: error,failed,rejected

Via API

curl -X PATCH https://app.usenotifica.com.br/v1/channels/sms/providers/sms_prov_generic_001 \
  -H "Authorization: Bearer nk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "response_mapping": {
      "message_id_field": "id",
      "status_field": "status",
      "success_values": ["sent", "ok", "success", "queued"],
      "failure_values": ["error", "failed", "rejected", "invalid"]
    }
  }'

Exemplos de respostas comuns

Sucesso:

{
  "id": "SMS123456",
  "status": "sent",
  "timestamp": "2024-01-15T10:00:00Z"
}

Falha:

{
  "error": true,
  "code": "INVALID_NUMBER",
  "message": "Número não encontrado"
}

Passo 5: Validar configuração

Teste a conectividade com o provedor:

curl -X POST https://app.usenotifica.com.br/v1/channels/sms/providers/validate \
  -H "Authorization: Bearer nk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_type": "generic",
    "config": {
      "api_url": "https://api.operadora.com.br/v1/sms/send",
      "http_method": "POST",
      "auth_header": "Bearer seu_token_aqui"
    }
  }'

Resposta:

{
  "valid": true,
  "details": {
    "api_reachable": true,
    "auth_valid": true,
    "test_response": {
      "status": "ok",
      "balance": "500.00"
    }
  }
}

Passo 6: Testar envio

Via Dashboard

Vá em Canais → SMS → Provedor → Testar

Via API

curl -X POST https://app.usenotifica.com.br/v1/channels/sms/providers/sms_prov_generic_001/test \
  -H "Authorization: Bearer nk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+5511987654321",
    "message": "Teste de integração Notifica + Gateway Customizado! ✅"
  }'

Resposta:

{
  "success": true,
  "provider_message_id": "SMS123456",
  "raw_response": {
    "id": "SMS123456",
    "status": "sent"
  }
}

Passo 7: Configurar webhooks (status de entrega)

Para receber atualizações de entrega, configure o webhook na sua operadora:

URL de Webhook

https://app.usenotifica.com.br/webhooks/sms/generic/:tenant_id

Substitua :tenant_id pelo ID do seu tenant (disponível nas configurações).

Exemplo de callback da operadora

A Notifica espera receber:

POST https://app.usenotifica.com.br/webhooks/sms/generic/tenant_abc123
Content-Type: application/json

{
  "message_id": "SMS123456",
  "status": "delivered",
  "timestamp": "2024-01-15T10:00:05Z",
  "phone": "+5511987654321"
}

Status suportados

Status	Significado
`sent`	Enviado para operadora
`delivered`	Entregue no celular
`failed`	Falha na entrega
`rejected`	Rejeitado

Enviando SMS via API

Após configurado, use normalmente:

curl -X POST https://app.usenotifica.com.br/v1/notifications \
  -H "Authorization: Bearer nk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "to": {
      "phone": "+5511987654321"
    },
    "channel": "sms",
    "content": "Seu pedido foi confirmado! 🛍️"
  }'

Node.js

async function sendSMS(phone, message) {
  const response = await fetch('https://app.usenotifica.com.br/v1/notifications', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.NOTIFICA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      to: { phone },
      channel: 'sms',
      content: message
    })
  });
  
  return response.json();
}

// Exemplos
await sendSMS('+5511987654321', 'Bem-vindo à nossa plataforma!');
await sendSMS('+5511998765432', 'Sua fatura vence amanhã.');

Python

import requests

API_KEY = "nk_live_sua_chave"
BASE_URL = "https://app.usenotifica.com.br/v1"

def send_sms(phone: str, message: str):
    response = requests.post(
        f"{BASE_URL}/notifications",
        headers={'Authorization': f'Bearer {API_KEY}'},
        json={
            'to': {'phone': phone},
            'channel': 'sms',
            'content': message
        }
    )
    return response.json()

# Enviar notificação
result = send_sms('+5511987654321', 'Seu agendamento foi confirmado!')
print(result)

Configurações avançadas

Timeout e retry

curl -X PATCH https://app.usenotifica.com.br/v1/channels/sms/providers/sms_prov_generic_001 \
  -H "Authorization: Bearer nk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "timeout_ms": 30000,
      "retry_count": 3,
      "retry_delay_ms": 1000
    }
  }'

Headers customizados

{
  "config": {
    "headers": {
      "X-Custom-Header": "valor",
      "X-Api-Version": "v2"
    }
  }
}

Autenticação por query parameter

{
  "config": {
    "api_url": "https://api.operadora.com/send",
    "query_params": {
      "api_key": "sua_chave_aqui",
      "user": "seu_usuario"
    }
  }
}

Troubleshooting

Erros comuns

Erro	Causa	Solução
`TIMEOUT`	API demorou para responder	Aumente `timeout_ms` ou verifique a API
`INVALID_AUTH`	Token inválido	Verifique o `auth_header`
`INVALID_RESPONSE`	Resposta não mapeada	Ajuste `response_mapping`
`TEMPLATE_ERROR`	Variável não encontrada	Use apenas: `{{to}}`, `{{message}}`, `{{from}}`
`HTTP_ERROR`	Erro 4xx/5xx da API	Verifique URL e credenciais

Debug de requisições

Para ver logs detalhados:

curl https://app.usenotifica.com.br/v1/channels/sms/providers/sms_prov_generic_001/logs \
  -H "Authorization: Bearer nk_live_sua_chave"

Testando manualmente

Teste sua API diretamente antes de configurar:

curl -X POST https://api.operadora.com.br/v1/sms/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer seu_token" \
  -d '{
    "numero": "+5511987654321",
    "mensagem": "Teste manual",
    "remetente": "Teste"
  }'

Perguntas frequentes

Q: Posso usar autenticação diferente de Bearer?
A: Sim! Use qualquer formato no auth_header: Basic base64, ApiKey key, etc.

Q: Funciona com APIs SOAP/XML?
A: No momento apenas JSON é suportado nativamente. Para SOAP, use um middleware.

Q: Como faço fallback entre provedores?
A: Configure múltiplos provedores e defina prioridades nas configurações de roteamento.

Q: Posso usar variáveis customizadas no template?
A: Não. Use apenas as variáveis documentadas: {{to}}, {{message}}, {{from}}, {{message_id}}.

Próximo passo

Configure o Compliance SMS para garantir conformidade com LGPD e boas práticas.

Para outras opções de provedor, veja:

Quando usar um provedor customizado​

O que você precisa​

Passo 1: Entender a estrutura da API​

Passo 2: Criar o provedor na Notifica​

Via Dashboard​

Template do Corpo da Requisição​

Via API​

Passo 3: Variáveis do template​

Exemplos de templates​

API com campos em português:​

API com formato diferente:​

API com query params (GET):​

Passo 4: Mapeamento de resposta​

Via Dashboard​

Via API​

Exemplos de respostas comuns​

Passo 5: Validar configuração​

Passo 6: Testar envio​

Via Dashboard​

Via API​

Passo 7: Configurar webhooks (status de entrega)​

URL de Webhook​

Exemplo de callback da operadora​

Status suportados​

Enviando SMS via API​

Node.js​

Python​

Configurações avançadas​

Timeout e retry​

Headers customizados​

Autenticação por query parameter​

Troubleshooting​

Erros comuns​

Debug de requisições​

Testando manualmente​

Perguntas frequentes​

Próximo passo​

Quando usar um provedor customizado

O que você precisa

Passo 1: Entender a estrutura da API

Passo 2: Criar o provedor na Notifica

Via Dashboard

Template do Corpo da Requisição

Via API

Passo 3: Variáveis do template

Exemplos de templates

API com campos em português:

API com formato diferente:

API com query params (GET):

Passo 4: Mapeamento de resposta

Via Dashboard

Via API

Exemplos de respostas comuns

Passo 5: Validar configuração

Passo 6: Testar envio

Via Dashboard

Via API

Passo 7: Configurar webhooks (status de entrega)

URL de Webhook

Exemplo de callback da operadora

Status suportados

Enviando SMS via API

Node.js

Python

Configurações avançadas

Timeout e retry

Headers customizados

Autenticação por query parameter

Troubleshooting

Erros comuns

Debug de requisições

Testando manualmente

Perguntas frequentes

Próximo passo