Testar uma integração da Tracking API em desenvolvimento: sandbox, números de teste, webhooks simulados
Para testar uma integração de API de rastreamento em desenvolvimento, use três métodos complementares: um sandbox do provedor ou números de teste documentados para o comportamento da API, fixtures locais para cenários de remessa reproduzíveis e webhooks simulados para o seu endpoint de recebimento. Em seguida, execute uma verificação controlada em ambiente real para validar as partes que as simulações não podem comprovar, incluindo credenciais, configuração da assinatura e entrega real de eventos.

Este guia é destinado a desenvolvedores que conectam o rastreamento de remessas a uma plataforma de comércio eletrônico, sistema de gerenciamento de pedidos, ERP ou serviço de notificação ao cliente. O objetivo não é simplesmente receber uma resposta bem-sucedida da API. É comprovar que as atualizações de rastreamento produzem o estado correto do pedido sem mensagens duplicadas, eventos perdidos ou contato acidental com clientes reais.
Separe o comportamento do provedor do comportamento da aplicação
Uma integração de rastreamento tem pelo menos dois limites: as solicitações que sua aplicação envia ao provedor e as atualizações que sua aplicação recebe ou consulta posteriormente. Uma solicitação bem-sucedida no primeiro limite não comprova que o segundo limite funciona.
Crie o plano de testes em torno desses limites, em vez de esperar que um único número de rastreamento de teste exercite todo o sistema.
| Método de teste | O que pode validar | O que não pode estabelecer sozinho |
|---|---|---|
| Sandbox do provedor | Formatos de solicitação compatíveis, autenticação e comportamento simulado descrito pelo provedor | Disponibilidade de dados de transportadoras em produção ou comportamento de entrega em produção |
| Números de teste documentados | Os cenários específicos atribuídos a esses números | Outros status, transportadoras ou sequências de webhooks |
| Fixtures locais e mocks de API | Seu analisador, regras de mapeamento, persistência e tratamento de falhas | Se o provedor real aceita solicitações ou emite o mesmo payload |
| Solicitações de webhook simuladas | Tratamento do endpoint, validação, deduplicação e efeitos posteriores | Configuração de callbacks no lado do provedor ou novas tentativas de entrega reais |
| Teste real controlado | Conectividade real e o fluxo de remessa observado | Todos os erros raros, exceções ou sequências de entrega |
Abordagem recomendada: torne os testes locais determinísticos, use os recursos de teste compatíveis com o provedor quando disponíveis e reserve as remessas reais para confirmar a conexão entre os sistemas.
Confirme o contrato do provedor antes de escrever fixtures
Comece pela documentação oficial da versão da API que pretende usar. Confirme a URL base, o método de autenticação, os requisitos de registro, o esquema de resposta, a configuração de webhook e quaisquer recursos de teste documentados. Não deduza que existe um sandbox separado apenas porque o provedor oferece uma API.
Para uma integração com a 17TRACK, use a página da Tracking API da 17TRACK e a documentação oficial da API como pontos de partida. Verifique ali as especificações aplicáveis de solicitações e callbacks antes de criar exemplos específicos do provedor. Os exemplos abaixo são deliberadamente fixtures pertencentes à aplicação, não representações do esquema da API da 17TRACK.
Resolva estas questões antes de conectar o código de desenvolvimento a uma conta externa:
- As credenciais de desenvolvimento e produção são separadas e a qual ambiente cada credencial dá acesso?
- O sandbox oferece callbacks ou apenas testes de solicitação e resposta?
- Os números de teste são documentados e quais resultados exatos eles produzem?
- Registros ou outras solicitações de teste podem consumir a cota da conta ou criar registros persistentes?
- Quais regras documentadas existem para autenticação de callbacks, confirmação, tempo limite e novas tentativas?
- Quais identificadores conectam um registro de rastreamento, uma remessa, uma transportadora e um evento de callback?
Se o comportamento de teste não estiver claramente documentado, peça ao provedor que o confirme. Enquanto isso, continue testando sua própria lógica de processamento com mocks. Uma capacidade de sandbox não confirmada é uma incerteza de planejamento, não uma evidência de que o provedor não possui essa capacidade.
Crie um ambiente de desenvolvimento isolado
Use um banco de dados separado ou um tenant isolado, segredos separados e pedidos sintéticos. Direcione e-mails, mensagens SMS e outras notificações para destinos de teste ou um coletor de notificações. Uma remessa marcada como entregue em uma fixture não deve disparar uma mensagem para um comprador real.
Adicione um marcador explícito de ambiente aos registros internos e logs. Mantenha as credenciais do provedor no servidor, fora do controle de versão, e remova os segredos das capturas de solicitações. Se for necessário acesso público temporário para callbacks, exponha apenas a rota de desenvolvimento pretendida e mantenha seus controles de autenticação.
Crie um pequeno conjunto de pedidos conhecidos antes de enviar eventos. Inclua duas remessas vinculadas a um pedido e, se sua aplicação oferecer suporte, a mesma string de número de rastreamento em diferentes contextos de transportadora. Esses casos revelam suposições de que um número de rastreamento, sozinho, sempre identifica um registro comercial exclusivo.
Defina antecipadamente o efeito esperado de cada teste: o estado da remessa, a associação ao pedido, as entradas da linha do tempo, a quantidade de notificações e o registro de auditoria. Isso transforma uma demonstração em uma asserção que pode passar ou falhar.
Use números de teste apenas para a finalidade documentada
Um número de rastreamento tem duas funções distintas nos testes. Ele pode ser uma entrada usada para validar o registro e pode identificar uma remessa que produz eventos de rastreamento. Um número que passa na validação de formato não necessariamente fornece um histórico de eventos útil.
Quando há números de teste oficiais disponíveis
Registre o cenário informado pelo provedor junto a cada número. Um número documentado para uma remessa entregue não deve ser considerado capaz de simular uma exceção, devolução ou tentativa de entrega malsucedida. Verifique também se o resultado é fixo, muda ao longo do tempo ou exige a seleção de uma transportadora específica.
Mantenha esses números em uma configuração dedicada aos testes de integração. Não os espalhe pelos testes unitários, nos quais mudanças no comportamento externo podem tornar não confiáveis testes que, de outra forma, seriam determinísticos.
Quando os números de teste oficiais não são confirmados
Use identificadores sintéticos dentro da sua própria aplicação e simule o limite do provedor. Nunca invente um número com aparência plausível presumindo que ele esteja reservado para testes: ele pode corresponder a uma remessa real.
Para validação em ambiente real, use remessas que você controla e está autorizado a acessar. Evite copiar números de rastreamento de capturas de tela públicas ou conversas com clientes. Trate os históricos de remessas como potencialmente sensíveis, pois podem conter localizações, horários e informações de entrega.
Uma remessa antiga entregue pode ajudar a validar a análise, mas é uma dependência ruim para integração contínua. A disponibilidade dos dados históricos e a resposta externa podem mudar. Preserve uma fixture sanitizada para testes reproduzíveis e mantenha a verificação real separada.
Crie fixtures em torno de transições significativas da remessa
Crie fixtures a partir do esquema documentado e, quando disponíveis, de respostas reais sanitizadas. Mantenha as fixtures de payload do provedor separadas do seu modelo interno normalizado de eventos. Teste o adaptador entre eles para que um mock interno não esconda um analisador do provedor quebrado.
Um conjunto inicial útil abrange estes cenários:
- Ainda não há eventos de rastreamento: mantenha a remessa sem afirmar movimentação ou entrega.
- Em trânsito: atualize a linha do tempo e preserve a associação correta ao pedido.
- Saiu para entrega: aplique sua política de notificações sem tratar a entrega como concluída.
- Entregue: registre a conclusão e emita a ação comercial pretendida uma única vez.
- Exceção ou tentativa de entrega: preserve a distinção em relação a uma entrega concluída.
- Movimentação de devolução: evite interpretar cada leitura posterior como progresso em direção ao destinatário original.
- Status desconhecido: mantenha informações suficientes para diagnóstico sem inventar um mapeamento de status.
Use seus próprios nomes normalizados para esses cenários e mapeie explicitamente os valores documentados do provedor para eles. Não presuma que APIs diferentes usam os mesmos rótulos de status ou que um rótulo tem o mesmo significado comercial em todos os lugares.
Varie também o formato dos dados: uma lista de eventos vazia, campos opcionais ausentes, campos desconhecidos adicionais, nomes de localização em Unicode, registros de data e hora com deslocamentos de fuso horário e valores obrigatórios malformados. Seu analisador deve tolerar adições compatíveis e rejeitar dados que não possam ser processados com segurança.
Envie webhooks simulados pelo caminho real de recebimento
Um webhook simulado deve exercitar a rota de recebimento, o middleware de autenticação, a validação, o armazenamento e o processamento pelo worker — não apenas chamar a função final de atualização de status.
O payload a seguir representa um evento interno sintético. Os nomes dos campos, o ID do evento e o status são ilustrativos; eles não constituem um contrato de callback do provedor.
{
"event_id": "dev-event-001",
"shipment_id": "dev-shipment-001",
"tracking_number": "INTERNAL-TEST-001",
"status": "in_transit",
"occurred_at": "2025-01-15T10:00:00Z"
}Salve-o como tracking-event.json e envie-o para um receptor de teste local:
curl --request POST \
http://localhost:3000/dev/tracking-events \
--header 'Content-Type: application/json' \
--data-binary @tracking-event.jsonEste comando valida apenas o roteamento e o tratamento locais. Ele não demonstra a autenticação do provedor. Mantenha uma rota exclusiva de desenvolvimento inacessível em produção ou teste o receptor de produção usando o método de autenticação documentado pelo provedor e um segredo de teste separado.
Teste a autenticação sem enfraquecer os controles de produção
Se o provedor especificar callbacks assinados, implemente exatamente esse esquema, em vez de escolher um cabeçalho de assinatura ou algoritmo arbitrário. Para esquemas que assinam os bytes da solicitação, preserve o corpo original para verificação; analisar e serializar novamente o JSON pode alterar esses bytes.
Teste autenticação válida, credenciais ausentes, corpos adulterados e assinaturas incorretas quando aplicável. Se o esquema documentado incluir registros de data e hora ou proteção contra repetição, teste essas regras também. HMAC é uma construção padronizada de autenticação de mensagens, mas sua existência não comprova que um determinado provedor de rastreamento a utiliza.
Teste duplicatas, ordenação e recuperação
O processamento de remessas deve continuar correto quando a mesma atualização chega repetidamente ou quando os eventos chegam em uma ordem inesperada. Estes são cenários de teste defensivos, não afirmações sobre a garantia de entrega de um provedor específico.
| Teste | Comportamento esperado da aplicação |
|---|---|
| Envie o mesmo evento duas vezes | Mantenha um único evento lógico e evite notificações duplicadas aos clientes. |
| Envie uma leitura de trânsito mais antiga após a entrega | Preserve o histórico útil sem reverter automaticamente o estado de entregue. |
| Envie atualizações simultâneas | Aplique transições de estado consistentes apesar dos workers concorrentes. |
| Interrompa o processamento após o recebimento durável | Recupere e processe o evento armazenado sem exigir um novo callback. |
| Falhe o armazenamento antes que o recebimento seja durável | Não confirme falsamente uma aceitação bem-sucedida. |
| Envie uma remessa desconhecida | Siga uma política definida de quarentena ou rejeição; nunca adivinhe a associação ao pedido. |
Prefira um identificador de evento estável e documentado para deduplicação quando ele for fornecido. Caso contrário, defina uma identidade cuidadosamente delimitada a partir de campos relevantes e teste colisões. Um número de rastreamento, por si só, não é uma identidade de evento, pois uma remessa pode gerar muitas atualizações legítimas.
Separe o histórico de eventos da projeção atual da remessa. Manter leituras históricas não exige permitir que toda leitura atrasada substitua o status exibido. Da mesma forma, “usar o registro de data e hora mais recente” não é uma regra completa: correções, fluxos de devolução e diferentes significados de registros de data e hora exigem tratamento explícito.
No processamento assíncrono, confirme apenas depois que o evento alcançar um ponto de transferência durável, como um registro de inbox confirmado ou uma fila durável, de acordo com sua arquitetura. Siga os requisitos documentados de confirmação do provedor. HTTP define a semântica dos códigos de status, mas o cronograma de novas tentativas de um remetente específico deve vir do próprio contrato.
Execute uma verificação real controlada e defina critérios de lançamento
Quando os testes determinísticos forem aprovados, registre uma remessa autorizada pela integração real e confirme o caminho completo. Verifique se o provedor aceitou o registro pretendido, se a configuração de callback aponta para o ambiente correto e se os dados recebidos são mapeados para a remessa esperada.
Não exija que todos os status de remessa apareçam durante essa verificação real. Remessas reais não são fixtures controláveis. Use a execução real para validar a conectividade e a compatibilidade observada do contrato; use fixtures reproduzíveis para abranger cenários raros ou destrutivos.
Antes do lançamento, exija os seguintes resultados:
- Respostas documentadas de sucesso e erro são tratadas, incluindo falhas no nível do item caso a API ofereça suporte a operações em lote.
- Os tempos limite não acionam novas tentativas cegas de criação quando a primeira solicitação já pode ter sido bem-sucedida.
- Eventos duplicados não podem criar ações comerciais duplicadas.
- Callbacks inválidos não podem alterar o estado da remessa.
- Falhas dos workers deixam eventos recuperáveis em vez de perdê-los silenciosamente.
- O tráfego de desenvolvimento não pode notificar clientes reais nem alterar pedidos de produção.
- Os logs conectam solicitações, eventos recebidos, resultados do processamento e tentativas de notificação sem expor segredos.
Um lançamento está pronto quando você consegue explicar tanto o fluxo normal quanto a forma como o sistema se recupera após uma solicitação incerta, um callback repetido ou um worker interrompido. Uma única consulta de rastreamento bem-sucedida não é suficiente.
FAQ
Posso testar uma integração de rastreamento sem um sandbox?
Sim. Simule o limite da API de saída, reproduza fixtures de callbacks documentados e teste localmente sua normalização e suas regras comerciais. Em seguida, use uma remessa real autorizada para confirmar a conectividade efetiva. Isso oferece uma cobertura substancial, mas não reproduz o comportamento não documentado do provedor.
Por que minha solicitação de rastreamento é bem-sucedida, mas não retorna eventos?
A aceitação da solicitação e a disponibilidade de dados de rastreamento são resultados diferentes. Verifique os detalhes da resposta do provedor, os requisitos de registro, as regras de identificação da transportadora e o comportamento documentado para remessas sem eventos. Não fabrique informações de movimentação ou entrega para preencher uma linha do tempo vazia.
Um webhook simulado bem-sucedido comprova que os webhooks reais chegarão?
Não. Ele comprova apenas o caminho exercitado pelo mock. A entrega real também depende da configuração do provedor, acessibilidade pública, TLS, autenticação e do contrato de callback efetivo. Valide esses pontos com uma entrega de teste compatível com o provedor ou um fluxo real autorizado.
Devo retornar HTTP 200 antes que o processamento termine?
Siga o contrato documentado de confirmação do provedor. Em um design assíncrono, confirme após a aceitação durável e processe depois em um worker. Retornar sucesso antes da aceitação durável pode perder um evento se o processo falhar imediatamente depois.
Como devo testar as notificações aos clientes?
Envie todas as notificações de desenvolvimento para um coletor controlado. Verifique o destino, o modelo, a transição que disparou a notificação e a quantidade de envios. Reproduza o mesmo evento e simule novas tentativas do worker para confirmar que uma atualização de remessa não gera mensagens repetidas aos clientes.
Fontes
- 17TRACK Tracking API — ponto de partida oficial para o produto de API de rastreamento.
- Documentação da API da 17TRACK — referência para o contrato de integração específico do provedor; confirme aqui os requisitos aplicáveis de testes e callbacks.
- RFC 9110: Semântica HTTP — semântica das respostas HTTP e considerações sobre novas tentativas de solicitações.
- RFC 2104: HMAC — construção padronizada de autenticação de mensagens discutida nas orientações de segurança de callbacks.


