Pro vývojáře
Tickets API

Tickets API

Tato dokumentace slouží k popisu implementace REST Tickets API, které je určeno ke čtení dat o případech 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/. 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 Tickets API. Kompletní technická reference Tickets API, obsahující přesný popis datových typů, se nachází na adrese app.retino.com/api/docs/v2/.

Seznam případů

GET
/tickets

Tento endpoint použijte pro získání dat o všech případech. Můžete je filtrovat a řadit podle data vytvoření, úpravy a uzavření.

💡 Tip
Pokud budete synchronizovat data o všech případech, raději si pro inkrementální změny vytvořte webhook a místo pravidelného stahování vám budeme zasílat strojově čitelná data o případech v reálném čase.
Request
CURL
curl -X GET "https://app.retino.com/api/v2/tickets" -H  "Authorization: Token [Váš API token]"
Response
200
{
  "count": 1,
  "current_page": 1,
  "total_pages": 1,
  "results": [
    {
      "id": "8fad1c8d-3740-4aab-a224-c0ef379ea216",
      "code": "20210001",
      "state": "4531636a-108f-4ae3-abff-367901418600",
      "tags": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ],
      "type": "44c88eec-b995-4c84-b269-2ff06c8fe5d5",
      "owner": "e342f794-7b11-4acc-a46e-784a74a30af2",
      "bound_order": null,
      "products": [
        {
          "id": "09c69980-299d-4d37-81d5-ed18c9565856",
          "bound_order_item": null,
          "price": {
            "with_vat": "990000000.0000",
            "without_vat": null,
            "vat": null
          },
          "files": [],
          "name": "Apollo 11",
          "manufacturer": "NASA",
          "category": "Rakety",
          "product_id": "#1",
          "variant": "XL",
          "ean": "",
          "serial": null,
          "amount": "1.0000",
          "custom_fields": {
            "1b8508b0-ba85-427c-b23c-ae739453b0cd": "74ea523e-ea95-44d4-85ff-758c485ff77d"
          }
        }
      ],
      "shipping": [],
      "customer": {
        "name": "Vladimír Remek",
        "email": "support@retino.com",
        "phone": "987654321"
      },
      "currency": "CZK",
      "language": "cs",
      "country": "CZ",
      "order_id": "234567",
      "order_date": "2020-09-09T00:00:00.000Z",
      "customer_rating": null,
      "customer_rating_comment": null,
      "custom_fields": { "resolve_by": "2020-10-08" },
      "verification_state": "VERIFIED_AUTOMATICALLY",
      "is_unread": false,
      "created_at": "2020-09-24T11:30:53.210107+02:00",
      "updated_at": "2020-09-24T11:30:53.525472+02:00",
      "closed_at": null
    }
  ]
}

Vyhledávání případů

GET
/tickets/search

Slouží k vyhledávání případů podle údajů o zákazníkovi, produktech, nebo navázané dopravě. Například takto můžete nalézt všechny případy vztahující se k nějaké objednávce.

Navrací stránkovaný seznam případů.

Request
CURL
curl -X GET "https://app.retino.com/api/v2/tickets/search?search=Vladimir+Remek" -H  "Authorization: Token [Váš API token]"
Response
200
{
  "count": 1,
  "current_page": 1,
  "total_pages": 1,
  "results": [
    {
      "id": "8fad1c8d-3740-4aab-a224-c0ef379ea216",
      "code": "20210001",
      "state": "4531636a-108f-4ae3-abff-367901418600",
      "tags": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ],
      "type": "44c88eec-b995-4c84-b269-2ff06c8fe5d5",
      "owner": "e342f794-7b11-4acc-a46e-784a74a30af2",
      "bound_order": null,
      "products": [
        {
          "id": "09c69980-299d-4d37-81d5-ed18c9565856",
          "bound_order_item": null,
          "price": {
            "with_vat": "990000000.0000",
            "without_vat": null,
            "vat": null
          },
          "files": [],
          "name": "Apollo 11",
          "manufacturer": "NASA",
          "category": "Rakety",
          "product_id": "#1",
          "variant": "XL",
          "ean": "",
          "serial": null,
          "amount": "1.0000",
          "custom_fields": {
            "1b8508b0-ba85-427c-b23c-ae739453b0cd": "74ea523e-ea95-44d4-85ff-758c485ff77d"
          }
        }
      ],
      "shipping": [],
      "customer": {
        "name": "Vladimír Remek",
        "email": "support@retino.com",
        "phone": "987654321"
      },
      "currency": "CZK",
      "language": "cs",
      "country": "CZ",
      "order_id": "234567",
      "order_date": "2020-09-09T00:00:00.000Z",
      "customer_rating": null,
      "customer_rating_comment": null,
      "custom_fields": { "resolve_by": "2020-10-08" },
      "verification_state": "VERIFIED_AUTOMATICALLY",
      "is_unread": false,
      "created_at": "2020-09-24T11:30:53.210107+02:00",
      "updated_at": "2020-09-24T11:30:53.525472+02:00",
      "closed_at": null
    }
  ]
}

