Kupon Plus
EN Naplánovať zapojenie partnera
Naplánovať zapojenie partnera

Pre retailových partnerov

Vaša pokladňa. Jedno volanie.

Čo váš tím potrebuje od vlastníka datasetu a jedno pravidlo, ktoré treba dodržať.

Prvé volanie nepotrebuje token.

Zapojenie vašich systémov do distribúcie voucherov

Ak vás vydavateľ oslovil s predajom svojich voucherov, s vaším technickým tímom alebo dodávateľom pokladníc prejdeme zapojenie do našej služby od nastavenia po spustenie. Kým sa nič nepodpíše, technické rozhovory aj prístup do sandboxu sú zdarma.

Naplánovať zapojenie partnera

Čo dostanete od vlastníka datasetu

  • meno datasetu, prvú časť každej adresy;
  • X-API-TOKEN, ktorý identifikuje vaše konto obchodníka a posiela sa s každým volaním;
  • X-DATA-TOKEN, kľúč, ktorý dešifruje vouchery; posiela sa s volaním, ktoré voucher vydá;
  • ktoré IP adresy vám povolil a či máte pre konto zapnutý denný výkaz;
  • aké hodnoty voucherov dataset drží, číslo ako 5 alebo 0.5, a v akej mene;
  • pri modeloch Advanced a Asymmetric špecifikáciu dešifrovania.

Oba tokeny držte v konfigurácii servera. Do webovej stránky ani mobilnej aplikácie nepatria nikdy, okrem dokumentácie API na tomto webe pre testy v sandboxe.

Najprv ping

ping/200 nepotrebuje token a vráti data.myIP, adresu, ktorú musí vlastník povoliť. ping/400, ping/401 a ping/500 vrátia tento stav, takže spracovanie chýb otestujete ešte predtým, než máte token.

curl -sS https://kupon.plus/api/sandbox/ping/200

Potom prvé skutočné volanie. Najprv v shelli exportujte oba tokeny; riadok funguje tak, ako ho vložíte, a vaše hodnoty sa v ňom nikdy neobjavia.

curl -sS https://kupon.plus/api/sandbox/getVoucherByValue/10 \
  -H "X-API-TOKEN: $X_API_TOKEN" \
  -H "X-DATA-TOKEN: $X_DATA_TOKEN"

Čo API robí

  • vydá jeden voucher danej hodnoty: GET getVoucherByValue/{value} alebo POST s vlastným JSON, napríklad {"TxID": "tx-0001"}, ktorý sa uloží s voucherom;
  • zruší voucher, keď sa predaj stornuje: PUT cancelVoucher/{vid};
  • vráti váš denný výkaz vydaných a zrušených voucherov, ktorý vzniká každú noc medzi 02:00 a 03:00 UTC;
  • odpovie na ping.

Každé volanie odpovedá v tej istej obálke {"error": {"code", "text"}, "data": {}}. Len denný výkaz odpovedá pri úspechu holým poľom JSON a pri chybe obálkou.

Rozhodujte podľa error.code

HTTP 200 nie je voucher. Voucher bol vydaný, len keď je v odpovedi data.voucher a nie je prázdne. Prázdny výsledok príde, keď voucher tejto hodnoty nie je, ale aj keď X-DATA-TOKEN chýba alebo je zlý. Prázdny výsledok sám preto nedokazuje, že je zásoba prázdna: hláška pre pokladníka nesmie tvrdiť „vypredané“.

Niektoré odmietnutia ostávajú pri HTTP 200 a výsledok nesú v error.code: volanie z nepovolenej IP adresy odpovie Unauthorized access (0000). Číslo v zátvorke označuje miesto odmietnutia; uveďte ho podpore.

Kľúč idempotencie neexistuje. Posielajte POST s vlastným ID transakcie; výkaz z nasledujúceho dňa ho obsahuje, takže osirelé vydanie nájdete podľa metadata.TxID a zrušíte cez cancelVoucher/{vid}.

Bezpečnostný model

S vlastníkom datasetu sa dohodnete, koľko bezpečnosti chcete a akú náročnosť implementácie za ňu prijmete. Rozhoduje hodnota kódov, ktoré si vymieňate, a tú posúdite vy sami. Zvolený model potom platí pre celý dataset. Čo od vás každý vyžaduje:

Basic symmetric

bezpečnosť náročnosť implementácie

S každým volaním na vydanie posielate X-DATA-TOKEN a dostanete čitateľný kód. Nič nedešifrujete.

Advanced symmetric

bezpečnosť náročnosť implementácie

Dešifrujete na svojej strane kľúčom, ktorý zdieľate s vlastníkom datasetu.

Asymmetric

bezpečnosť náročnosť implementácie

Vlastníkovi dáte svoj verejný kľúč a dešifrujete súkromným kľúčom. Kupon Plus drží kód len ako šifrovaný text, nikdy kľúč.

Za čo nezodpovedáte

  • žiadna zásoba kódov na vašej strane;
  • žiadna úschova kľúčov v modeli Basic;
  • žiadny prístup do siete vydavateľa a ani on nemá prístup do vašej.

Čo sa pre vás nemení

  • Každý vydavateľ vám dá vlastné meno datasetu a tokeny; zapojenie ostáva rovnaké.

Testy v sandboxe

sandbox je zdieľaný dataset na testy; vouchery vydané v ňom sú testovacie. Aké hodnoty drží, závisí od toho, čo sa doň nahralo, preto sa pri prázdnej odpovedi opýtajte vlastníka. Vo vlastnom datasete je každé volanie ostré.

Otvoriť dokumentáciu API Napíšte nám

Už vás oslovili so zapojením? Tokeny a prístup do sandboxu vám vydá vlastník vášho datasetu; obráťte sa najprv naňho.