Recebendo códigos OTP por SMS da República Tcheca por endpoints, webhooks ou painel

Em quais endpoints a API OTP da República Tcheca se apoia?

Tudo roda em https://otproute.com/api/v1 com uma chave Bearer de prefixo or_live_. Você cria as chaves no console do desenvolvedor, e uma conta pode ter até 10 delas, o que facilita dar credenciais separadas a staging, CI e a um notebook local, cada uma revogável de forma independente. O limite de taxa é de 300 requisições por minuto por conta.

Uma execução típica com +420 é assim:

1. Busque GET /api/v1/countries e GET /api/v1/services uma vez por deploy e guarde em cache. O id do país da República Tcheca é cz.
2. Peça a GET /api/v1/prices?country=cz&service=<id> o preço ao vivo da rota que pretende usar; ele muda conforme o serviço e a disponibilidade.
3. Crie a ativação com POST /api/v1/activations e o corpo JSON {"service": "<id>", "country": "cz"}. A resposta traz um id de ativação e o número a digitar no formulário de cadastro que você está testando.
4. Aguarde o código, por webhook ou lendo GET /api/v1/activations/{id} em intervalos moderados.
5. Se o teste for abortado, libere o número com POST /api/v1/activations/{id}/cancel para que o valor retido volte à carteira imediatamente.

Chamar GET /api/v1/balance antes de uma suíte grande é uma forma barata de falhar cedo quando a carteira está baixa. A referência completa está na documentação.

Como verifico webhooks das ativações +420?

Os webhooks eliminam a necessidade de polling e combinam com executores de teste em paralelo. Aponte um dos seus endpoints (o console do desenvolvedor permite 5 por conta) para o fluxo tcheco e inscreva-o em activation.sms_received, activation.expired e activation.cancelled.

Cada requisição traz um cabeçalho X-OTPRoute-Signature no formato t=<unix>,v1=<hex>. Reconstrua a string <t>.<raw body> a partir dos bytes originais da requisição, calcule o HMAC-SHA256 com o segredo daquele endpoint, compare o resultado com o v1 em tempo constante e descarte tudo cujo timestamp seja antigo demais para ser uma entrega recente. Nosso guia sobre como proteger webhooks de OTP com HMAC percorre um handler linha por linha.

Trate os eventos como indexados pelo id da ativação e torne o handler idempotente: uma entrega repetida deve encontrar a ativação já marcada como concluída e simplesmente retornar sucesso. Consultar GET /api/v1/activations/{id} continua sendo uma alternativa válida para scripts que rodam onde não existe endpoint público.

Quais serviços podem enviar códigos para números tchecos?

A rota tcheca cobre atualmente mais de 1.700 serviços. Entre os nomes populares no último snapshot estão WhatsApp, Telegram, Google (Gmail & YouTube), Facebook, Instagram, TikTok, Microsoft & Outlook, LinkedIn, Discord, Uber, Airbnb, Signal, Viber e ChatGPT (OpenAI).

Essa lista não é fixa. A disponibilidade se move ao longo do dia, então o código deve ler a disponibilidade da API em tempo de execução, e não de uma tabela fixa. Se um serviço de que você precisa estiver ausente em determinado momento, ele pode voltar mais tarde, ou uma rota vizinha da Europa Central pode servir ao caso de teste.

Como armazenar e interpretar um número de verificação tcheco?

A numeração tcheca é fechada: os números nacionais têm nove dígitos e não há prefixo de tronco, então a forma doméstica e a internacional diferem apenas pelo +420 na frente. Isso deixa a normalização mais simples que em muitos mercados, mas os formulários ainda recebem espaços, o prefixo internacional 00420 ou apenas os nove dígitos. Remova os separadores, converta 00 em +, acrescente +420 quando faltar e grave o resultado em E.164.

Os códigos de apps voltados ao público tcheco costumam chegar em tcheco ou em inglês. O texto tcheco usa diacríticos como háček e čárka, e alguns remetentes os removem para manter a mensagem em um conjunto de caracteres simples, então um parser deve procurar o grupo de dígitos em vez de comparar uma frase inteira.

