Dokumentace: Implementace Seznam Schématu pro objednávky

Co v této nápovědě naleznete?

Proč využívat strukturovaná data?

Technická implementace

Datová struktura objednávky

Příklad kompletní objednávky

Chybové stavy

Požadavky pro úspěšné vygenerování JSON-LD

Často kladené otázky (FAQ)

Tato nápověda popisuje, jak do transakčních e-mailů integrovat strukturovaná data (JSON-LD) pomocí našeho Widgetu Order. Tato integrace umožňuje zobrazovat interaktivní přehledy objednávek přímo v inboxu služeb Seznam.cz.

Další informace ke strukturovaným datům u Seznamu naleznete například ZDE.

Proč využívat strukturovaná data?

• Zviditelnění v inboxu: Zobrazení loga, stavu objednávky a tlačítka pro sledování zásilky přímo v seznamu zpráv.
• Lepší doručitelnost: E-maily se schématem jsou lépe klasifikovány a snižuje se riziko jejich zapadnutí do složky "Hromadné".
• Snížení zátěže podpory: Zákazníci vidí nejdůležitější informace (tracking, obsah objednávky) ihned bez nutnosti otevírat e-mail nebo hledat v textu.
• Kompatibilita: Používáme standard Schema.org, který je Seznamem podporován.

Technická implementace

Integrace probíhá vložením jednoho řádku kódu do vaší e-mailové šablony. Náš widget se postará o validaci dat a vygenerování správného JSON-LD skriptu. Kód je nejlepší vložit do textu kdekoliv na konec e-mailu, nebo do nějakého scriptu u prvku v Magic editoru.

Můžete použít 3 způsoby uvedené níže.

Pokud data předáváte přes metadata (např. v rámci Automatizace)

V tomto případě použijete Trigger "Při události" - Nová objednávka a skript níže.

Pokud načítáte objednávku přímo z naší databáze

V tomto případě je nutné, aby se k nám objednávka vždy importovala dříve, než se odešle samostatný transakční e-mail.

Widget automaticky vrátí HTML tag script type="application/ld+json" s validním obsahem, nebo skrytý HTML komentář v případě chyby.

Pokud posíláte transakční e-mailu přes API

Pokud v našem systému nemáte objednávky, je možné data doplnit pomocí této metody:

https://app.smartemailing.cz/docs/api/v3/index.html#api-Custom_campaigns-Send_transactional_emails

Nezapomeňte v odesílaném požadavku (requestu) správně definovat template_variables a proměnnou objednavka.

Samotný request pak vypadá takto:

{
  "sender_credentials": {
    "from": "martin@smartemailing.cz",
    "reply_to": "martin@smartemailing.cz",
    "sender_name": "Martin"
  },
  "tag": "transactional_1",
  "email_id": 14,
  "tasks": [
    {
      "recipient": {
        "emailaddress": "martin@smartemailing.cz"
      },
      "replace": [],
      "template_variables": {
        "objednavka": {
          "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
          "created_at": "2024-01-15T10:30:00+01:00",
          "contact_id": 12345,
          "status": "shipped",
          "eshop_name": "Muj Eshop",
          "eshop_code": "OBJ-2024-001",
          "order_url": "https://muj-eshop.cz/objednavka/OBJ-2024-001",
          "items": [
            {
              "id": "PROD-123",
              "name": "Modre tricko",
              "description": "Bavlnene tricko modre barvy",
              "price": {
                "with_vat": 499,
                "without_vat": 412.4,
                "currency": "CZK"
              },
              "quantity": 2,
              "unit": "ks",
              "url": "https://muj-eshop.cz/produkt/modre-tricko",
              "image_url": "https://muj-eshop.cz/images/modre-tricko.jpg"
            }
          ],
          "seller": {
            "name": "Muj Eshop s.r.o.",
            "url": "https://muj-eshop.cz",
            "logo": "https://muj-eshop.cz/logo.png"
          },
          "order_delivery": {
            "tracking_number": "CZ123456789",
            "tracking_url": "https://ppl.cz/tracking/CZ123456789",
            "expected_arrival_from": "2024-01-17T08:00:00+01:00",
            "expected_arrival_until": "2024-01-17T18:00:00+01:00",
            "has_delivery_method": "parcel-service",
            "provider": {
              "name": "PPL",
              "url": "https://ppl.cz",
              "logo": "https://ppl.cz/logo.png"
            },
            "delivery_address": {
              "address_country": "CZ",
              "address_region": "Hlavni mesto Praha",
              "address_locality": "Praha",
              "street_address": "Vaclavske namesti 1",
              "postal_code": "11000"
            }
          }
        },
        "products": []
      },
      "attachments": []
    }
  ]
}

