Tickets API

Tata dokumentace popisuje implementaci REST Tickets API, které je určeno ke správě a čtení dat o případech (ticketech) 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.

Autentifikace

Autentifikace probíhá pomocí tokenu, který naleznete v Nastavení > API > API token. 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

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ý.

Přehled endpointů

Níže 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/.

Podrobný popis endpointů

Seznam případů

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í.

Parametry pro filtrování

• created_at_from - filtruje případy vytvořené po zadaném datu
• updated_at_from - filtruje případy upravené po zadaném datu
• closed_at_from - filtruje případy uzavřené po zadaném datu
• is_closed - filtruje uzavřené/otevřené případy (boolean)

Ukázka

curl -X GET "https://app.retino.com/api/v2/tickets" -H  "Authorization: Token [Váš API token]"

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

Vytvoření případu

Slouží k vytvoření nového případu. V requestu je potřeba poslat minimálně údaje o zákazníkovi, měnu, jazyk a další povinné údaje podle dokumentace.

Ukázka

curl -X POST \
  -H 'Authorization: Token [Váš API token]' \
  -H "Content-type: application/json" \
  -d '{
    "customer": {
      "name": "Jan Novák",
      "email": "jan.novak@example.com",
      "phone": "123456789"
    },
    "currency": "CZK",
    "language": "cs",
    "country": "CZ",
    "order_id": "123456",
    "order_date": "2025-01-15T00:00:00.000Z",
    "type": "44c88eec-b995-4c84-b269-2ff06c8fe5d5"
  }' \
  https://app.retino.com/api/v2/tickets

Vyhledávání případů

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 jedné objednávce. Navrací stránkovaný seznam případů.

Ukázka

curl -X GET "https://app.retino.com/api/v2/tickets/search?search=Vladimir+Remek" -H  "Authorization: Token [Váš API token]"

{
  "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": [
        // Detail produktu
      ],
      "shipping": [],
      "customer": {
        "name": "Vladimír Remek",
        "email": "support@retino.com",
        "phone": "987654321"
      },
      // Další detaily případu
    }
  ]
}

Detail případu

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

Ukázka

curl -X GET "https://app.retino.com/api/v2/tickets/8fad1c8d-3740-4aab-a224-c0ef379ea216" -H  "Authorization: Token [Váš API token]"

Úprava případu

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. Metoda PUT vyžaduje všechny povinné parametry, PATCH umožňuje aktualizovat jen konkrétní pole.

Hodnoty, které jsou primární klíče entit (state, type, owner atd.), naleznete v adresním řádku příslušné entity v administraci nebo je můžete získat pomocí příslušných API endpointů pro seznamy entit.

Ukázka

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

Uzavření případu

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.

Ukázka

curl -X POST "https://app.retino.com/api/v2/tickets/8fad1c8d-3740-4aab-a224-c0ef379ea216/close" -H  "Authorization: Token [Váš API token]"

Seznam produktů v případu

Slouží k získání seznamu všech produktů v konkrétním případu.

Ukázka

curl -X GET "https://app.retino.com/api/v2/tickets/8fad1c8d-3740-4aab-a224-c0ef379ea216/products" -H  "Authorization: Token [Váš API token]"

Přidání produktu do případu

Slouží k přidání nového produktu do existujícího případu.

Ukázka

curl -X POST \
   -H 'Authorization: Token [Váš API token]' \
   -H "Content-type: application/json" \
   -d '{
     "name": "MacBook Pro",
     "amount": "1.0000",
     "price": {
       "with_vat": "45000.0000"
     },
     "product_id": "MBP-2024",
     "manufacturer": "Apple",
     "category": "Notebooky",
     "variant": "Space Black"
   }' \
   https://app.retino.com/api/v2/tickets/8fad1c8d-3740-4aab-a224-c0ef379ea216/products

Detail produktu v případu

Slouží k získání detailních informací o konkrétním produktu v případu.

Ukázka

curl -X GET "https://app.retino.com/api/v2/tickets/8fad1c8d-3740-4aab-a224-c0ef379ea216/products/09c69980-299d-4d37-81d5-ed18c9565856" -H  "Authorization: Token [Váš API token]"

Aktualizace produktu

Slouží k aktualizaci informací o produktu v případu. Metoda PUT vyžaduje všechny povinné parametry, PATCH umožňuje aktualizovat jen vybraná pole.

Ukázka

curl -X PATCH \
   -H 'Authorization: Token [Váš API token]' \
   -H "Content-type: application/json" \
   -d '{
     "amount": "2.0000",
     "price": {
       "with_vat": "90000.0000"
     }
   }' \
   https://app.retino.com/api/v2/tickets/8fad1c8d-3740-4aab-a224-c0ef379ea216/products/09c69980-299d-4d37-81d5-ed18c9565856

Odstranění produktu

Slouží k odstranění produktu z případu.

