Tracking — Rastreo Logístico de Pedidos
1. Visión General
El servicio de Tracking permite acompañar, en tiempo real, el ciclo de vida logístico de un pedido realizado en la plataforma Getnet. Responde a preguntas como:
- "¿Dónde está el equipo que pedí?"
- "¿El técnico ya salió para hacer el mantenimiento?"
- "¿Mi pedido fue entregado o devuelto?"
En lugar de consultar múltiples sistemas internos, el consumidor de la API obtiene en una única llamada una visión consolidada de todo lo que ocurrió con el pedido — desde el momento en que fue registrado hasta la conclusión de la entrega, retiro o mantenimiento del equipo.
2. Contexto y Casos de Uso
¿Cuándo usar este servicio?
Use el Tracking siempre que necesite mostrar o procesar el avance logístico de un pedido. Está indicado para:
| Escenario | Descripción |
|---|---|
| Portal del comerciante | Mostrar al merchant el estado actualizado del equipo solicitado (ej.: terminal en camino). |
| Atención al cliente | Permitir que agentes de soporte consulten rápidamente la situación de un pedido sin acceder a sistemas internos. |
| Notificaciones automáticas | Activar alertas (email, SMS, push) cuando el estado del pedido cambie (ej.: equipo entregado). |
| Auditoría y compliance | Registrar y auditar la línea de tiempo completa de eventos de un pedido. |
| Seguimiento de mantenimiento | Verificar si un técnico fue despachado y cuándo el mantenimiento fue completado. |
| Gestión de devoluciones | Rastrear el retiro de equipos en casos de cancelación o devolución. |
Ejemplos de escenarios reales
Escenario 1 — Nuevo comerciante esperando el terminal:
Un establecimiento acaba de contratar el servicio Getnet. El portal del comerciante consulta el Tracking por
order_id para mostrar en qué etapa se encuentra el equipo — si está siendo preparado, si fue despachado o si ya fue entregado.Escenario 2 — Mantenimiento de equipo:
Un terminal presentó un defecto y se abrió una orden de servicio. El sistema de soporte consulta el Tracking por
service_number para saber si el técnico ya recogió el equipo y cuándo el mantenimiento fue completado.Escenario 3 — Retiro de equipo:
Un contrato fue finalizado y Getnet necesita recoger el terminal. El backoffice monitorea por
order_number si el retiro fue realizado con éxito o si hubo una falla en el intento de recolección.3. Flujo Principal
El servicio de Tracking posee un único endpoint de consulta. El consumidor informa el identificador del pedido y recibe el objeto completo con situación, etapas y eventos.
text
┌─────────────────────────────────────────────────────────────────┐
│ FLUJO DE CONSULTA │
└─────────────────────────────────────────────────────────────────┘
[1] Obtener Token de Acceso
└─► 600;">POST /token (dominio Authentication)
│
▼
[2] Consultar Tracking
└─► 600;">GET /tracking/detail
│ query: order_id | order_number | service_number
│
▼
[3] Procesar Respuesta (TrackingDTO)
│
├─► situation → Estado general del pedido (pending / finished)
│
├─► identifier → Todos los números de referencia del pedido
│
├─► merchant → Datos del establecimiento comercial
│
├─► buyer → Datos del comprador
│
├─► items[]
│ ├─► products[] → Equipos/materiales del ítem
│ ├─► steps[] → Etapas macro (order, payment, fulfillment,
│ │ delivery, withdrawal, finish)
│ └─► events[] → Eventos detallados dentro de cada etapa
│
└─► delivery_info → Transportadora, código de rastreo,
fechas estimada y efectiva de entrega
text
┌─────────────────────────────────────────────────────────────────┐
│ FLUJO DE CONSULTA │
└─────────────────────────────────────────────────────────────────┘
[1] Obtener Token de Acceso
└─► 600;">POST /token (dominio Authentication)
│
▼
[2] Consultar Tracking
└─► 600;">GET /tracking/detail
│ query: order_id | order_number | service_number
│
▼
[3] Procesar Respuesta (TrackingDTO)
│
├─► situation → Estado general del pedido (pending / finished)
│
├─► identifier → Todos los números de referencia del pedido
│
├─► merchant → Datos del establecimiento comercial
│
├─► buyer → Datos del comprador
│
├─► items[]
│ ├─► products[] → Equipos/materiales del ítem
│ ├─► steps[] → Etapas macro (order, payment, fulfillment,
│ │ delivery, withdrawal, finish)
│ └─► events[] → Eventos detallados dentro de cada etapa
│
└─► delivery_info → Transportadora, código de rastreo,
fechas estimada y efectiva de entrega
Estructura de etapas y eventos
Cada pedido avanza por etapas (steps) que agrupan eventos (events) granulares. Vea la progresión 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 retiro o mantenimiento, los eventos siguen la misma lógica, pero con los prefijoswithdrawal_ymaintenance_respectivamente.
4. Prerrequisitos
Autenticación
Toda llamada al Tracking requiere un token de acceso válido, obtenido previamente en el servicio de autenticación de Getnet.
| Ítem | Detalle |
|---|---|
| Cómo obtener | POST /token en el dominio Authentication |
| Cómo enviar | Header HTTP: Authorization: {access_token} |
| Formato | Sin prefijo "Bearer" — envíe el token directamente |
Dependencias de otros servicios
| Servicio | Motivo |
|---|---|
| Authentication | Generación del token de acceso obligatorio |
| Orders | Origen de los identificadores order_id y order_number |
Ambientes disponibles
| Ambiente | URL base |
|---|---|
| Homologación | https://api-homologacao.getnet.com.br:443/v1 |
| Producción | https://api-backoffice.getnet.com.br:443/v1 |
5. Guía de Integración Rápida
Consultar el tracking de un pedido (happy path)
Paso 1 — Obtenga el token de autenticación
Consulte el dominio de Authentication y guarde el
access_token retornado.Paso 2 — Realice la consulta al Tracking
Informe al menos uno de los parámetros de búsqueda disponibles:
text
600;">GET /tracking/detail?order_id=<uuid-del-pedido>
Headers:
Authorization: <access_token>
text
600;">GET /tracking/detail?order_id=<uuid-del-pedido>
Headers:
Authorization: <access_token>
O, si prefiere buscar por el número de pedido legible:
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>
O por el número de la Orden de Servicio:
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>
Paso 3 — Interprete la respuesta
Una respuesta exitosa (
HTTP 200) retorna el objeto TrackingDTO. Vea los campos más relevantes para el consumo inmediato:text
{
"tracking_id": "...",
"situation": {
"status": "pending", ← Estado actual: pending o finished
"description": "Em transporte", ← Descripción legible de la situación
"status_update_date": "..." ← Cuándo fue actualizado por última vez
},
"flow_type": "sale_delivery", ← Tipo de flujo 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", ← Estado actual: pending o finished
"description": "Em transporte", ← Descripción legible de la situación
"status_update_date": "..." ← Cuándo fue actualizado por última vez
},
"flow_type": "sale_delivery", ← Tipo de flujo 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. Reglas de Negocio
Parámetros de búsqueda
- Al menos uno de los tres parámetros debe ser informado:
order_id,order_numberoservice_number. - El
order_idsigue el formato UUID (ej.:550e8400-e29b-41d4-a716-446655440000). - En caso de que más de un parámetro sea enviado, el sistema utilizará la combinación para refinar la búsqueda.
Tipos de flujo (flow_type)
El campo
flow_type indica la naturaleza logística del pedido. Cada tipo determina qué etapas y eventos son esperados:| Valor | Descripción funcional |
|---|---|
sale_delivery | Venta con entrega de equipo |
rent_delivery | Alquiler con entrega de equipo |
prepaid_card_delivery | Entrega de tarjeta prepaga |
maintenance_rent | Mantenimiento de equipo alquilado |
rent_withdrawal | Retiro de equipo alquilado |
sale_maintenance | Mantenimiento de equipo vendido |
sale_devolution | Devolución de equipo vendido |
affiliation_fee_delivery | Entrega de kit de afiliación |
affiliation_fee_maintenance | Mantenimiento de kit de afiliación |
affiliation_fee_withdrawal | Retiro de kit de afiliación |
affiliation_fee_replacement | Sustitución de kit de afiliación |
Estado del tracking (status)
| Valor | Significado |
|---|---|
pending | El ciclo logístico aún está en curso |
finished | El ciclo logístico fue completado (con éxito o falla) |
Eventos con datos adicionales
El campo
additional_data dentro de un evento puede contener información variable dependiendo del tipo de evento, como:- AR (Acuse de Recibo) — para confirmación de recepción
- Fecha de previsión de entrega actualizada — en casos de
delivery_forecast_changed - Nombre del técnico — en eventos de mantenimiento
7. Tratamiento de Errores
| Código HTTP | Significado | Qué hacer |
|---|---|---|
400 | Solicitud inválida — parámetros ausentes, formato incorrecto (ej.: UUID mal formateado) o ningún filtro informado. | Verifique que al menos uno de los parámetros fue enviado y que los formatos sean correctos. |
401 | Autenticación inválida — token ausente, expirado o incorrecto. | Renueve el token consultando el endpoint POST /token y reenvíe la solicitud. |
404 | No encontrado — no se localizó ningún tracking con los parámetros informados. | Confirme que el order_id, order_number o service_number sea correcto. El pedido puede aún no tener un tracking asociado. |
500 | Error interno — falla inesperada en el servidor. | Espere algunos instantes e intente nuevamente. Si el problema persiste, contacte al soporte Getnet. |
503 | Servicio no disponible — el servicio está temporalmente fuera de servicio. | Implemente una lógica de retry con backoff exponencial. |
504 | Timeout de gateway — el servicio no respondió en el tiempo esperado. | Intente nuevamente después de algunos segundos. Evite reenvíos inmediatos en ráfaga. |
Estructura del objeto de error
Todos los errores retornan un objeto estandarizado:
text
{
"code": "TRACKING_NOT_FOUND", ← Código de negocio del error
"message": "Tracking não encontrado para os filtros informados.",
"details": [
{
"field": "order_id", ← Campo que causó el problema (cuando aplique)
"message": "Formato UUID inválido."
}
]
}
text
{
"code": "TRACKING_NOT_FOUND", ← Código de negocio del error
"message": "Tracking não encontrado para os filtros informados.",
"details": [
{
"field": "order_id", ← Campo que causó el problema (cuando aplique)
"message": "Formato UUID inválido."
}
]
}
Use el campo
code para identificar programáticamente el tipo de error sin depender del mensaje textual.8. Glosario
| Término | Definición |
|---|---|
| Tracking | Objeto raíz que consolida toda la información logística de un pedido, incluyendo situación actual, etapas y eventos. |
| Step (Etapa) | Fase macro del flujo logístico. Ejemplos: order (pedido registrado), payment (pago), fulfillment (preparación), delivery (entrega), withdrawal (retiro), finish (conclusión). |
| Event (Evento) | Hito granular dentro de una etapa. Representa una acción específica que ocurrió, como delivery_sent_partner (enviado a transportadora) o delivery_delivered (entregado al destinatario). |
| Situation | Snapshot del estado actual del tracking o de una etapa. Contiene el status (pending o finished) y una descripción legible. |
| Flow Type | Clasifica el tipo de operación logística del pedido (venta, alquiler, mantenimiento, retiro, devolución, etc.). Determina qué etapas y eventos son esperados. |
| Order ID | Identificador único del pedido en formato UUID. Generado en el dominio de Orders. |
| Order Number | Número legible del pedido, generalmente mostrado al comerciante en el portal. |
| Service Number | Número de la Orden de Servicio (OS), usado en casos de mantenimiento y asistencia técnica. |
| Siebel Number | Número de referencia del pedido en el sistema CRM Siebel. |
| Marketplace Order ID | Identificador del pedido en la plataforma VTEX (cuando el pedido se origina en un marketplace). |
| Merchant | Establecimiento comercial (comerciante) asociado al pedido. |
| Buyer | Persona física o jurídica que realizó el pedido. |
| Fulfillment | Proceso de preparación del pedido para envío, incluyendo separación, embalaje y emisión de factura. |
| Carrier (Transportadora) | Empresa responsable del transporte físico del equipo hasta el destinatario. |
| Tracking Code | Código proporcionado por la transportadora para rastreo externo del envío (ej.: código de Correos). |
| AR (Acuse de Recibo) | Confirmación formal de que el destinatario recibió el ítem entregado. |
| Additional Data | Campo de datos libres en eventos de tracking, utilizado para información contextual variable como previsión de entrega actualizada o nombre del técnico responsable. |
| Audit Information | Metadatos de auditoría del registro: quién lo creó, cuándo lo creó, quién lo actualizó y cuándo lo actualizó. |
En esta página
Tracking — Rastreo Logístico de Pedidos