cURL é uma ferramenta poderosa e onipresente em ambientes de desenvolvimento e operações. Para quem precisa testar fluxos de cadastro, validar a entrega de códigos OTP (One-Time Password) ou automatizar tarefas que dependem de verificação por SMS, dominar o cURL é um diferencial.

Este guia prático mostra como utilizar cURL para consultar uma API de recebimento de SMS, extrair o código de verificação e integrar essa lógica em scripts de teste.

Pré-requisitos para começar

Antes de colocar a mão na massa, você precisará de alguns itens básicos. A configuração é simples e rápida.

  • cURL instalado: A maioria dos sistemas baseados em Linux e macOS já vem com ele. No Windows, ele está incluído nas versões mais recentes ou pode ser instalado separadamente.
  • Acesso a uma API de SMS: Você precisará de uma chave de API (API Key) de um serviço de números virtuais, como a SMS VOLT. Essa chave autentica suas requisições.
  • Um número virtual: Ativado na plataforma de sua escolha, pronto para receber o SMS de verificação.
  • (Opcional) jq: Uma ferramenta de linha de comando para processar e fatiar dados JSON. É extremamente útil para extrair informações específicas da resposta da API.

Entendendo a Lógica da API de Recebimento

É fundamental entender o fluxo. Ao contrário de uma API para enviar SMS, uma plataforma de números virtuais oferece endpoints para consultar os SMS que um número recebeu. O processo geralmente segue estes passos:

  1. Você solicita um número virtual na plataforma.
  2. Você usa esse número no cadastro do serviço que deseja verificar (ex: uma rede social, um e-commerce).
  3. O serviço envia um SMS com o código OTP para o seu número virtual.
  4. Você usa cURL para chamar um endpoint da API da plataforma de números virtuais, perguntando: "Quais mensagens chegaram para este número?".
  5. A API retorna uma lista de mensagens em formato JSON.
  6. Você extrai o código de verificação do corpo da mensagem.

Nossa abordagem será focada nos passos 4, 5 e 6.

Passo 1: Consultando a Caixa de Entrada com cURL

Vamos supor que a documentação da nossa API de exemplo define um endpoint para buscar mensagens. O comando cURL para fazer a consulta seria parecido com este:

curl -X GET "https://api.smsvolt.com.br/v1/messages?number=55119XXXXXXXX&limit=1" \
     -H "Authorization: Bearer SUA_CHAVE_DE_API"

Vamos detalhar cada parte do comando:

  • curl -X GET: Especifica que estamos fazendo uma requisição do tipo GET, que é o método padrão para solicitar dados de um recurso.
  • "https://api.smsvolt.com.br/v1/messages?number=55119XXXXXXXX&limit=1": Esta é a URL do endpoint. Note os parâmetros de consulta (query parameters):
    • number=55119XXXXXXXX: Identifica para qual número virtual estamos pedindo as mensagens. Substitua pelo seu número.
    • limit=1: Pede apenas a mensagem mais recente, o que é ideal para buscar um código de verificação que acabou de ser enviado.
  • -H "Authorization: Bearer SUA_CHAVE_DE_API": Este é o cabeçalho (header) de autorização. É aqui que você insere sua chave de API para provar que tem permissão para acessar os dados. Substitua SUA_CHAVE_DE_API pela sua chave real.

Passo 2: Interpretando a Resposta JSON

A API, se a requisição for bem-sucedida, responderá com um objeto JSON. A estrutura pode variar, mas um exemplo comum seria:

{
  "status": "success",
  "data": [
    {
      "id": "msg_123456789",
      "from": "28901",
      "text": "Seu código de verificação para AppExemplo é: 852147.",
      "received_at": "2026-08-15T14:30:10Z"
    }
  ]
}

Nesta resposta, o código de que precisamos (852147) está dentro do campo text. O próximo passo é extraí-lo de forma automática.

Passo 3: Extraindo o Código OTP com jq e grep

Analisar o JSON manualmente não é prático para automação. Aqui, a ferramenta jq brilha. Podemos encadear a saída do cURL diretamente para o jq para extrair o texto da mensagem.

