Webhook o objednání dopravy

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

Aktivace webhook události

1. Připravte na vašem serveru URL endpoint pro příjem webhooků (např. vas-eshop.cz/webhook-retino-shipping )
2. Přejděte do Nastavení > Webhooky v Retinu
3. Klikněte na "Vytvořit webhook"
4. Zadejte URL adresu vašeho endpointu
5. Vyberte událost shipping.ordered
6. Ulož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

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:

1. Implementovat ověření X-Retino-Secret hlavičky pro zabezpečení
2. Zajistit, že váš server odpoví do 10 sekund (i když zpracování dat bude probíhat asynchronně)
3. 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

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.