Lista de Rastreamentos

Listagem de rastreamentos

GET {url_base}/trackings/list

Retorna uma lista paginada de rastreamentos de pedidos de uma loja específica, filtrada por intervalo de datas do último status atualizado. Os status são automaticamente traduzidos para o idioma configurado da loja.

São permitidos apenas filtros com até 30 dias no período informado nos parâmetros last_status_date_from e last_status_date_to.

O ideal por questão de performance é não passar dos 15 dias, quanto menor o período, mais rápido a API responde

Query Parameters

Name	Type	Description
store_id*	UUID	ID único da loja
last_status_date_from*	String	Data inicial do filtro (inclusive) Formato: YYYY-MM-DD
last_status_date_to*	String	Data final do filtro (inclusive) Formato: YYYY-MM-DD
page	Integer	Número da página que será retornada os dados dos rastreamentos Padrão: 1
limit	Integer	Quantidade de itens por página Padrão: 100, máximo: 300

Headers

Name	Type	Description
X-Api-Key*	String	Chave de API criada através da plataforma
X-Api-Version*	String	Versão da API a ser utilizada, de acordo com a documentação Enviar "v1" como default

Nota: Se você estiver usando a NODE_API_KEY (chave interna do sistema), é necessário fornecer o store_id na requisição para identificar a loja.

200: OK Rastreamentos listados com sucesso

{
  "status": "Tracking list found",
  "data": [
    {
      "order_id": "550e8400-e29b-41d4-a716-446655440000",
      "tracking_code": "BR123456789BR",
      "redispatch_tracking_code": null,
      "delivery_company": "Correios",
      "delivered_date": "2024-01-20T14:30:00",
      "shipped_date": "2024-01-15T10:00:00",
      "last_status_date": "2024-01-20T14:30:00",
      "status": "Entregue",
      "sub_status": "Entregue ao destinatário",
      "recipient": "João Silva",
      "expected_delivery_date": "2024-01-22T00:00:00",
      "client_cnpj": "12.345.678/0001-90"
    }
  ],
  "page": {
    "count": null,
    "total_pages": 5,
    "current_page": 1,
    "per_page": 100,
    "has_next": true,
    "has_previous": false
  }
}

Campos do Objeto Tracking

Campo	Tipo	Descrição	Pode ser null?
order_id	UUID (String)	ID único do pedido	Não
tracking_code	String	Código de rastreamento principal	Sim
redispatch_tracking_code	String	Código de rastreamento de reenvio	Sim
delivery_company	String	Nome da transportadora	Sim
delivered_date	ISO 8601 DateTime	Data e hora da entrega	Sim
shipped_date	ISO 8601 DateTime	Data e hora do envio	Sim
last_status_date	ISO 8601 DateTime	Data e hora do último status atualizado	Não
status	String	Status traduzido do rastreamento	Sim
sub_status	String	Sub-status traduzido do rastreamento	Sim
recipient	String	Nome do destinatário	Sim
expected_delivery_date	ISO 8601 Date	Data prevista de entrega	Sim
client_cnpj	String	CNPJ do cliente	Sim

Campos de Paginação

Campo	Tipo	Descrição
count	null	Total de registros (sempre null por performance)
total_pages	Integer	Número total de páginas (aproximado)
current_page	Integer	Página atual
per_page	Integer	Itens por página
has_next	Boolean	Indica se há próxima página
has_previous	Boolean	Indica se há página anterior

400: Bad Request Parâmetros obrigatórios inválidos

401: Unauthorized Acesso não autorizado

404: Not Found Rastreamentos não encontrados

429: Too Many Requests Limite de requisições atingido

Notas Importantes

Tradução de Status

Os status de rastreamento são automaticamente traduzidos com base nas configurações da loja. A tradução é aplicada tanto no campo status quanto no sub_status.

Exemplo:

• Status original: "Em trânsito"

• Status traduzido: "In transit" (se a loja estiver configurada para inglês)

A tradução é feita usando regras configuráveis que podem usar operadores:

• equals: Comparação exata (case-insensitive)

• contains: Contém a string (case-insensitive)

Performance

• ⚡ A API é otimizada para grandes volumes de dados

• ⚡ O campo count retorna null intencionalmente para evitar queries lentas

• ⚡ Use limit=300 (máximo) para reduzir o número de requisições

• ⚡ A ordenação é sempre por last_status_date DESC (mais recentes primeiro)

Limites de Requisição

• O intervalo de datas é limitado a 30 dias por requisição

• Para períodos maiores, faça múltiplas requisições dividindo o intervalo

• O limite máximo de itens por página é 300

Fuso Horário

• Todas as datas são retornadas em formato ISO 8601

• As datas de filtro (last_status_date_from e last_status_date_to) são tratadas como datas completas (00:00:00 até 23:59:59)

• O fuso horário usado é o configurado no servidor

Filtros Aplicados

• Apenas rastreamentos de pedidos não deletados são retornados

• Apenas rastreamentos da loja especificada são retornados

• Apenas rastreamentos com last_status_date dentro do intervalo são retornados