Specyfikacja niestandardowej integracji e-commerce

Niniejszy dokument opisuje, co musi zapewnić niestandardowa implementacja e-commerce, aby mogła być skonfigurowana w polach administracyjnych:

  • „Niestandardowy punkt końcowy klonowania”
  • „Niestandardowy punkt końcowy kategorii”

Ponadto opisuje:

  • Zachowanie automatycznego logowania / SSO
  • Formularz automatycznego wysyłania (ponowne wysłanie koszyka do oprogramowania pośredniczącego)

Zawiera wymagane czasowniki HTTP, parametry, znaczenia parametrów i możliwe wartości, oczekiwane odpowiedzi (sukces i błąd) oraz konkretne przykłady.

1) Niestandardowy punkt końcowy klonowania (cel)
Używany przez oprogramowanie pośredniczące do:

  • Tworzenia nowego zamówienia/sesji w zdalnym sklepie (przepływ „tworzenia”) lub
  • Edycji/wypełniania istniejącego zamówienia/koszyka (przepływ EDYCJI). Punkt końcowy musi zwrócić:
  • Adres URL SSO, który loguje kupującego za pomocą jednorazowego tokena do zdalnej witryny, gdzie użytkownik może zostać przekierowany do koszyka, jeśli jest to przepływ EDYCJI i koszyk jest wypełniony, może zostać przekierowany do wybranego produktu (w przypadku, gdy jest to komunikowane podczas przepływu „tworzenia”), w przeciwnym razie jest przekierowywany na stronę główną

Zalecana ścieżka URL (przykład):

  • POST https://your-store.example.com/api/punchout/clone

Czasownik HTTP

  • POST (obowiązkowe). Użyj treści JSON (application/json). Oprogramowanie pośredniczące wywoła POST.

Treść żądania (JSON)
Pola podstawowe (zawsze obecne)

    • username (string) — nazwa użytkownika w e-commerce użytkownika do sklonowania w celu wygenerowania nowego użytkownika powiązanego z sesją punchout.
    • api_key (string) — klucz API, który powinien odpowiadać kluczowi ustawionemu w Punchout Rocket dla bieżącego e-commerce
    • end_customer_id (integer) — identyfikator klienta końcowego w oprogramowaniu pośredniczącym Punchout Rocket dla e-commerce dla bieżącego żądania punchout
    • session_token (string) — unikalny plik cookie kupującego w przypadku CXML lub unikalny UUID lub podobny w przypadku OCI
    • operation (string) — „create” lub „edit” lub „inspect” w przypadku CXML, „create” w przypadku OCI. W przypadku „edit” lub „inspect” może zostać przekazana lista pozycji koszyka
    • gateway_base_url (string) — adres URL oprogramowania pośredniczącego, do którego koszyk powinien zostać później wysłany

Dodatki specyficzne dla protokołu

  • Jeśli rozstrzygnięty protokół to CXML, mogą zostać dodane następujące dodatkowe pola:

selected_item (object) — identyfikacja produktu, do którego użytkownik powinien zostać przekierowany, opcjonalna w przypadku operacji „create”:

  • supplier_part_id (string) — identyfikator SKU (kodu produktu) w e-commerce (jeśli istnieje)
  • supplier_part_auxiliary_id (string) — identyfikator produktu w e-commerce (jeśli istnieje)

Przykład: json

{  
  „selected_item”:  
  {  
  „supplier_part_id”: „ABC-001”,  
  „supplier_part_auxiliary_id”: „19852”  
  }  
}

cart_items (array) — lista pozycji koszyka do ponownego dodania do koszyka bieżącej sesji. Każda pozycja w cart_items zazwyczaj zawiera:

  • sku (string) — identyfikator SKU (kodu produktu) w e-commerce (jeśli istnieje)
  • product_id (string) — identyfikator produktu w e-commerce (jeśli istnieje)
  • quantity (integer) — ilość pozycji w koszyku
  • price (decimal number with dot as decimal separator) — cena jednostkowa pozycji w koszyku. Należy pamiętać, że zostanie ona zaktualizowana do bieżącej ceny, gdy użytkownik zostanie przekierowany do koszyka
  • description (string) — opis produktu
  • currency (string) — kod waluty ISO 4217

Przykładowy ładunek (tworzenie, CXML, wybrana pozycja obecna)

{
  „username”: „buyer123”,
  „api_key”: „site-api-key-abc”,
  „session_token”: „sess-012345”,
  „operation”: „create”,
  „end_customer_id” : 2,
  „gateway_base_url”: „https://middleware.example.com”,
  „selected_item”: {
  „supplier_part_id”: „X-100”,
  „supplier_part_auxiliary_id”: „19853”
  }
}