Ukázka

curl -X DELETE "https://app.retino.com/api/v2/tickets/8fad1c8d-3740-4aab-a224-c0ef379ea216/products/09c69980-299d-4d37-81d5-ed18c9565856" -H  "Authorization: Token [Váš API token]"

Vytvoření interní poznámky

Slouží k přidání interní poznámky k případu. Interní poznámky jsou viditelné pouze pro agenty, nikoliv pro zákazníky.

Ukázka

curl -X POST \
   -H 'Authorization: Token [Váš API token]' \
   -H "Content-type: application/json" \
   -d '{
     "ticket": "8fad1c8d-3740-4aab-a224-c0ef379ea216",
     "text": "Poznámka k případu, kterou zákazník neuvidí."
   }' \
   https://app.retino.com/api/v2/internal-note

Aktualizace dobropisu

Slouží k aktualizaci dobropisu, především k přidání souboru dobropisu ze správy dobropisů vlastním ERP systémem.

Ukázka

curl -X PATCH \
   -H 'Authorization: Token [Váš API token]' \
   -H "Content-type: application/json" \
   -d '{
     "file_base64": "JVBERi0xLjUKJdDUxdgKNSAwIG9iago8PC9GaWx0ZXIv..."
   }' \
   https://app.retino.com/api/v2/retino-credit-notes/5cae6caf-c1cb-49ed-96bd-2d2837765ffc

Seznam stavů případů

Slouží k získání seznamu všech stavů případů v účtu. Tyto stavy je možné použít při vytváření nebo aktualizaci případů.

Ukázka

curl -X GET "https://app.retino.com/api/v2/states" -H  "Authorization: Token [Váš API token]"

Seznam tagů

Slouží k získání seznamu všech tagů, které je možné přiřadit k případům.

Ukázka

curl -X GET "https://app.retino.com/api/v2/tags" -H  "Authorization: Token [Váš API token]"

Seznam typů případů

Slouží k získání seznamu všech typů případů v účtu. Tyto typy je možné použít při vytváření nebo aktualizaci případů.

Ukázka

curl -X GET "https://app.retino.com/api/v2/types" -H  "Authorization: Token [Váš API token]"

Seznam uživatelů

Slouží k získání seznamu všech uživatelů (agentů) v účtu. Tyto uživatele je možné přiřazovat jako vlastníky případů.

Ukázka

curl -X GET "https://app.retino.com/api/v2/users" -H  "Authorization: Token [Váš API token]"

Seznam vlastních polí pro případy

Slouží k získání seznamu všech vlastních polí pro případy. Tato pole je možné používat při vytváření nebo aktualizaci případů.

Ukázka

curl -X GET "https://app.retino.com/api/v2/custom-fields" -H  "Authorization: Token [Váš API token]"

Seznam vlastních polí pro produkty

Slouží k získání seznamu všech vlastních polí pro produkty. Tato pole je možné používat při vytváření nebo aktualizaci produktů v případech.

Ukázka

curl -X GET "https://app.retino.com/api/v2/product-custom-fields" -H  "Authorization: Token [Váš API token]"

Seznam tras dopravy

Slouží k získání seznamu dostupných tras dopravy pro výběr dopravce při odesílání produktů.

Ukázka

curl -X GET "https://app.retino.com/api/v2/shipping-routes" -H  "Authorization: Token [Váš API token]"

Seznam typů dopravy

Slouží k získání seznamu typů dopravy, které jsou dostupné v účtu.

Ukázka

curl -X GET "https://app.retino.com/api/v2/shipping-types" -H  "Authorization: Token [Váš API token]"

Seznam účtů pro refundace

Slouží k získání seznamu bankovních účtů pro refundace.

Ukázka

curl -X GET "https://app.retino.com/api/v2/refund-accounts" -H  "Authorization: Token [Váš API token]"

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.

Ukázka

curl -X GET "https://app.retino.com/api/v2/tickets?page=2&page_size=10" -H  "Authorization: Token [Váš API token]"

{
  "count": number,
  "current_page": number,
  "total_pages": number,
  "results": [...data...]
}

Best Practices

• Webhooky vs. Polling - Pro získávání aktualizací o případech doporučujeme používat webhooky místo pravidelného dotazování API.
• Rate limiting - API má omezení na počet požadavků, které můžete poslat v určitém časovém intervalu. Implementujte správné zacházení s rate limitem a retry mechanismy.
• Ukládání ID entit - Pro úpravy případů budete potřebovat ID entit (stavy, typy, atd.). Tyto údaje je vhodné si ukládat a pravidelně aktualizovat.
• Paginace výsledků - Při práci s větším počtem případů vždy používejte paginaci pro optimalizaci výkonu.

Časté problémy

Technická reference

Pro detailní popis všech endpointů, parametrů, datových modelů a možností filtrace se podívejte do naší reference Tickets API.