Códigos de verificação

O endpoint de códigos de verificação permite enviar códigos de verificação de uso único (OTP) para números de telefone através de múltiplos canais de entrega. Suporta uma estratégia de roteamento em várias etapas com fallback automático — se um canal falhar ou expirar, o próximo canal é tentado automaticamente.

• Criar um pedido de código de verificação com uma estratégia de roteamento flexível
• Suporte para canais de entrega Telegram, Voz (texto para fala) e SMS
• Fallback automático entre canais em caso de falha ou tempo limite
• Consultar o estado do código de verificação, histórico de entrega e informações de custo
• Eliminar códigos de verificação do armazenamento após a entrega por segurança

Como funciona

Ao criar um pedido de código de verificação, define uma estratégia de roteamento — uma lista ordenada de canais de entrega a tentar. O sistema processa cada canal por ordem:

1. Envia o código de verificação através do primeiro canal (ex. Telegram).
2. Telegram: aguarda uma confirmação de entrega da API do Telegram dentro de timeout_sec. Voz: faz uma tentativa de chamada; o sucesso ocorre se o destinatário atender. SMS: é considerado bem-sucedido assim que a mensagem é aceite pela rede móvel.
3. Se o canal falhar ou expirar, recua automaticamente para o próximo canal.
4. Repete até que um canal seja bem-sucedido ou todos os canais sejam esgotados.

Estratégia de roteamento

Cada etapa na estratégia de roteamento especifica um channel e parâmetros opcionais. Todos os parâmetros exceto channel são opcionais — valores padrão sensatos são usados quando omitidos.

Canal	Parâmetros	Critério de sucesso	Notas
telegram	timeout_sec	Confirmação de entrega recebida do Telegram dentro de timeout_sec	timeout_sec: mín 30, máx 3600, padrão 30.
voice	sender_id, template	O destinatário atendeu à chamada	Chamada de texto para fala. Apenas uma tentativa de chamada é feita. O modelo é automaticamente envolvido em tags SSML <speak>.
sms	sender_id, template	O SMS foi aceite para entrega pela rede	Entrega padrão por SMS. Só pode ser a última etapa na estratégia de roteamento.

Regras:

• Pelo menos um canal é obrigatório.
• Canais duplicados não são permitidos.
• O canal sms só pode ser a última etapa (sem fallback após SMS).
• O parâmetro timeout_sec é apenas aplicável para o canal telegram.

Otimização de custos

O custo total de um pedido de código de verificação é a soma de todas as mensagens enviadas por todos os canais que foram tentados — mesmo que alguns canais tenham falhado. Cada tentativa de canal incorre num custo por mensagem.

Recomendação: Ordene a sua estratégia de roteamento do canal mais económico para o mais caro. Por exemplo, coloque telegram primeiro (custo mais baixo), depois voice e sms por último. Desta forma, se o canal mais económico for bem-sucedido, evita pagar pelos mais caros.

Bloqueio e filtragem

Antes de tentar a entrega, o sistema verifica o número de telefone do destinatário contra as restrições da sua conta:

• Números de telefone bloqueados: Se o número do destinatário estiver na sua lista de números bloqueados, a mensagem não será enviada.
• Filtros SMS: Se o número do destinatário corresponder a qualquer um dos seus filtros SMS, a mensagem não será enviada.

Quando uma mensagem é bloqueada por um filtro ou número bloqueado, a etapa do canal e a tarefa geral recebem o estado 20 (Falhado). Não é tentado o fallback para o próximo canal neste caso.

Código de verificação

O código de verificação é uma cadeia numérica (4–8 dígitos) enviada ao destinatário:

• Código personalizado: Forneça o seu próprio código através da propriedade code (4–8 caracteres).
• Gerado automaticamente: Se code não for fornecido, um código numérico aleatório é gerado. Controle o comprimento com code_length (padrão: 4, intervalo: 4–8).

Use a propriedade template por canal para personalizar o texto da mensagem. O espaço reservado {{code}} é substituído pelo código de verificação real. Se nenhum modelo for fornecido, é usada uma mensagem traduzida padrão com base no campo lang.

Segurança: Eliminar código após o envio

Defina is_code_deleted como true para eliminar automaticamente o código de verificação do armazenamento LOX24 após este ter sido enviado ao destinatário. Isto garante que o código não é retido na base de dados após a entrega.

IMPORTANTE: Quando is_code_deleted está ativo, o campo code estará ausente nas respostas GET subsequentes após a conclusão da tarefa.

Códigos de estado

Tanto a tarefa geral como cada canal individual usam os mesmos valores de estado, mas a semântica difere:

Estado da tarefa (status de nível superior):

Estado	Significado
0	Novo — pedido criado, ainda não processado
5	Em andamento — entrega em curso
10	Sucesso — código entregue com sucesso através de pelo menos um canal
20	Falhado — a entrega falhou em todos os canais
100	Erro — erro do sistema

Estado do canal (history[].status):

Estado	Significado
0	Novo — etapa do canal criada, ainda não processada
5	Em andamento — envio através deste canal
10	Sucesso — entrega confirmada neste canal
20	Falhado — a entrega falhou neste canal
100	Erro — erro do sistema neste canal

Notificações Webhook

Eventos de códigos de verificação podem ser enviados para o seu endpoint de webhook. Os seguintes eventos estão disponíveis:

• verify_code.success — o código foi entregue com sucesso
• verify_code.failed — a entrega falhou em todos os canais
• verify_code.channel.sent — código enviado através de um canal específico
• verify_code.channel.success — o canal confirmou a entrega com sucesso
• verify_code.channel.failed — o canal falhou na entrega
• verify_code.channel.updated — estado do canal atualizado

Consulte a secção Notificações Webhook para mais detalhes sobre a configuração de endpoints de webhook.