This documentation serves to describe the implementation of the REST Tracking API, which is designed for reading data about tracked shipments registered in Retino. Communication takes place via JSON for input and output. The API is stateless – every request must be authorized with an API token in the request header.
The current technical reference containing a description of the data can be found at app.retino.com/api/tracking/v1/docs.
For clarity, the technical reference is provided only in English. If you have any problems with the integration, please contact us.
Authentication
Authentication is performed using a token that you can find in the API settings page. You must then send this token in the Authentication header of every request to the Tickets API in the following format:
Authentication: Token [Your API token]
Each user in your account has their own unique token. If you have multiple accounts under a single user in Retino, you will have a different token for each Retino account.
Token Renewal
If you suspect that your token has been compromised, you can renew it in the settings.
WARNING: If you renew the token, the original token will be immediately invalidated, which will cause a disruption in the integration with your system until you replace the old token with the new one.
List of endpoints
Here is a list of the endpoints provided by the Tracking API. The complete technical reference for the Tracking API, containing a detailed description of data types, is located at app.retino.com/api/docs/v2/tracking/.
The base URL for the production API is: https://app.retino.com/api/v2/tracking/
List of shipments
GET /shipping
Use this endpoint to retrieve data for all shipments. You can filter and sort them by creation, modification, order, and delivery date, as well as by carrier, status, and custom labels.
It returns a paginated list of shipments.
Request
curl -X GET "https://app.retino.com/api/v2/tracking/shipping" -H "Authorization: Token [Your API token]"
Response - 200
{
"count": 1,
"current_page": 1,
"total_pages": 1,
"results": [
{
"carrier": "TOPTRANS",
"carrier_estimated_delivery": null,
"delivered_at": "2024-11-05T12:09:00+01:00",
"delivery_type": "TO_ADDRESS",
"destination_country": "hu",
"id": "3104447e-d019-453c-96ec-2805daf937b4",
"issues": [
{
"created_at": "2024-11-05T04:30:00+01:00",
"is_resolved": false,
"note": "",
"shipping_id": "3104447e-d019-453c-96ec-2805daf937b4",
"status": "EXCEPTION",
"sub_status": "EXCEPTION",
"type": null
}
],
"last_sync_at": "2024-12-18T14:30:45.300195+01:00",
"order_code": "224112025",
"ordered_at": "2024-10-31T15:02:00+01:00",
"original_tracking_number": "24775117217",
"picked_from_branch_at": null,
"pickup_at": "2024-11-04T09:57:00+01:00",
"source": null,
"status": "DELIVERED",
"stored_until": null,
"sub_status": "DELIVERED",
"tags": [
"049a18e5-5378-42b2-bfc0-19bcee2a02d7"
],
"tracking": [
{
"carrier_description": "Zásilka doručena",
"created_at": "2024-11-05T12:09:00+01:00",
"location": "001 - Praha",
"status": "DELIVERED",
"sub_status": "DELIVERED"
},
{
"carrier_description": "Zásilka se rozváží",
"created_at": "2024-11-05T09:18:00+01:00",
"location": "001 - Praha",
"status": "OUT_FOR_DELIVERY",
"sub_status": "OUT_FOR_DELIVERY"
},
{
"carrier_description": "Chybné nasortování na depo",
"created_at": "2024-11-05T04:30:00+01:00",
"location": "001 - Praha",
"status": "EXCEPTION",
"sub_status": "EXCEPTION"
},
{
"carrier_description": "Zásilka je na rozvozovém středisku",
"created_at": "2024-11-05T01:40:00+01:00",
"location": "001 - Praha",
"status": "IN_TRANSIT",
"sub_status": "IN_TRANSIT__DEPOT"
},
{
"carrier_description": "Zásilka odešla do cílového střediska",
"created_at": "2024-11-04T16:22:00+01:00",
"location": "-",
"status": "IN_TRANSIT",
"sub_status": "IN_TRANSIT"
},
{
"carrier_description": "Zásilka svezena do skladu",
"created_at": "2024-11-04T09:57:00+01:00",
"location": "750 - Ostrava",
"status": "IN_TRANSIT",
"sub_status": "IN_TRANSIT__HUB"
},
{
"carrier_description": "Přijata objednávka přepravy",
"created_at": "2024-11-04T06:41:00+01:00",
"location": "750 - Ostrava",
"status": "INFORMATION_RECEIVED",
"sub_status": "INFORMATION_RECEIVED"
}
],
"tracking_number": "24775117217",
"tracking_url": "https://apis.toptrans.cz/tracking?parcel_number=24775117217"
}
]
}
Searching for shipments
GET /shipping/search
Used to search for shipments by order number or tracking number. It finds all shipments that contain the given string.
Returns a paginated list of shipments.
Request
curl -X GET "https://app.retino.com/api/v2/tracking/search?search=TEST-TRACKING-NUMBER" -H "Authorization: Token [Your API token]"
Response - 200
{
"count": 1,
"current_page": 1,
"total_pages": 1,
"results": [
{
"carrier": "TOPTRANS",
"carrier_estimated_delivery": null,
"delivered_at": "2024-11-05T12:09:00+01:00",
"delivery_type": "TO_ADDRESS",
"destination_country": "hu",
"id": "3104447e-d019-453c-96ec-2805daf937b4",
"issues": [
{
"created_at": "2024-11-05T04:30:00+01:00",
"is_resolved": false,
"note": "",
"shipping_id": "3104447e-d019-453c-96ec-2805daf937b4",
"status": "EXCEPTION",
"sub_status": "EXCEPTION",
"type": null
}
],
"last_sync_at": "2024-12-18T14:30:45.300195+01:00",
"order_code": "224112025",
"ordered_at": "2024-10-31T15:02:00+01:00",
"original_tracking_number": "24775117217",
"picked_from_branch_at": null,
"pickup_at": "2024-11-04T09:57:00+01:00",
"source": null,
"status": "DELIVERED",
"stored_until": null,
"sub_status": "DELIVERED",
"tags": [
"049a18e5-5378-42b2-bfc0-19bcee2a02d7"
],
"tracking": [
{
"carrier_description": "Zásilka doručena",
"created_at": "2024-11-05T12:09:00+01:00",
"location": "001 - Praha",
"status": "DELIVERED",
"sub_status": "DELIVERED"
},
{
"carrier_description": "Zásilka se rozváží",
"created_at": "2024-11-05T09:18:00+01:00",
"location": "001 - Praha",
"status": "OUT_FOR_DELIVERY",
"sub_status": "OUT_FOR_DELIVERY"
},
{
"carrier_description": "Chybné nasortování na depo",
"created_at": "2024-11-05T04:30:00+01:00",
"location": "001 - Praha",
"status": "EXCEPTION",
"sub_status": "EXCEPTION"
},
{
"carrier_description": "Zásilka je na rozvozovém středisku",
"created_at": "2024-11-05T01:40:00+01:00",
"location": "001 - Praha",
"status": "IN_TRANSIT",
"sub_status": "IN_TRANSIT__DEPOT"
},
{
"carrier_description": "Zásilka odešla do cílového střediska",
"created_at": "2024-11-04T16:22:00+01:00",
"location": "-",
"status": "IN_TRANSIT",
"sub_status": "IN_TRANSIT"
},
{
"carrier_description": "Zásilka svezena do skladu",
"created_at": "2024-11-04T09:57:00+01:00",
"location": "750 - Ostrava",
"status": "IN_TRANSIT",
"sub_status": "IN_TRANSIT__HUB"
},
{
"carrier_description": "Přijata objednávka přepravy",
"created_at": "2024-11-04T06:41:00+01:00",
"location": "750 - Ostrava",
"status": "INFORMATION_RECEIVED",
"sub_status": "INFORMATION_RECEIVED"
}
],
"tracking_number": "24775117217",
"tracking_url": "https://apis.toptrans.cz/tracking?parcel_number=24775117217"
}
]
}
Shipment detail GET /shipping/[id]
Used to retrieve data for a single specific shipment by its ID.
Request
curl -X GET "https://app.retino.com/api/v2/tracking/shipping/8768954d-de80-4b1a-bdcd-4eeeb68b126f" -H "Authorization: Token [Your API token]]"
Response - 200
{
"carrier": "TOPTRANS",
"carrier_estimated_delivery": null,
"delivered_at": "2024-11-05T12:09:00+01:00",
"delivery_type": "TO_ADDRESS",
"destination_country": "CZ",
"id": "3104447e-d019-453c-96ec-2805daf937b4",
"issues": [
{
"created_at": "2024-11-05T04:30:00+01:00",
"is_resolved": false,
"note": "",
"shipping_id": "3104447e-d019-453c-96ec-2805daf937b4",
"status": "EXCEPTION",
"sub_status": "EXCEPTION",
"type": null
}
],
"last_sync_at": "2024-12-18T14:30:45.300195+01:00",
"order_code": "ORDER-CODE",
"ordered_at": "2024-10-31T15:02:00+01:00",
"original_tracking_number": "TEST-TRACKING-NUMBER",
"picked_from_branch_at": null,
"pickup_at": "2024-11-04T09:57:00+01:00",
"source": null,
"status": "DELIVERED",
"stored_until": null,
"sub_status": "DELIVERED",
"tags": [
"049a18e5-5378-42b2-bfc0-19bcee2a02d7"
],
"tracking": [
{
"carrier_description": "Zásilka doručena",
"created_at": "2024-11-05T12:09:00+01:00",
"location": "001 - Praha",
"status": "DELIVERED",
"sub_status": "DELIVERED"
},
{
"carrier_description": "Zásilka se rozváží",
"created_at": "2024-11-05T09:18:00+01:00",
"location": "001 - Praha",
"status": "OUT_FOR_DELIVERY",
"sub_status": "OUT_FOR_DELIVERY"
},
{
"carrier_description": "Chybné nasortování na depo",
"created_at": "2024-11-05T04:30:00+01:00",
"location": "001 - Praha",
"status": "EXCEPTION",
"sub_status": "EXCEPTION"
},
{
"carrier_description": "Zásilka je na rozvozovém středisku",
"created_at": "2024-11-05T01:40:00+01:00",
"location": "001 - Praha",
"status": "IN_TRANSIT",
"sub_status": "IN_TRANSIT__DEPOT"
},
{
"carrier_description": "Zásilka odešla do cílového střediska",
"created_at": "2024-11-04T16:22:00+01:00",
"location": "-",
"status": "IN_TRANSIT",
"sub_status": "IN_TRANSIT"
},
{
"carrier_description": "Zásilka svezena do skladu",
"created_at": "2024-11-04T09:57:00+01:00",
"location": "750 - Ostrava",
"status": "IN_TRANSIT",
"sub_status": "IN_TRANSIT__HUB"
},
{
"carrier_description": "Přijata objednávka přepravy",
"created_at": "2024-11-04T06:41:00+01:00",
"location": "750 - Ostrava",
"status": "INFORMATION_RECEIVED",
"sub_status": "INFORMATION_RECEIVED"
}
],
"tracking_number": "TEST-TRACKING-NUMBER",
"tracking_url": "https://apis.toptrans.cz/tracking?parcel_number=TEST-TRACKING-NUMBER"
}
List of problematic shipments GET /issues
Use this endpoint to retrieve data about all problems that have occurred during transport. You can filter them by the date of occurrence, resolution status, and shipment ID.
Request
curl -X GET "https://app.retino.com/api/v2/tracking/issues" -H "Authorization: Token [Váš API token]"
Response - 200
{
"count": 3,
"current_page": 1,
"total_pages": 1,
"results": [
{
"created_at": "2025-01-09T14:42:20+01:00",
"is_resolved": true,
"note": null,
"shipping_id": "5b9423f5-4c56-4ded-b36e-1dcbe9a48eba",
"status": "EXCEPTION",
"sub_status": "RETURNING_TO_SENDER",
"type": null
},
{
"created_at": "2024-11-05T08:54:08+01:00",
"is_resolved": false,
"note": null,
"shipping_id": "5e51d12a-0f18-426c-982d-3c17458eb5d9",
"status": "EXCEPTION",
"sub_status": "DELAYED_EXTERNAL_FACTORS",
"type": null
},
{
"created_at": "2024-11-05T04:30:00+01:00",
"is_resolved": false,
"note": "",
"shipping_id": "3104447e-d019-453c-96ec-2805daf937b4",
"status": "EXCEPTION",
"sub_status": "EXCEPTION",
"type": null
},
]
}
List of labels
GET /tags
Use this endpoint to retrieve data about labels.
Request
curl -X GET "https://app.retino.com/api/v2/tracking/tags" -H "Authorization: Token [Váš API token]"
Response - 200
{
"count": 2,
"current_page": 1,
"total_pages": 1,
"results": [
{
"bgcolor": "#000000",
"fgcolor": "#ffffff",
"id": "049a18e5-5378-42b2-bfc0-19bcee2a02d7",
"name": "tag1"
},
{
"bgcolor": "#000000",
"fgcolor": "#e60000",
"id": "4855bb67-ff74-482c-89ac-ec3e814be97a",
"name": "tag2"
}
]
}
Pagination
Paginated endpoints return the total number of returned results and pages in the response.
These endpoints accept page and page_size arguments in the query. For example, a request for the 2nd page of the shipment list looks like this:
Request
curl -X GET "https://app.retino.com/api/v2/tracking/shipping?page=2" -H "Authorization: Token [Your API token]"
Response - 200
{
"count": number,
"current_page": number,
"total_pages": number,
"results": [...data...]
}