Úvod

Zobrazení objednávek v Seznam Emailu

Záložka Objednávky v e‑mailových schránkách od Seznam.cz bude obsahovat přehledný výpis objednávek a jejich stavů zjištěných pomocí strukturovaných dat v příchozích transakčních e‑mailech. Z každé objednávky bude zároveň dostupný soupis všech souvisejících e‑mailových zpráv. Na samotné doručení e‑mailu nebo jeho zařazení do složkové struktury nemá zpracování strukturovaných dat v žádné fázi vliv.

Zpracování e‑mailu

E‑mailový server při přijetí e‑mailu hledá v HTML MIME části strukturovaná data o objednávce v souladu s rozvíjejícím se standardem strukturovaných e‑mailů, přičemž pro popis jednotlivých položek je využíván slovník dostupný na schema.org. Očekávaná struktura a umístění těchto dat o objednávce je popsána níže. Najde-li server v e‑mailu správně popsanou objednávku, vytvoří pro ni ve výpisu nový záznam nebo aktualizuje stávající, jestliže nalezne shodu v klíčových parametrech.

Vložení dat do e‑mailu

Umístění strojově čitelných dat v e‑mailu je inspirováno již existující specifikací, kterou využívají globální poskytovatelé e‑mailových služeb. Strukturovaný e‑mail je tvořen HTML MIME částí, která obsahuje strukturovaná data o nejvýše jedné objednávce, a to v jednom ze dvou podporovaných formátů:

Použití JSON-LD může vypadat takto:

Subject: Potvrzení objednávky #1234
Content-Type: text/html; charset=utf-8
Content-Transfer-Encoding: 8bit 

<!DOCTYPE html>
<html>
  <head>
    <title>Potvrzení objednávky #1234</title>
  </head>
  <body>
    <h1>Potvrzení objednávky #1234</h1>
    <p>Vaše objednávka byla přijata a je právě zpracovávána.</p>
    <script type="application/ld+json">
      <!-- JSON-LD data -->
    </script>
  </body>
</html>

Použití Microdat může vypadat takto:

Subject: Potvrzení objednávky #1234
Content-Type: text/html; charset=utf-8
Content-Transfer-Encoding: 8bit

<!DOCTYPE html>
<html>
  <head>
    <title>Potvrzení objednávky #1234</title>
  </head>
  <body>
    <h1>Potvrzení objednávky #1234</h1>
    <p>Vaše objednávka byla přijata a čeká na vyřízení.</p>
    <div itemscope itemtype="https://schema.org/Order">
      <!-- Další Microdata -->
    </div>
  </body>
</html>

V případě použití JSON-LD očekáváme výše popsaný <script... element, který obsahuje jeden nezanořený objekt a nic jiného. Tento objekt přímo reprezentuje samotnou objednávku. Chybně umístěná data nebudou nalezena a zpracována. To nemá vliv na doručení e‑mailu uživateli.

Struktura dat

Data o objednávce vychází ze schématu pro objednávky. Očekáváme data s následující strukturou:

Datové položky, které nejsou uvedené v seznamu výše, jsou ignorovány. Všechny URL musí být v podobě s https://.

(*) V položce acceptedOffer je možné poslat celkovou cenu (preferováno) nebo ceny jednotlivých položek objednávky jako více položek price. V takovém případě bude jejich hodnota sečtena a zobrazena bude výsledná částka. Více kusů lze vyjádřit parametrem eligibleQuantity; je-li tento parametr přítomen, hodnota parametru price je považována za jednotkovou a bude vynásobena příslušným množstvím kusů. Parametr price akceptujeme také na hlavní úrovni. Takto uvedenou cenu považujeme vždy za celkovou a pokud je přítomna, ve výpisu se zobrazí tato a položky ve struktuře acceptedOffer jsou ignorovány.

Datová struktura s objednávkou musí mít správně uvedený svůj typ pomocí rdf:type s hodnotou která reprezentuje https://schema.org/Order. Tento konkrétní typ slouží k označení správné datové struktury s objednávkou.

V JSON-LD se vyjádří takto:

{
  "@context": "https://schema.org",
  "@type": "Order",

  // další data
}

V Microdatech se vyjádří takto:

<div itemscope itemtype="https://schema.org/Order">
  <!-- další data -->
</div>

Jestliže se tento konkrétní typ vyskytne v e‑mailu více než jednou, může být vybrána a zpracována špatná datová struktura.

Pokud chybí některá z povinných položek nebo datová struktura s objednávkou nemá správně uvedený svůj typ, pak data o objednávce nebudou zpracována a neuloží se. To nemá vliv na doručení e‑mailu uživateli.

