Tracking — Rastreamento Logístico de Pedidos
1. Visão Geral
O serviço de Tracking permite acompanhar, em tempo real, o ciclo de vida logístico de um pedido realizado na plataforma Getnet. Ele responde a perguntas como:
- "Onde está o equipamento que pedi?"
- "O técnico já saiu para fazer a manutenção?"
- "Meu pedido foi entregue ou devolvido?"
Em vez de consultar múltiplos sistemas internos, o consumidor da API obtém em uma única chamada uma visão consolidada de tudo o que aconteceu com o pedido — desde o momento em que foi registrado até a conclusão da entrega, retirada ou manutenção do equipamento.
2. Contexto e Casos de Uso
Quando usar este serviço?
Use o Tracking sempre que precisar exibir ou processar o andamento logístico de um pedido. É indicado para:
| Cenário | Descrição |
|---|---|
| Portal do lojista | Exibir ao merchant o status atualizado do equipamento solicitado (ex.: maquininha em caminho). |
| Atendimento ao cliente | Permitir que agentes de suporte consultem rapidamente a situação de um pedido sem acessar sistemas internos. |
| Notificações automáticas | Acionar alertas (e-mail, SMS, push) quando o status do pedido mudar (ex.: equipamento entregue). |
| Auditoria e compliance | Registrar e auditar a linha do tempo completa de eventos de um pedido. |
| Acompanhamento de manutenção | Verificar se um técnico foi despachado e quando a manutenção foi concluída. |
| Gestão de devoluções | Rastrear a retirada de equipamentos em casos de cancelamento ou devolução. |
Exemplos de cenários reais
Cenário 1 — Novo lojista aguardando a maquininha:
Um estabelecimento acabou de assinar o serviço Getnet. O portal do lojista consulta o Tracking pelo
order_id para exibir em qual etapa o equipamento se encontra — se está sendo preparado, se foi despachado ou se já foi entregue.Cenário 2 — Manutenção de equipamento:
Um terminal apresentou defeito e uma ordem de serviço foi aberta. O sistema de suporte consulta o Tracking pelo
service_number para saber se o técnico já buscou o equipamento e quando a manutenção foi concluída.Cenário 3 — Retirada de equipamento:
Um contrato foi encerrado e a Getnet precisa recolher o terminal. O backoffice acompanha pelo
order_number se a retirada foi realizada com sucesso ou se houve falha na tentativa de coleta.3. Fluxo Principal
O serviço de Tracking possui um único endpoint de consulta. O consumidor informa o identificador do pedido e recebe o objeto completo com situação, etapas e eventos.
text
┌─────────────────────────────────────────────────────────────────┐
│ FLUXO DE CONSULTA │
└─────────────────────────────────────────────────────────────────┘
[1] Obter Token de Acesso
└─► 600;">POST /token (domínio Authentication)
│
▼
[2] Consultar Tracking
└─► 600;">GET /tracking/detail
│ query: order_id | order_number | service_number
│
▼
[3] Processar Resposta (TrackingDTO)
│
├─► situation → Status geral do pedido (pending / finished)
│
├─► identifier → Todos os números de referência do pedido
│
├─► merchant → Dados do estabelecimento comercial
│
├─► buyer → Dados do comprador
│
├─► items[]
│ ├─► products[] → Equipamentos/materiais do item
│ ├─► steps[] → Etapas macro (order, payment, fulfillment,
│ │ delivery, withdrawal, finish)
│ └─► events[] → Eventos detalhados dentro de cada etapa
│
└─► delivery_info → Transportadora, código de rastreio,
datas estimada e efetiva de entrega
text
┌─────────────────────────────────────────────────────────────────┐
│ FLUXO DE CONSULTA │
└─────────────────────────────────────────────────────────────────┘
[1] Obter Token de Acesso
└─► 600;">POST /token (domínio Authentication)
│
▼
[2] Consultar Tracking
└─► 600;">GET /tracking/detail
│ query: order_id | order_number | service_number
│
▼
[3] Processar Resposta (TrackingDTO)
│
├─► situation → Status geral do pedido (pending / finished)
│
├─► identifier → Todos os números de referência do pedido
│
├─► merchant → Dados do estabelecimento comercial
│
├─► buyer → Dados do comprador
│
├─► items[]
│ ├─► products[] → Equipamentos/materiais do item
│ ├─► steps[] → Etapas macro (order, payment, fulfillment,
│ │ delivery, withdrawal, finish)
│ └─► events[] → Eventos detalhados dentro de cada etapa
│
└─► delivery_info → Transportadora, código de rastreio,
datas estimada e efetiva de entrega
Estrutura de etapas e eventos
Cada pedido avança por etapas (steps) que agrupam eventos (events) granulares. Veja a progressão típica:
text
ORDER ──────────────────────────────────────────────────────────►
└── order_submitted
└── order_approved | order_canceled
PAYMENT ────────────────────────────────────────────────────────►
└── payment_required
└── payment_registered | payment_canceled | payment_chargeback
FULFILLMENT ────────────────────────────────────────────────────►
└── fulfilment_preparing
└── fulfilment_done
└── fulfilment_invoice | fulfilment_canceled
DELIVERY ───────────────────────────────────────────────────────►
└── delivery_generate_shipment
└── delivery_sent_partner
└── delivery_route_distribution_center
└── delivery_received_distribution_center
└── delivery_route
└── delivery_delivered | delivery_failure | delivery_returned
FINISH ─────────────────────────────────────────────────────────►
└── finished_success | finished_failure
text
ORDER ──────────────────────────────────────────────────────────►
└── order_submitted
└── order_approved | order_canceled
PAYMENT ────────────────────────────────────────────────────────►
└── payment_required
└── payment_registered | payment_canceled | payment_chargeback
FULFILLMENT ────────────────────────────────────────────────────►
└── fulfilment_preparing
└── fulfilment_done
└── fulfilment_invoice | fulfilment_canceled
DELIVERY ───────────────────────────────────────────────────────►
└── delivery_generate_shipment
└── delivery_sent_partner
└── delivery_route_distribution_center
└── delivery_received_distribution_center
└── delivery_route
└── delivery_delivered | delivery_failure | delivery_returned
FINISH ─────────────────────────────────────────────────────────►
└── finished_success | finished_failure
Nota: Para pedidos de retirada ou manutenção, os eventos seguem a mesma lógica, porém com prefixoswithdrawal_emaintenance_respectivamente.
4. Pré-requisitos
Autenticação
Toda chamada ao Tracking requer um token de acesso válido, obtido previamente no serviço de autenticação da Getnet.
| Item | Detalhe |
|---|---|
| Como obter | POST /token no domínio Authentication |
| Como enviar | Header HTTP: Authorization: {access_token} |
| Formato | Sem prefixo "Bearer" — envie o token diretamente |
Dependências de outros serviços
| Serviço | Motivo |
|---|---|
| Authentication | Geração do token de acesso obrigatório |
| Orders | Origem dos identificadores order_id e order_number |
Ambientes disponíveis
| Ambiente | URL base |
|---|---|
| Homologação | https://api-homologacao.getnet.com.br:443/v1 |
| Produção | https://api-backoffice.getnet.com.br:443/v1 |
5. Guia de Integração Rápida
Consultar o tracking de um pedido (happy path)
Passo 1 — Obtenha o token de autenticação
Consulte o domínio de Authentication e guarde o
access_token retornado.Passo 2 — Faça a consulta ao Tracking
Informe ao menos um dos parâmetros de busca disponíveis:
text
600;">GET /tracking/detail?order_id=<uuid-do-pedido>
Headers:
Authorization: <access_token>
text
600;">GET /tracking/detail?order_id=<uuid-do-pedido>
Headers:
Authorization: <access_token>
Ou, se preferir buscar pelo número do pedido legível:
text
600;">GET /tracking/detail?order_number=PED-2024-00123
Headers:
Authorization: <access_token>
text
600;">GET /tracking/detail?order_number=PED-2024-00123
Headers:
Authorization: <access_token>
Ou pelo número da Ordem de Serviço:
text
600;">GET /tracking/detail?service_number=OS-9876543
Headers:
Authorization: <access_token>
text
600;">GET /tracking/detail?service_number=OS-9876543
Headers:
Authorization: <access_token>
Passo 3 — Interprete a resposta
Uma resposta bem-sucedida (
HTTP 200) retorna o objeto TrackingDTO. Veja os campos mais relevantes para o consumo imediato:text
{
"tracking_id": "...",
"situation": {
"status": "pending", ← Status atual: pending ou finished
"description": "Em transporte", ← Descrição legível da situação
"status_update_date": "..." ← Quando foi atualizado pela última vez
},
"flow_type": "sale_delivery", ← Tipo de fluxo logístico
"identifier": {
"order_id": "...",
"order_number": "...",
"service_number": "...",
...
},
"items": [
{
"products": [ { "name": "POS Smart", ... } ],
"steps": [
{
"name": "delivery",
"situation": { "status": "pending", "description": "..." }
}
],
"events": [
{
"name": "delivery_sent_partner",
"description": "Enviado para transportadora",
"update_date_time": "2024-06-01T10:30:00Z"
}
]
}
],
"delivery_info": {
"carrier_name": "Correios",
"tracking_code": "BR123456789BR",
"estimated_delivery_date": "2024-06-05"
}
}
text
{
"tracking_id": "...",
"situation": {
"status": "pending", ← Status atual: pending ou finished
"description": "Em transporte", ← Descrição legível da situação
"status_update_date": "..." ← Quando foi atualizado pela última vez
},
"flow_type": "sale_delivery", ← Tipo de fluxo logístico
"identifier": {
"order_id": "...",
"order_number": "...",
"service_number": "...",
...
},
"items": [
{
"products": [ { "name": "POS Smart", ... } ],
"steps": [
{
"name": "delivery",
"situation": { "status": "pending", "description": "..." }
}
],
"events": [
{
"name": "delivery_sent_partner",
"description": "Enviado para transportadora",
"update_date_time": "2024-06-01T10:30:00Z"
}
]
}
],
"delivery_info": {
"carrier_name": "Correios",
"tracking_code": "BR123456789BR",
"estimated_delivery_date": "2024-06-05"
}
}
6. Regras de Negócio
Parâmetros de busca
- Ao menos um dos três parâmetros deve ser informado:
order_id,order_numberouservice_number. - O
order_idsegue o formato UUID (ex.:550e8400-e29b-41d4-a716-446655440000). - Caso mais de um parâmetro seja enviado, o sistema utilizará a combinação para refinar a busca.
Tipos de fluxo (flow_type)
O campo
flow_type indica a natureza logística do pedido. Cada tipo determina quais etapas e eventos são esperados:| Valor | Descrição funcional |
|---|---|
sale_delivery | Venda com entrega de equipamento |
rent_delivery | Locação com entrega de equipamento |
prepaid_card_delivery | Entrega de cartão pré-pago |
maintenance_rent | Manutenção de equipamento alugado |
rent_withdrawal | Retirada de equipamento alugado |
sale_maintenance | Manutenção de equipamento vendido |
sale_devolution | Devolução de equipamento vendido |
affiliation_fee_delivery | Entrega de kit de afiliação |
affiliation_fee_maintenance | Manutenção de kit de afiliação |
affiliation_fee_withdrawal | Retirada de kit de afiliação |
affiliation_fee_replacement | Substituição de kit de afiliação |
Status do tracking (status)
| Valor | Significado |
|---|---|
pending | O ciclo logístico ainda está em andamento |
finished | O ciclo logístico foi concluído (com sucesso ou falha) |
Eventos com dados adicionais
O campo
additional_data dentro de um evento pode conter informações variáveis dependendo do tipo de evento, como:- AR (Aviso de Recebimento) — para confirmação de recebimento
- Data de previsão de entrega atualizada — em casos de
delivery_forecast_changed - Nome do técnico — em eventos de manutenção
7. Tratamento de Erros
| Código HTTP | Significado | O que fazer |
|---|---|---|
400 | Requisição inválida — parâmetros ausentes, formato incorreto (ex.: UUID mal formatado) ou nenhum filtro informado. | Verifique se ao menos um dos parâmetros foi enviado e se os formatos estão corretos. |
401 | Autenticação inválida — token ausente, expirado ou incorreto. | Renove o token consultando o endpoint POST /token e reenvie a requisição. |
404 | Não encontrado — nenhum tracking foi localizado com os parâmetros informados. | Confirme se o order_id, order_number ou service_number está correto. O pedido pode ainda não ter um tracking associado. |
500 | Erro interno — falha inesperada no servidor. | Aguarde alguns instantes e tente novamente. Se o problema persistir, acione o suporte Getnet. |
503 | Serviço indisponível — o serviço está temporariamente fora do ar. | Implemente uma lógica de retry com backoff exponencial. |
504 | Timeout de gateway — o serviço não respondeu no tempo esperado. | Tente novamente após alguns segundos. Evite reenvios imediatos em rajada. |
Estrutura do objeto de erro
Todos os erros retornam um objeto padronizado:
text
{
"code": "TRACKING_NOT_FOUND", ← Código de negócio do erro
"message": "Tracking não encontrado para os filtros informados.",
"details": [
{
"field": "order_id", ← Campo que causou o problema (quando aplicável)
"message": "Formato UUID inválido."
}
]
}
text
{
"code": "TRACKING_NOT_FOUND", ← Código de negócio do erro
"message": "Tracking não encontrado para os filtros informados.",
"details": [
{
"field": "order_id", ← Campo que causou o problema (quando aplicável)
"message": "Formato UUID inválido."
}
]
}
Use o campo
code para identificar programaticamente o tipo de erro sem depender da mensagem textual.8. Glossário
| Termo | Definição |
|---|---|
| Tracking | Objeto raiz que consolida todas as informações logísticas de um pedido, incluindo situação atual, etapas e eventos. |
| Step (Etapa) | Fase macro do fluxo logístico. Exemplos: order (pedido registrado), payment (pagamento), fulfillment (preparação), delivery (entrega), withdrawal (retirada), finish (conclusão). |
| Event (Evento) | Marco granular dentro de uma etapa. Representa uma ação específica que ocorreu, como delivery_sent_partner (enviado para transportadora) ou delivery_delivered (entregue ao destinatário). |
| Situation | Snapshot do estado atual do tracking ou de uma etapa. Contém o status (pending ou finished) e uma descrição legível. |
| Flow Type | Classifica o tipo de operação logística do pedido (venda, locação, manutenção, retirada, devolução etc.). Determina quais etapas e eventos são esperados. |
| Order ID | Identificador único do pedido no formato UUID. Gerado no domínio de Orders. |
| Order Number | Número legível do pedido, geralmente exibido ao lojista no portal. |
| Service Number | Número da Ordem de Serviço (OS), usado em casos de manutenção e assistência técnica. |
| Siebel Number | Número de referência do pedido no sistema CRM Siebel. |
| Marketplace Order ID | Identificador do pedido na plataforma VTEX (quando o pedido origina-se de um marketplace). |
| Merchant | Estabelecimento comercial (lojista) associado ao pedido. |
| Buyer | Pessoa física ou jurídica que realizou o pedido. |
| Fulfillment | Processo de preparação do pedido para envio, incluindo separação, embalagem e emissão de nota fiscal. |
| Carrier (Transportadora) | Empresa responsável pelo transporte físico do equipamento até o destinatário. |
| Tracking Code | Código fornecido pela transportadora para rastreamento externo da encomenda (ex.: código dos Correios). |
| AR (Aviso de Recebimento) | Confirmação formal de que o destinatário recebeu o item entregue. |
| Additional Data | Campo de dados livres em eventos de tracking, utilizado para informações contextuais variáveis como previsão de entrega atualizada ou nome do técnico responsável. |
| Audit Information | Metadados de auditoria do registro: quem criou, quando criou, quem atualizou e quando atualizou. |
Nesta página
Tracking — Rastreamento Logístico de Pedidos