Webhook shipping.ordered umožňuje integraci dopravy ve vašem systému s Retinem. Tento webhook je vyvolán vždy při úspěšném objednání dopravy v systému Retino a poskytuje vám kompletní informace o objednané dopravě.
Poznámka: Webhooky jsou prémiová funkcionalita, která je součástí rozšíření "API & Webhooky". Pokud máte toto rozšíření aktivní, naleznete nastavení webhooků v Nastavení > Webhooky.
Aktivace webhook události
Připravte na vašem serveru URL endpoint pro příjem webhooků (např.
vas-eshop.cz/webhook-retino-shipping)Přejděte do Nastavení > Webhooky v Retinu
Klikněte na "Vytvořit webhook"
Zadejte URL adresu vašeho endpointu
Vyberte událost
shipping.orderedUložte nastavení
Zabezpečení
Každý webhook obsahuje v hlavičce požadavku autentifikační token pro ověření, že požadavek skutečně pochází z Retina:
X-Retino-Secret: <token>
Tento token naleznete v nastavení jednotlivých webhooků. Při příjmu webhooků byste měli vždy ověřit, že hlavička obsahuje správný token, který odpovídá vašemu webhooku.
Vzorová data
Webhook shipping.ordered odesílá data ve formátu JSON s následujícími informacemi:
{
"event_type": "shipping.ordered",
"created_at": "2023-01-23T10:28:10.010Z",
"shipping": {
"id": "2b20e85f-2201-494a-b3f9-85d89721174e",
"client_reference": "20210001",
"option_name": "Zásilkovna - Na výdejní místo",
"tracking_number": "Z3824826667",
"tracking_url": "https://www.zasilkovna.cz/vyhledavani?number=Z3824826667",
"customer_payment_details": [
{
"amount": "99.00",
"currency": "CZK",
"invoice_url": "https://example.com/invoice/123456.pdf"
}
]
}
}
Popis datové struktury
Pole | Popis | Typ |
| Typ události webhooku | String |
| Čas vytvoření události | ISO 8601 DateTime |
| Unikátní identifikátor dopravy v systému Retino | UUID |
| Kód případu, ke kterému se doprava vztahuje | String |
| Název dopravní služby | String |
| Sledovací číslo zásilky | String |
| URL adresa pro sledování zásilky | URL |
| Údaje o platbě zákazníka za dopravu | Array |
| Částka, kterou zákazník platí za dopravu | Decimal |
| Měna platby | String (ISO 4217) |
| URL adresa faktury za dopravu | URL |
Využití dat z webhooku
Data z webhook události shipping.ordered můžete využít například k:
Aktualizaci informací o odeslané zásilce ve vašem systému
Automatickému odeslání e-mailu zákazníkovi s informacemi o sledování zásilky
Zaznamenání nákladů na dopravu pro účetní a analytické účely
Synchronizaci stavu objednávky mezi Retinem a vaším e-shopem
Implementace na straně příjemce
Pro správné přijímání a zpracování webhooků doporučujeme:
Implementovat ověření X-Retino-Secret hlavičky pro zabezpečení
Zajistit, že váš server odpoví do 10 sekund (i když zpracování dat bude probíhat asynchronně)
Implementovat idempotentní zpracování webhooků (stejný webhook může být doručen vícekrát)
Ukázka implementace v PHP
// Získání dat z webhoku
$payload = file_get_contents('php://input');
$data = json_decode($payload, true);
$secretToken = $_SERVER['HTTP_X_RETINO_SECRET'] ?? null;// Ověření tajného tokenu
$expectedToken = 'váš_tajný_token'; // Získáte z nastavení webhooku v Retinu
if ($secretToken !== $expectedToken) {
http_response_code(401);
exit('Unauthorized');
}// Rychlá odpověď a asynchronní zpracování
http_response_code(200);
header('Content-Type: application/json');
echo json_encode(['status' => 'accepted']);// Uvolnění spojení pro zpracování na pozadí
if (function_exists('fastcgi_finish_request')) {
fastcgi_finish_request();
}// Zpracování dat o dopravě
if ($data['event_type'] === 'shipping.ordered') {
$shipping = $data['shipping'];
// Uložení dat o zásilce do vaší databáze
saveShippingData(
$shipping['id'],
$shipping['client_reference'],
$shipping['tracking_number'],
$shipping['tracking_url']
);
// Odeslání e-mailu zákazníkovi s informacemi o sledování
if (!empty($shipping['tracking_url']) && !empty($shipping['tracking_number'])) {
sendTrackingEmail(
$shipping['client_reference'],
$shipping['tracking_number'],
$shipping['tracking_url']
);
}
}
Monitorování a řešení problémů
Všechny odeslané webhooky a odpovědi jsou v Retinu dostupné v detailu konkrétního webhooku v Nastavení webhooků. Zde můžete:
Vidět historii odeslaných webhooků
Zobrazit detaily požadavků včetně payloadu
Zobrazit odpovědi vašeho serveru
Odeslat testovací událost pro ověření funkčnosti
Upozornění: Pokud váš server neodpoví do 10 sekund nebo odpoví chybovým stavovým kódem, doručení webhooku selže. Retino se bude snažit doručit takový webhook znovu po dobu 72 hodin s exponenciálním odstupem mezi pokusy (2 min, 4 min, 8 min, 16 min...) až do max. intervalu 1 hodiny.
Pokud bude doručování neúspěšné po dobu 72 hodin, endpoint bude automaticky deaktivován a administrátoři účtu budou informováni emailem.