Pular para o conteúdo

Criar um código de verificação

POST
/verify_codes

Inicia um processo de verificação criando um novo código de verificação com uma estratégia de roteamento especificada.

The verify code request payload

Media type application/json

Payload de escrita do código de verificação. Cria um novo pedido de código de verificação com uma estratégia de roteamento em várias etapas.

object
phone
required

Número de telefone do destinatário em formato internacional (ex. +491701234567).

string
>= 5 characters <= 30 characters
code

Código de verificação personalizado. Se não for fornecido, um código numérico aleatório é gerado automaticamente com base em code_length.

string | null
>= 4 characters <= 8 characters
code_length

Comprimento do código de verificação gerado automaticamente. Usado apenas quando code não é fornecido. Padrão: 4.

integer | null
default: 4 >= 4 <= 8
lang

Idioma para o modelo de mensagem padrão. Determina o idioma do texto SMS/Voz gerado automaticamente quando nenhum template personalizado é fornecido. Não se aplica ao canal telegram — o Telegram sempre envia uma mensagem do sistema no idioma da aplicação Telegram do utilizador.

string
default: DE
Allowed values: EN DE FR IT ES PL NL RO PT CS HU SV DA FI SK HR TR RU BG UK
payload

Dados personalizados que serão armazenados com o código de verificação e retornados nos eventos de webhook. Útil para correlacionar pedidos de verificação com os seus sistemas internos.

string | null
<= 128 characters
is_code_deleted

Se verdadeiro, o código de verificação será eliminado do armazenamento após ser enviado ao destinatário. Padrão: false.

boolean | null
routing_strategy
required

Lista ordenada de canais de entrega. Cada etapa define um canal a tentar. Se um canal falhar ou expirar, a próxima etapa é tentada. Pelo menos uma etapa é necessária. O canal sms só pode ser a última etapa. Canais duplicados não são permitidos.

Array
>= 1 items
One of: discriminator: channel

Etapa de roteamento do Telegram. Entrega o código de verificação através de uma mensagem do bot do Telegram.

object
channel
required

Canal de entrega: Telegram.

string
Allowed values: telegram
timeout_sec

Tempo em segundos para aguardar uma resposta do Telegram antes de recuar para a próxima etapa. Se não definido, é usado um padrão do sistema.

integer | null
default: 30 >= 30 <= 3600
Examples

Verify code with multi-channel routing

Create a verification code with a 3-step routing strategy: Telegram, Voice, and SMS.

{
"phone": "+491701234567",
"code": "1234",
"is_code_deleted": false,
"payload": "yours payload here",
"lang": "EN",
"routing_strategy": [
{
"channel": "telegram",
"timeout_sec": 30
},
{
"channel": "voice",
"sender_id": "LOX24",
"template": "Your code is {{code}}"
},
{
"channel": "sms",
"sender_id": "LOX24",
"template": "Your code is {{code}}"
}
]
}

Verify code created and delivery process started

Resposta de leitura do código de verificação. Contém os detalhes completos do pedido de código de verificação, incluindo o estado atual, histórico de entrega e informações de custo.

object
id

Identificador único (UUID) do pedido de código de verificação.

string
user_id

ID do utilizador que criou o pedido de código de verificação.

integer
phone

Número de telefone do destinatário em formato internacional.

string
code

O valor do código de verificação. Se is_code_deleted foi definido e a tarefa concluída, o código estará ausente.

string | null
code_length

Comprimento do código de verificação.

integer | null
lang

Idioma usado para o modelo de mensagem.

string
Allowed values: EN DE FR IT ES PL NL RO PT CS HU SV DA FI SK HR TR RU BG UK
routing_strategy

Lista ordenada de canais de entrega que foram configurados para este pedido.

Array
One of: discriminator: channel

Etapa de roteamento do Telegram. Entrega o código de verificação através de uma mensagem do bot do Telegram.

object
channel
required

Canal de entrega: Telegram.

string
Allowed values: telegram
timeout_sec

Tempo em segundos para aguardar uma resposta do Telegram antes de recuar para a próxima etapa. Se não definido, é usado um padrão do sistema.

