novauth
PreçosDocumentaçãoComece grátis
Referência

Referência da API

Referência completa de todos os endpoints de verificação da Novauth. Todos os canais partilham o mesmo modelo de autenticação e a mesma URL base — só a rota e o payload diferem.

BASE URLhttps://api.novauth.com/api/v1/connect-hub

Autenticação

Cada pedido deve incluir dois cabeçalhos. Pode encontrar as suas credenciais na secção Programador → Chaves de API do painel. As credenciais são guardadas em cache do lado do servidor durante 5 minutos, pelo que as chaves recém-criadas ficam ativas em segundos.

x-api-keyA sua chave de API. Trate-a como uma palavra-passe — nunca a exponha em código do lado do cliente.
x-account-idO identificador da sua conta. Aparece no painel ao lado de cada chave de API.
x-request-idID de correlação opcional. Passe qualquer UUID; é devolvido nas respostas de erro para facilitar o rastreio.

Guarde as credenciais em variáveis de ambiente (BETATEL_API_KEY, BETATEL_ACCOUNT_ID). Nunca as escreva diretamente nos ficheiros de código.

As chaves com o prefixo sk_test_ são chaves de sandbox — nunca tocam em operadoras reais nem geram custos. Use-as durante o desenvolvimento e depois troque pela sua chave BTEL_ quando passar a produção. Modo sandbox →

Lista de IPs autorizados

Ao criar uma chave de API, pode opcionalmente associar um ou mais endereços IP ou intervalos CIDR. Se estiver configurada uma lista de IPs autorizados, qualquer pedido proveniente de um IP fora da lista é rejeitado com 401 Unauthorized, mesmo que a chave de API seja válida. Isto permite restringir uma chave ao IP do seu servidor, para que não possa ser usada em caso de fuga.

Exemplo de pedido autenticado
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/call/flash \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{"callee": "+14155552671"}'

Verify Call

Inicia uma chamada de curta duração que toca e desliga. O ID de chamada codifica o OTP — o seu SDK móvel lê o número recebido sem que o utilizador tenha de atender.

Enviar um Verify Call
POST/api/v1/connect-hub/call/flash
Corpo do pedido
calleestringobrigatório
Telefone do destinatário em formato E.164 (p. ex. +14155552671).
callerstring
ID de chamada em formato E.164. Por predefinição, usa-se o número configurado na conta.
max_ring_timenumber
Duração do toque em segundos antes de desligar automaticamente. Por predefinição, um valor aleatório entre os tempos de toque mínimo e máximo da conta.
Resposta — 200 OK
uuidstring (ULID)
Identificador único da chamada. Guarde-o — é necessário para consultar o CDR e para os relatórios via webhook.
callerstring
ID de chamada realmente usado (pode diferir do pedido se foi aplicada a predefinição).
calleestring
Número do destinatário (eco).
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/call/flash \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "callee": "+14155552671",
    "caller": "+38761000001",
    "max_ring_time": 5
  }'

# Response:
# {
#   "uuid": "01KAK9KATW01A437PSXS5EVDCR",
#   "caller": "+38761000001",
#   "callee": "+14155552671"
# }
Obter registo detalhado de chamada
GET/api/v1/connect-hub/call/flash/:uuid/cdr
Resposta — 200 OK
hangup_causestring
Motivo de desligamento SIP (p. ex. NORMAL_CLEARING, NO_ANSWER, ORIGINATOR_CANCEL).
durationnumber
Duração total da chamada em segundos (toque + ligado).
billsecnumber
Duração faturada em segundos (do atendimento ao desligamento).
pddnumber
Atraso pós-marcação em segundos (tempo até ao primeiro toque).
destination_countrystring
Nome do país de destino resolvido.
start_stampstring (ISO 8601)
Marca temporal UTC do início da chamada.
bash
curl https://api.novauth.com/api/v1/connect-hub/call/flash/01KAK9KATW01A437PSXS5EVDCR/cdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID"