Przykładowy ładunek (edycja, CXML, koszyk wypełniony)

{
  „username”: „buyer123”,
  „api_key”: „site-api-key-abc”,
  „session_token”: „sess-67890”,
  „operation”: „edit”,
  „end_customer_id” : 2,
  „gateway_base_url”: „https://middleware.example.com”,
  „cart_items”: [
  {
  „sku”: „ABC-001”,
  „product_id”: „19852”,
  „quantity”: 2,
  „price”: 15.95,
  „description” : „Przykładowy opis”,
  „currency”: „EUR”
  },
  {
  „sku”: „XYZ-002”,
  „product_id”: „19854”,
  „quantity”: 1,
  „price”: 249.00,
  „description” : „Inny przykładowy opis”,
  „currency”: „EUR”
  }
  ]
}

Pomyślne odpowiedzi
Opcja A — Podaj bezpośredni adres URL SSO (JSON) – HTTP 200 – Content-Type: application/json – Treść:

{
  „status”: „ok”,
  „sso_url”: „https://your-store.example.com/sso?token=eyJ…”
}

Zachowanie: Oprogramowanie pośredniczące przekieruje kupującego na sso_url (GET), odeśle go do platformy zakupowej w przypadku CXML lub bezpośrednio w przypadku OCI. Zdalny sklep musi wykorzystać token, zalogować użytkownika, a następnie:

  • Jeśli akcja to „edit” lub „inspect”: zdalna witryna powinna odczytać informacje o koszyku i wypełnić koszyk tak, aby użytkownik wylądował na stronie koszyka w sklepie z już dodanymi pozycjami odpowiadającymi ilościom.
  • Jeśli akcja to „create”: zdalna witryna powinna przekierować do wybranej pozycji, jeśli została przekazana i znaleziona, w przeciwnym razie po prostu wylądować na stronie głównej sklepu

    • Odpowiedzi o błędach
    HTTP 400 — Nieprawidłowe żądanie (brak wymaganych pól) json

    {  
  „status”: „error”,  
  „error_code”: „invalid_request”,  
  „message”: „Brakujące pole: action”  
}

    HTTP 422 — Nie można zbudować SSO (np. brak identyfikatora kupującego) json

    {  
  „status”: „error”,  
  „error_code”: „sso_unavailable”,  
  „message”: „Nie można wygenerować tokena SSO dla tego użytkownika”  
}

    HTTP 500 — Błąd wewnętrzny json

    {  
  „status”: „error”,  
  „error_code”: „internal_error”  
}

    2) Zachowanie Autologin / SSO (jak zalogować kupującego i wypełnić koszyk)
    Odpowiadając adresem sso_url, sklep powinien:

    • Wykorzystać token (aby nie mógł być użyty dwukrotnie) i zalogować kupującego za pomocą sklonowanego użytkownika.
    • Po zalogowaniu:

      • Jeśli akcja to „edit”:

        • Wypełnić koszyk użytkownika dokładnie takimi produktami i ilościami, jakie zostały podane jako pozycje koszyka.
        • Przekierować użytkownika na stronę koszyka/kasy, gdzie może edytować przed finalizacją zamówienia.
      • Jeśli akcja to „create”:

        • Opcjonalnie przekierować do produktu określonego jako wybrana pozycja. Jeśli oprogramowanie pośredniczące nie podało wybranej pozycji lub jeśli nie ma jej już w e-commerce, przekierować użytkownika na stronę główną sklepu.

    Bezpieczeństwo:

  • Używaj tylko HTTPS.
  • Tokeny muszą być jednorazowe.

    • 3) Formularz automatycznego wysyłania (ponowne wysłanie koszyka do oprogramowania pośredniczącego)
    Gdy sklep musi odesłać koszyk/potwierdzenie koszyka do oprogramowania pośredniczącego (po zalogowaniu SSO, dodaniu produktów do koszyka lub edycji), gdy użytkownik kliknie przycisk (zazwyczaj w koszyku), który powinien zainicjować finalizację zamówienia, a zamiast tego w przypadku sklonowanych użytkowników sesji punchout powinien wysłać formularz (content-type: application/x-www-form-urlencoded) na adres URL oprogramowania pośredniczącego przekazany w żądaniu do punktu końcowego klonowania w względnej ścieżce „/start-sso-checkout”. Preferowane UX: sklep wyświetla stronę HTML pokazującą ładowarkę, która automatycznie wysyła ukryty formularz do punktu końcowego oprogramowania pośredniczącego (co sprawia, że SSO jest płynne).

    Pola formularza oczekiwane przez oprogramowanie pośredniczące:

    • session_token (string) — token sesji otrzymany przez e-commerce podczas żądania klonowania
    • end_customer_id (integer) — identyfikacja klienta końcowego otrzymana przez e-commerce podczas żądania klonowania
    • Dla każdej pozycji koszyka powinniśmy mieć dane formularza z indeksem zerowym, na przykład z kluczem products[0][product_id] dla identyfikatora produktu pierwszej pozycji w koszyku. Dla każdej pozycji w koszyku lista pól to
      • sku (string) — identyfikator SKU (kodu produktu) w e-commerce (jeśli istnieje)
      • product_id (string) — identyfikator produktu w e-commerce (jeśli istnieje)
      • description (string) — opis produktu
      • quantity (integer) — ilość produktu w koszyku
      • price (decimal number with dot as decimal separator) — cena jednostkowa
      • currency (string) — kod waluty ISO 4217
      • manufacturer_name (string) — nazwa producenta produktu
      • category_ids (string) — lista, oddzielona przecinkami, identyfikatorów kategorii (liczby całkowite) w e-commerce, do których produkt należy bezpośrednio (zazwyczaj liść w strukturze drzewa kategorii)

    Przykładowy formularz HTML do automatycznego wysyłania (sklep zwraca go do przeglądarki użytkownika i automatycznie wysyła z powrotem do oprogramowania pośredniczącego):

    Zachowanie:

  • Przeglądarka automatycznie wysyła dane do middleware_callback.
  • Oprogramowanie pośredniczące odbiera koszyk i kontynuuje swój przepływ pracy, dodając kody kategorii (np. UNSPSC) obliczone poprzez dopasowanie kategorii e-commerce do ponownie przypisanych kodów kategorii.

    • 4) Niestandardowy punkt końcowy kategorii (cel)
    Używany przez oprogramowanie pośredniczące/administratora do pobierania kategorii ze zdalnego sklepu, aby umożliwić mapowanie ze standardowymi kodami kategorii (np. UNSPSC).

    Zalecana ścieżka URL (przykład):

  • POST https://your-store.example.com/api/punchout/categories

    • Czasownik HTTP

  • POST (obowiązkowe). Dozwolone są opcjonalne parametry zapytania (patrz poniżej).

    • Parametry zapytania

  • api_key (string) — klucz API, który powinien odpowiadać kluczowi ustawionemu w Punchout Rocket dla bieżącego e-commerce

    • Pomyślna odpowiedź
    HTTP 200
    Content-Type: application/json
    Treść:

    {
  „status”: „ok”,
  „categories”:[
  {"id":1345,"name":"Office Supplies","parent_id":0},
  {"id":1847,"name":"Pens","parent_id":1345},
     {"id":2345,"name":"Electronics","parent_id":0}
  ]
}

    Semantyka:

  • id (integer) — unikalny identyfikator (zazwyczaj identyfikator liczby całkowitej kategorii w tabeli kategorii w e-commerce) kategorii, który później oprogramowanie pośredniczące wykorzysta podczas wysyłania koszyka do systemu zakupowego z ponownie przypisanymi kategoriami (np. kod UNSPSC).
  • name (string) — nazwa wyświetlana
  • parent_id (integer) — unikalny identyfikator (zazwyczaj identyfikator liczby całkowitej kategorii w tabeli kategorii w e-commerce) kategorii nadrzędnej bieżącej kategorii. Zazwyczaj „0”, jeśli nie ma nadrzędnej

    • Odpowiedzi o błędach:

  • HTTP 400 — nieprawidłowe zapytanie
  • HTTP 500 — błąd wewnętrzny

    • Przykładowe żądanie: GET /api/punchout/categories?api_key=site-api-key-abc

    Przykładowa odpowiedź:

    {
  „status”: „ok”,
  „categories”:[
  {"id":1345,"name":"Office Supplies","parent_id":0},
  {"id":1847,"name":"Pens","parent_id":1345},
     {"id":2345,"name":"Electronics","parent_id":0}
  ]
}

    5) Uwagi i wskazówki dotyczące implementacji

  • Zawsze używaj HTTPS.
  • Używaj jednorazowych tokenów SSO.
  • Podczas wysyłania pozycji koszyka zachowaj kolejność indeksów (sku[], product_id[], quantity[], unit_price[], extended_price[], categories[]). Oprogramowanie pośredniczące będzie parować pozycje według indeksu.