Como enviar vários números de rastreamento em uma única solicitação de API (limites de lote e falhas parciais)
Para enviar vários números de rastreamento em uma única solicitação de API, use um endpoint da Tracking API que aceite explicitamente um lote, formate cada remessa de acordo com o esquema da solicitação e divida listas maiores em lotes dentro dos limites documentados. Em seguida, analise tanto a resposta HTTP quanto o resultado de cada remessa: uma solicitação HTTP bem-sucedida não significa necessariamente que todos os números de rastreamento foram aceitos. Tente novamente apenas as falhas elegíveis e reconcilie os resultados incertos antes de reenviar um lote inteiro.

Este guia destina-se a desenvolvedores que conectam o rastreamento de remessas a um sistema de gerenciamento de pedidos, uma plataforma de armazém, uma aplicação de comércio eletrônico ou um painel interno. O objetivo não é simplesmente enviar menos solicitações. É contabilizar todas as remessas sem criar trabalho duplicado nem perder registros com falha.
Primeiro, identifique o que o endpoint de lote realmente faz
Uma integração de rastreamento pode envolver várias operações distintas. Registrar remessas, obter as informações de rastreamento mais recentes e receber atualizações posteriores não são operações intercambiáveis.
- Registro: Envie remessas para que o serviço possa iniciar ou manter o rastreamento delas.
- Consulta: Solicite informações de rastreamento das remessas, sujeitas às regras de obtenção do endpoint.
- Atualização da entrega: Receba alterações posteriores por meio de um mecanismo compatível, como webhooks, ou obtenha-as por solicitações programadas.
Consulte a documentação para confirmar a operação exata de que precisa. Um endpoint de registro que aceita vários registros não comprova que um endpoint de consulta aceite a mesma quantidade, use o mesmo esquema ou compartilhe o mesmo limite de taxa.
Para uma integração com 17TRACK, comece pela página do produto Tracking API e use a documentação oficial da API para confirmar a operação, o método de autenticação, o formato da solicitação e os campos da resposta. Considere os exemplos abaixo como padrões de implementação, não como substitutos do contrato dessa API.
Os limites de lote são mais do que um número máximo de remessas
Não existe um limite universal de lote para uma Tracking API. Os limites podem variar de acordo com o provedor, o endpoint, a versão da API e a configuração da conta. Antes de implementar o processamento em lotes, registre essas restrições separadamente.
| Restrição | O que confirmar | Consequência para a implementação |
|---|---|---|
| Itens por solicitação | Número máximo de registros para a operação específica | Dividir a lista de entrada antes do envio |
| Tamanho do corpo da solicitação | Qualquer limite de bytes documentado | Considerar campos opcionais e o tamanho da serialização |
| Taxa de solicitações | Solicitações permitidas em um intervalo definido | Controlar o ritmo das solicitações por meio de um limitador compartilhado |
| Concorrência | Qualquer restrição a solicitações simultâneas | Limitar o número de workers ativos |
| Contabilização de uso | Se o uso é contado por solicitação, remessa ou outra unidade | Estimar o consumo separadamente do volume de solicitações |
Por exemplo, se um endpoint hipotético permitir 25 registros por solicitação, 63 registros exigirão três solicitações contendo 25, 25 e 13 registros. Esses números ilustram apenas o particionamento; eles não são limites declarados da 17TRACK.
Não presuma que o processamento em lotes reduz o uso faturável. Ele pode reduzir a sobrecarga das solicitações HTTP, mas qualquer efeito sobre as cobranças depende das regras reais de contabilização do provedor. Da mesma forma, um tamanho de lote válido não autoriza solicitações paralelas ilimitadas.
Prepare os registros antes de criar a solicitação
A maioria das falhas evitáveis em lotes começa na preparação da entrada. Valide cada remessa antes de adicioná-la a um lote, mas evite regras que rejeitem acidentalmente números de rastreamento legítimos de diferentes transportadoras.
- Preserve os números de rastreamento como strings. Convertê-los em números pode remover zeros à esquerda ou alterar identificadores longos.
- Remova espaços em branco acidentais ao redor. Não remova caracteres internos nem altere maiúsculas e minúsculas, a menos que a especificação relevante permita essa normalização.
- Valide os campos obrigatórios. Alguns fluxos de trabalho podem exigir um identificador de transportadora ou informações adicionais da remessa. Use apenas nomes e valores de campos documentados.
- Escolha um escopo explícito de deduplicação. Um número de rastreamento repetido não é automaticamente uma duplicata em todas as transportadoras, comerciantes ou remessas históricas.
- Mantenha um identificador local da remessa. Armazene a relação entre o item enviado e seu registro de pedido ou remessa, mesmo quando a API não aceitar campos de referência personalizados.
Para o Carrier Tracking em várias redes, não deduza a transportadora exclusivamente pelo comprimento ou prefixo de um número de rastreamento, a menos que essa inferência seja confiável para seu fluxo de trabalho específico. Quando a API oferecer suporte à identificação da transportadora, siga o comportamento documentado para lidar com ambiguidades.
Estrutura ilustrativa da solicitação
O JSON a seguir mostra o conceito de um payload em lote. O wrapper, os nomes das propriedades e os identificadores são ilustrativos, não correspondem ao esquema de solicitação da 17TRACK. Algumas APIs esperam um array no nível superior em vez de um objeto contendo um array.
{
"shipments": [
{
"tracking_number": "EXAMPLE000001",
"carrier_id": "DOCUMENTED_CARRIER_ID"
},
{
"tracking_number": "EXAMPLE000002",
"carrier_id": "DOCUMENTED_CARRIER_ID"
}
]
}Crie o payload por meio de um serializador JSON, em vez de concatenar strings. Envie as credenciais de autenticação pelo mecanismo documentado e mantenha-as fora do controle de versão, do código entregue ao navegador e dos logs rotineiros.
Processe a resposta em dois níveis
Uma solicitação em lote tem um resultado no nível de transporte e um resultado no nível da aplicação. Sua integração deve avaliar ambos.
Nível 1: A solicitação recebeu uma resposta utilizável?
Comece pelo status HTTP, pelos cabeçalhos da resposta e pelo corpo da resposta. Erros de autenticação, solicitações malformadas, limitação de taxa e falhas do servidor podem impedir o processamento normal dos itens. Um tempo limite de rede é diferente: o cliente pode não saber se o servidor recebeu ou processou a solicitação.
A semântica HTTP é definida na RFC 9110. No entanto, a documentação do provedor determina como os campos de resultado no nível da aplicação correspondem aos resultados reais das remessas.
Nível 2: O que aconteceu com cada remessa?
Se a resposta oferecer resultados no nível do item, classifique cada registro enviado. Não presuma que HTTP 200 significa que todos os registros foram bem-sucedidos, nem que uma lista de resultados preserva a ordem da solicitação, a menos que o contrato garanta isso explicitamente.
- Aceito: A operação foi bem-sucedida de acordo com a definição documentada do endpoint.
- Falha permanente de entrada: Corrija ou investigue o registro antes de outra tentativa.
- Falha que pode ser repetida: Programe outra tentativa de acordo com as orientações de repetição do provedor.
- Resultado desconhecido: A resposta está ausente, incompleta ou não pode ser associada com segurança ao registro enviado.
Mantenha as respostas “já registrado” ou semelhantes relacionadas a duplicatas separadas até compreender seu significado documentado. Elas podem indicar que o estado desejado já existe, mas não devem ser tratadas automaticamente como confirmação de propriedade, configuração ou assinatura bem-sucedida.
Após processar uma resposta, cada registro de entrada deve ter exatamente um resultado local. Uma verificação de reconciliação útil é: registros enviados são iguais a registros aceitos mais falhas permanentes mais falhas repetíveis mais resultados desconhecidos. Esta é uma regra de contabilização local, não um formato de resposta exigido pela API.
Lide com falhas parciais sem repetir registros bem-sucedidos
Suponha que um lote ilustrativo contenha dez remessas: sete são aceitas, duas têm campos obrigatórios inválidos e uma encontra um erro temporário documentado. Salve os sete resultados bem-sucedidos, encaminhe os dois registros inválidos para correção e tente novamente apenas a falha temporária.
Repetir os dez registros cria tráfego desnecessário e pode complicar o tratamento de duplicatas. Também torna mais difícil distinguir uma rejeição original de uma resposta posterior relacionada a duplicatas.
| Resultado | Ação recomendada |
|---|---|
| Campo inválido ou valor não compatível | Corrija a entrada; não repita sem alterações |
| Falha de autenticação ou permissão | Pause o trabalho afetado e corrija as credenciais ou o acesso |
| Resposta de limitação de taxa | Aguarde de acordo com as orientações documentadas e os cabeçalhos de resposta aplicáveis |
| Erro temporário no nível do item | Tente novamente esse item com tentativas limitadas e recuo progressivo |
| Tempo limite após o envio | Marque como incerto; reconcilie ou use garantias documentadas de segurança para repetição |
| Resultado não reconhecido ou incompleto | Preserve as evidências e investigue em vez de presumir sucesso |
HTTP 429 indica solicitações em excesso, e a resposta pode incluir um cabeçalho Retry-After, conforme descrito na RFC 6585. Não presuma que esse cabeçalho estará sempre presente. Quando nenhum atraso explícito para nova tentativa for fornecido, use uma política de recuo progressivo limitado compatível com a documentação da API.
Adicione jitter para distribuir as novas tentativas de vários workers, defina uma contagem máxima de tentativas ou uma idade máxima de repetição e envie os registros esgotados para uma fila de revisão. Repetir indefinidamente pode ocultar um problema persistente de configuração.
Por que os tempos limite exigem tratamento especial
Um tempo limite não comprova rejeição. O servidor pode ter aceito o lote antes de a conexão falhar. Portanto, repetir automaticamente uma solicitação que altera o estado pode repetir o trabalho.
Se o endpoint oferecer suporte a chaves de idempotência documentadas, siga suas regras, incluindo o escopo e a retenção da chave. Não invente um cabeçalho de idempotência presumindo que o servidor o respeitará. Caso contrário, use um fluxo de consulta ou reconciliação compatível para determinar se o estado desejado existe antes de reenviar. A deduplicação local ajuda a coordenar seus próprios workers, mas não garante idempotência no lado do servidor.
Um fluxo de trabalho prático para processamento em lotes
Mantenha os detalhes específicos do provedor em um adaptador para que a fila, o programador de novas tentativas e a lógica de monitoramento não dependam dos nomes brutos dos campos da resposta.
validate records and retain local shipment IDs
resolve duplicates within the intended business scope
split records using documented item and payload limits
for each batch through a bounded worker pool:
persist an attempt record before sending
wait for the shared rate limiter
send using the provider-specific adapter
if the outcome is uncertain:
enqueue reconciliation
continue
classify request-level and item-level outcomes
persist one outcome for every submitted record
schedule only eligible failures for retry
route invalid or exhausted records for review
Torne persistentes e recuperáveis o armazenamento dos resultados e o agendamento de novas tentativas. Por exemplo, um registro de trabalho durável ou um padrão transacional de enfileiramento pode impedir que uma falha do processo perca a decisão de repetição. Quando os workers forem reiniciados, eles deverão conseguir distinguir o trabalho não enviado daquele cujo resultado remoto ainda é incerto.
Use o tamanho do lote como uma configuração ajustável vinculada ao endpoint relevante, não como uma constante espalhada pela base de código. Um lote menor pode ser útil ao solucionar problemas ou isolar registros problemáticos; o maior lote permitido não é automaticamente o melhor tamanho operacional.
Monitore os resultados das remessas, não apenas a disponibilidade HTTP
O monitoramento da API deve mostrar se as remessas estão alcançando o estado desejado. Um painel que reporte apenas as taxas de sucesso HTTP pode não detectar falhas parciais dentro de respostas aparentemente bem-sucedidas.
- Taxa de aceitação de itens: Registros aceitos divididos pelos registros enviados, com um tratamento claramente definido para as repetições.
- Distribuição de falhas: Contagens por endpoint, código de erro documentado e contexto relevante da transportadora.
- Resultados desconhecidos: Registros não reconciliados e há quanto tempo permanecem sem resolução.
- Fila de novas tentativas: Repetições pendentes, idade da repetição mais antiga e tentativas esgotadas.
- Saúde das solicitações: Latência, tempos limite, limitação de taxa e erros do servidor.
- Atualidade do rastreamento: Se as remessas aceitas recebem posteriormente informações de rastreamento utilizáveis.
A aceitação do registro não é prova de uma nova leitura da transportadora. Mantenha o status do processamento da API separado do movimento da remessa e da atualidade dos dados para que um incidente de integração não seja confundido com um atraso na entrega.
Registre IDs locais de lote, referências de remessa, contagens de tentativas, códigos de erro documentados e IDs de solicitação do provedor quando disponíveis. Oculte credenciais e informações pessoais desnecessárias. Use identificadores de rastreamento apenas quando forem operacionalmente necessários e evite colocar identificadores brutos de remessas em rótulos de métricas de alta cardinalidade.
Teste estes casos antes da produção
Use um sandbox documentado ou um ambiente de testes controlado quando disponível. Não presuma que números de rastreamento inventados produzirão respostas previsíveis em produção.
- Envie um lote válido no limite documentado de itens e depois teste como seu cliente impede um lote grande demais.
- Verifique se os números de rastreamento com zeros à esquerda sobrevivem à serialização e ao armazenamento.
- Teste itens aceitos e rejeitados misturados sem repetir os registros bem-sucedidos.
- Simule a limitação de taxa e confirme que vários workers respeitam o mesmo limite.
- Simule um tempo limite após o envio e verifique o caminho de reconciliação.
- Reinicie um worker entre o recebimento da resposta e a persistência local.
- Teste resultados de itens ausentes, desconhecidos ou impossíveis de associar.
- Confirme que os registros inválidos chegam a uma fila de correção visível em vez de serem repetidos indefinidamente.
Uma integração pronta para produção consegue explicar o estado de cada remessa enviada, inclusive aquelas cujo resultado é temporariamente desconhecido. Reduzir o número de solicitações é útil; preservar essa responsabilidade é o objetivo de design mais importante.
Perguntas frequentes
Quantos números de rastreamento posso enviar em uma única solicitação?
Use o limite documentado para o endpoint e a versão exatos da API. Verifique também o tamanho da solicitação, os limites de taxa e quaisquer restrições específicas da conta. Não existe um número universal seguro que possa ser aplicado a todas as APIs de rastreamento ou a diferentes operações dentro de uma mesma API.
Um número de rastreamento inválido pode fazer todo o lote falhar?
Sim, dependendo das regras de validação do endpoint. Algumas APIs retornam rejeições individuais, enquanto outras podem rejeitar uma solicitação antes do processamento dos itens. Verifique tanto os erros no nível da solicitação quanto os resultados no nível do item; não presuma que todo endpoint de lote aceite parcialmente os registros.
Devo repetir um lote quando a resposta HTTP for bem-sucedida?
Não automaticamente. Primeiro analise o status documentado no nível da aplicação e os resultados dos itens. Persista os registros bem-sucedidos e repita apenas as falhas elegíveis. Se o resultado não puder ser interpretado com segurança, classifique-o como incerto e investigue.
Posso misturar transportadoras no mesmo lote?
Somente quando o endpoint oferecer suporte a essa estrutura de solicitação. Confirme se as informações da transportadora são fornecidas por remessa, se a identificação automática é compatível e o que acontece quando a identificação é ambígua. Um serviço de várias transportadoras, por si só, não estabelece as regras de lote de todos os endpoints.
O processamento em lotes faz as atualizações de rastreamento chegarem mais rápido?
O processamento em lotes pode reduzir o número de solicitações enviadas pela aplicação, mas não faz, por si só, com que os eventos da transportadora apareçam mais cedo. O registro, a obtenção de dados, a disponibilidade da leitura da transportadora e a entrega das atualizações são partes separadas do fluxo de trabalho.
Fontes
- Tracking API da 17TRACK — ponto de entrada oficial do produto para desenvolvedores que avaliam uma integração de rastreamento.
- Documentação da API da 17TRACK — referência para o contrato específico dos endpoints do provedor, limites, autenticação e tratamento de respostas.
- RFC 9110: Semântica HTTP — semântica dos status HTTP, idempotência, novas tentativas automáticas e Retry-After.
- RFC 6585: Códigos de status HTTP adicionais — definição de HTTP 429 Too Many Requests e seu cabeçalho Retry-After opcional.


