Tracking — Logistic Order Tracking
1. Overview
The Tracking service allows you to follow, in real time, the logistic lifecycle of an order placed on the Getnet platform. It answers questions such as:
- "Where is the equipment I ordered?"
- "Has the technician already left for maintenance?"
- "Was my order delivered or returned?"
Instead of querying multiple internal systems, the API consumer obtains in a single call a consolidated view of everything that has happened with the order — from the moment it was registered to the completion of delivery, pickup, or equipment maintenance.
2. Context and Use Cases
When to use this service?
Use Tracking whenever you need to display or process the logistic progress of an order. It is suitable for:
| Scenario | Description |
|---|---|
| Merchant portal | Display the updated equipment status to the merchant (e.g., card machine on the way). |
| Customer support | Allow support agents to quickly check the status of an order without accessing internal systems. |
| Automatic notifications | Trigger alerts (email, SMS, push) when the order status changes (e.g., equipment delivered). |
| Audit and compliance | Record and audit the complete timeline of events for an order. |
| Maintenance tracking | Check if a technician has been dispatched and when the maintenance was completed. |
| Return management | Track equipment pickup in cases of cancellation or return. |
Real-world scenario examples
Scenario 1 — New merchant waiting for the card machine:
A business has just signed up for the Getnet service. The merchant portal queries Tracking by
order_id to display which stage the equipment is at — whether it is being prepared, dispatched, or already delivered.Scenario 2 — Equipment maintenance:
A terminal has malfunctioned and a service order was opened. The support system queries Tracking by
service_number to find out if the technician has already picked up the equipment and when the maintenance was completed.Scenario 3 — Equipment pickup:
A contract was terminated and Getnet needs to collect the terminal. The back office monitors by
order_number whether the pickup was successfully completed or if the collection attempt failed.3. Main Flow
The Tracking service has a single query endpoint. The consumer provides the order identifier and receives the complete object with status, steps, and events.
text
┌─────────────────────────────────────────────────────────────────┐
│ QUERY FLOW │
└─────────────────────────────────────────────────────────────────┘
[1] Obtain Access Token
└─► 600;">POST /token (Authentication domain)
│
▼
[2] Query Tracking
└─► 600;">GET /tracking/detail
│ query: order_id | order_number | service_number
│
▼
[3] Process Response (TrackingDTO)
│
├─► situation → Overall order status (pending / finished)
│
├─► identifier → All reference numbers for the order
│
├─► merchant → Business establishment data
│
├─► buyer → Buyer data
│
├─► items[]
│ ├─► products[] → Equipment/materials for the item
│ ├─► steps[] → Macro steps (order, payment, fulfillment,
│ │ delivery, withdrawal, finish)
│ └─► events[] → Detailed events within each step
│
└─► delivery_info → Carrier, tracking code,
estimated and actual delivery dates
text
┌─────────────────────────────────────────────────────────────────┐
│ QUERY FLOW │
└─────────────────────────────────────────────────────────────────┘
[1] Obtain Access Token
└─► 600;">POST /token (Authentication domain)
│
▼
[2] Query Tracking
└─► 600;">GET /tracking/detail
│ query: order_id | order_number | service_number
│
▼
[3] Process Response (TrackingDTO)
│
├─► situation → Overall order status (pending / finished)
│
├─► identifier → All reference numbers for the order
│
├─► merchant → Business establishment data
│
├─► buyer → Buyer data
│
├─► items[]
│ ├─► products[] → Equipment/materials for the item
│ ├─► steps[] → Macro steps (order, payment, fulfillment,
│ │ delivery, withdrawal, finish)
│ └─► events[] → Detailed events within each step
│
└─► delivery_info → Carrier, tracking code,
estimated and actual delivery dates
Steps and events structure
Each order progresses through steps that group granular events. See the typical progression:
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
Note: For pickup or maintenance orders, events follow the same logic but withwithdrawal_andmaintenance_prefixes respectively.
4. Prerequisites
Authentication
Every call to Tracking requires a valid access token, previously obtained from the Getnet authentication service.
| Item | Detail |
|---|---|
| How to obtain | POST /token in the Authentication domain |
| How to send | HTTP Header: Authorization: {access_token} |
| Format | Without "Bearer" prefix — send the token directly |
Dependencies on other services
| Service | Reason |
|---|---|
| Authentication | Generation of the required access token |
| Orders | Source of the order_id and order_number identifiers |
Available environments
| Environment | Base URL |
|---|---|
| Staging | https://api-homologacao.getnet.com.br:443/v1 |
| Production | https://api-backoffice.getnet.com.br:443/v1 |
5. Quick Integration Guide
Query the tracking of an order (happy path)
Step 1 — Obtain the authentication token
Consult the Authentication domain and store the returned
access_token.Step 2 — Query the Tracking
Provide at least one of the available search parameters:
text
600;">GET /tracking/detail?order_id=<order-uuid>
Headers:
Authorization: <access_token>
text
600;">GET /tracking/detail?order_id=<order-uuid>
Headers:
Authorization: <access_token>
Or, if you prefer to search by the human-readable order number:
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>
Or by the Service Order number:
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>
Step 3 — Interpret the response
A successful response (
HTTP 200) returns the TrackingDTO object. See the most relevant fields for immediate consumption:text
{
"tracking_id": "...",
"situation": {
"status": "pending", ← Current status: pending or finished
"description": "Em transporte", ← Human-readable situation description
"status_update_date": "..." ← When it was last updated
},
"flow_type": "sale_delivery", ← Logistic flow type
"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", ← Current status: pending or finished
"description": "Em transporte", ← Human-readable situation description
"status_update_date": "..." ← When it was last updated
},
"flow_type": "sale_delivery", ← Logistic flow type
"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. Business Rules
Search parameters
- At least one of the three parameters must be provided:
order_id,order_number, orservice_number. - The
order_idfollows the UUID format (e.g.,550e8400-e29b-41d4-a716-446655440000). - If more than one parameter is sent, the system will use the combination to refine the search.
Flow types (flow_type)
The
flow_type field indicates the logistic nature of the order. Each type determines which steps and events are expected:| Value | Functional description |
|---|---|
sale_delivery | Sale with equipment delivery |
rent_delivery | Rental with equipment delivery |
prepaid_card_delivery | Prepaid card delivery |
maintenance_rent | Rented equipment maintenance |
rent_withdrawal | Rented equipment pickup |
sale_maintenance | Sold equipment maintenance |
sale_devolution | Sold equipment return |
affiliation_fee_delivery | Affiliation kit delivery |
affiliation_fee_maintenance | Affiliation kit maintenance |
affiliation_fee_withdrawal | Affiliation kit pickup |
affiliation_fee_replacement | Affiliation kit replacement |
Tracking status (status)
| Value | Meaning |
|---|---|
pending | The logistic cycle is still in progress |
finished | The logistic cycle has been completed (success or failure) |
Events with additional data
The
additional_data field within an event may contain variable information depending on the event type, such as:- AR (Acknowledgment of Receipt) — for delivery confirmation
- Updated delivery forecast date — in cases of
delivery_forecast_changed - Technician name — in maintenance events
7. Error Handling
| HTTP Code | Meaning | What to do |
|---|---|---|
400 | Invalid request — missing parameters, incorrect format (e.g., malformed UUID) or no filter provided. | Verify that at least one parameter was sent and that the formats are correct. |
401 | Invalid authentication — token missing, expired, or incorrect. | Renew the token by calling the POST /token endpoint and resend the request. |
404 | Not found — no tracking was found with the provided parameters. | Confirm that the order_id, order_number, or service_number is correct. The order may not yet have an associated tracking. |
500 | Internal error — unexpected server failure. | Wait a few moments and try again. If the problem persists, contact Getnet support. |
503 | Service unavailable — the service is temporarily down. | Implement a retry logic with exponential backoff. |
504 | Gateway timeout — the service did not respond within the expected time. | Try again after a few seconds. Avoid immediate burst retries. |
Error object structure
All errors return a standardized object:
text
{
"code": "TRACKING_NOT_FOUND", ← Business error code
"message": "Tracking não encontrado para os filtros informados.",
"details": [
{
"field": "order_id", ← Field that caused the problem (when applicable)
"message": "Formato UUID inválido."
}
]
}
text
{
"code": "TRACKING_NOT_FOUND", ← Business error code
"message": "Tracking não encontrado para os filtros informados.",
"details": [
{
"field": "order_id", ← Field that caused the problem (when applicable)
"message": "Formato UUID inválido."
}
]
}
Use the
code field to programmatically identify the error type without depending on the text message.8. Glossary
| Term | Definition |
|---|---|
| Tracking | Root object that consolidates all logistic information for an order, including current status, steps, and events. |
| Step | Macro phase of the logistic flow. Examples: order (order registered), payment (payment), fulfillment (preparation), delivery (delivery), withdrawal (pickup), finish (completion). |
| Event | Granular milestone within a step. Represents a specific action that occurred, such as delivery_sent_partner (sent to carrier) or delivery_delivered (delivered to recipient). |
| Situation | Snapshot of the current state of the tracking or a step. Contains the status (pending or finished) and a human-readable description. |
| Flow Type | Classifies the type of logistic operation for the order (sale, rental, maintenance, pickup, return, etc.). Determines which steps and events are expected. |
| Order ID | Unique order identifier in UUID format. Generated in the Orders domain. |
| Order Number | Human-readable order number, usually displayed to the merchant in the portal. |
| Service Number | Service Order (SO) number, used in maintenance and technical assistance cases. |
| Siebel Number | Order reference number in the Siebel CRM system. |
| Marketplace Order ID | Order identifier on the VTEX platform (when the order originates from a marketplace). |
| Merchant | Business establishment (retailer) associated with the order. |
| Buyer | Individual or legal entity that placed the order. |
| Fulfillment | Order preparation process for shipping, including picking, packing, and invoice issuance. |
| Carrier | Company responsible for the physical transport of the equipment to the recipient. |
| Tracking Code | Code provided by the carrier for external shipment tracking (e.g., postal service code). |
| AR (Acknowledgment of Receipt) | Formal confirmation that the recipient received the delivered item. |
| Additional Data | Free-form data field in tracking events, used for variable contextual information such as updated delivery forecast or name of the responsible technician. |
| Audit Information | Record audit metadata: who created it, when it was created, who updated it, and when it was updated. |
On this page
Tracking — Logistic Order Tracking