curl ... | jq -r '.data[0].text'
  • | (pipe): Envia a saída do comando cURL como entrada para o próximo comando.
  • jq -r '.data[0].text': Instrui o jq a fazer o seguinte:
    • . : Comece no topo do objeto JSON.
    • .data[0]: Acesse o primeiro elemento ([0]) do array data.
    • .text: Pegue o valor do campo text.
    • -r: raw output, remove as aspas da string de resultado.

A saída deste comando será:

Seu código de verificação para AppExemplo é: 852147.

Agora, para isolar apenas os dígitos, podemos adicionar mais um pipe para uma ferramenta como grep ou sed. Usando grep com uma expressão regular simples:

curl ... | jq -r '.data[0].text' | grep -o '[0-9]\{6\}'
  • grep -o '[0-9]\{6\}': Procura por uma sequência de exatamente 6 dígitos ([0-9]) e o -o (--only-matching) garante que apenas o trecho correspondente seja impresso.

O resultado final será exatamente o que precisamos:

852147

Automatizando em um Script Shell

Agora podemos juntar tudo em um script get_otp.sh para facilitar o reuso, especialmente em cenários de testes de QA com números virtuais.

#!/bin/bash

# Verifica se um número de telefone foi passado como argumento
if [ -z "$1" ]; then
  echo "Uso: $0 <numero_telefone_e164>"
  exit 1
fi

PHONE_NUMBER=$1
API_KEY="$MY_SMS_API_KEY" # Lendo de uma variável de ambiente

API_URL="https://api.smsvolt.com.br/v1/messages?number=${PHONE_NUMBER}&limit=1"

# Faz a requisição e extrai o código
OTP_CODE=$(curl -s -X GET "$API_URL" -H "Authorization: Bearer $API_KEY" | jq -r '.data[0].text' | grep -o '[0-9]\{6\}')

# Verifica se um código foi encontrado
if [ -n "$OTP_CODE" ]; then
  echo "Código OTP encontrado: $OTP_CODE"
else
  echo "Nenhum código OTP encontrado na última mensagem."
fi

Este script aceita o número de telefone como parâmetro e busca o código OTP, tornando o processo de teste muito mais ágil. Note o uso do curl -s para operar em modo silencioso, sem exibir a barra de progresso.

Dominar a verificação por cURL abre portas para a criação de testes de integração robustos, monitoramento de serviços e diversas outras automações. É uma habilidade essencial para qualquer desenvolvedor ou analista de qualidade que lida com fluxos de autenticação. Para entender mais sobre as alternativas, veja nosso comparativo entre polling e webhooks para receber SMS.

Perguntas Frequentes

Como lidar com erros de API usando cURL?

Você pode usar a flag -w "%{http_code}" no cURL para obter o código de status HTTP. Um código 200 indica sucesso, enquanto códigos da série 4xx (como 401 Unauthorized ou 404 Not Found) ou 5xx indicam erros. Seu script pode verificar esse código antes de tentar processar a resposta.

O que é jq e por que preciso dele?

jq é um processador de JSON para a linha de comando. Ele é essencial para analisar e extrair dados de respostas de API em formato JSON de forma programática. Sem ele, você teria que usar ferramentas de manipulação de texto mais complexas e frágeis, como sed ou awk, para analisar a string JSON.

Posso usar cURL para enviar SMS também?

Sim, mas isso depende de uma API diferente. Plataformas de comunicação (CPaaS) oferecem APIs para envio de SMS (A2P - Application-to-Person). O comando cURL seria diferente, tipicamente usando o método POST e enviando um corpo de dados (-d) com o destinatário e a mensagem. A API discutida aqui é para recebimento (P2A - Person-to-Application).

Por que o comando pode não retornar nada?

Pode haver vários motivos: o SMS ainda não chegou (demora da operadora), a chave de API está incorreta, o número de telefone está errado, ou a API retornou um array de mensagens vazio. Verifique o código de status HTTP e certifique-se de que o SMS foi de fato entregue ao número antes de consultar a API. Aprofunde-se em como usar uma API de SMS para mais detalhes.