Konfigurátor egyedi bolthoz vagy ERP-hez

Az egyedi bolt vagy ERP olyan, amelyhez nincs kész bővítmény, ezért a fejlesztője köti a konfigurátort a kosárhoz. Minden itteni dolog mögött egyetlen mondat áll: a böngésző által küldött ár soha nem válhat kosárárrá. A szervere előbb ellenőrzi a CutOptimmal.

A CutOptim nem fogad fizetést, és nem üzemeltet boltot; a kosár, a pénztár és a fizetés az Öné marad. Még nincs SDK. A konfigurátor API-referenciája minden útvonalat, hibakódot és korlátot felsorol, egy OpenAPI 3.1 dokumentummal; ez az oldal, a rendelések oldal és a referenciakód lépésről lépésre végigvezet az integráción.

Két kulcs

A publishable key (nyilvános kulcs) az oldalában van a beágyazáshoz. Csak azt teheti, amit egy vásárló, és csak a hozzá felsorolt domainekről.
A secret key (titkos kulcs) a szerveréhez való, és soha nem kerül oldalra. A szolgáltatásnak Authorization: Bearer <key> fejlécben küldi, alapértelmezés szerint a https://cfg.cutoptim.com címre. POST-nál mindig küldjön Content-Type: application/json fejlécet.

1. lépés: az árajánlat ellenőrzése a kosár előtt

Amikor a vevő rendel, az oldala egy cutoptim:order eseményt kap egy árajánlat-tokennel. Küldje el a tokent a szerverének, és onnan:

curl -X POST https://cfg.cutoptim.com/cfg/v1/quote/verify \
  -H "Authorization: Bearer $CFG_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"quoteToken":"<token from the page>"}'

A válasz 200 a {"valid": true, "redeemed": false, "claims": {...}} vagy a {"valid": false, "reason": "..."} tartalommal. Az elutasítás is 200, ezért olvassa a valid mezőt. Az időtúllépést, a 401-et, az 500-at vagy az olvashatatlan törzset kezelje ellenőrizetlenként, és utasítsa vissza a sort. Ezután vesse össze az állításokat a kosársorával: a tenant az Öné, a pénznem a kosáré, a lejárat a jövőben van, és az árajánlat-hash egyenlő az oldala által megjelenített árajánlat hashével. A referenciakód tartalmazza a hash kiszámítását végző függvényt.

A token alakjának, tenantjának és lejáratának helyi ellenőrzése olcsóbb, de nem bizonyíthatja az aláírást, mert az aláírókulcsot nem adjuk ki. Csak előzetes ellenőrzésként használja.

2. lépés: a rendelés ellenőrzése

Az árajánlat ellenőrzése azt mutatja, hogy az ármegállapodás hiteles. Azt nem mutatja, melyik rendelésre gondol a böngésző. Mielőtt rendelésazonosító alapján tárol vagy teljesít, kérje le a szerverén a GET /cfg/v1/orders/{id} hívással és a titkos kulccsal. Visszaadja a terv-hasht, az árajánlat-hasht, az állapotot, a pénznemet és a három összeget másodlagos egységben, személyes adat nélkül. Vesse össze az ellenőrzöttel.

3. lépés: a webhook fogadása

Állítson be egy webhookot a rendelések oldalon leírtak szerint. A fogadója:

a nyers törzset olvassa, mielőtt feldolgozza;
olvassa a CutOptim-Signature fejlécet, t=<unix seconds>,v1=<hex> (a titok forgatása közben két v1 érték is lehet);
újraszámolja a HMAC-SHA256(secret, "<t>.<raw body>") értéket, állandó idejű összehasonlítást végez, és elutasítja a körülbelül öt percnél távolabbi időbélyeget;
a CutOptim-Event-Id eseményazonosítót bármilyen munka előtt lefoglalja, és figyelmen kívül hagyja a már kezelt azonosítót;
figyelmen kívül hagyja az ismeretlen eseménytípusokat, és 2xx-szel válaszol, hogy a küldő ne próbálkozzon feleslegesen.

A fogadótitkot a POST /cfg/v1/admin/webhooks/{id}/secret hívással és a titkos kulccsal kapja meg. A titkokat tartsa a környezetében, soha ne oldalon, tárolóban vagy naplóban.

