Kupon Plus
EN SK Planificați integrarea unui partener
Planificați integrarea unui partener

Pentru partenerii de retail

Casa dumneavoastră de marcat. Un singur apel.

De ce are nevoie echipa dumneavoastră de la proprietarul setului de date și singura regulă pe care trebuie să o respectați.

Primul apel nu necesită token.

Conectarea sistemelor la distribuția de vouchere

Dacă un emitent v-a propus să distribuiți voucherele sale, lucrăm cu echipa dumneavoastră tehnică sau cu furnizorul de case de marcat la conectarea la serviciul nostru, de la configurare până la lansarea în producție. Până la semnarea oricărui acord, discuțiile tehnice și accesul la sandbox sunt gratuite.

Planificați integrarea unui partener

Ce primiți de la proprietarul setului de date

  • numele setului de date (dataset), prima parte a fiecărei adrese;
  • X-API-TOKEN, care identifică contul dumneavoastră de comerciant și însoțește fiecare apel;
  • X-DATA-TOKEN, cheia care decriptează voucherele; însoțește apelul care emite un voucher;
  • ce adrese IP v-a permis și dacă raportul zilnic este activat pentru contul dumneavoastră;
  • ce valori de vouchere conține setul de date, un număr precum 5 sau 0.5, și în ce monedă;
  • pentru modelele Advanced și Asymmetric, specificația de decriptare.

Păstrați ambele tokenuri în configurația serverului. Nu au ce căuta într-o pagină web sau într-o aplicație mobilă, cu excepția documentației API de pe acest site, pentru teste în sandbox.

Apelați mai întâi ping

ping/200 nu necesită token și returnează data.myIP, adresa pe care proprietarul trebuie să o permită. ping/400, ping/401 și ping/500 returnează statusul respectiv, așa că puteți testa tratarea erorilor înainte de a avea un token.

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

Apoi, primul apel real. Exportați mai întâi ambele tokenuri în shell; linia funcționează exact așa cum o lipiți, iar valorile dumneavoastră nu apar niciodată în ea.

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

Ce face API-ul

  • emite un voucher de o anumită valoare: GET getVoucherByValue/{value} sau POST cu propriul JSON, de exemplu {"TxID": "tx-0001"}, stocat împreună cu voucherul;
  • anulează un voucher când vânzarea este stornată: PUT cancelVoucher/{vid};
  • returnează raportul zilnic al voucherelor emise și anulate, generat în fiecare noapte între 02:00 și 03:00 UTC;
  • răspunde la ping.

Fiecare apel răspunde în aceeași structură {"error": {"code", "text"}, "data": {}}. Doar raportul zilnic răspunde la succes cu un simplu array JSON, iar la eroare, în această structură.

Decideți după error.code

HTTP 200 nu înseamnă voucher. Voucherul a fost emis doar dacă data.voucher există și nu este gol. Rezultatul gol apare când nu există voucher de acea valoare, dar și când X-DATA-TOKEN lipsește sau este greșit, deci nu dovedește un stoc gol: mesajul pentru casier nu trebuie să spună „stoc epuizat”.

Unele refuzuri păstrează HTTP 200 și transmit rezultatul în error.code: un apel de pe o adresă IP nepermisă primește Unauthorized access (0000). Numărul din paranteză identifică locul refuzului; comunicați-l echipei de suport.

Nu există cheie de idempotență. Trimiteți POST cu propriul ID de tranzacție; raportul din ziua următoare îl conține, așa că o emitere orfană se găsește după metadata.TxID și se anulează cu cancelVoucher/{vid}.

Modelul de securitate

Împreună cu proprietarul setului de date stabiliți câtă securitate doriți și ce complexitate de implementare acceptați pentru ea. Decide valoarea codurilor pe care le schimbați, iar pe aceasta o apreciați chiar dumneavoastră. Modelul ales se aplică apoi întregului set de date. Ce vă cere fiecare:

Basic symmetric

securitate complexitatea implementării

Trimiteți X-DATA-TOKEN cu fiecare apel de emitere și primiți un cod lizibil. Nu aveți nimic de decriptat.

Advanced symmetric

securitate complexitatea implementării

Decriptați pe partea dumneavoastră, cu o cheie partajată cu proprietarul setului de date.

Asymmetric

securitate complexitatea implementării

Îi dați proprietarului cheia dumneavoastră publică și decriptați cu cheia privată. Kupon Plus păstrează codul doar criptat, niciodată o cheie.

Ce nu intră în responsabilitatea dumneavoastră

  • niciun stoc de coduri pe partea dumneavoastră;
  • nicio păstrare de chei în modelul Basic;
  • niciun acces la rețeaua emitentului și nici al acestuia la a dumneavoastră.

Ce rămâne neschimbat pentru dumneavoastră

  • Fiecare emitent vă oferă propriul nume de set de date și propriile tokenuri; integrarea rămâne aceeași.

Testați în sandbox

sandbox este setul de date comun pentru teste; voucherele emise acolo sunt vouchere de test. Valorile disponibile depind de ce s-a încărcat, așa că întrebați proprietarul dacă un apel nu returnează nimic. În propriul set de date, fiecare apel este real.

Deschideți documentația API Scrieți-ne

Vi s-a cerut deja conectarea? Tokenurile și accesul la sandbox vi le emite proprietarul setului de date; adresați-vă mai întâi lui.