Detail případu

GET
/tickets/[id]

Slouží k načtení dat o jednom konkrétním případu.

Request
CURL
curl -X GET "https://app.retino.com/api/v2/tickets/8fad1c8d-3740-4aab-a224-c0ef379ea216" -H  "Authorization: Token [Váš API token]"
Response
200
{
  "id": "8fad1c8d-3740-4aab-a224-c0ef379ea216",
  "code": "20210001",
  "state": "4531636a-108f-4ae3-abff-367901418600",
  "tags": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "type": "44c88eec-b995-4c84-b269-2ff06c8fe5d5",
  "owner": "e342f794-7b11-4acc-a46e-784a74a30af2",
  "bound_order": null,
  "products": [
    {
      "id": "09c69980-299d-4d37-81d5-ed18c9565856",
      "bound_order_item": null,
      "price": {
        "with_vat": "990000000.0000",
        "without_vat": null,
        "vat": null
      },
      "files": [],
      "name": "Apollo 11",
      "manufacturer": "NASA",
      "category": "Rakety",
      "product_id": "#1",
      "variant": "XL",
      "ean": "",
      "serial": null,
      "amount": "1.0000",
      "custom_fields": {
        "1b8508b0-ba85-427c-b23c-ae739453b0cd": "74ea523e-ea95-44d4-85ff-758c485ff77d"
      }
    }
  ],
  "shipping": [],
  "customer": {
    "name": "Vladimír Remek",
    "email": "support@retino.com",
    "phone": "987654321"
  },
  "currency": "CZK",
  "language": "cs",
  "country": "CZ",
  "order_id": "234567",
  "order_date": "2020-09-09T00:00:00.000Z",
  "customer_rating": null,
  "customer_rating_comment": null,
  "custom_fields": { "resolve_by": "2020-10-08" },
  "verification_state": "VERIFIED_AUTOMATICALLY",
  "is_unread": false,
  "created_at": "2020-09-24T11:30:53.210107+02:00",
  "updated_at": "2020-09-24T11:30:53.525472+02:00",
  "closed_at": null
}


Úprava případu

PUT
PATCH
/tickets/[id]

Slouží k úpravě dat případu. Lze upravit stav, typ, přiřazený agent, informace o zákazníkovi, jazyk, měna, země a vlastní pole.

Hodnoty, které jsou primární klíče entit, naleznete v adresním řádku příslušné entity v administraci.

Request
CURL
curl -X PATCH \
   -H 'Authorization: Token [Váš API token]' \
   -H "Content-type: application/json" \
   -d '{"state": "b3d97cdc-a2d8-4fcc-96f0-1ac91b47d8d3"}' \
   https://app.retino.com/api/v2/tickets/8fad1c8d-3740-4aab-a224-c0ef379ea216