# Response:
# {
#   "uuid": "01KAK9KATW01A437PSXS5EVDCR",
#   "caller": "+38761000001",
#   "callee": "+14155552671",
#   "hangup_cause": "NORMAL_CLEARING",
#   "duration": 6,
#   "billsec": 0,
#   "pdd": 2,
#   "start_stamp": "2024-06-01T10:30:00.000Z",
#   "destination_country": "United States",
#   "destination_country_code": "US"
# }
Listar registos de chamadas
POST/api/v1/connect-hub/call/flash/cdr

Devolve uma lista paginada de todas as chamadas da sua conta. Use filter para restringir os resultados por qualquer campo do CDR (p. ex. callee, hangup_cause).

Corpo do pedido
pagenumber
Número da página (mínimo: 1, predefinição: 1).
rows_per_pagenumber
Registos por página (1–100, predefinição: 20).
sort_bystring
Campo pelo qual ordenar (p. ex. start_stamp, callee).
sort_direction"ASC" | "DESC"
Ordem de ordenação.
filterobject
Filtros chave/valor opcionais aplicados aos campos do CDR.
Resposta — 200 OK
totalnumber
Total de registos que correspondem ao filtro.
total_pagesnumber
Número total de páginas.
has_next_pageboolean
Indica se existe uma página seguinte.
has_previous_pageboolean
Indica se existe uma página anterior.
listCDR[]
Array de registos detalhados de chamada da página atual.
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/call/flash/cdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "rows_per_page": 20,
    "sort_by": "start_stamp",
    "sort_direction": "DESC"
  }'
Desligar uma chamada
DELETE/api/v1/connect-hub/call/flash/:uuid

Termina uma chamada ativa antes de esta terminar naturalmente. Devolve 204 No Content em caso de sucesso.

bash
# Terminate an active call before it naturally ends
curl -X DELETE https://api.novauth.com/api/v1/connect-hub/call/flash/01KAK9KATW01A437PSXS5EVDCR \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID"

# Returns 204 No Content on success

SMS

Entrega uma mensagem de texto via SMPP. Normalmente usada para enviar um código OTP numérico que o utilizador digita na sua aplicação.

Enviar um SMS
POST/api/v1/connect-hub/sms
Corpo do pedido
tostringobrigatório
Telefone do destinatário em formato E.164.
textstringobrigatório
Corpo da mensagem. Até 4096 caracteres; as mensagens mais longas são divididas em partes concatenadas.
fromstring
Sender ID (alfanumérico ou telefone). Por predefinição, o remetente configurado na conta.
Resposta — 200 OK
messageIdstring (UUID)
Identificador único da mensagem. Guarde-o — é necessário para consultar o SDR e para os relatórios via webhook.
fromstring
Sender ID utilizado.
tostring
Número do destinatário (eco).
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/sms \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "text": "Your verification code is 482910. Valid for 5 minutes.",
    "from": "Novauth"
  }'

# Response:
# {
#   "messageId": "0a62face-6d15-11f0-962f-d89d6729654c",
#   "from": "Novauth",
#   "to": "14155552671"
# }
Obter estado da mensagem
GET/api/v1/connect-hub/sms/:messageId/sdr

Consulta o estado de entrega de uma mensagem enviada. O estado é atualizado de forma assíncrona à medida que chegam os relatórios de entrega das operadoras (DLRs).

Resposta — valores de estado
deliveredEntrega confirmada no telefone.
sentEnviado à operadora; a aguardar o DLR.
failedEntrega falhada (número inválido, bloqueado).
undeliveredA operadora aceitou, mas a entrega não foi confirmada.
bash
curl https://api.novauth.com/api/v1/connect-hub/sms/0a62face-6d15-11f0-962f-d89d6729654c/sdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID"

# Response:
# {
#   "uuid": "...",
#   "messageId": "0a62face-6d15-11f0-962f-d89d6729654c",
#   "from": "Novauth",
#   "to": "+14155552671",
#   "status": "delivered",
#   "timestamp": "2024-06-01T10:30:00.000Z"
# }
Listar mensagens
POST/api/v1/connect-hub/sms/sdr

Devolve uma lista paginada de todas as mensagens enviadas. Aceita o mesmo corpo de paginação dos outros endpoints de listagem (page, rows_per_page, sort_by, filter).

bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/sms/sdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "rows_per_page": 20,
    "sort_direction": "DESC"
  }'

OTP do Telegram

Envia um OTP numérico através da Gateway API oficial do Telegram. Suporta verificações de entregabilidade, validação do código do lado do servidor e revogação com reembolso automático.

Enviar OTP do Telegram
POST/api/v1/connect-hub/telegram
Corpo do pedido
tostringobrigatório
Telefone do destinatário em formato E.164.
codestringobrigatório
Código OTP a entregar (4–8 dígitos).
ttlnumber
Validade do código em segundos (30–3600). Predefinição: 300.
sender_usernamestring
Nome de utilizador de canal Telegram verificado. Omita para usar a predefinição da conta.
callback_urlstring
Substituição de webhook por pedido. O Telegram Gateway fará POST dos eventos de estado diretamente para este URL.
Resposta — 200 OK
uuidstring (ULID)
ID de correlação da Novauth. Use-o para os relatórios via webhook.
request_idstring
ID de pedido do Telegram Gateway. Use-o para consultas de estado e revogação.
statusstring
Estado de entrega normalizado (sent, delivered, …).
request_costnumber
Custo deste pedido em EUR.
remaining_balancenumber
Saldo da conta após o débito.
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "code": "482910",
    "ttl": 300
  }'

# Response:
# {
#   "uuid": "01KNV9CWW9ZEYVDFBJ1N7M1DVR",
#   "request_id": "tg_req_abc123",
#   "to": "14155552671",
#   "status": "sent",
#   "request_cost": 0.05,
#   "remaining_balance": 49.95
# }
Verificar alcançabilidade
POST/api/v1/connect-hub/telegram/check-send-ability

Sonda se o número tem uma conta Telegram antes do envio. Se is_refunded for true, o utilizador não tem conta Telegram — o custo da sondagem é reembolsado e deve recorrer ao fallback por SMS ou Verify Call.

bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram/check-send-ability \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{"to": "+14155552671"}'

# Response:
# {
#   "request_id": "tg_req_abc123",
#   "phone_number": "14155552671",
#   "request_cost": 0.01,
#   "is_refunded": false,
#   "remaining_balance": 49.99,
#   "delivery_status": { "status": "sent", "updated_at": 1713350400 }
# }
Verificar estado da verificação
POST/api/v1/connect-hub/telegram/check-verification-status

Consulta o resultado da introdução do código para um dado request_id. Opcionalmente, passe o code introduzido pelo utilizador para validação do lado do servidor.

valores de verification_status
code_validO utilizador introduziu o código correto.
code_invalidO utilizador introduziu um código errado.
code_max_attempts_exceededDemasiadas tentativas falhadas.
expiredO TTL do código expirou antes da introdução.
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram/check-verification-status \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "tg_req_abc123",
    "code": "482910"
  }'

# Response:
# {
#   "request_id": "tg_req_abc123",
#   "verification_status": {
#     "status": "code_valid",
#     "updated_at": 1713350400
#   }
# }
Revogar verificação
POST/api/v1/connect-hub/telegram/revoke-verification

Cancela um pedido OTP ativo antes de o utilizador o concluir. Se a mensagem ainda não tiver sido lida, is_refunded será true e o valor é devolvido ao seu saldo.

bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram/revoke-verification \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "tg_req_abc123"}'

# Response:
# {
#   "request_id": "tg_req_abc123",
#   "is_refunded": true,
#   "remaining_balance": 50.0
# }
Obter registo de entrega
GET/api/v1/connect-hub/telegram/:uuid/tdr

Obtém o registo de entrega do Telegram completo para um dado uuid (o ID de correlação da Novauth devolvido pelo endpoint de envio). Inclui estado de entrega, estado de verificação, custo e país.

bash
curl https://api.novauth.com/api/v1/connect-hub/telegram/01KNV9CWW9ZEYVDFBJ1N7M1DVR/tdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID"

