Megrendelések létrehozása

3.1.3. Megrendelések létrehozása#

Ez az oldal tartalmazza az összes dokumentációt a videós bemutatóhoz, amely egy egyszerű megrendelés létrehozását magyarázza el az API-n keresztül, és ellenőrzi annak státuszát.

3.1.3.1. Videó#

3.1.3.2. Követelmények#

Ehhez az oktatósorozathoz szükséges:

  • Taler kereskedői backend
    Ha segítségre van szüksége a kereskedői háttértár első használatához, megnézheti a Taler kereskedő bevezetés bemutatót.
  • Egy Taler pénztárca példány
    A beállítási utasítások a https://wallet.taler.net oldalon találhatók.
  • REST API-kezelő szoftver vagy releváns programozási ismeretek
    Ebben a videósorozatban az Insomnia ingyenes szoftvert fogjuk használni, amely letölthető a https://insomnia.rest weboldalról.

3.1.3.3. Demo backend értesítés#

Ehhez a bemutatóhoz használhatja saját kereskedői háttérszolgáltatását vagy a https://backend.demo.taler.net/instances/sandbox/ oldalon található online bemutató szolgáltatást.

3.1.3.4. Kereskedői fizetés feldolgozása#

  1. Fizetési megbízás létrehozása

A Talerben a fizetések egy megbízás körül forognak, amely egy gépileg olvasható leírása annak az üzleti tranzakciónak, amelyre a fizetést teljesíteni kell. Mielőtt kereskedőként elfogadna egy Taler-fizetést, létre kell hoznia egy ilyen megbízást.

Ez egy JSON objektum POSTolásával történik a backend /private/orders API végpontjára. A rendelés mezőn belül legalább a következő mezőket kell megadni:

  • összeg: A fizetendő összeg, egy karakterlánc formájában, a CURRENCY:DECIMAL_VALUE formátumban, például EUR:10 10 euróért vagy KUDOS:1.5 1.5 KUDOS-ért.

  • „Összefoglaló”: Ember által olvasható összefoglaló arról, hogy miről szól a fizetés. Az összefoglalónak elég rövidnek kell lennie ahhoz, hogy beleférjen a címekbe, bár nincs szigorú korlát.

  • fulfillment_url: URL, amely a fizetés befejezése után jelenik meg. Digitális áruk esetében ennek egy olyan oldalnak kell lennie, amely megjeleníti a megvásárolt terméket. Sikeres fizetés esetén a pénztárca automatikusan hozzáadja a order_id lekérdezési paraméterként, valamint a session_sig a munkamenethez kötött fizetések esetén (lásd alább).

A megrendeléseknek több mezője is lehet, lásd a A Taler megrendelés formátuma. A megrendelés POSTolásakor további részleteket is megadhat, például a visszatérítés időtartamának felülbírálását és a készletkezelésre vonatkozó utasításokat. Ezekre ritkán van szükség, és ebben a bemutatóban nem tárgyaljuk őket; a részletekért lásd a Hivatkozási kézikönyv.

Egy minimális Python részlet egy rendelés létrehozásához így nézne ki:

>>> 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]>

A backend kitölti a megrendelésből hiányzó néhány adatot, például a kereskedői példány címét. A teljes részleteket szerződési feltételeknek nevezzük.

Megjegyzés

A fenti kérés letiltja az igénylési tokenek használatát a create_token opció false értékre állításával. Ha igénylési tokenekre van szükség, akkor az alábbiakban megadott taler://pay/ URI kódot úgy kell módosítani, hogy az tartalmazza az igénylési tokent.

