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 backendHa 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ányA 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 ismeretekEbben 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#
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, aCURRENCY:DECIMAL_VALUE
formátumban, példáulEUR:10
10 euróért vagyKUDOS: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 aorder_id
lekérdezési paraméterként, valamint asession_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.
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.