Vytváření objednávek

3.1.3. Vytváření objednávek#

Tato stránka obsahuje veškerou dokumentaci k videonávodu, který vysvětluje jednoduché vytvoření objednávky prostřednictvím rozhraní API a kontrolu jejího stavu.

3.1.3.1. Video#

3.1.3.2. Požadavky#

Povinné pro tuto sérii výukových programů:

  • Obchodní backend Taler
    Pokud potřebujete pomoc s prvním použitím backendu obchodníka, můžete se podívat na Taler merchant introduction tutorial.
  • Instance peněženky Taler
    Pokyny k nastavení jsou k dispozici na adrese https://wallet.taler.net.
  • Software pro správu rozhraní REST API nebo příslušné programátorské dovednosti
    V této sérii videí budeme používat bezplatný software Insomnia, který je k dispozici ke stažení na adrese https://insomnia.rest.

3.1.3.3. Upozornění na ukázku backendu#

Pro tento návod můžete použít vlastní backendovou službu obchodníka nebo ukázkovou službu online na adrese https://backend.demo.taler.net/instances/sandbox/.

3.1.3.4. Další poznámky ke zpracování obchodních plateb#

  1. Vytvoření příkazu k úhradě

Platby v systému Taler probíhají na základě příkazu, což je strojově čitelný popis obchodní transakce, za kterou má být platba provedena. Před přijetím platby v systému Taler jako obchodník musíte takovou objednávku vytvořit.

To se provádí odesláním objektu JSON na koncový bod rozhraní API /private/orders backendu. Uvnitř pole order musí být uvedena alespoň následující pole:

  • částka: například EUR:10 pro 10 eur nebo KUDOS:1.5 pro 1.5 KUDOS.

  • souhrn: Lidsky čitelné shrnutí toho, čeho se platba týká. Shrnutí by mělo být dostatečně krátké, aby se vešlo do nadpisů, i když není stanoven žádný pevný limit.

  • fulfillment_url: URL adresa, která se zobrazí po dokončení platby. V případě digitálního zboží by to měla být stránka, která zobrazuje zakoupený produkt. Při úspěšné platbě peněženka automaticky připojí order_id jako parametr dotazu a také session_sig pro platby vázané na relaci (popsáno níže).

Objednávky mohou mít mnohem více polí, viz Formát objednávky Taleru. Při odesílání objednávky POST můžete také zadat další podrobnosti, například přepis doby trvání vrácení peněz a pokyny pro správu zásob. Ty jsou potřeba jen zřídka a tento návod se jimi nezabývá; podrobnosti naleznete v referenční příručce.

Minimální fragment jazyka Python pro vytvoření objednávky by vypadal takto:

>>> import requests
>>> body = dict(order=dict(amount="KUDOS:10",
...                        summary="Donation",
...                        fulfillment_url="https://example.com/thanks.html"),
...             create_token=False)
>>> response = requests.post("https://backend.demo.taler.net/instances/sandbox/private/orders",
...               json=body,
...               headers={"Authorization": "Bearer secret-token:sandbox"})
<Response [200]>

Backend doplní některé údaje, které v objednávce chybí, například adresu instance obchodníka. Úplné údaje se nazývají smluvní podmínky.

Poznámka

Výše uvedený požadavek zakáže používání tokenů deklarací nastavením možnosti create_token na hodnotu false. Pokud tokeny deklarace potřebujete, musíte upravit kód pro konstrukci URI taler://pay/ uvedeného níže tak, aby obsahoval token deklarace.

Po úspěšném POSTu do /private/orders se vrátí JSON s polem order_id s řetězcem reprezentujícím ID objednávky. Pokud se zobrazí také reklamační token, překontrolujte, zda jste požadavek použili tak, jak je popsáno výše.

Společně s instancí obchodníka identifikuje ID objednávky jednoznačně objednávku v rámci backendu obchodníka. Pomocí ID objednávky lze triviálně zkonstruovat příslušný URI taler://pay/, který je třeba poskytnout peněžence. Nechť example.com je název domény, kde jsou dosažitelné veřejné koncové body instance. URI Taler pay je pak jednoduše taler://pay/example.com/$ORDER_ID/, kde $ORDER_ID musí být nahrazeno ID objednávky, která byla vrácena.

URI taler:// můžete vložit jako cíl odkazu pro otevření peněženky Taler prostřednictvím schématu taler:// nebo jej vložit do kódu QR. Pro webový obchod je však nejjednodušší jednoduše přesměrovat prohlížeč na https://example.com/orders/$ORDER_ID. Tato stránka pak spustí peněženku Taler. Zde backend vygeneruje správnou logiku pro spuštění peněženky a podporuje různé typy existujících peněženek Taler. Místo ruční konstrukce výše uvedené adresy URL je také možné ji získat kontrolou stavu platby, jak je popsáno v následující části.

Při ručním sestavování této adresy URL nezapomeňte zadat token deklarace (pokud nebyl zakázán) a pokud backend běží bez TLS, použijte taler+http:// (všimněte si, že posledně jmenované je podporováno pouze peněženkami běžícími v režimu ladění).

Poznámka

Triviální způsob, jak získat správnou payment_redirect_url, je zkontrolovat stav platby (viz níže). Pokud si tedy stále nejste jisti, jak jej zkonstruovat, můžete jednoduše požádat backend, aby to udělal za vás. V produkčním provozu byste ji však pravděpodobně měli zkonstruovat ručně a vyhnout se tak dodatečnému požadavku na backend.

  1. Kontrola stavu platby a výzva k platbě

Vzhledem k ID objednávky lze stav platby zkontrolovat pomocí koncového bodu /private/orders/$ORDER_ID. Pokud zákazník platbu ještě neprovedl, poskytne koncovka /private/orders/$ORDER_ID frontendu adresu URL (pod názvem payment_redirect_url), která spustí v peněžence zákazníka provedení platby. V podstatě se jedná o adresu URL https://example.com/orders/$ORDER_ID, o které jsme hovořili výše.

>>> import requests
>>> r = requests.get("https://backend.demo.taler.net/instances/sandbox/private/orders/" + order_id,
...                  headers={"Authorization": "Bearer secret-token:sandbox"})
>>> print(r.json())

Pokud je pole order_status v odpovědi paid, nezobrazí se payment_redirect_url a místo toho se zobrazí informace o stavu platby, včetně:

  • smluvní_podmínky: Úplné smluvní podmínky objednávky.

  • refunded: true, pokud byla za tento nákup poskytnuta (případně částečná) náhrada.

  • refunded_amount: Částka, která byla vrácena

Jakmile frontend potvrdí, že platba proběhla úspěšně, musí obvykle spustit obchodní logiku pro obchodníka, aby splnil své povinnosti vyplývající ze smlouvy.

Poznámka

Nemusíte se neustále dotazovat, abyste si všimli změn stavu transakce objednávky. Koncové body podporují dlouhé dotazování, stačí zadat parametr dotazu timeout_ms s tím, jak dlouho chcete čekat na změnu stavu objednávky na zaplaceno.

3.1.3.5. Další výukové programy#

Chcete-li si prohlédnout další výukové programy, můžete si prohlédnout tento web nebo navštívit stránku https://docs.taler.net, kde najdete nejnovější dokumentaci ke službám Taler.