Datová struktura objednávky

Aby mohl widget schéma správně vygenerovat, musí mít objekt objednávky (Order) následující strukturu, uvedenou níže.

Objednavka (Order) byla obohacena o tato pole:

Prodejce (Seller)

Jedná se o volitelný údaj. Pokud není seller vyplněn, widget se pokusí získat informace z URL první položky objednávky.

Povinná pole (pokud je seller vyplněn):

Automatické doplnění (pokud seller není vyplněn):

• name = eshop_name
• url = zakladni domena z URL prvni polozky
• logo = {domena}/logo.png

Stav objednávky (OrderStatus)

Stávající stavy objednávky byly rozšířeny:

Doručení (OrderDelivery)

Jedná se opět o volitelný údaj.

Povinná pole (pokud je order_delivery vyplněn):

Metoda doručení (DeliveryMethod)

Přepravce (DeliveryProvider)

Jedná se o povinné pole.

Doručovací adresa (DeliveryAddress)

Jedná se o povinné pole.

Příklad kompletní objednávky

{
  "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "created_at": "2024-01-15T10:30:00+01:00",
  "contact_id": 12345,
  "status": "shipped",
  "eshop_name": "Muj Eshop",
  "eshop_code": "OBJ-2024-001",
  "order_url": "https://muj-eshop.cz/objednavka/OBJ-2024-001",
  "items": [
    {
      "id": "PROD-123",
      "name": "Modre tricko",
      "description": "Bavlnene tricko modre barvy",
      "price": {
        "with_vat": 499,
        "without_vat": 412.4,
        "currency": "CZK"
      },
      "quantity": 2,
      "unit": "ks",
      "url": "https://muj-eshop.cz/produkt/modre-tricko",
      "image_url": "https://muj-eshop.cz/images/modre-tricko.jpg"
    }
  ],
  "seller": {
    "name": "Muj Eshop s.r.o.",
    "url": "https://muj-eshop.cz",
    "logo": "https://muj-eshop.cz/logo.png"
  },
  "order_delivery": {
    "tracking_number": "CZ123456789",
    "tracking_url": "https://ppl.cz/tracking/CZ123456789",
    "expected_arrival_from": "2024-01-17T08:00:00+01:00",
    "expected_arrival_until": "2024-01-17T18:00:00+01:00",
    "has_delivery_method": "parcel-service",
    "provider": {
      "name": "PPL",
      "url": "https://ppl.cz",
      "logo": "https://ppl.cz/logo.png"
    },
    "delivery_address": {
      "address_country": "CZ",
      "address_region": "Hlavni mesto Praha",
      "address_locality": "Praha",
      "street_address": "Vaclavske namesti 1",
      "postal_code": "11000"
    }
  }
}

Chybové stavy

Widget vrací HTML komentáře při chybách:

Požadavky pro úspěšné vygenerování JSON-LD

Pro úspěšné vygenerování JSON-LD schématu musí objednávka splňovat následující:

• Musí obsahovat alespoň jednu položku s platnou URL adresou
• Musí mít vyplněnu order_url NEBO musí být možné získat URL z první položky
• Všechny položky musí mít stejnou měnu

Často kladené otázky (FAQ)

Je nutné se předem registrovat nebo žádat o schválení?

Registrace ani schvalování se neprovádí. Pokud budou vaše e-maily obsahovat strukturovaná data ve správné podobě, po nasazení funkce se automaticky začnou zpracovávat. Přidání dat je možné provést kdykoli.

Budou zákazníci dál dostávat moje e-maily?

Ano, vaši zákazníci budou nadále dostávat vaše e-maily tak, jak jsou zvyklí. Samotné zprávy nejsou touto funkcí nijak ovlivněny, data se získávají z metadat.

Jaké jsou další plány se strukturovanými daty?

V budoucnu by Seznam.cz rád přinesl přehled objednávek i do mobilní aplikace a na hlavní stránku. Plánuje se také podpora pro vstupenky, jízdenky nebo slevové kupóny.