Přeskočit na hlavní obsah

Orders API: Synchronizace objednávek

REST API pro synchronizaci objednávek z e-shopu. Okamžité vytváření objednávek, aktualizace stavů a hromadný import.

Kryštof Řeháček avatar
Autor: Kryštof Řeháček
Aktualizováno před více než 2 měsíci

Orders API umožňuje synchronizovat objednávky z vašeho e-shopu do Retina v reálném čase. Je to moderní alternativa k Retino XML feedu – místo periodických importů synchronizujete objednávky okamžitě při jejich vytvoření.

Kompletní technickou referenci naleznete v API dokumentaci.

🤔 Kdy použít Orders API?

Před implementací zvažte, jaký typ synchronizace potřebujete:

Potřebujete Tracking s okamžitými notifikacemi?

✅ ANO → Orders API (instantní synchronizace)

  • E-maily o vytvoření objednávky zasílané okamžitě

  • Real-time sledování zásilek

  • Okamžité aktualizace stavů

  • Integrace webhooků s e-shopem

✅ NE → Retino XML Feed (synchronizace do 6 hodin)

  • Jednodušší implementace (jen vystavíte XML feed URL)

  • Stačí, pokud používáte Returns

  • Zákazník nemůže vrátit zboží do 6 hodin po nákupu

  • Vhodné, pokud nemůžete volat API z vašeho systému

Proč používat Orders API?

  • Okamžitá synchronizace – objednávka je v Retinu ihned po vytvoření

  • Transakční e-maily – můžete odesílat potvrzení objednávky v reálném čase

  • Aktuální data – změny v objednávce se projeví okamžitě

Příprava

1. Vytvořte API Token

V Nastavení → API v2 vytvořte nový token. Token použijete v hlavičce každého požadavku:

Authorization: váš_api_token

2. Vytvořte Store ID

Co je Store ID?

Store ID je jedinečný identifikátor vašeho e-shopu v Retinu. Společně s číslem objednávky (code) tvoří unikátní klíč pro každou objednávku.

Proč je Store ID důležité?

  • Unikátní identifikace: Kombinace code + store_id jednoznačně identifikuje objednávku

  • Automatický upsert: Při opakovaném odeslání stejné kombinace se objednávka aktualizuje místo vytvoření duplikátu

  • Multi-store podpora: Můžete mít více e-shopů pod jedním Retino účtem

Jak vytvořit Store ID:

  1. Přejděte do Nastavení → API v2

  2. V sekci "Store IDs" klikněte na "Přidat Store ID"

  3. Zadejte identifikátor (např. "hlavni-eshop", "eshop-sk")

  4. Uložte a použijte tento identifikátor v každém API požadavku

Důležité: Store ID nelze po vytvoření objednávky změnit. Vždy používejte stejné Store ID pro všechny objednávky z jednoho e-shopu.

Typické use cases

Use Case 1: Webhook při vytvoření objednávky

Scénář: Zákazník dokončí nákup ve vašem e-shopu a chcete mu okamžitě poslat potvrzovací e-mail.

Řešení:

  1. Nastavte webhook v e-shopu, který se spustí po vytvoření objednávky

  2. Webhook odešle objednávku do Retina pomocí POST /api/v2/orders

  3. Retino objednávku vytvoří a může odeslat potvrzovací e-mail zákazníkovi

Příklad požadavku:

curl -X POST "https://app.retino.com/api/v2/orders" \  -H "Authorization: váš_api_token" \  -H "Content-Type: application/json" \  -d '{    "code": "OBJ-2025-001",    "store_id": "hlavni-eshop",    "order_date": "2025-10-23T14:00:00Z",    "currency": "CZK",    "language": "cs",    "price": {      "with_vat": "1999.00"    },    "customer": {      "email": "[email protected]",      "phone": "+420123456789"    },    "shipping_address": {      "name": "Jan Novák",      "street": "Testovací",      "house_number": "1",      "city": "Praha",      "postal_code": "11000",      "country": "CZ"    },    "items": [      {        "name": "Smartphone XY",        "code": "PROD-001",        "amount": "1.00",        "item_type": "PRODUCT",        "total_price": {          "with_vat": "1799.00"        }      },      {        "name": "Doprava PPL",        "item_type": "SHIPPING",        "total_price": {          "with_vat": "199.00"        }      }    ]  }'

Use Case 2: Aktualizace stavu při expedici

Scénář: Objednávku jste zabalili a expedovali. Chcete informovat zákazníka o odeslání.

Řešení:

  1. Skladový systém označí objednávku jako expedovanou

  2. Zavolejte endpoint pro změnu stavu

  3. Retino může odeslat e-mail o odeslání zásilky

Příklad:

curl -X PATCH "https://app.retino.com/api/v2/orders/UUID_OBJEDNAVKY/status?status_value=DISPATCHED" \  -H "Authorization: váš_api_token"

Use Case 3: Prvotní import historických objednávek

Scénář: Máte existující e-shop s tisíci objednávek a chcete je přenést do Retina.