Vytvoření a aktualizace stavu objednávky

Pro vytvoření nového záznamu objednávky jsou povinné všechny uvedené položky s výjimkou položek ve struktuře orderDelivery. Úspěšně vytvořený záznam je zobrazen v rozhraní e‑mailové schránky.

Stav objednávky se aktualizuje přijetím nového e‑mailu, který obsahuje strukturovaná data o objednávce s novým stavem a/nebo doplněnými informacemi o přepravě. Pro úspěšné zaktualizování stavu objednávky musí každý následující e‑mail obsahovat seller.name, orderNumber a url s hodnotami odpovídajícími hodnotám v předešlé zprávě. V opačném případě není možné zprávu zpracovat jako aktualizaci existující objednávky.

Všechny ostatní položky budou doplněny či zaktualizovány podle dat v nové zprávě. Pro položky, které nebudou v následující zprávě dohledány, budou v zobrazení objednávky použity hodnoty uložené z předešlých zpráv. Pro bezproblémové zpracování přesto doporučujeme v každé zprávě poskytnout maximum známých informací. Pro odebrání uložené informace je potřeba zahrnout příslušný parametr a namísto hodnoty ponechat prázdný řetězec.

V případě, že dopravu objednávky zajišťuje přepravní služba, je pro úspěšné zpracování aktualizací o přepravě nutné, aby e‑mailové zprávy od přepravce obsahovaly odpovídající název obchodu v parametru seller.name a minimálně jeden z parametrů orderNumber nebo url s hodnotami odpovídajícími hodnotám v předešlé zprávě od prodejce.

Příklady dat

Základní příklad JSON-LD dat pro objednávku:

{
  "@context": "https://schema.org",
  "@type": "Order",

  "orderDate": "2024-01-01T00:00:00+01:00",
  "orderNumber": "1234",
  "orderStatus": "https://schema.org/OrderProcessing",
  "url": "https://example.com/orders/1234",

  "seller": {
    "@type": "Organization",
    "name": "Example.com",
    "url": "https://example.com",
    "logo": "https://example.com/logo.png"
  },

  "acceptedOffer": {
    "@type": "Offer",
    "price": "100.00",
    "priceCurrency": "CZK"
  }
}

Pokud je v době vytvoření objednávky znám i způsob doručení a dopravce, je možné je zahrnout do dat:

{
  "@context": "https://schema.org",
  "@type": "Order",

  // stejné jako výše

  "orderDelivery": {
    "@type": "ParcelDelivery",
    "trackingNumber": "4321",
    "trackingUrl": "https://example.com/tracking/4321",
    "expectedArrivalFrom": "2024-01-01T00:00:00+01:00",
    "expectedArrivalUntil": "2024-01-02T00:00:00+01:00",
    "hasDeliveryMethod": "https://schema.org/ParcelService",
    "provider": {
      "@type": "Organization",
      "name": "Ponny Express",
      "url": "https://ponnyexpress.com",
      "logo": "https://ponnyexpress.com/logo.png"
    }
  }
}

Pro kontrolu správnosti datových struktur je k dispozici validátor na adrese https://fbl.seznam.cz/orders

Změna stavu objednávky

Cílem funkcionality je poskytnout uživateli přehled o provedených objednávkách a aktuální fázi jejich vyřízení. Stěžejní informací každého e‑mailu s aktualizací by proto měl být skutečný stav zpracování objednávky. Aktuální stav vyřízení bude v přehledu objednávek v rozhraní schránky zobrazen a uživatel bude mít možnost podle něj objednávky řadit či filtrovat.

Stav zpracování objednávky je uveden v datové položce orderStatus. V té rozlišujeme následující stavy zpracování objednávky dle seznamu možných stavů.

Příklad změny stavu v JSON-LD:

{
  "@context": "https://schema.org",
  "@type": "Order",

  // stejné jako výše

  "orderStatus": "https://schema.org/OrderInTransit"
}

Doplňující informace

Předpokládaný termín nasazení funkce do provozu je konec Q2/2025.

Již nyní je možné po domluvě provést test zpracování dat ve vašich transakčních e-mailech. V případě zájmu nebo jakýchkoli dotazů se prosím obracejte na e-mail dotazy@schema.seznam.cz.

Informace o objednávkách jsou získávány výhradně ze strukturovaných dat, nikoli z těla e-mailové zprávy. Všechna uživatelská data jsou zpracovávána a uchovávána v souladu se smluvními podmínkami služby Email.cz.