Referenciakód

Két kicsi, függőségmentes példa mutatja mindhárom lépést. Olvasandó és másolandó kód, nem üzemeltetett szolgáltatás:

Node 18 vagy újabb: cutoptim-verify.mjs és example-server.mjs.
PHP 7.4 vagy újabb: CutOptimVerify.php és example-webhook.php.

A bennük lévő titkok helyőrzők. A példák memóriabeli duplikátumtára csak helyettesítő: éles üzemben a kezelt eseményazonosítókat tartsa az adatbázisában, és az azonosítót ugyanabban a tranzakcióban foglalja le, amelyben a rendelést rögzíti.

Ugyanezek a lépések a pontos kérésekkel és válaszokkal a referenciában vannak: Egyedi bolt vagy ERP.

Kulcsok forgatása

A kulcs vagy a webhooktitok átfedéssel forgatható, így a régi egy megadott ideig tovább működik, amíg az újat telepíti. A webhooktitok forgatása közben a kézbesítés hét napig két v1 aláírást hordoz, és bármelyik elfogadása leállás nélküli váltást tesz lehetővé. Az átfedéses forgatás konzolgombjai még nincsenek megépítve; a konzol kulcsokat tud létrehozni és visszavonni.

Más módok a rendelések fogadására

WooCommerce-hez használja a bővítményt. Ha csak a saját szoftverén belül van szüksége vágási tervekre, beágyazott vevőoldali képernyő nélkül, az az Engine API.

FAQ

Kell bővítmény ahhoz, hogy a konfigurátort a saját boltommal használjam?

Nem. A konfigurátor egy scripttel és egy elemmel ágyazható be, és a szervere három dolgot tesz: a kosár előtt ellenőrzi az árajánlatot, megnézi a hozzá tartozó rendelést, és ellenőrzi az aláírt webhookot. Ez az oldal ezeket írja le, és Node és PHP referenciakódra hivatkozik. A WooCommerce-hez van kész bővítmény; más platformhoz nincs.

Hogyan ellenőrzi a szerverem az árat?

Elküldi az árajánlat-tokent a konfigurátor szolgáltatás POST /cfg/v1/quote/verify végpontjára a titkos kulccsal. A válasz: érvényes-e, és be lett-e már váltva. Ezután összeveti a token állításait a saját kosársorával: tenant, pénznem, lejárat és az árajánlat-hash. A csak helyben végzett ellenőrzés nem bizonyíthatja az aláírást, ezért az árról soha ne ez alapján döntsön.

Felhasználja az árajánlatot az ellenőrzés?

Nem. Az ellenőrzés csak olvasó. Az árajánlatot csak a rendelés leadása használja fel, egyszer. Egy érvényes árajánlat visszajöhet már beváltottként is, ezért mindkét mezőt ellenőrizze.

Honnan tudom, hogy a böngészőből kapott rendelésazonosító az a rendelés, amelyet ellenőriztem?

Kérdezze le a szerverén: a GET /cfg/v1/orders/{id} a titkos kulccsal visszaadja a rendelés terv-hashét, árajánlat-hashét, állapotát és összegeit, soha nem személyes adatot. Vesse össze őket az ellenőrzött árajánlattal. Enélkül egy olcsó, ellenőrzött árajánlat egy másik rendelés azonosítója mellett is elküldhető.

Van SDK vagy OpenAPI-dokumentum?

Nincs SDK és nincs üzemeltetett adapter, de van API-referencia: minden útvonal, hibakód és korlát, egy OpenAPI 3.1 dokumentummal a /configurator/openapi.json címen, amelyet egy klienskód-generátor is el tud olvasni. A referenciafájlok kicsi, függőségmentes Node- és PHP-példák, amelyeket elolvas és átmásol. A Python, a Java és a C# nincs lefedve; az aláírás egyszerű HMAC-SHA256, így bármely nyelven elvégezhető.

Mely konfigurátoresemények érkezhetnek?

Az order.created és az order.status_changed. A konfiguráció által elfogadott egyéb eseménynevek, például az árajánlat- vagy projektesemények, soha nem kerülnek elküldésre. A kézbesítés legalább egyszeri, ezért tartson nyilván a kezelt eseményazonosítókról.