API da Sinallo: compatível com o protocolo SMS-Activate

Se você já tem um programa, script ou bot que fala o protocolo SMS-Activate, ele funciona com a Sinallo trocando só duas coisas: o endereço e a chave. A documentação completa, com exemplos, está em API.

O que muda

• Endereço: o mesmo caminho do protocolo, /stubs/handler_api.php, no domínio da Sinallo.
• Chave: gerada em Conta, no cartão "Chave da API". Passe em api_key.
• Valores: tudo em reais, descontado do mesmo saldo que você usa no site.

GET ou POST funcionam. O país pode ser o id numérico do protocolo (Brasil é 73) ou o código de duas letras (br). O serviço usa os códigos do protocolo, como wa para WhatsApp e tg para Telegram.

Ações disponíveis

• getBalance: saldo da conta, em reais.
• getNumber: compra um número. Aceita maxPrice, em reais.
• getNumberV2: o mesmo, com resposta em JSON.
• getStatus: espera, código recebido ou cancelado.
• setStatus: 1 para avisar que está pronto, 3 para pedir outro SMS, 6 para concluir e 8 para cancelar.
• getPrices e getPricesV2: preços em reais. O primeiro traz o menor preço; o segundo, todas as faixas.
• getCountries e getServicesList: países e serviços disponíveis.
• getActiveActivations: seus pedidos abertos, com os códigos recebidos.

Fora dessa lista, não conte com outras ações. Se o seu script usa alguma diferente, confira na documentação antes.

Como o preço é escolhido

Sem maxPrice, a compra vai na faixa mais barata. Com maxPrice, vai na faixa mais cara que couber nele, que costuma ter mais chance de entrega. Se não houver número dentro do limite, a resposta é NO_NUMBERS. Pela API não existe oferta de número mais caro: quem decide subir o limite é o seu programa.

As faixas são as mesmas do site. Para entender o que cada uma significa, veja faixas de qualidade.

Reserva e reembolso

O número fica reservado por 20 minutos. Sem código nesse tempo, o valor volta ao saldo sozinho, igual no site. Se você cancelar e a resposta for EARLY_CANCEL_DENIED, quer dizer que a operadora ainda não libera o cancelamento: ele fica agendado e a Sinallo faz sozinha, devolvendo o valor quando der. Seu programa não precisa repetir o pedido.

Boas práticas

• Consulte o getStatus a cada 3 a 5 segundos. Mais rápido que isso não traz o código antes.
• Respeite o limite de chamadas por minuto descrito na documentação.
• Use setStatus 6 ao terminar, para liberar o número da lista de abertos.
• Existe um limite de pedidos esperando código ao mesmo tempo por conta. Conclua ou cancele o que não vai usar.

Segurança da chave

• A chave inteira aparece uma vez só, quando você gera. Guarde num lugar seguro.
• Gerar uma chave nova desliga a anterior. Use isso se achar que a chave vazou.
• Não coloque a chave em código público, como repositórios abertos ou páginas de site.
• Muitas tentativas com chave errada, vindas do mesmo IP, bloqueiam o acesso por alguns minutos.

Use com responsabilidade

A API é para automatizar o seu uso, como testes de cadastro do seu próprio app ou um painel interno. Siga sempre as regras de uso de cada app em que você usa os números. Números para bancos, carteiras digitais e corretoras não estão disponíveis, nem pela API.