Sklep niestandardowy lub ERP to taki, dla którego nie ma gotowej wtyczki, więc Twój programista łączy konfigurator z koszykiem. Zasada stojąca za wszystkim tutaj mieści się w jednym zdaniu: cena przesłana przez przeglądarkę nigdy nie może stać się ceną w koszyku. Najpierw weryfikuje ją Twój serwer w CutOptim.

CutOptim nie pobiera płatności i nie hostuje sklepu; koszyk, finalizacja zamówienia i płatność pozostają po Twojej stronie. Nie ma jeszcze SDK. Referencja API konfiguratora wymienia każdą trasę, każdy kod błędu i każdy limit, z dokumentem OpenAPI 3.1; ta strona, strona o zamówieniach i kod referencyjny prowadzą przez integrację krok po kroku.

Dwa klucze

• Klucz publiczny (publishable key) znajduje się na Twojej stronie w osadzeniu. Może robić tylko to, co robi kupujący, i tylko z domen, które dla niego wymieniono.
• Klucz tajny (secret key) jest dla Twojego serwera i nigdy nie trafia na stronę. Wysyła się go jako Authorization: Bearer <key> do usługi, domyślnie https://cfg.cutoptim.com. Przy POST zawsze wysyłaj Content-Type: application/json.

Krok 1: zweryfikuj wycenę przed koszykiem

Gdy klient zamawia, Twoja strona otrzymuje zdarzenie cutoptim:order z tokenem wyceny. Wyślij token na swój serwer i stamtąd:

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

Odpowiedź to 200 z {"valid": true, "redeemed": false, "claims": {...}} albo {"valid": false, "reason": "..."}. Odmowa to nadal 200, więc czytaj valid. Przekroczenie czasu, 401, 500 lub nieczytelną treść traktuj jako niezweryfikowane i odrzuć pozycję. Następnie porównaj dane (claims) z pozycją koszyka: tenant jest Twój, waluta jest walutą koszyka, termin ważności leży w przyszłości, a hash wyceny jest równy hashowi wyceny, którą wyświetliła Twoja strona. Kod referencyjny zawiera funkcję, która oblicza ten hash.

Lokalne sprawdzenie kształtu tokenu, tenanta i terminu ważności jest tańsze, ale nie może dowieść podpisu, ponieważ klucz podpisujący nie jest wydawany. Używaj go tylko jako wstępnej kontroli.

Krok 2: sprawdź zamówienie

Weryfikacja wyceny pokazuje, że obietnica ceny jest prawdziwa. Nie pokazuje, o które zamówienie chodzi przeglądarce. Zanim zapiszesz zamówienie lub zrealizujesz je według identyfikatora, pobierz je na swoim serwerze przez GET /cfg/v1/orders/{id} z kluczem tajnym. Zwraca ono hash planu, hash wyceny, status, walutę i trzy sumy w najmniejszych jednostkach (minor units), bez danych osobowych. Porównaj je z tym, co zweryfikowałeś.

Krok 3: odbierz webhook

Skonfiguruj webhook zgodnie z opisem na stronie o zamówieniach. Twój odbiorca:

1. odczytuje surową treść przed jej parsowaniem;
2. odczytuje nagłówek CutOptim-Signature, t=<unix seconds>,v1=<hex> (podczas rotacji sekretu mogą być dwie wartości v1);
3. przelicza HMAC-SHA256(secret, "<t>.<raw body>"), porównuje w stałym czasie i odrzuca znacznik czasu odległy o więcej niż około pięciu minut;
4. rezerwuje identyfikator zdarzenia z CutOptim-Event-Id przed wykonaniem jakiejkolwiek pracy i ignoruje identyfikator, który już obsłużono;
5. ignoruje nieznane mu typy zdarzeń i odpowiada 2xx, aby nadawca nie ponawiał na próżno.

Sekret odbiorcy otrzymujesz przez POST /cfg/v1/admin/webhooks/{id}/secret z kluczem tajnym. Sekrety trzymaj w środowisku, nigdy na stronie, w repozytorium ani w logu.

Kod referencyjny

Dwa małe przykłady bez zależności pokazują wszystkie trzy kroki. To kod do przeczytania i skopiowania, nie hostowana usługa:

• Node 18 lub nowszy: cutoptim-verify.mjs i example-server.mjs.
• PHP 7.4 lub nowszy: CutOptimVerify.php i example-webhook.php.

Ich sekrety są symbolami zastępczymi. Magazyn duplikatów w pamięci w przykładach to zastępnik: w produkcji trzymaj obsłużone identyfikatory zdarzeń w swojej bazie danych i rezerwuj identyfikator w tej samej transakcji, która zapisuje zamówienie.

Te same kroki, z dokładnymi żądaniami i odpowiedziami, znajdziesz w referencji: Sklep własny lub ERP.

Rotacja kluczy

Klucz lub sekret webhooka można rotować z nakładaniem się okresów, tak że stary działa jeszcze przez ustalony czas, gdy wdrażasz nowy. Podczas rotacji webhooka dostarczenie niesie dwa podpisy v1 przez siedem dni, a zaakceptowanie któregokolwiek z nich pozwala przełączyć się bez przestoju. Przycisków w konsoli do rotacji z nakładaniem się jeszcze nie zbudowano; konsola potrafi tworzyć i unieważniać klucze.

Inne sposoby odbierania zamówień

Dla WooCommerce użyj wtyczki. Jeśli potrzebujesz tylko planów cięcia wewnątrz własnego oprogramowania, bez osadzonego ekranu klienta, jest to Engine API.