GET api/v1/pedidoRastreio

Descrição

Consulta os volumes e a timeline completa de rastreio manual de um pedido.

Diferente da página pública, esta consulta devolve também os eventos internos (visivelClienteFinal: false), porque quem consulta é a própria loja, autenticada pelo token.

Como chamar. Informe o filtro em chave e o valor em valor:

GET /api/v1/pedidoRastreio?chave=numeroPedido&valor=2000015820134890

Filtros aceitos:

chave	Descrição
numeroPedido	Número do pedido no HelpyGo.
pedidoCanal	Número do pedido no canal/marketplace.
codigoRastreio	Código de rastreio de um volume. A resposta é expandida para todos os volumes do mesmo pedido, não apenas o volume do código informado.
idPedido	Identificador do pedido devolvido pelo endpoint de registro de eventos. É o filtro mais preciso, porque numeroPedido não é único por loja (envio e reversa coexistem).

Qualquer outro valor em chave resulta em 400.

Escopo. A consulta é sempre restrita à loja do token. Rastreio de outra loja não é alcançável por este endpoint.

Ordenação. Os eventos de cada volume vêm em ordem cronológica crescente (mais antigo primeiro), independente da ordem em que foram registrados.

Obs.: Utilizar tokenAPI (Authorization: Bearer)

Limite de requisições: 120 requisições por minuto.

Códigos de erro:

Código	Descrição
400	Requisição inválida — valor não informado ou filtro fora da lista aceita.
401	Não autorizado — Token ausente, inválido, inativo ou sem permissão para este serviço/método.
404	Rastreio não encontrado — não existe rastreio manual para o filtro informado nesta loja.
429	Limite de requisições ultrapassada — Aguarde o próximo minuto para novas requisições.

Parâmetros de Entrada

Campo	Descrição	Tipo	Tamanho	Obrigatório
chave	Filtro da consulta, na query string. Valores aceitos: numeroPedido, pedidoCanal, codigoRastreio ou idPedido.	string	20	sim
valor	Valor correspondente ao filtro escolhido em chave.	string	100	sim

Parâmetros de Retorno

Campo	Descrição	Tipo	Tamanho
idPedido	Identificador do pedido no HelpyGo.	string	32
numeroPedido	Número do pedido no HelpyGo.	string	100
pedidoCanal	Número do pedido no canal/marketplace.	string	100
linkRastreio	URL pública de rastreio, compartilhada por todos os volumes do pedido.	string	255
totalVolumes	Quantidade de volumes devolvidos.	integer
volumes	Lista de volumes do pedido.	array
volumes[].chaveEnvio	Chave estável que identifica o volume.	string	100
volumes[].origemChave	De qual campo veio a chaveEnvio: codigoRastreio, chaveNFe ou identificador.	string	20
volumes[].codigoRastreio	Código de rastreio do volume, quando informado.	string	100
volumes[].chaveNFe	Chave da NF-e do volume, quando informada.	string	44
volumes[].rotulo	Rótulo do volume exibido na página pública.	string	255
volumes[].codigoEnvio	Código do envio no sistema da loja, usado como rótulo do volume nas telas. Vazio quando não informado.	string	50
volumes[].tipoPedido	Tipo do pedido do volume: envio ou reversa.	string	7
volumes[].status	Situação do volume: ativo ou encerrado.	string	10
volumes[].totalEventos	Total de eventos do volume, internos inclusive.	integer
volumes[].eventos	Eventos do volume, em ordem cronológica crescente.	array
eventos[].hash	Identificador do evento. É o valor a informar no endpoint de correção de evento.	string	40
eventos[].tipo	Tipo do evento: envio ou reversa.	string	7
eventos[].dataHora	Data e hora da movimentação, em ISO-8601 com offset.	string	40
eventos[].descricao	Descrição da movimentação.	string	500
eventos[].sigla	Código do evento no sistema da loja. Vazio quando não informado, inclusive em eventos gravados antes de o campo existir.	string	10
eventos[].visivelClienteFinal	Indica se o evento aparece na página pública. Eventos com false são devolvidos aqui, mas não ao consumidor.	boolean
eventos[].origem	Origem do registro do evento.	string	20

Exemplo de Resposta

{
  "idPedido": "21487f878432f9f72dfe4df59c4a47d4",
  "numeroPedido": "2000015820134890",
  "pedidoCanal": "2000015820134890",
  "linkRastreio": "https://www.helpygo.com.br/rastreio/9c1f4a7b2e6d8035a4c9f1b7e2d60483",
  "totalVolumes": 1,
  "volumes": [
    {
      "chaveEnvio": "1175100",
      "origemChave": "codigoRastreio",
      "codigoRastreio": "1175100",
      "chaveNFe": "41260477941490029480550010011751001065962395",
      "rotulo": "Tanquinho Wanke Super 4kg",
      "codigoEnvio": "ABC123",
      "tipoPedido": "envio",
      "status": "ativo",
      "totalEventos": 3,
      "eventos": [
        {
          "hash": "c41e9a2b7f0d3856a1c4e9b2d7f60483a1c4e9b2",
          "tipo": "envio",
          "dataHora": "2026-04-06T15:07:19-03:00",
          "descricao": "Nota fiscal emitida",
          "sigla": "NFS",
          "visivelClienteFinal": true,
          "origem": "api"
        },
        {
          "hash": "77ab3c1e9d5f2048b6a3c1e9d5f2048b6a3c1e9d",
          "tipo": "envio",
          "dataHora": "2026-04-07T09:12:00-03:00",
          "descricao": "Em trânsito para Prudêncio Thomaz - MS",
          "sigla": "ETR",
          "visivelClienteFinal": true,
          "origem": "api"
        },
        {
          "hash": "e0d24f8a1c6b93705d2f8a1c6b93705d2f8a1c6b",
          "tipo": "envio",
          "dataHora": "2026-04-07T18:40:00-03:00",
          "descricao": "Divergência de endereço - contatar comercial",
          "sigla": "CDL",
          "visivelClienteFinal": false,
          "origem": "api"
        }
      ]
    }
  ]
}