# Response includes full TDR:
# {
#   "uuid": "01KNV9CWW9ZEYVDFBJ1N7M1DVR",
#   "to": "+14155552671",
#   "status": "DELIVERED",
#   "delivery_status": "delivered",
#   "verification_status": "code_valid",
#   "request_cost": 0.05,
#   "country": "United States",
#   "created_at": "2024-06-01T10:30:00.000Z"
# }
Listar registos de entrega
POST/api/v1/connect-hub/telegram/tdr

Devolve uma lista paginada de todos os registos de entrega do Telegram. Filtre por <code>verification_status</code>, <code>delivery_status</code> ou qualquer outro campo do TDR.

bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram/tdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "rows_per_page": 20,
    "sort_direction": "DESC"
  }'

WhatsApp

Envia uma mensagem OTP através da API do WhatsApp Business. O utilizador lê o código na conversa de WhatsApp e digita-o na sua aplicação.

Enviar OTP do WhatsApp
POST/api/v1/connect-hub/whatsapp/otp
Corpo do pedido
tostringobrigatório
Telefone do destinatário em formato E.164.
textstringobrigatório
Corpo da mensagem. Inclua o código OTP e uma indicação de validade.
Resposta — 200 OK
uuidstring (ULID)
Identificador único da mensagem. Guarde-o — é necessário para os relatórios via webhook.
tostring
Número do destinatário (eco).
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/whatsapp/otp \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "text": "Your verification code is 482910. Valid for 5 minutes."
  }'

# Response:
# {
#   "uuid": "01KAK9KATW01A437PSXS5EVDCR",
#   "to": "+14155552671"
# }

Após o envio, comunique o resultado da verificação do utilizador via POST /whatsapp/webhook. Consulte a referência de Webhooks para mais detalhes.

Obter registo de entrega
GET/api/v1/connect-hub/whatsapp/:uuid/wdr

Obtém o registo de entrega do WhatsApp para um dado uuid devolvido pelo endpoint de envio.

bash
curl https://api.novauth.com/api/v1/connect-hub/whatsapp/01KAK9KATW01A437PSXS5EVDCR/wdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID"

# Response:
# {
#   "uuid": "01KAK9KATW01A437PSXS5EVDCR",
#   "to": "+14155552671",
#   "status": "DELIVERED",
#   "created_at": "2024-06-01T10:30:00.000Z"
# }
Listar registos de entrega
POST/api/v1/connect-hub/whatsapp/wdr

Devolve uma lista paginada de todos os registos de entrega do WhatsApp. Suporta o mesmo corpo <code>page</code>, <code>rows_per_page</code>, <code>filter</code> de todos os outros endpoints de listagem.

bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/whatsapp/wdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "rows_per_page": 20,
    "sort_direction": "DESC"
  }'

Códigos de erro

Todas as respostas de erro seguem o mesmo envelope JSON. O campo error contém uma string legível por máquina; indique o seu x-request-id ao suporte quando comunicar problemas.

EstadoCódigoDescrição
400BAD_REQUESTCorpo do pedido inválido — campo obrigatório em falta, formato errado ou número de telefone inválido.
401UNAUTHORIZEDCabeçalhos x-api-key / x-account-id em falta ou inválidos.
402PAYMENT_REQUIREDSaldo da conta insuficiente. Carregue a sua conta para continuar.
403FORBIDDENA chave de API existe, mas não tem permissão para esta operação.
404NOT_FOUNDO UUID ou recurso solicitado não existe.
409CONFLICTPedido duplicado ou estado em conflito (p. ex. revogar um pedido já expirado).
480TEMPORARY_UNAVAILABLEGateway temporariamente inacessível. Repita com back-off exponencial.
486BUSY_HERE(Verify Call) O destinatário está ocupado ou a chamada foi rejeitada pela rede.
500INTERNAL_SERVER_ERRORErro inesperado do servidor. Contacte o suporte com o seu x-request-id.
503SERVICE_UNAVAILABLEGateway desligado ou serviço em manutenção. Consulte a página de estado.
603DECLINE(Verify Call) O destinatário recusou explicitamente a chamada.

Para a lista completa de códigos de erro, incluindo passos de correção sugeridos, consulte o guia de gestão de erros.