Konfigurator za vlastitu trgovinu ili ERP

Vlastita trgovina ili ERP je ona za koju ne postoji gotov dodatak, pa vaš razvojni programer povezuje konfigurator s košaricom. Pravilo iza svega ovdje stane u jednu rečenicu: cijena koju je poslao preglednik nikada ne smije postati cijena u košarici. Vaš poslužitelj je prvo provjerava kod CutOptima.

CutOptim ne naplaćuje plaćanje i ne hostira trgovinu; košarica, naplata i plaćanje ostaju vaši. Još ne postoji SDK. API referenca konfiguratora navodi svaku rutu, kôd pogreške i ograničenje, s OpenAPI 3.1 dokumentom; ova stranica, stranica o narudžbama i referentni kod vode kroz integraciju korak po korak.

Dva ključa

Javni ključ (publishable key) nalazi se na vašoj stranici za ugradnju. Može činiti samo ono što čini kupac i to samo s domena koje ste za njega naveli.
Tajni ključ (secret key) je za vaš poslužitelj i nikada se ne stavlja na stranicu. Šalje se kao Authorization: Bearer <key> usluzi, prema zadanim postavkama https://cfg.cutoptim.com. Uz POST uvijek šaljite Content-Type: application/json.

Korak 1: provjerite ponudu prije košarice

Kad kupac naruči, vaša stranica prima događaj cutoptim:order s tokenom ponude. Pošaljite token svom poslužitelju i odande:

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>"}'

Odgovor je 200 s {"valid": true, "redeemed": false, "claims": {...}} ili {"valid": false, "reason": "..."}. Odbijanje je i dalje 200, pa čitajte valid. Istek vremena, 401, 500 ili nečitljivo tijelo tretirajte kao neprovjereno i odbijte stavku. Zatim usporedite tvrdnje sa svojom stavkom košarice: tenant je vaš, valuta je valuta košarice, istek je u budućnosti, a hash ponude jednak je hashu ponude koju je vaša stranica prikazala. Referentni kod uključuje funkciju koja izračunava taj hash.

Lokalna provjera oblika tokena, tenanta i isteka jeftinija je, ali ne može dokazati potpis, jer se ključ za potpisivanje ne izdaje. Koristite je samo kao prethodnu provjeru.

Korak 2: provjerite narudžbu

Provjera ponude pokazuje da je obećanje cijene autentično. Ne pokazuje koju narudžbu preglednik misli. Prije nego što pohranite ili ispunite narudžbu prema id-ju, dohvatite je na svom poslužitelju s GET /cfg/v1/orders/{id} i svojim tajnim ključem. Vraća hash plana, hash ponude, status, valutu i tri ukupna iznosa u manjim jedinicama, bez osobnih podataka. Usporedite ih s onim što ste provjerili.

Korak 3: primite webhook

Konfigurirajte webhook kako je opisano na stranici o narudžbama. Vaš primatelj:

čita sirovo tijelo prije parsiranja;
čita zaglavlje CutOptim-Signature, t=<unix seconds>,v1=<hex> (dok se tajna rotira, mogu postojati dvije vrijednosti v1);
ponovno izračunava HMAC-SHA256(secret, "<t>.<raw body>"), uspoređuje u konstantnom vremenu i odbija vremensku oznaku udaljenu više od otprilike pet minuta;
preuzima id događaja iz CutOptim-Event-Id prije bilo kakvog posla i zanemaruje id koji je već obradio;
zanemaruje vrste događaja koje ne poznaje i odgovara s 2xx, kako pošiljatelj ne bi uzalud ponavljao slanje.

Tajnu primatelja dobivate s POST /cfg/v1/admin/webhooks/{id}/secret i svojim tajnim ključem. Tajne držite u svom okruženju, nikada na stranici, u repozitoriju ili dnevniku.

Referentni kod

Dva mala primjera bez ovisnosti prikazuju sva tri koraka. To je kod za čitanje i kopiranje, a ne hostirana usluga:

Node 18 ili noviji: cutoptim-verify.mjs i example-server.mjs.
PHP 7.4 ili noviji: CutOptimVerify.php i example-webhook.php.

Njihove tajne su rezervirana mjesta. Pohrana duplikata u memoriji u primjerima je zamjena: u produkciji čuvajte obrađene id-jeve događaja u svojoj bazi i preuzimajte id u istoj transakciji koja bilježi narudžbu.

Isti koraci, s točnim zahtjevima i odgovorima, nalaze se u referenci: Vlastita trgovina ili ERP.

Rotacija ključeva

Ključ ili tajna webhooka mogu se rotirati s preklapanjem, pa stari nastavlja raditi određeno vrijeme dok postavljate novi. Tijekom rotacije webhooka isporuka nosi dva potpisa v1 sedam dana, a prihvaćanje bilo kojeg od njih omogućuje prelazak bez zastoja. Gumbi u konzoli za rotaciju s preklapanjem još nisu izgrađeni; konzola može stvarati i opozivati ključeve.

Drugi načini primanja narudžbi

Za WooCommerce koristite dodatak. Ako vam trebaju samo planovi rezanja unutar vlastitog softvera, bez ugrađenog zaslona za kupca, to je Engine API.

FAQ

Trebam li dodatak za korištenje konfiguratora s vlastitom trgovinom?

Ne. Konfigurator se ugrađuje skriptom i elementom, a vaš poslužitelj radi tri stvari: provjerava ponudu prije košarice, provjerava narudžbu kojoj pripada i provjerava potpisani webhook. Ova stranica ih opisuje i povezuje referentni kod za Node i PHP. WooCommerce ima gotov dodatak; nijedna druga platforma nema.

Kako moj poslužitelj provjerava cijenu?

Šalje token ponude na POST /cfg/v1/quote/verify na usluzi konfiguratora, sa svojim tajnim ključem. Odgovor kaže je li valjana i je li već iskorištena. Zatim uspoređuje tvrdnje u tokenu sa svojom stavkom košarice: tenant, valutu, istek i hash ponude. Provjera obavljena samo lokalno ne može dokazati potpis, pa nikada na njoj ne odlučujte o cijeni.

Troši li provjera ponude tu ponudu?

Ne. Provjera je samo za čitanje. Ponudu jednom troši tek zaprimanje narudžbe. Valjana ponuda može se vratiti kao već iskorištena, pa provjerite oba polja.

Kako znam da je id narudžbe iz preglednika ona narudžba koju sam provjerio?

Potražite je na svom poslužitelju: GET /cfg/v1/orders/{id} s tajnim ključem vraća hash plana, hash ponude, status i ukupne iznose te narudžbe, nikada osobne podatke. Usporedite ih s provjerenom ponudom. Bez toga bi se jeftina provjerena ponuda mogla poslati uz id druge narudžbe.

Postoji li SDK ili OpenAPI dokument?

Nema SDK-a ni hostiranog adaptera, ali postoji API referenca: svaka ruta, kôd pogreške i ograničenje, s OpenAPI 3.1 dokumentom na /configurator/openapi.json koji može pročitati generator klijenata. Referentne datoteke su mali primjeri bez ovisnosti u Nodeu i PHP-u koje čitate i kopirate. Python, Java i C# nisu pokriveni; potpis je običan HMAC-SHA256, pa ga može izračunati bilo koji jezik.

Koje događaje konfiguratora mogu primati?

order.created i order.status_changed. Ostali nazivi događaja koje konfiguracija prihvaća, poput događaja ponude ili projekta, nikada se ne šalju. Isporuka se događa barem jednom, pa vodite evidenciju id-jeva događaja koje ste obradili.