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/.
Endpoint | HTTP Metoda | Popis |
| GET | Seznam všech případů s možností filtrování |
| POST | Vytvoření nového případu |
| GET | Vyhledávání případů podle obsahu |
| GET | Detail případu podle ID |
| PUT | Kompletní aktualizace případu |
| PATCH | Částečná aktualizace případu |
| POST | Uzavření případu |
| GET | Seznam produktů v případu |
| POST | Přidání produktu do případu |
| GET | Detail produktu v případu |
| PUT/PATCH | Aktualizace produktu v případu |
| DELETE | Odstranění produktu z případu |
| POST | Vytvoření interní poznámky k případu |
| GET | Seznam stavů případů |
| GET | Seznam tagů pro případy |
| GET | Seznam typů případů |
| GET | Seznam uživatelů (agentů) |
| GET | Seznam vlastních polí pro případy |
| GET | Seznam vlastních polí pro produkty |
| GET | Seznam tras dopravy |
| GET | Seznam typů dopravy |
| GET | Seznam účtů pro refundace |
| PATCH | Aktualizace dobropisu |
Podrobný popis endpointů
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: Pro inkrementální změny doporučujeme spíše vytvořit webhook a nechat si zasílat strojově čitelná data o případech v reálném čase.
Parametry pro filtrování
created_at_from- filtruje případy vytvořené po zadaném datuupdated_at_from- filtruje případy upravené po zadaném datuclosed_at_from- filtruje případy uzavřené po zadaném datuis_closed- filtruje uzavřené/otevřené případy (boolean)
Ukázka
Request
curl -X GET "https://app.retino.com/api/v2/tickets" -H "Authorization: Token [Váš API token]"
Response
{
"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": "[email protected]",
"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
POST
/tickets
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
Request
curl -X POST \
-H 'Authorization: Token [Váš API token]' \
-H "Content-type: application/json" \
-d '{
"customer": {
"name": "Jan Novák",
"email": "[email protected]",
"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ů
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 jedné objednávce. Navrací stránkovaný seznam případů.
Ukázka
Request
curl -X GET "https://app.retino.com/api/v2/tickets/search?search=Vladimir+Remek" -H "Authorization: Token [Váš API token]"
Response
{
"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": "[email protected]",
"phone": "987654321"
},
// Další detaily případu
}
]
}
Detail případu
GET
/tickets/[id]
Slouží k načtení dat o jednom konkrétním případu podle ID.
Ukázka
Request
curl -X GET "https://app.retino.com/api/v2/tickets/8fad1c8d-3740-4aab-a224-c0ef379ea216" -H "Authorization: Token [Váš API token]"
Ú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. 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
Request
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
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.
Ukázka
Request
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
GET
/tickets/[ticket_id]/products
Slouží k získání seznamu všech produktů v konkrétním případu.
Ukázka
Request
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
POST
/tickets/[ticket_id]/products
Slouží k přidání nového produktu do existujícího případu.
Ukázka
Request
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
GET
/tickets/[ticket_id]/products/[id]
Slouží k získání detailních informací o konkrétním produktu v případu.
Ukázka
Request
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
PUT / PATCH
/tickets/[ticket_id]/products/[id]
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
Request
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
DELETE
/tickets/[ticket_id]/products/[id]
Slouží k odstranění produktu z případu.
Ukázka
Request
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
POST
/internal-note
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
Request
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-noteAktualizace dobropisu
PATCH
/retino-credit-notes/[id]
Slouží k aktualizaci dobropisu, především k přidání souboru dobropisu ze správy dobropisů vlastním ERP systémem.
Ukázka
Request
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ů
GET
/states
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
Request
curl -X GET "https://app.retino.com/api/v2/states" -H "Authorization: Token [Váš API token]"
Seznam tagů
GET
/tags
Slouží k získání seznamu všech tagů, které je možné přiřadit k případům.
Ukázka
Request
curl -X GET "https://app.retino.com/api/v2/tags" -H "Authorization: Token [Váš API token]"
Seznam typů případů
GET
/types
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
Request
curl -X GET "https://app.retino.com/api/v2/types" -H "Authorization: Token [Váš API token]"
Seznam uživatelů
GET
/users
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
Request
curl -X GET "https://app.retino.com/api/v2/users" -H "Authorization: Token [Váš API token]"
Seznam vlastních polí pro případy
GET
/custom-fields
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
Request
curl -X GET "https://app.retino.com/api/v2/custom-fields" -H "Authorization: Token [Váš API token]"
Seznam vlastních polí pro produkty
GET
/product-custom-fields
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
Request
curl -X GET "https://app.retino.com/api/v2/product-custom-fields" -H "Authorization: Token [Váš API token]"
Seznam tras dopravy
GET
/shipping-routes
Slouží k získání seznamu dostupných tras dopravy pro výběr dopravce při odesílání produktů.
Ukázka
Request
curl -X GET "https://app.retino.com/api/v2/shipping-routes" -H "Authorization: Token [Váš API token]"
Seznam typů dopravy
GET
/shipping-types
Slouží k získání seznamu typů dopravy, které jsou dostupné v účtu.
Ukázka
Request
curl -X GET "https://app.retino.com/api/v2/shipping-types" -H "Authorization: Token [Váš API token]"
Seznam účtů pro refundace
GET
/refund-accounts
Slouží k získání seznamu bankovních účtů pro refundace.
Ukázka
Request
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
Request
curl -X GET "https://app.retino.com/api/v2/tickets?page=2&page_size=10" -H "Authorization: Token [Váš API token]"
Response
{
"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
401 Unauthorized - Zkontrolujte, zda posíláte správný API token v hlavičce požadavku.
403 Forbidden - Zkontrolujte, zda má váš uživatel dostatečná oprávnění pro přístup k požadovaným datům.
429 Too Many Requests - Překročili jste limit počtu požadavků. Implementujte exponenciální backoff pro opakování požadavků.
Technická reference
Pro detailní popis všech endpointů, parametrů, datových modelů a možností filtrace se podívejte do naší reference Tickets API.