Tracking API

Tato dokumentace slouží k popisu implementace REST Tracking API, které je určeno ke čtení dat o sledovaných zásilkách evidovaných v Retinu. Komunikace probíhá přes JSON pro vstup a výstup. API je bezestavové – každý požadavek musí být autorizován API tokenem v hlavičce požadavku.

Aktuální technickou referenci obsahující popis dat, naleznete na adrese app.retino.com/api/docs/v2/tracking.

Technická reference je pro přehlednost vedena pouze v angličtině, pokud byste měli nějaký problém s integrací, kontaktujte nás.

Autentifikace

Autentifikace probíhá pomocí tokenu, který naleznete v nastavení na stránce nastavení API. Tento token poté odesílejte v každém požadavku na Tickets API v hlavičce Authentication ve tvaru:

Authentication: Token [Váš API token]

Každý uživatel ve vašem účtu má přidělený svůj vlastní token. Pokud máte více účtů pod jedním uživatelem v Retinu, poté budete mít rozdílný token pro každý účet v Retinu.


Obnovení tokenu

Pokud máte podezření, že váš token byl kompromitován, můžete jej v nastavení obnovit.

POZOR, pokud token obnovíte, tak bude původní token okamžitě neplatný, takže integrace s vaším systémem bude mít výpadek, dokud token nevyměníte za nový.

Seznam endpointů

Zde je uveden seznam endpointů, které poskytuje Tracking API. Kompletní technická reference Tracking API, obsahující přesný popis datových typů, se nachází na adrese app.retino.com/api/docs/v2/tracking/.


Základní url produkční API je: https://app.retino.com/api/v2/tracking/


Seznam doprav

GET /shipping

Tento endpoint použijte pro získání dat o všech dopravách. Můžete je filtrovat a řadit podle data vytvoření, úpravy, objednání a doručení. Dále podle dopravce, stavu a vlastních štítků.

Navrací stránkovaný seznam doprav.


Request 
curl -X GET "https://app.retino.com/api/v2/tracking/shipping" -H  "Authorization: Token [Váš 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"
    }
  ]
}

Vyhledávání doprav

GET /shipping/search


Slouží k vyhledávání doprav podle čísla zakázky nebo sledovacího čísla. Vyhledá všechny dopravy, které obsahují daný řetězec.

Navrací stránkovaný seznam doprav.


Request

curl -X GET "https://app.retino.com/api/v2/tracking/search?search=TEST-TRACKING-NUMBER" -H  "Authorization: Token [Váš 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"
    }
  ]
}

Detail dopravy GET /shipping/[id]


Slouží k načtení dat o jedné konkrétní dopravě podle jejího id.


Request

curl -X GET "https://app.retino.com/api/v2/tracking/shipping/8768954d-de80-4b1a-bdcd-4eeeb68b126f" -H  "Authorization: Token [Váš 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"
}

Seznam problémových zásilek GET /issues


Tento endpoint použijte pro získání dat o všech problémech, které se naskytly během přepravy. Můžete je filtrovat podle data vzniku, stavu vyřešení a id dopravy.


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
    },
  ]
}

Seznam štítků

GET /tags

Tento endpoint použijte pro získání dat o štítcích.


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"
    }
  ]
}

Stránkování

Stránkované endpointy navrací v odpovědi celkový počet navrácených výsledků a stran.

Takové endpointy potom přijímají argumenty page a page_size v query, na příklad dotaz na 2. stránku seznamu doprav vypadá:


Request

curl -X GET "https://app.retino.com/api/v2/tracking/shipping?page=2" -H  "Authorization: Token [Váš API token]"
Response - 200 
{
  "count": number,
  "current_page": number,
  "total_pages": number,
  "results": [...data...]
}
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Related Articles