Sandbox e a primeira requisição: como testar a integração sem cobranças

A primeira requisição a uma API desconhecida quase sempre é feita na base da tentativa e erro: um cabeçalho errado, um erro de digitação em um parâmetro, um espaço a mais na chave. No ambiente real, cada erro desses custa uma cobrança ou um número perdido. O ambiente de teste existe para que toda essa tentativa e erro aconteça sem custo. Vamos ver a ordem de verificação da integração, quais requisições são gratuitas e quais erros mais atrapalham o primeiro dia de trabalho com a API.

Por que usar um ambiente de teste antes das requisições reais

Uma integração raramente funciona de primeira, e isso não tem a ver com a qualificação do desenvolvedor: em um sistema desconhecido sempre há detalhes que só aparecem na prática, como o formato da data na resposta, a diferença entre maiúsculas e minúsculas em um parâmetro ou a ordem dos argumentos. O ambiente de teste dá o direito de errar: uma requisição incorreta ali apenas devolve um código de erro, sem debitar o saldo nem ocupar um recurso necessário para uma tarefa real.

Outro motivo é a confiança no formato da resposta. Enquanto o desenvolvedor não vê com os próprios olhos a resposta real do servidor — o aninhamento dos campos, os tipos de dados, a indicação de erros —, o código escrito só com base na documentação continua sendo uma suposição. A requisição de teste transforma a suposição em fato verificado antes que um processo real passe a depender dela.

Ordem dos primeiros passos da integração

Uma sequência sensata não pula níveis de complexidade. O primeiro passo é obter a chave de acesso e confirmar que ela existe e está ativa: isso basta para distinguir um problema na própria chave de um problema na lógica da requisição nos passos seguintes. O segundo passo é uma requisição simples, sem carga de significado, que verifica apenas a autorização: uma chamada a um método de consulta que não exige escolher país, serviço ou valor. Uma resposta bem-sucedida significa que a chave e os cabeçalhos estão configurados corretamente, e daí em diante dá para cuidar do conteúdo, e não do acesso.

O terceiro passo é olhar o formato real da resposta: quais campos chegam, o que significa cada código de status, como é a resposta de erro. Esse passo costuma ser pulado por quem confia na documentação, e é um erro — a resposta real às vezes difere do exemplo em detalhes que importam justamente para a sua lógica de tratamento. Só depois de cumprir os três passos faz sentido passar aos métodos que gastam dinheiro ou ocupam um recurso: pedir um número, comprar uma ativação, reservar um canal. Passar cedo demais aos métodos pagos transforma a depuração da integração em depuração por conta própria.

Quais requisições são gratuitas e quais cobram

Os métodos de consulta — lista de países, lista de serviços, preços atuais por destino — costumam ser gratuitos e sem limite de chamadas, dentro do razoável: são uma vitrine, e não uma ação. A verificação do status de uma ativação já criada e a consulta de saldo também, em regra, não custam nada — é leitura de estado, e não alteração. A cobrança acontece onde o sistema reserva um recurso para você: pedir um número, iniciar uma ativação, renovar um aluguel, comprar um canal — o dinheiro sai do saldo independentemente de o resultado esperado ter chegado até você. Vale conferir a fronteira entre o gratuito e o pago na documentação da API antes da primeira chamada real, em vez de descobri-la por meio de cobranças aleatórias.

Erros típicos do primeiro dia

O erro mais comum e mais caro é uma chave de produção que acaba no ambiente de teste: o desenvolvedor copia o exemplo da documentação, troca a chave pela sua sem olhar, e a primeira execução de teste já debita dinheiro do saldo real. A separação das chaves entre os ambientes e suas consequências são abordadas no artigo dados para testes: como não criar contas reais no ambiente de testes.

O segundo erro é pedir um número repetidamente em loop, sem intervalo: se o código não chega de imediato, um script com lógica mal pensada pede um novo número na hora, em vez de esperar uma pausa e um número razoável de tentativas. Cada tentativa em um destino ruim é cobrada de novo, e o preço do resultado fica várias vezes maior que o de uma única tentativa — isso é detalhado no artigo sobre custos ocultos: cancelamentos, repetições e tempo ocioso.

O terceiro erro é a falta de tratamento de recusas: um código escrito apenas para o happy path não distingue «o código ainda não chegou, aguarde» de «destino indisponível» ou «chave bloqueada», e então trava sem reação ou bombardeia a API com requisições repetidas sem pausa. Tratar cada tipo de recusa em um ramo próprio da lógica não é um aprimoramento opcional, e sim a condição para que uma única resposta com falha não se transforme em uma avalanche de requisições inúteis.

O que registrar antes de ir para o ambiente real

Antes da primeira chamada real, vale registrar por escrito quatro coisas: qual chave pertence ao ambiente de teste e qual ao ambiente real, e que elas não se cruzam de forma alguma; quais métodos são pagos e quais não são — com base na sua própria verificação, e não na memória; uma pausa razoável e o número de repetições entre tentativas malsucedidas, em vez de um loop infinito; e um limite de gastos por chave, para o caso de a lógica de repetição falhar em algum ponto. Como definir o limite diário e mensal por chave está descrito no artigo limites para a equipe: como restringir os gastos.

Perguntas frequentes

É possível testar todo o cenário sem gastar dinheiro nenhuma vez?

A verificação da chave, da autorização e do formato da resposta, sim, de forma totalmente gratuita. Obter um número ou iniciar uma ativação exigirá pelo menos uma chamada paga, mas só vale chegar a esse passo depois de verificar todo o resto.

Como perceber rápido que a chave foi colocada no ambiente errado?

Faça uma requisição gratuita e comprovadamente simples e compare o saldo antes e depois: se o saldo mudou em um passo gratuito, a chave aponta para um lugar diferente do esperado, e convém interromper imediatamente as chamadas seguintes.

Quantas vezes vale repetir a requisição se o código não chegou?

Uma referência razoável é uma nova tentativa depois de uma pausa, e não um loop infinito logo após o primeiro timeout: a segunda tentativa absorve um atraso eventual, enquanto uma falha sistemática em um destino indica um problema no destino, e não falta de sorte.

O esquema completo de métodos, códigos de resposta e limites está na seção de documentação da API do turbon.rent: lá também está indicado quais chamadas são gratuitas e quais debitam fundos do saldo.