Vytváranie objednávok

3.1.3. Vytváranie objednávok#

Táto stránka obsahuje celú dokumentáciu k videonávodu, ktorý vysvetľuje jednoduché vytvorenie objednávky prostredníctvom rozhrania API a kontrolu jej stavu.

3.1.3.1. Video#

3.1.3.2. Požiadavky#

Potrebné pre túto sériu výukových programov:

  • Backend obchodníka Taler
    Ak potrebujete pomoc pri prvom použití backendu obchodníka, môžete si pozrieť Taler merchant introduction tutoriál.
  • Príklad peňaženky Taler
    Pokyny na nastavenie sú k dispozícii na stránke https://wallet.taler.net.
  • Softvér na správu rozhrania API REST alebo príslušné programátorské zručnosti
    V tejto sérii videí budeme používať bezplatný softvér Insomnia, ktorý je k dispozícii na stiahnutie na adrese https://insomnia.rest.

3.1.3.3. Ukážka backendu#

Na tento návod môžete použiť vlastnú obchodnú backendovú službu alebo online demonštračnú službu na adrese https://backend.demo.taler.net/instances/sandbox/.

3.1.3.4. Ďalšie poznámky k spracovaniu platieb u obchodníkov#

  1. Vytvorenie príkazu na platbu

Platby v systéme Taler sa uskutočňujú na základe príkazu, čo je strojovo čitateľný opis obchodnej transakcie, za ktorú sa má vykonať platba. Pred prijatím platby v systéme Taler ako obchodník musíte vytvoriť takýto príkaz.

To sa vykoná odoslaním objektu JSON na koncový bod API /private/orders backendu. Vo vnútri poľa order musia byť uvedené aspoň tieto polia:

  • mount: napríklad EUR:10 pre 10 eur alebo KUDOS:1.5 pre 1.5 KUDOS.

  • summary: Ľudsky čitateľné zhrnutie toho, čoho sa platba týka. Zhrnutie by malo byť dostatočne krátke, aby sa zmestilo do nadpisov, hoci nie je stanovený žiadny pevný limit.

  • fulfillment_url: URL adresa, ktorá sa zobrazí po dokončení platby. V prípade digitálneho tovaru by to mala byť stránka, na ktorej sa zobrazí zakúpený produkt. Pri úspešnej platbe peňaženka automaticky pripojí order_id ako parameter dotazu, ako aj session_sig pre platby viazané na reláciu (popísané nižšie).

Objednávky môžu mať oveľa viac polí, pozrite si Formát objednávky Taler. Pri odosielaní objednávky POST môžete zadať aj ďalšie podrobnosti, ako je napríklad prepis doby trvania vrátenia peňazí a pokyny pre správu zásob. Tieto sú potrebné len zriedkavo a v tomto návode sa nimi nezaoberáme; podrobnosti nájdete v referenčnej príručke.

Minimálny úryvok jazyka Python na vytvorenie objednávky by vyzeral 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í niektoré údaje, ktoré v objednávke chýbajú, napríklad adresu inštancie obchodníka. Úplné údaje sa nazývajú zmluvné podmienky.

Poznámka

Vyššie uvedená požiadavka zakáže používanie claim tokenov nastavením možnosti create_token na hodnotu false. Ak potrebujete token reklamácie, musíte upraviť kód na zostavenie URI taler://pay/ uvedeného nižšie tak, aby obsahoval token reklamácie.

Po úspešnom POSTe do /private/orders sa vráti JSON s poľom order_id s reťazcom reprezentujúcim ID objednávky. Ak sa vám zobrazí aj token reklamácie, prekontrolujte, či ste požiadavku použili tak, ako je popísané vyššie.

Spolu s inštanciou obchodníka identifikuje ID objednávky jednoznačne objednávku v rámci backendu obchodníka. Pomocou ID objednávky môžete triviálne skonštruovať príslušný URI taler://pay/, ktorý sa musí poskytnúť peňaženke. Nech example.com je názov domény, v ktorej sú dosiahnuteľné verejné koncové body inštancie. Taler pay URI je potom jednoducho taler://pay/example.com/$ORDER_ID/, kde $ORDER_ID musí byť nahradené ID objednávky, ktorá bola vrátená.

URI taler:// môžete umiestniť ako cieľ odkazu na otvorenie peňaženky Taler prostredníctvom schémy taler:// alebo ho môžete umiestniť do kódu QR. Pre webový obchod je však najjednoduchšie jednoducho presmerovať prehliadač na https://example.com/orders/$ORDER_ID. Táto stránka potom spustí peňaženku Taler. Tu backend vygeneruje správnu logiku na spustenie peňaženky, pričom podporuje rôzne typy existujúcich peňaženiek Taler. Namiesto ručnej konštrukcie uvedenej adresy URL je možné ju získať aj kontrolou stavu platby, ako je popísané v nasledujúcej časti.

Pri ručnom zostavovaní tejto adresy URL nezabudnite zadať token nároku (pokiaľ nebol vypnutý) a ak backend beží bez TLS, použite taler+http:// (všimnite si, že posledné uvedené je podporované len peňaženkami spustenými v režime ladenia).

Poznámka

Triviálny spôsob, ako získať správnu payment_redirect_url, je skontrolovať stav platby (pozri nižšie). Ak si teda stále nie ste istí, ako ho skonštruovať, môžete jednoducho požiadať backend, aby to urobil za vás. V produkčnej prevádzke by ste ho však pravdepodobne mali skonštruovať ručne a vyhnúť sa dodatočnej požiadavke na backend.

  1. Kontrola stavu platby a výzva na zaplatenie

Vzhľadom na ID objednávky je možné skontrolovať stav platby pomocou koncového bodu /private/orders/$ORDER_ID. Ak zákazník platbu ešte neukončil, /private/orders/$ORDER_ID poskytne frontendu adresu URL (pod názvom payment_redirect_url), ktorá spustí peňaženku zákazníka na vykonanie platby. V podstate ide o adresu URL https://example.com/orders/$ORDER_ID, o ktorej sme hovorili vyššie.

>>> 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())

Ak je pole order_status v odpovedi paid, nedostanete payment_redirect_url a namiesto toho dostanete informácie o stave platby vrátane:

  • contract_terms: Úplné zmluvné podmienky objednávky.

  • refunded: true, ak bola za tento nákup poskytnutá (prípadne čiastočná) náhrada.

  • refunded_amount: Suma, ktorá bola vrátená

Keď frontend potvrdí, že platba prebehla úspešne, zvyčajne musí spustiť obchodnú logiku pre obchodníka, aby splnil svoje povinnosti vyplývajúce zo zmluvy.

Poznámka

Nemusíte sa neustále pýtať, aby ste si všimli zmeny stavu transakcie objednávky. Koncové body podporujú dlhé dotazovanie, stačí zadať parameter dotazu timeout_ms s údajom, ako dlho chcete čakať na zmenu stavu objednávky na zaplatené.

3.1.3.5. Ďalšie výukové programy#

Ak si chcete pozrieť ďalšie návody, môžete si prezrieť túto stránku alebo navštíviť stránku https://docs.taler.net, kde nájdete najnovšiu dokumentáciu o službách Taler.