Sua primeira solicitação à Tracking API: um guia passo a passo de um cliente REST com Postman e Curl
Para fazer sua primeira solicitação à API de rastreamento, configure o endpoint, o cabeçalho de autenticação e o corpo JSON em um cliente REST, envie a solicitação e verifique tanto o status HTTP quanto o corpo da resposta. Este guia usa a Tracking API da 17TRACK para demonstrar o mesmo fluxo de trabalho no Postman e no curl: registrar uma remessa, solicitar suas informações de rastreamento e verificar se o resultado está pronto para ser usado pelo seu aplicativo.
O objetivo é um pequeno teste de integração reproduzível, não uma implantação em produção. Você precisará de uma credencial de API e de um número de rastreamento que esteja autorizado a processar. Os comandos abaixo usam o padrão de endpoint v2.2; confirme a versão do endpoint e os requisitos específicos da conta na documentação da API da 17TRACK antes de executá-los.
Entenda o que sua primeira solicitação deve realizar
Uma integração de rastreamento de remessas envolve duas tarefas distintas: informar ao serviço qual remessa deve ser rastreada e recuperar as informações de rastreamento associadas a essa remessa. No fluxo demonstrado aqui, essas são solicitações separadas. O registro não significa que o pacote já tenha sido movimentado, e um registro bem-sucedido não garante que os eventos da transportadora estarão disponíveis imediatamente.
Para seu primeiro teste, use uma única remessa em vez de um lote. Isso facilita isolar erros de autenticação, números de rastreamento inválidos e problemas de interpretação da resposta. Seu primeiro marco útil não é simplesmente “recebi HTTP 200”. É “a API aceitou a operação pretendida e consigo explicar o resultado no nível da remessa”.
O Postman oferece uma interface visual para editar solicitações e inspecionar respostas. O curl torna a mesma comunicação HTTP reproduzível em um terminal. Nenhum dos dois altera as regras de autenticação, os dados da remessa ou o comportamento de processamento da API. Use o que ajudar a investigar a solicitação com mais clareza e, em seguida, reproduza a configuração funcional na outra ferramenta.
Prepare sua credencial, remessa e os detalhes da solicitação
Antes de abrir qualquer um dos clientes, reúna o seguinte:
- Uma credencial de API autorizada: obtenha-a por meio da configuração da sua conta da API da 17TRACK. Uma sessão de rastreamento para consumidores não substitui uma credencial de API.
- Um número de rastreamento real: use uma remessa que pertença a você ou à qual tenha permissão de acesso. Uma remessa recentemente ativa geralmente é mais útil do que um número inventado ao testar dados reais de rastreamento.
- A transportadora, se conhecida: mantenha o nome da transportadora disponível para diagnóstico. Se um identificador da transportadora for necessário no seu caso, use o valor e o campo definidos na documentação da API em vez de tentar adivinhar.
- O contrato atual da solicitação: confirme a versão da API, o cabeçalho de autenticação, o esquema da solicitação e quaisquer restrições da conta.
- Um ambiente de trabalho seguro: evite colocar credenciais, dados de clientes ou respostas completas de rastreamento em repositórios públicos, capturas de tela ou mensagens de suporte compartilhadas.
Os exemplos mínimos de solicitação usam estas configurações:
| Configuração | Exemplo |
|---|---|
| URL base | https://api.17track.net/track/v2.2 |
| Operação de registro | POST /register |
| Operação de informações de rastreamento | POST /gettrackinfo |
| Cabeçalho de autenticação | 17token: YOUR_API_TOKEN |
| Formato do corpo | Content-Type: application/json, com um array JSON de objetos de remessa |
Mantenha os números de rastreamento como strings. Convertê-los para um tipo numérico pode remover zeros à esquerda ou alterar seu valor de outra forma. O placeholder YOUR_TRACKING_NUMBER abaixo deve ser substituído pela sua remessa de teste real; ele não é um número de exemplo funcional.
Faça a solicitação de registro no Postman
1. Crie um pequeno ambiente de teste
No Postman, crie um ambiente com três variáveis: base_url, tracking_token e tracking_number. Defina base_url como a URL base acima e insira sua credencial e o número da remessa nas outras variáveis. Selecione esse ambiente antes de enviar a solicitação.
Use os controles disponíveis do Postman para gerenciamento de segredos do token e verifique o que seu espaço de trabalho compartilha ou sincroniza. Ocultar um valor na interface não substitui o controle de quem pode acessá-lo. Não exporte credenciais preenchidas com uma coleção destinada a colegas ou à documentação pública.
2. Configure o método, a URL e os cabeçalhos
Crie uma solicitação HTTP, selecione POST e insira {{base_url}}/register como URL. Na aba Headers, adicione:
17token: {{tracking_token}}
Content-Type: application/json
Neste exemplo, a credencial deve estar no cabeçalho personalizado 17token. Não o substitua por uma configuração de token Bearer apenas porque outra API usa esse padrão. Verifique também se as configurações herdadas da coleção introduzem um cabeçalho Authorization indesejado.
3. Adicione o corpo JSON
Abra Body, escolha raw e selecione JSON. Insira:
[
{
"number": "{{tracking_number}}"
}
]
Os colchetes externos são importantes: esta solicitação usa um array, mesmo contendo apenas uma remessa. Use aspas duplas, remova vírgulas finais e não inclua comentários no JSON. Se a documentação exigir informações adicionais para sua transportadora ou remessa, adicione os campos documentados antes do envio.
4. Envie e inspecione o resultado
Clique em Send. Primeiro, verifique se você recebeu uma resposta HTTP. Uma falha de DNS, um erro de TLS, um problema de proxy ou um timeout são diferentes de uma resposta informando que a solicitação era inválida. Em seguida, inspecione o corpo da resposta em busca do resultado da operação e de qualquer informação de aceitação ou rejeição no nível da remessa.
Salve a solicitação como “Register test shipment”. Registre o status HTTP, o resultado da API e qualquer mensagem de erro sem copiar o token. Se o registro falhar, resolva essa falha antes de prosseguir. Enviar repetidamente uma solicitação inalterada dificulta o diagnóstico e pode consumir recursos da conta.
Reproduza a solicitação com curl
Os comandos a seguir usam um shell no estilo POSIX, como Bash ou Zsh. O PowerShell e o Windows Command Prompt possuem regras diferentes para aspas e variáveis. No PowerShell, use curl.exe quando necessário para chamar o executável do curl em vez de um alias de comando específico do shell.
Defina a URL base e carregue sua credencial em uma variável de ambiente usando seu fluxo normal de gerenciamento de segredos:
export TRACKING_BASE_URL='https://api.17track.net/track/v2.2'
# Set TRACKING_API_TOKEN securely before continuing.
Uma variável de ambiente mantém a credencial fora do exemplo reutilizável, mas não constitui um sistema completo de gerenciamento de segredos. Para testes locais, evite digitar um token real em um comando que ficará armazenado no histórico do shell. Para automação, use o armazenamento de segredos da sua plataforma e restrinja a saída dos logs.
Crie um arquivo chamado shipment.json e substitua o placeholder pelo seu número de rastreamento de teste:
[
{
"number": "YOUR_TRACKING_NUMBER"
}
]
Envie a solicitação de registro:
curl --request POST \
--url "$TRACKING_BASE_URL/register" \
--header "17token: $TRACKING_API_TOKEN" \
--header 'Content-Type: application/json' \
--data-binary @shipment.json \
--connect-timeout 10 \
--max-time 30 \
--silent --show-error \
--output register-response.json \
--write-out 'HTTP status: %{http_code}\n'
Isso salva o corpo da resposta em register-response.json e imprime o status HTTP separadamente. Os timeouts de conexão e total são escolhas para testes locais, não garantias do serviço da 17TRACK. Abra o arquivo salvo para inspecionar o resultado da API; apenas a linha de status é insuficiente.
O curl pode concluir uma transferência com sucesso mesmo quando o servidor retorna uma resposta de erro HTTP. Por outro lado, uma falha de transporte pode impedir que qualquer resposta utilizável da API seja recebida. Ao criar scripts, trate o status de saída do curl, o status HTTP e o resultado no nível da aplicação como sinais distintos.
Solicite as informações de rastreamento da remessa
Após confirmar o registro, duplique a solicitação do Postman e altere a URL para {{base_url}}/gettrackinfo. Mantenha o método POST, o cabeçalho de autenticação, o tipo de conteúdo e o corpo da remessa. Salve-a separadamente para não registrar acidentalmente a remessa novamente quando sua intenção for recuperar dados.
A solicitação equivalente no curl é:
curl --request POST \
--url "$TRACKING_BASE_URL/gettrackinfo" \
--header "17token: $TRACKING_API_TOKEN" \
--header 'Content-Type: application/json' \
--data-binary @shipment.json \
--connect-timeout 10 \
--max-time 30 \
--silent --show-error \
--output tracking-response.json \
--write-out 'HTTP status: %{http_code}\n'
Não presuma que uma remessa recém-registrada retornará imediatamente um histórico completo de eventos. A disponibilidade dos dados depende da remessa e do processamento do serviço. Se as informações ainda não estiverem disponíveis, siga as orientações documentadas de recuperação e atualização em vez de registrar repetidamente o mesmo número ou executar um loop de polling muito frequente.
Leia a resposta em três camadas
- Transporte: o cliente conseguiu se conectar e recebeu uma resposta HTTP?
- Operação: a API aceitou a solicitação e a remessa individual foi processada com sucesso?
- Informações da remessa: os dados retornados identificam o pacote pretendido e o que seu status ou histórico de eventos realmente comprova?
Use o esquema oficial da resposta para localizar os campos de status, transportadora e eventos. Preserve a distinção entre um status normalizado da remessa e a descrição original do evento pela transportadora. Uma consulta bem-sucedida não comprova a entrega, e a ausência de eventos não comprova que um pacote foi perdido.
Ao armazenar timestamps, mantenha as informações de fuso horário ou deslocamento fornecidas. Evite ordenar strings de datas brutas de formatos diferentes presumindo que representam uma sequência cronológica correta. Diferencie também o momento em que seu aplicativo recuperou um registro do momento em que o evento da remessa ocorreu.
Solucione problemas sem alterar tudo de uma vez
- Nenhuma resposta: verifique o hostname, o acesso à rede, as configurações de proxy, a configuração de TLS e o timeout local. Não desative a verificação de certificados como solução rotineira.
- Falha de autenticação: confirme que o token está ativo, que o cabeçalho
17tokenestá presente e que o ambiente selecionado no Postman resolve a variável corretamente. Verifique espaços em branco acidentais. - Solicitação inválida: confirme a versão da API, o caminho da operação, o método POST, o tipo de conteúdo e a estrutura do array JSON conforme a documentação.
- Remessa rejeitada: leia o erro específico da remessa. Verifique o número e quaisquer informações obrigatórias da transportadora, em vez de tratar toda rejeição como um problema de autenticação.
- Nenhum evento de rastreamento: confirme o registro e a identidade da remessa pretendida. Verifique se são necessárias informações da transportadora e se há atualizações disponíveis antes de tentar novamente.
- O Postman funciona, mas o curl falha: compare a URL resolvida, os cabeçalhos reais e os bytes do corpo. O uso de aspas no shell e variáveis de ambiente não definidas são pontos comuns de divergência entre as solicitações.
Altere uma variável por teste e mantenha um registro breve do resultado. Se você inspecionar o console do Postman ou usar a saída detalhada do curl, trate essa saída como sensível: os cabeçalhos da solicitação podem expor credenciais. Oculte segredos e informações de clientes antes de compartilhar diagnósticos.
Saiba quando o guia está concluído
Você concluiu um primeiro teste de integração significativo quando ambos os clientes enviam a solicitação pretendida, o registro é compreendido, a recuperação retorna um resultado interpretável e você consegue distinguir uma falha da API de uma remessa sem novas informações. A simples correspondência dos códigos de status HTTP não comprova que os dois clientes se comportaram de forma idêntica.
Antes de levar o fluxo para um aplicativo, mantenha as credenciais no servidor, valide as entradas e use um tratamento estruturado de erros. Consulte os limites de taxa, limites de lote, orientações de novas tentativas e opções de entrega de atualizações documentados para sua conta. Não presuma que seja seguro repetir cegamente um registro após um timeout: o servidor pode ter processado a solicitação mesmo que seu cliente não tenha recebido a resposta.
Adicione testes para uma credencial inválida, JSON malformado, um número de remessa inválido, uma remessa já registrada, dados de rastreamento indisponíveis e um timeout de rede. Cada caso deve levar a um resultado deliberado no aplicativo, e não a uma exceção não tratada ou a um status enganoso exibido ao cliente.
FAQ
Posso testar sem um número de rastreamento real?
Você pode testar alguns comportamentos de validação da solicitação com um valor inválido, mas isso não verifica o rastreamento da remessa. Para testar eventos reais, use uma remessa autorizada ou um recurso de teste documentado, caso o serviço forneça um. Não presuma que números de exemplo arbitrários pertençam a um sandbox.
Por que uma resposta HTTP 200 ainda contém uma falha?
O status HTTP e os resultados da aplicação descrevem camadas diferentes. Um servidor pode receber e processar uma solicitação com sucesso e, ao mesmo tempo, informar que uma remessa individual foi rejeitada. Leia o corpo da resposta e o resultado documentado no nível da remessa, não apenas o status HTTP.
Por que POST é usado para recuperar informações de rastreamento?
Use o método especificado pelo contrato do endpoint. Este exemplo de recuperação aceita identificadores de remessas em um corpo de solicitação JSON por meio de POST. Alterá-lo para GET porque a operação lê dados não preserva a solicitação documentada.
Devo colocar o token da API em JavaScript no navegador?
Não incorpore uma credencial privada de API em código frontend distribuído publicamente. Encaminhe as solicitações por um backend autorizado que proteja a credencial, valide as entradas e controle quais informações de remessa cada usuário pode acessar.
Preciso do Postman e do curl em produção?
Não. Eles são ferramentas úteis de teste e diagnóstico. Seu aplicativo de produção pode usar um cliente HTTP apropriado. Mantenha uma solicitação do Postman ou um comando curl sanitizado como referência reproduzível, sem um token ativo ou dados desnecessários de clientes.
Fontes
- Documentação da API da 17TRACK — referência para autenticação, contratos de endpoints, campos de solicitação, interpretação de respostas e requisitos de integração.
- Documentação do Postman: Enviar solicitações de API — configuração de solicitações e inspeção de respostas.
- Documentação do Postman: Variáveis — configuração de solicitações baseada em variáveis.
- Manual do curl — opções de comando para cabeçalhos, corpos de solicitação, timeouts, respostas salvas e saída do status HTTP.