Řešení:

  1. Exportujte objednávky za posledních 30 měsíců z vašeho e-shopu

  2. Rozdělte je do dávek po max. 100 objednávkách

  3. Použijte endpoint POST /api/v2/orders/bulk pro import každé dávky

Příklad:

curl -X POST "https://app.retino.com/api/v2/orders/bulk" \  -H "Authorization: váš_api_token" \  -H "Content-Type: application/json" \  -d '[    {      "code": "OBJ-001",      "store_id": "hlavni-eshop",      "price": {"with_vat": "1000.00"},      "customer": {"email": "[email protected]"}    },    {      "code": "OBJ-002",      "store_id": "hlavni-eshop",      "price": {"with_vat": "2000.00"},      "customer": {"email": "[email protected]"}    }  ]'

API vrací informaci o úspěšně zpracovaných a chybných objednávkách.

Use Case 4: Částečná aktualizace údajů

Scénář: Zákazník změnil e-mail nebo telefonní číslo a vy chcete aktualizovat objednávku.

Řešení:

Použijte PATCH /api/v2/orders/{id} a odešlete pouze pole, která se mění:

curl -X PATCH "https://app.retino.com/api/v2/orders/UUID_OBJEDNAVKY" \  -H "Authorization: váš_api_token" \  -H "Content-Type: application/json" \  -d '{    "customer": {      "email": "[email protected]",      "phone": "+420999888777"    }  }'

Ostatní údaje objednávky zůstávají beze změny.

Stavy objednávek

Objednávka má dva typy stavů. Můžete je měnit pomocí endpointu PATCH /api/v2/orders/{id}/status:

Typ stavu

Hodnota

Význam

Zpracování

NEW

Nová objednávka

Zpracování

PICKING

Kompletace

Zpracování

PACKED

Zabaleno

Zpracování

DISPATCHED

Expedováno

Zpracování

ON_HOLD

Pozastaveno

Zpracování

READY_FOR_PICKUP

Připraveno k vyzvednutí

Zpracování

PICKED_UP

Vyzvednuto

Platba

AWAITING_PAYMENT

Čeká na platbu

Platba

PAID

Zaplaceno

Platba

PARTIALLY_REFUNDED

Částečně vráceno

Platba

REFUNDED

Vráceno

Platba

FAILED

Platba selhala

Automatická aktualizace vs. vytvoření

Orders API automaticky rozpozná, zda objednávku vytvořit nebo aktualizovat podle kombinace code + store_id:

  • První zaslání objednávky OBJ-001 + hlavni-eshop → vytvoří se nová (HTTP 201)

  • Druhé zaslání stejné kombinace → aktualizuje se existující (HTTP 200)

Díky tomu můžete používat stejný webhook pro vytvoření i aktualizaci objednávek. Nemusíte kontrolovat, zda objednávka již existuje.

Praktické tipy

Pojmenování Store ID

Pokud provozujete více e-shopů nebo prodejních kanálů, vytvořte pro každý vlastní Store ID:

  • eshop-cz – hlavní český e-shop

  • eshop-sk – slovenský e-shop

  • shopify-store – Shopify obchod

  • amazon-cz – Amazon

Důležitost e-mailu zákazníka

Pole customer.email není povinné, ale je kritické pro transakční e-maily. Bez e-mailu nemůže Retino poslat zákazníkovi:

  • Potvrzení objednávky

  • Upozornění na odeslání zásilky

  • Informace o doručení

Správné typy položek

Rozlišujte typy položek pro lepší přehled:

  • PRODUCT – produkty

  • SHIPPING – poplatek za dopravu

  • BILLING – poplatek za platbu

  • DISCOUNT – slevy a kupóny

Historie stavů

Můžete poslat celou historii stavů objednávky najednou pomocí pole statuses. To je užitečné při prvotním importu:

"statuses": [  {"name": "PAID", "date": "2025-10-23T10:00:00Z"},  {"name": "PICKING", "date": "2025-10-23T12:00:00Z"},  {"name": "DISPATCHED", "date": "2025-10-23T15:00:00Z"}]

Časté problémy

Store ID neexistuje

Chyba: "Store ID 'xyz' does not exist"

Řešení: Vytvořte Store ID v nastavení API před odesláním první objednávky.

Objednávka se nevytváří, jen aktualizuje

Důvod: Objednávka s tímto code + store_id již existuje.

Řešení: Toto je očekávané chování. Pokud chcete vytvořit novou objednávku, použijte jiné číslo objednávky (code).

Chyba s cenami

Chyba: "Price mismatch: 1000 + 210 ≠ 1200"

Řešení: Pokud posíláte všechny tři cenové hodnoty (with_vat, without_vat, vat), musí matematicky souhlasit. Můžete poslat jen jednu hodnotu a ostatní vynechat.

Technická dokumentace: app.retino.com/api/docs

Nastavení API: app.retino.com/settings/api-v2/

Související články
Tickets API
Webhooky
Synchronizace objednávek a zásilek přes API
Dostali jste odpověď na svou otázku?