PUT
api/v1/pedidoRastreioNovo
Registra eventos de rastreio manual em um volume do pedido. Para lojas que não têm link de rastreio da transportadora. Cada evento tem tipo (envio ou reversa), data e hora, descrição e controle de visibilidade ao cliente final. Devolve a URL pública de rastreio do HelpyGo para enviar ao consumidor.
Limite: 120 requisições por minuto
Descrição
Registra eventos de rastreio manual em um volume de um pedido e devolve a URL pública de rastreio do HelpyGo para você enviar ao consumidor final.Feito para lojas que não têm link de rastreio de transportadora: frota própria, transportadora regional sem portal, ou logística que informa o status por telefone/planilha.
O pedido precisa existir. O pedido é localizado na loja do token, nesta ordem:
1. Por numeroPedido
2. Se não encontrado e informado, por pedidoCanal
3. Se não encontrado e informado, por pedidoLoja
Não havendo pedido, a resposta é 404 e nada é gravado.
Identificação do volume (chaveEnvio). Um pedido pode ter mais de um volume — é o caso de quem vende quantidade 2 e depois desmembra em dois envios, ou de quem tem várias entregas para o mesmo pedido. Cada volume tem sua própria timeline, identificada por uma chave estável resolvida nesta precedência, do identificador mais específico para o menos específico:
1. identificadorEnvio — texto livre seu (ex.: o número da entrega no seu ERP). Informar este campo é declarar explicitamente a identidade do volume, e ele vence os outros dois
2. codigoRastreio — código do objeto na transportadora
3. chaveNFe — 44 dígitos, usada só quando não há nenhuma das anteriores
Ao menos uma das três é obrigatória. Reenviar a mesma chave acrescenta eventos ao volume já existente; uma chave nova cria um volume novo.
ATENÇÃO — mais de uma entrega por pedido. A
chaveNFe é a última da lista por um motivo prático: uma nota fiscal pode cobrir várias entregas. Se você tem três entregas do mesmo pedido e manda só a chaveNFe (a mesma nas três), as três resolvem para a MESMA chaveEnvio e os eventos colapsam num único volume.
Para separar as entregas, mande
identificadorEnvio com o identificador da entrega no seu sistema. A chaveNFe continua sendo gravada como dado do volume — ela só deixa de disputar a identidade:
| Campo | Valor por entrega |
| identificadorEnvio | DIFERENTE em cada entrega — é o que separa os volumes |
| codigoEnvio | Normalmente igual ao identificadorEnvio, só para exibição no rótulo |
| chaveNFe | Pode repetir entre as entregas — é gravada como dado, não como identidade |
Identificação × exibição. Dois campos têm nomes parecidos e papéis diferentes:
| Campo | Papel |
| identificadorEnvio | Identidade. Terceira opção de chaveEnvio. Mudar este valor cria um volume NOVO, com timeline própria. |
| codigoEnvio | Exibição. Rótulo do volume nas telas — substitui o número sequencial (Envio #ABC123 em vez de Envio #1). Pode ser alterado a qualquer momento sem afetar a identidade nem os eventos já gravados. |
Atualização dos campos de exibição. Como a chamada é um upsert, informar
codigoEnvio, rotulo ou codigoRastreio para um volume que já existe atualiza esses campos junto da gravação dos eventos. Isso permite começar a enviar o código depois, sem recriar nada.
Idempotência. Cada evento recebe um identificador calculado a partir de tipo + data/hora (precisão de segundo) + descrição. Reenviar o mesmo evento não duplica a timeline: ele é contado em
eventosDuplicados e a resposta continua 200. Diferenças apenas de espaçamento ou de maiúsculas/minúsculas na descrição não criam evento novo. Isso permite que sua rotina reprocesse janelas sobrepostas sem se preocupar.
A sigla NÃO entra na identidade do evento. Consequência prática em duas direções: reenviar o mesmo evento com sigla diferente é tratado como duplicado e a sigla gravada não é atualizada — para corrigi-la, use o serviço 45. E mudar a sigla no seu sistema não faz o evento ser reinserido como novo.
Visibilidade ao cliente final. O campo
visivelClienteFinal controla o que aparece na página pública. Eventos com false ficam visíveis apenas para o atendente, na tela de detalhes do pedido — útil para anotações operacionais como "divergência de endereço, contatar comercial". Quando o campo é omitido, o padrão é true.
Fuso horário. Envie
dataHora em ISO-8601 com offset (ex.: 2026-04-06T15:07:19-03:00). Sem offset, o valor é interpretado como horário de Brasília.
Link único por pedido. Todos os volumes de um pedido compartilham o mesmo link. Se o pedido for uma reversa com numeroPedidoEnvioPai, o link do pedido de envio pai é reaproveitado — assim um único link mostra a ida e a volta.
Link no pedido. A URL pública também é gravada no envio correspondente do pedido, em
envio[].linkRastreioHelpyGo, e espelhada em envio[].linkRastreio somente quando este está vazio (para não sobrescrever o link de uma transportadora que exista). O campo linkNoPedido da resposta informa se a gravação ocorreu: false significa que nenhum envio do pedido casou com a chave informada — o rastreio funciona normalmente, só não foi vinculado a um envio.
Limites. Até 100 eventos por requisição e até 200 eventos por volume.
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 — JSON ausente ou malformado, nenhuma forma de localizar o pedido, nenhuma fonte de chaveEnvio, tipo fora de envio/reversa, descrição vazia, dataHora inválida, sigla que não é texto, ou mais de 100 eventos. A mensagem indica o campo e, quando aplicável, o índice do evento. |
| 401 | Não autorizado — Token ausente, inválido, inativo ou sem permissão para este serviço/método. |
| 404 | Pedido não encontrado na loja do token. |
| 409 | Volume já atingiu o máximo de 200 eventos. Nenhum evento novo é aceito neste volume. |
| 429 | Limite de requisições ultrapassada — Aguarde o próximo minuto para novas requisições. |
Body da Requisição
JSON
{
"numeroPedido": "2000015820134890",
"pedidoCanal": "",
"pedidoLoja": "",
"codigoRastreio": "1175100",
"chaveNFe": "41260477941490029480550010011751001065962395",
"identificadorEnvio": "",
"rotulo": "Tanquinho Wanke Super 4kg",
"codigoEnvio": "ABC123",
"eventos": [
{
"tipo": "envio",
"dataHora": "2026-04-06T15:07:19-03:00",
"descricao": "Nota fiscal emitida",
"sigla": "NFS",
"visivelClienteFinal": true
},
{
"tipo": "envio",
"dataHora": "2026-04-07T09:12:00-03:00",
"descricao": "Em trânsito para Prudêncio Thomaz - MS",
"sigla": "ETR",
"visivelClienteFinal": true
},
{
"tipo": "envio",
"dataHora": "2026-04-07T18:40:00-03:00",
"descricao": "Divergência de endereço - contatar comercial",
"sigla": "CDL",
"visivelClienteFinal": false
}
]
}
Parâmetros de Entrada
| Campo | Descrição | Tipo | Tamanho | Obrigatório |
| numeroPedido | Número do pedido no HelpyGo. Primeira tentativa de localização do pedido. Obrigatório se pedidoCanal e pedidoLoja não forem informados. | string | 100 | condicional |
| pedidoCanal | Número do pedido no canal/marketplace. Segunda tentativa de localização. | string | 100 | condicional |
| pedidoLoja | Número do pedido na loja/plataforma de envio. Terceira tentativa de localização. | string | 100 | condicional |
| identificadorEnvio | Identificador do volume no seu sistema (ex.: o número da entrega). É a primeira opção de identificação (chaveEnvio) e vence as outras duas. Use este campo quando o pedido tem mais de uma entrega — é ele que separa os volumes. Obrigatório se codigoRastreio e chaveNFe não forem informados. | string | 100 | condicional |
| codigoRastreio | Código de rastreio do volume na transportadora. Segunda opção de identificação do volume. | string | 100 | condicional |
| chaveNFe | Chave da NF-e, 44 dígitos. Última opção de identificação, porque uma nota pode cobrir VÁRIAS entregas — mandar só ela num pedido com múltiplas entregas faz os eventos colapsarem num único volume. Pontuação é removida automaticamente. É sempre gravada como dado do volume, mesmo quando não é usada como identidade. | string | 44 | condicional |
| rotulo | Rótulo do volume exibido ao consumidor na página pública (ex.: nome do produto). Ajuda a identificar o volume quando o pedido foi desmembrado. | string | 255 | não |
| codigoEnvio | Código do envio no seu sistema, usado como rótulo do volume nas telas. Quando informado, substitui o número sequencial: aparece Envio #ABC123 em vez de Envio #1. Não confundir com identificadorEnvio: este é só exibição e pode ser alterado a qualquer momento sem criar volume novo — aquele participa da identificação do volume. | string | 50 | não |
| eventos | Lista de eventos de movimentação. Mínimo 1, máximo 100 por requisição. | array | 100 | sim |
| eventos[].tipo | Tipo do evento. Valores aceitos: envio ou reversa. Quando omitido, assume envio. | string | 7 | não |
| eventos[].dataHora | Data e hora em que a movimentação ocorreu, em ISO-8601. Com offset (2026-04-06T15:07:19-03:00) o offset é respeitado; sem offset o valor é interpretado como horário de Brasília. A precisão usada na identificação do evento é de segundo. | string | 40 | sim |
| eventos[].descricao | Descrição da movimentação, exibida ao consumidor. Truncada em 500 caracteres. Não pode ser vazia. | string | 500 | sim |
| eventos[].sigla | Código do evento no seu sistema (ex.: ETR, NFS, ENT, CDL, ADE). Exibido abaixo da descrição, tanto na tela do atendente quanto na página pública de rastreio. Truncado em 10 caracteres. Não compõe a identidade do evento — ver a nota sobre idempotência na descrição deste endpoint. | string | 10 | não |
| eventos[].visivelClienteFinal | Define se o evento aparece na página pública de rastreio. Com false, o evento fica visível apenas ao atendente na tela do pedido. Quando omitido, assume true. | boolean | não |
Parâmetros de Retorno
| Campo | Descrição | Tipo | Tamanho |
| mensagem | Mensagem da operação. Em erro, descreve o campo e o motivo. | string | 255 |
| idPedido | Identificador do pedido no HelpyGo. Guarde este valor para usar como filtro nos endpoints de consulta e de correção de evento. | string | 32 |
| numeroPedido | Número do pedido localizado. | string | 100 |
| chaveEnvio | Chave do volume efetivamente usada, após a resolução por precedência. | string | 100 |
| origemChave | De qual campo veio a chaveEnvio. Valores: codigoRastreio, chaveNFe ou identificador. | string | 20 |
| eventosCriados | Quantidade de eventos efetivamente gravados nesta requisição. | integer | |
| eventosDuplicados | Quantidade de eventos ignorados porque já existiam no volume. Reenvio do mesmo lote resulta em eventosCriados 0 e eventosDuplicados igual ao total — a resposta continua 200. | integer | |
| totalEventos | Total de eventos no volume após esta requisição. | integer | |
| linkRastreio | URL pública de rastreio para enviar ao consumidor. É a mesma para todos os volumes do pedido, e para a reversa vinculada. | string | 255 |
| linkNoPedido | Indica se a URL foi gravada no envio correspondente do pedido. false significa que nenhum envio casou com a chaveEnvio informada — o rastreio e o link público funcionam normalmente, apenas não houve vínculo com um envio. | boolean | |
| limiteAtingido | Presente apenas quando o limite de 200 eventos do volume foi alcançado durante o processamento do lote. Os eventos anteriores ao limite foram gravados. | boolean |
Exemplo de Resposta
JSON
{
"mensagem": "Eventos registrados",
"idPedido": "21487f878432f9f72dfe4df59c4a47d4",
"numeroPedido": "2000015820134890",
"chaveEnvio": "1175100",
"origemChave": "codigoRastreio",
"eventosCriados": 3,
"eventosDuplicados": 0,
"totalEventos": 3,
"linkRastreio": "https://www.helpygo.com.br/rastreio/9c1f4a7b2e6d8035a4c9f1b7e2d60483",
"linkNoPedido": true
}