Kasa

Przegląd

Funkcja checkout() tworzy zamówienie z aktualnego koszyka i automatycznie przekierowuje klienta do hostowanej strony kasy Komerza w celu dokończenia płatności.

Funkcja kasy waliduje koszyk, tworzy zamówienie i automatycznie przekierowuje do strony płatności. Nie jest potrzebna ręczna obsługa przekierowania.

Podstawowe użycie

const response = await komerza.checkout(emailAddress, couponCode);

Parametry

string

wymagane

Adres e-mail klienta dla zamówienia. Musi być w prawidłowym formacie e-mail.

string

Opcjonalny kod kuponu/rabatu do zastosowania w zamówieniu. Musi mieć od 3 do 32 znaków, jeśli podany.

Zwraca

Zwraca Promise, które rozwiązuje się do ApiResponse<Order>:

interface ApiResponse<Order> {
  success: boolean; // Czy zamówienie zostało utworzone
  message?: string; // Komunikat błędu w przypadku niepowodzenia
  invalidFields?: Array<{
    // Błędy walidacji jeśli są
    fieldName: string;
    reason: string;
  }>;
  data?: Order; // Szczegóły zamówienia w przypadku sukcesu
}

Jeśli success jest true, przeglądarka automatycznie przekieruje do strony kasy. Odpowiedź jest głównie przydatna do obsługi błędów.

Walidacja

Funkcja kasy przeprowadza walidację przed utworzeniem zamówienia: Walidacja koszyka:

Koszyk nie może być pusty
Wszystkie produkty muszą mieć prawidłowe ID produktu i wariantu

Walidacja e-maila:

Musi być w prawidłowym formacie adresu e-mail

Walidacja kuponu (jeśli podany):

Musi mieć co najmniej 3 znaki
Nie może przekraczać 32 znaków

Prosty przykład

// Obsługa przycisku kasy
async function obsluzKase() {
  const email = document.getElementById("email").value;
  const coupon = document.getElementById("coupon").value;

  try {
    const response = await komerza.checkout(email, coupon);

    // Wykonuje się tylko jeśli kasa się nie powiodła (brak przekierowania)
    if (!response.success) {
      alert(response.message || "Kasa się nie powiodła");
    }
  } catch (error) {
    console.error("Błąd kasy:", error);
    alert("Wystąpił błąd podczas realizacji zamówienia");
  }
}

Pełny przykład z walidacją