Response
200
{
  "id": "8fad1c8d-3740-4aab-a224-c0ef379ea216",
  "code": "20210001",
  "state": "b3d97cdc-a2d8-4fcc-96f0-1ac91b47d8d3",
  "tags": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "type": "44c88eec-b995-4c84-b269-2ff06c8fe5d5",
  "owner": "e342f794-7b11-4acc-a46e-784a74a30af2",
  "bound_order": null,
  "products": [
    {
      "id": "09c69980-299d-4d37-81d5-ed18c9565856",
      "bound_order_item": null,
      "price": {
        "with_vat": "990000000.0000",
        "without_vat": null,
        "vat": null
      },
      "files": [],
      "name": "Apollo 11",
      "manufacturer": "NASA",
      "category": "Rakety",
      "product_id": "#1",
      "variant": "XL",
      "ean": "",
      "serial": null,
      "amount": "1.0000",
      "custom_fields": {
        "1b8508b0-ba85-427c-b23c-ae739453b0cd": "74ea523e-ea95-44d4-85ff-758c485ff77d"
      }
    }
  ],
  "shipping": [],
  "customer": {
    "name": "Vladimír Remek",
    "email": "support@retino.com",
    "phone": "987654321"
  },
  "currency": "CZK",
  "language": "cs",
  "country": "CZ",
  "order_id": "234567",
  "order_date": "2020-09-09T00:00:00.000Z",
  "customer_rating": null,
  "customer_rating_comment": null,
  "custom_fields": { "resolve_by": "2020-10-08" },
  "verification_state": "VERIFIED_AUTOMATICALLY",
  "is_unread": false,
  "created_at": "2020-09-24T11:30:53.210107+02:00",
  "updated_at": "2020-09-24T11:30:53.525472+02:00",
  "closed_at": null
}


Uzavření případu

POST
/tickets/[id]/close

Slouží k uzavření případu. Pokud máte nastavenou automatizaci na uzavření případu, tak bude spuštěna, což může vyvolat například odeslání dotazníku s hodnocením.

Request
CURL
curl -X GET "https://app.retino.com/api/v2/tickets/8fad1c8d-3740-4aab-a224-c0ef379ea216/close" -H  "Authorization: Token [Váš API token]"
Response
200
{
  "id": "8fad1c8d-3740-4aab-a224-c0ef379ea216",
  "code": "20210001",
  "state": "4531636a-108f-4ae3-abff-367901418600",
  "tags": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "type": "44c88eec-b995-4c84-b269-2ff06c8fe5d5",
  "owner": "e342f794-7b11-4acc-a46e-784a74a30af2",
  "bound_order": null,
  "products": [
    {
      "id": "09c69980-299d-4d37-81d5-ed18c9565856",
      "bound_order_item": null,
      "price": {
        "with_vat": "990000000.0000",
        "without_vat": null,
        "vat": null
      },
      "files": [],
      "name": "Apollo 11",
      "manufacturer": "NASA",
      "category": "Rakety",
      "product_id": "#1",
      "variant": "XL",
      "ean": "",
      "serial": null,
      "amount": "1.0000",
      "custom_fields": {
        "1b8508b0-ba85-427c-b23c-ae739453b0cd": "74ea523e-ea95-44d4-85ff-758c485ff77d"
      }
    }
  ],
  "shipping": [],
  "customer": {
    "name": "Vladimír Remek",
    "email": "support@retino.com",
    "phone": "987654321"
  },
  "currency": "CZK",
  "language": "cs",
  "country": "CZ",
  "order_id": "234567",
  "order_date": "2020-09-09T00:00:00.000Z",
  "customer_rating": null,
  "customer_rating_comment": null,
  "custom_fields": { "resolve_by": "2020-10-08" },
  "verification_state": "VERIFIED_AUTOMATICALLY",
  "is_unread": false,
  "created_at": "2020-09-24T11:30:53.210107+02:00",
  "updated_at": "2020-09-24T11:30:53.525472+02:00",
  "closed_at": "2020-09-24T11:35:53.210107+02:00"
}


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 případu vypadá:

Request
CURL
curl -X GET "https://app.retino.com/api/v2/tickets?page=2" -H  "Authorization: Token [Váš API token]"
Response
200
{
  "count": number,
  "current_page": number,
  "total_pages": number,
  "results": [...data...]
}

Pro detailní popis těchto endpointů se podívejte do naší reference Tickets API.

Máte dotaz? Napište nám na support@retino.com.

Tohle je Sparta Retino. A měli byste ho zkusit.

Myslíme si, že se vám bude líbit. Ale chápeme, že náš názor nebude úplně objektivní. Proto můžete všechny funkce Retina vyzkoušet na 14 dní zdarma.

Vyzkoušet Retino zdarma Kontaktujte nás
App screenshot