As equipes usam um número +420 para testes ao lançar um produto para clientes tchecos, ao revisar o texto de onboarding em tcheco ou ao confirmar que um fluxo regional de cadastro aceita números sem zero à esquerda. A página de testes de QA descreve como as equipes estruturam essas execuções.

O que deve acontecer quando um código tcheco não chega?

Alguns serviços recusam números virtuais, e algumas rotas são mais lentas em certos horários. Um código perdido não custa nada: se nenhum SMS chegar dentro da janela de 20 minutos, ou se você cancelar antes, o valor integral volta automaticamente para a carteira.

• Deixe a janela correr antes de decidir que a tentativa falhou.
• Verifique se o serviço que você está testando aceita números virtuais.
• Tente de novo mais tarde ou use outra rota de país compatível com o serviço.
• Espere entre as tentativas; refazer o pedido em um laço rápido consome o limite de taxa e raramente ajuda.
• Registre o id da ativação a cada falha, para que padrões apareçam entre as execuções.

Quem não é desenvolvedor pode usar a rota +420 pelo painel?

Pode. Depois de criar sua conta com e-mail e um código de 6 dígitos enviado por e-mail (ou com o login do Google), abra o OTP Gateway, escolha o serviço e República Tcheca, confira o preço exibido e faça o pedido. O número de verificação da República Tcheca aparece na hora; cole-o no app, e o código surge na mesma tela quando chegar. Cancelar pelo painel devolve o valor à carteira do mesmo modo que a chamada de API.

Existe um número tcheco de longo prazo e como funciona a cobrança?

Hoje não existe número tcheco de longo prazo com contratação self-service. Os Dedicated Numbers são um produto dos EUA e do Canadá, a partir de $1.95/month, com SMS de entrada e saída e chamadas pelo navegador; veja os detalhes em números virtuais. Se a sua equipe precisa de uma linha +420 duradoura, escreva para [email protected] e pergunte, sabendo que a disponibilidade depende das regras locais e não é prometida.

A cobrança é uma única carteira pré-paga em USD, sem mensalidade e sem plano para escolher. Os fundos entram por cartão ou como USDT/USDC, e cada recarga gera uma fatura em PDF enviada por e-mail. Para o trabalho de integração, uma conta de desenvolvimento pode ser colocada em sandbox a pedido, de modo que números e códigos simulados exercitem todo o fluxo sem gastar fundos da carteira. A autenticação em dois fatores com TOTP está disponível para a própria conta.

Perguntas frequentes

Posso testar o fluxo de cadastro tcheco do meu app sem um chip tcheco?

Sim. Peça um número +420 no OTP Gateway para o serviço que você está testando, digite-o no seu app e leia o código no painel, pela API ou por um webhook.

Qual é o id da República Tcheca na API da OTP Route?

Use cz no campo country de POST /api/v1/activations e nas consultas de preço.

Quanto custa um código de verificação tcheco?

Os códigos começam em $0.20 por código, e o preço exato de cada serviço é retornado por GET /api/v1/prices e mostrado antes de você pedir. Você só paga se um código chegar.

Os números tchecos precisam de zero à esquerda?

Não. Os números tchecos não têm prefixo de tronco, então armazene-os como +420 seguido dos nove dígitos nacionais.

Por quanto tempo uma ativação +420 fica aberta?

Vinte minutos. Se nada chegar nesse tempo, a ativação expira e a carteira é reembolsada integralmente.

O roteamento de OTP para a República Tcheca serve para criação de contas em massa?

Não. A OTP Route serve para testar o seu próprio produto e operar as suas próprias contas legítimas. Mantenha cada ativação +420 ligada ao seu próprio produto ou conta, dentro dos termos de cada serviço e da Política de Uso Aceitável da OTP Route.

Posso manter o mesmo número tcheco para logins futuros?

Não como produto self-service. Os Dedicated Numbers de longo prazo existem apenas nos Estados Unidos e no Canadá, e você pode escrever ao suporte para perguntar sobre outros mercados.

Os nomes dos serviços são marcas registradas de seus respectivos proprietários. A OTP Route não é afiliada a eles. Use os números de forma lícita e siga os termos de cada serviço e nossa Política de Uso Aceitável.