<!DOCTYPE html>
<html>
  <head>
    <title>Kasa</title>
    <script src="https://cdn.komerza.com/komerza.min.js"></script>
    <style>
      .error {
        color: red;
        font-size: 14px;
      }
      .field-error {
        border-color: red;
      }
    </style>
  </head>
  <body>
    <div id="checkout-form">
      <h2>Kasa</h2>

      <div id="cart-summary"></div>

      <form onsubmit="handleCheckout(event)">
        <div>
          <label for="email">Adres e-mail *</label>
          <input
            type="email"
            id="email"
            required
            placeholder="twoj@email.com"
          />
          <div id="email-error" class="error"></div>
        </div>

        <div>
          <label for="coupon">Kod kuponu (opcjonalnie)</label>
          <input
            type="text"
            id="coupon"
            placeholder="Wpisz kod kuponu"
            minlength="3"
            maxlength="32"
          />
          <div id="coupon-error" class="error"></div>
        </div>

        <button type="submit" id="checkout-btn">Sfinalizuj zakup</button>
      </form>
    </div>

    <script>
      // Inicjalizacja
      komerza.init("your-store-id");

      // Wyświetl podsumowanie koszyka
      function updateCartSummary() {
        const basket = komerza.getBasket();
        const count = komerza.getBasketItemCount();

        if (count === 0) {
          document.getElementById("cart-summary").innerHTML = `
          <p class="error">Twój koszyk jest pusty</p>
        `;
          document.getElementById("checkout-btn").disabled = true;
          return;
        }

        document.getElementById("cart-summary").innerHTML = `
        <p>${count} produkt(ów) w koszyku</p>
      `;
      }

      // Obsługa kasy
      async function handleCheckout(event) {
        event.preventDefault();

        // Wyczyść poprzednie błędy
        document.getElementById("email-error").textContent = "";
        document.getElementById("coupon-error").textContent = "";
        document.getElementById("email").classList.remove("field-error");
        document.getElementById("coupon").classList.remove("field-error");

        const email = document.getElementById("email").value.trim();
        const coupon = document.getElementById("coupon").value.trim();

        // Podstawowa walidacja po stronie klienta
        if (!email) {
          document.getElementById("email-error").textContent =
            "E-mail jest wymagany";
          return;
        }

        // Wyłącz przycisk i pokaż ładowanie
        const btn = document.getElementById("checkout-btn");
        const originalText = btn.textContent;
        btn.disabled = true;
        btn.textContent = "Przetwarzanie...";

        try {
          // Utwórz kopię zapasową przed kasą
          komerza.createBasketBackup();

          // Spróbuj kasy
          const response = await komerza.checkout(email, coupon || undefined);

          // Jeśli dotarliśmy tutaj, kasa się nie powiodła (brak przekierowania)
          if (!response.success) {
            // Obsłuż błędy walidacji
            if (response.invalidFields) {
              response.invalidFields.forEach((field) => {
                const errorEl = document.getElementById(
                  `${field.fieldName}-error`,
                );
                const inputEl = document.getElementById(field.fieldName);

                if (errorEl) errorEl.textContent = field.reason;
                if (inputEl) inputEl.classList.add("field-error");
              });
            } else {
              // Błąd ogólny
              alert(
                response.message || "Kasa się nie powiodła. Spróbuj ponownie.",
              );
            }

            // Przywróć koszyk z kopii zapasowej
            komerza.restoreBasketFromBackup();
          }
        } catch (error) {
          console.error("Błąd kasy:", error);
          alert("Wystąpił nieoczekiwany błąd. Spróbuj ponownie.");

          // Przywróć koszyk z kopii zapasowej
          komerza.restoreBasketFromBackup();
        } finally {
          // Ponownie włącz przycisk
          btn.disabled = false;
          btn.textContent = originalText;
        }
      }

      // Zainicjuj wyświetlanie
      updateCartSummary();
    </script>
  </body>
</html>

Obsługa błędów

Typowe scenariusze błędów i sposób ich obsługi:

Pusty koszyk

const response = await komerza.checkout(email);

if (!response.success && response.message === "Basket is empty") {
  alert("Dodaj produkty do koszyka przed złożeniem zamówienia");
}

Błędy walidacji

const response = await komerza.checkout(email, coupon);

if (!response.success && response.invalidFields) {
  response.invalidFields.forEach((field) => {
    console.log(`${field.fieldName}: ${field.reason}`);
    // Wyświetl błąd obok odpowiedniego pola formularza
  });
}

Błędy ogólne

try {
  await komerza.checkout(email, coupon);
} catch (error) {
  // Błąd sieci lub inna wyjątek
  console.error("Kasa się nie powiodła:", error);
  alert("Nie można sfinalizować zamówienia. Sprawdź połączenie.");
}

Getting Started

Client Library

Przegląd

Podstawowe użycie

Parametry

Zwraca

Walidacja

Prosty przykład

Pełny przykład z walidacją

Obsługa błędów

Pusty koszyk

Błędy walidacji

Błędy ogólne

​Przegląd

​Podstawowe użycie

​Parametry

​Zwraca

​Walidacja

​Prosty przykład

​Pełny przykład z walidacją

​Obsługa błędów

​Pusty koszyk

​Błędy walidacji

​Błędy ogólne

Przegląd

Podstawowe użycie

Parametry

Zwraca

Walidacja

Prosty przykład

Pełny przykład z walidacją

Obsługa błędów

Pusty koszyk

Błędy walidacji

Błędy ogólne