Miután sikeresen POST```oltunk a ``/private/orders-be, egy JSON-t kapunk vissza, amely csak egy order_id mezőt tartalmaz a rendelés azonosítóját jelző karakterlánccal. Ha egy igénylési tokent is kap, kérjük, ellenőrizze, hogy a fent leírtak szerint használta-e a kérést.

A kereskedő „instancia” azonosítójával együtt a rendelés azonosítója egyedileg azonosítja a rendelést a kereskedői háttértárban. A rendelés azonosítójának felhasználásával triviálisan meg lehet alkotni a megfelelő taler://pay/ URI-t, amelyet a pénztárcának kell megadni. Legyen example.com az a tartománynév, ahol a példány nyilvános végpontjai elérhetőek. A Taler pay URI ekkor egyszerűen taler://pay/example.com/$ORDER_ID/`, ahol a $ORDER_ID-t a visszaküldött rendelés azonosítójával kell helyettesíteni.

A taler:// URI-t egy link célpontjaként használhatja a Taler tárca megnyitására a taler:// sémán keresztül, vagy egy QR-kódba helyezheti. Egy webshop esetében azonban a legegyszerűbb, ha egyszerűen átirányítja a böngészőt a https://example.com/orders/$ORDER_ID címre. Ez az oldal ezután elindítja a Taler pénztárcát. Itt a backend generálja a megfelelő logikát a tárca kiváltásához, támogatva a létező különböző típusú Taler tárcákat. Ahelyett, hogy a fenti URL-t kézzel szerkesztenénk, a fizetési státusz ellenőrzése révén is megkaphatjuk, ahogyan azt a következő szakaszban leírtuk.

Ha kézzel állítod össze ezt az URL-t, győződj meg róla, hogy megadod az igénylési tokent (hacsak nem tiltottad le), és ha a háttértár TLS nélkül fut, akkor használd a taler+http:// (vedd figyelembe, hogy ez utóbbit csak a debug módban futó pénztárcák támogatják).

Megjegyzés

A helyes payment_redirect_url elérésének triviális módja a fizetés státuszának ellenőrzése (lásd alább). Ha tehát még mindig bizonytalan vagy abban, hogyan kell ezt megkonstruálni, egyszerűen megkérheted a backendet, hogy tegye meg helyetted. Termelésben azonban valószínűleg kézzel kell megkonstruálnod, és elkerülni a backendhez intézett extra kérést.

  1. Fizetési állapot ellenőrzése és fizetési felszólítás

A rendelés azonosítójának megadásával a fizetés állapota ellenőrizhető a /private/orders/$ORDER_ID végponttal. Ha a fizetést még nem fejezte be a vásárló, a /private/orders/$ORDER_ID egy URL-t ad a frontendnek (payment_redirect_url néven), amely elindítja a vásárló pénztárcáját a fizetés végrehajtására. Ez lényegében a fentebb tárgyalt https://example.com/orders/$ORDER_ID URL.

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

Ha a „order_status” mező a válaszban „paid”, akkor nem a „payment_redirect_url”-t kapja meg, hanem a fizetés státuszára vonatkozó információkat, beleértve:

  • contract_terms: A megrendelés teljes szerződési feltételei.

  • refunded: true, ha (esetleg részleges) visszatérítés történt a vásárlásra.

  • refunded_amount: Visszatérített összeg

Miután a frontend megerősítette, hogy a fizetés sikeres volt, általában a kereskedőnek el kell indítania az üzleti logikát, hogy teljesítse a kereskedő szerződéses kötelezettségeit.

Megjegyzés

Nem kell folyamatosan lekérdezni, hogy észrevegye a megrendelés tranzakciós státuszának változásait. A végpontok támogatják a hosszú lekérdezést, egyszerűen adjuk meg a timeout_ms lekérdezési paramétert, amelyben megadjuk, hogy legfeljebb mennyi ideig szeretnénk várni, amíg a megrendelés státusza paid-re változik.

3.1.3.5. További útmutatók#

További oktatóanyagok megtekintéséhez böngészhet ezen az oldalon, vagy a https://docs.taler.net oldalon a Taler szolgáltatásokról szóló legfrissebb dokumentációért.