Configurator pentru magazin propriu sau ERP

Un magazin propriu sau un ERP este unul pentru care nu există plug-in gata făcut, deci dezvoltatorul tău conectează Configuratorul la coș. Regula din spatele a tot ce urmează este o singură propoziție: un preț trimis de browser nu trebuie să devină niciodată preț de coș. Serverul tău îl verifică mai întâi cu CutOptim.

CutOptim nu încasează plăți și nu găzduiește niciun magazin; coșul, finalizarea comenzii și plata rămân ale tale. Nu există încă SDK. Referința API a Configuratorului listează fiecare rută, cod de eroare și limită, cu un document OpenAPI 3.1; această pagină, pagina despre comenzi și codul de referință te ghidează prin integrare pas cu pas.

Două chei

Cheia publicabilă (publishable key) stă în pagina ta pentru integrare. Poate face doar ceea ce face un cumpărător și doar de pe domeniile pe care le-ai listat pentru ea.
Cheia secretă (secret key) este pentru serverul tău și nu este pusă niciodată într-o pagină. Se trimite ca Authorization: Bearer <key> către serviciu, implicit https://cfg.cutoptim.com. Trimite întotdeauna Content-Type: application/json la un POST.

Pasul 1: verifică oferta înainte de coș

Când clientul comandă, pagina ta primește un eveniment cutoptim:order cu un token de ofertă. Trimite tokenul la serverul tău și de acolo:

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

Răspunsul este 200 cu {"valid": true, "redeemed": false, "claims": {...}} sau {"valid": false, "reason": "..."}. Un refuz este tot un 200, deci citește valid. Tratează o expirare a timpului, un 401, un 500 sau un corp ilizibil ca neverificat și refuză linia. Apoi compară afirmațiile cu linia ta de coș: tenant-ul este al tău, moneda este cea a coșului, expirarea este în viitor, iar hash-ul ofertei este egal cu hash-ul ofertei afișate de pagina ta. Codul de referință include funcția care calculează acel hash.

O verificare locală a formei tokenului, a tenant-ului și a expirării este mai ieftină, dar nu poate dovedi semnătura, deoarece cheia de semnare nu este dată altora. Folosește-o doar ca pre-verificare.

Pasul 2: verifică comanda

Verificarea ofertei arată că promisiunea de preț este autentică. Nu arată la ce comandă se referă browserul. Înainte de a stoca sau de a onora după un id de comandă, preia-l pe serverul tău cu GET /cfg/v1/orders/{id} și cu cheia ta secretă. Returnează hash-ul planului, hash-ul ofertei, starea, moneda și cele trei totaluri în unități minore, fără date personale. Compară-le cu ceea ce ai verificat.

Pasul 3: primește webhook-ul

Configurează un webhook așa cum este descris pe pagina despre comenzi. Receptorul tău:

citește corpul brut înainte de a-l interpreta;
citește antetul CutOptim-Signature, t=<unix seconds>,v1=<hex> (pot exista două valori v1 în timp ce un secret este rotit);
recalculează HMAC-SHA256(secret, "<t>.<raw body>"), compară în timp constant și refuză un marcaj de timp aflat la mai mult de aproximativ cinci minute distanță;
revendică id-ul evenimentului din CutOptim-Event-Id înainte de a face orice lucru și ignoră un id pe care l-a tratat deja;
ignoră tipurile de evenimente pe care nu le cunoaște și răspunde 2xx, pentru ca expeditorul să nu reîncerce degeaba.

Obții secretul receptorului cu POST /cfg/v1/admin/webhooks/{id}/secret și cheia ta secretă. Păstrează secretele în mediul tău, niciodată într-o pagină, într-un depozit de cod sau într-un jurnal.

Cod de referință

Două exemple mici, fără dependențe, arată toți cei trei pași. Sunt cod de citit și de copiat, nu un serviciu găzduit:

Node 18 sau mai nou: cutoptim-verify.mjs și example-server.mjs.
PHP 7.4 sau mai nou: CutOptimVerify.php și example-webhook.php.

Secretele lor sunt substituenți. Stocul de duplicate din memorie din exemple este un înlocuitor: în producție, păstrează id-urile de eveniment tratate în baza ta de date și revendică un id în aceeași tranzacție care înregistrează comanda.

Aceiași pași, cu cererile și răspunsurile exacte, sunt în referință: Magazin personalizat sau ERP.

Rotirea cheilor

O cheie sau un secret de webhook poate fi rotit cu suprapunere, astfel încât cel vechi continuă să funcționeze o perioadă stabilită, cât timp îl implementezi pe cel nou. În timpul unei rotiri de webhook, o livrare poartă două semnături v1 timp de șapte zile, iar acceptarea oricăreia dintre ele îți permite să treci fără întrerupere. Butoanele din consolă pentru rotirea cu suprapunere nu sunt încă construite; consola poate crea și revoca chei.

Alte moduri de a primi comenzi

Pentru WooCommerce folosește plug-in-ul. Dacă ai nevoie doar de planuri de tăiere în propriul software, fără un ecran integrat pentru client, aceasta este Engine API.

FAQ

Am nevoie de un plug-in pentru a folosi Configuratorul cu propriul meu magazin?

Nu. Configuratorul se integrează cu un script și un element, iar serverul tău face trei lucruri: verifică oferta înainte de coș, verifică comanda de care aparține și verifică webhook-ul semnat. Această pagină le descrie și trimite la cod de referință în Node și PHP. WooCommerce are un plug-in gata făcut; nicio altă platformă nu are.

Cum verifică serverul meu un preț?

Trimite tokenul ofertei la POST /cfg/v1/quote/verify pe serviciul Configurator, cu cheia ta secretă. Răspunsul spune dacă este validă sau nu și dacă a fost deja răscumpărată (redeemed). Apoi compară afirmațiile din token cu propria linie de coș: tenant, monedă, expirare și hash-ul ofertei. O verificare făcută doar local nu poate dovedi semnătura, deci nu decide niciodată un preț pe baza ei.

Consumă verificarea unei oferte oferta?

Nu. Verificarea este doar pentru citire. Doar plasarea comenzii consumă oferta, o singură dată. O ofertă validă poate reveni ca deja răscumpărată, deci verifică ambele câmpuri.

Cum știu că un id de comandă venit din browser este comanda pe care am verificat-o?

Caută-l pe serverul tău: GET /cfg/v1/orders/{id} cu cheia secretă returnează hash-ul planului, hash-ul ofertei, starea și totalurile acelei comenzi, niciodată date personale. Compară-le cu oferta verificată. Fără aceasta, o ofertă ieftină verificată ar putea fi trimisă alături de id-ul unei alte comenzi.

Există un SDK sau un document OpenAPI?

Nu există SDK și nici adaptor găzduit, dar există o referință API: fiecare rută, cod de eroare și limită, cu un document OpenAPI 3.1 la /configurator/openapi.json pe care îl poate citi un generator de clienți. Fișierele de referință sunt exemple mici, fără dependențe, în Node și PHP, pe care le citești și le copiezi. Python, Java și C# nu sunt acoperite; semnătura este un HMAC-SHA256 simplu, deci orice limbaj o poate face.

Ce evenimente ale Configuratorului pot primi?

order.created și order.status_changed. Alte nume de evenimente pe care le acceptă configurația, precum evenimentele de ofertă sau de proiect, nu sunt trimise niciodată. Livrarea este cel puțin o dată, deci păstrează o evidență a id-urilor de eveniment pe care le-ai tratat.