integer | null
default: 30 >= 30 <= 3600
status

Estado atual do código de verificação: 0 = Novo, 5 = Em andamento, 10 = Sucesso, 20 = Falhado, 100 = Erro.

integer
Allowed values: 0 5 10 20 100
delivered_channel

O canal que entregou com sucesso o código de verificação. Null se ainda não foi entregue ou se a entrega falhou.

string | null
Allowed values: telegram voice sms
cost

Custo total do pedido de verificação em cêntimos de euro. Null até que o processamento seja concluído.

integer | null
currency

Código da moeda para o custo.

string | null
payload

Dados de payload personalizados do pedido original.

string | null
created_at

Timestamp Unix de quando o código de verificação foi criado.

integer
updated_at

Timestamp Unix da última atualização.

integer
history

Histórico de processamento para cada tentativa de canal. Uma entrada por etapa de roteamento.

Array<object>
object
id

UUID da entrada do histórico.

string
channel

Tipo de canal para esta tentativa.

string
Allowed values: telegram voice sms
status

Estado desta tentativa de canal: 0 = Novo, 5 = Em andamento, 10 = Sucesso, 20 = Falhado, 100 = Erro.

integer
processed_at

Timestamp Unix de quando esta etapa foi processada.

integer
external_id

ID da mensagem do provedor externo.

string | null
is_code_deleted

Se o código de verificação foi eliminado do armazenamento após ser enviado ao destinatário.

boolean | null
Examples
Example multi_channel

Verify code response with multi-channel routing

Successful response after creating a verification code with a 3-step routing strategy. Telegram and voice channels failed, SMS succeeded.

{
"id": "d7ad7539-fb8f-4dbb-a7f7-7c40babec969",
"user_id": 12345,
"phone": "+491701234567",
"routing_strategy": [
{
"channel": "telegram",
"timeout_sec": 30
},
{
"channel": "voice",
"sender_id": "LOX24",
"template": "Your code is {{code}}"
},
{
"channel": "sms",
"sender_id": "LOX24",
"template": "Your code is {{code}}"
}
],
"status": 10,
"delivered_channel": "sms",
"cost": 120,
"currency": "EUR",
"code": "1234",
"code_length": 4,
"payload": "yours payload here",
"lang": "EN",
"created_at": 1779903448,
"updated_at": 1779903510,
"history": [
{
"id": "bccaff09-59f2-11f1-a685-7c10c91d54a1",
"channel": "telegram",
"status": 20,
"processed_at": 1779903478,
"external_id": "tg_msg_001"
},
{
"id": "bccaff09-59f2-11f1-a685-7c10c91d54a2",
"channel": "voice",
"status": 20,
"processed_at": 1779903490,
"external_id": "voice_msg_002"
},
{
"id": "bccaff09-59f2-11f1-a685-7c10c91d54a3",
"channel": "sms",
"status": 10,
"processed_at": 1779903510,
"external_id": "sms_msg_003"
}
],
"is_code_deleted": false
}

Invalid input

Client ID or API key isn’t active or invalid!

There are not enough funds on your account!

Account isn’t activated. Please wait or contact to support!

The request was well-formed but was unable to be followed due to semantic errors

O endereço IP foi bloqueado temporariamente, pois durante um curto período de tempo foram enviadas várias solicitações com credenciais inválidas. Aguarde e tente mais tarde.

Code Samples

#!/usr/bin/env bash
curl -X POST https://api.lox24.eu/verify_codes \
-H 'Content-Type: application/json' \
-H 'X-LOX24-AUTH-TOKEN: 1234567:e3f3a759b6677959b6ebfcxxxxxxxxxx' \
-d '{
"phone": "+491701234567",
"code": "1234",
"is_code_deleted": false,
"payload": "yours payload here",
"lang": "EN",
"routing_strategy": [
{
"channel": "telegram",
"timeout_sec": 30
},
{
"channel": "voice",
"sender_id": "LOX24",
"template": "Your code is {{code}}"
},
{
"channel": "sms",
"sender_id": "LOX24",
"template": "Your code is {{code}}"
}
]
}'