Gniazda rozszerzeń

W module - Gniazda rozszerzeń Administracja Integracje zewnętrzne, dostępne są funkcjonalności pozwalające na rozszerzenie dostępnych funkcjonalności Systemu o komunikację z serwisami zewnętrznymi lub rozszerzenie ich za pomocą kodu JavaScript.

Rysunek 1. Widok modułu Gniazda rozszerzeń w Panelu Administracyjnym

Rysunek 2. Dodawanie Gniazda rozszerzeń w Panelu Administracyjnym - przykład

Usługa Gniazd rozszerzeń jest dostępna w katalogu usług dodatkowych (płatnych). Jest ona dostępna w Wariancie MAX abonamentu. Istnieje również możliwość jej wykupienia jako usługi dodatkowej w abonamencie Standard w module Moje rozrachunki Konfiguracja

W celu śledzenia poprawności działania połączenia z Gniazdem rozszerzeń w module Audyt Administracja Narzędzia udostępniono zakładkę Audyt komunikacji przez gniazda rozszerzeń z informacjami o statusach poszczególnych zapytań.

Dobrą praktykę po wprowadzeniu zmian jest odświeżenie cache "Metod dostawy" Narzędzia Indeksacja i cache.

Nie można usunąć Gniazda rozszerzeń aktualnie powiązanego z Metodą dostawy.

W celu skonfigurowania należy dodać Gniazdo rozszerzeń, podając jego Nazwę, wybierając Typ gniazda i Logikę gniazda.

Dostępne są Logiki gniazd:

REST_API - pozwalający na komunikację z serwisami zewnętrznymi ich wykorzystywanie do rozszerzenia funkcjonalności Systemu - patrz: Logika gniazda - RESTAPI;
JavaScript - pozwalający na rozszerzenie funkcjonalności z wykorzystaniem kodu JavaScript - patrz Logika gniazda - JavaScript;

Każdą z tych Logik gniazd można wykorzystać do stworzenia dowolnego Typu gniazd

Dostępne są Typy gniazd:

Koszty dostawy - pozwalające na wyliczanie ogólnych kosztów dla niesystemowych Metod dostawy - patrz: Koszty dostawy;
Dodatkowe koszty dostawy - pozwalające na wyliczanie opłaty dodatkowej do standardowych kosztów wynikających z Metody dostawy - patrz: Dodatkowe koszty dostawy;
Minimalna kwota zamówienia- pozwalające na dynamiczne określenie minimalnej wartości Zamówienia - patrz: Minimalna wartość zamówienia;

Do Gniazda przekazywane będą dane Zamówienia w formacie json.

Przykładowy komunikat:

 {
  "additionalData" : {
    "divisionAttributes" : [ {
      "attribute" : {
        "attributeExternalId" : "KRAJ",
        "attributeId" : 11,
        "attributeName" : "Kraj",
        "type" : "MONO_LINGUAL"
      },
      "values" : [ "PL" ]
    }, {
      "attribute" : {
        "attributeExternalId" : "KRAJOWY",
        "attributeId" : 12,
        "attributeName" : "Krajowy",
        "type" : "BOOLEAN"
      },
      "values" : [ "true" ]
    } ]
  },
  "clientExternalId" : "XSmart",
  "clientLanguage" : "pl",
  "companyUser": true,
  "contractorExternalId" : "XSmart",
  "createDate" : "2024-10-15T12:35:36.373Z",
  "currencyRate" : 1.0,
  "deliveryAddress" : {
    "firstName" : "Jan",
    "lastName" : "Kowalski",
    "phone" : "500100200",
    "firmName" : "Firma Testowa Sp. z o.o.",
    "street" : "ul. Testowa 1",
    "zipCode" : "00-001",
    "city" : "Warszawa"
  },
  "deliveryCost" : {
    "currency" : "PLN",
    "gross" : 12.0,
    "metadata" : null,
    "net" : 12.0,
    "vat" : 0.0
  },
  "deliveryDate" : "2024-10-21T10:42:23.227Z",
  "deliveryType" : "ADDRESS_DELIVERY",
  "deliveryExternalId": "delivery-ext",
  "finalProductsSum" : {
    "currency" : "PLN",
    "gross" : 12.8,
    "metadata" : null,
    "net" : 10.4,
    "vat" : 2.4
  },
  "id" : 63,
  "invoiceAddress" : {
    "firstName" : "Jan",
    "lastName" : "Kowalski",
    "phone" : "500100200",
    "firmName" : "Firma Testowa Sp. z o.o.",
    "street" : "ul. Testowa 1",
    "zipCode" : "00-001",
    "city" : "Warszawa"
  },
  "number" : "ZAM/2024/001",
  "orderCurrency" : "PLN",
  "orderPositions" : [ {
    "additionalData" : {
      "attributes" : [ {
        "attribute" : {
          "attributeExternalId" : null,
          "attributeId" : 3,
          "attributeName" : "Waga opakowania [kg]",
          "type" : "NUMBER"
        },
        "values" : [ "2" ]
      }, {
        "attribute" : {
          "attributeExternalId" : null,
          "attributeId" : 5,
          "attributeName" : "Wysokość opakowania [cm]",
          "type" : "NUMBER"
        },
        "values" : [ "15" ]
      }, {
        "attribute" : {
          "attributeExternalId" : null,
          "attributeId" : 6,
          "attributeName" : "Głębokość opakowania [cm]",
          "type" : "NUMBER"
        },
        "values" : [ "25" ]
      }, {
        "attribute" : {
          "attributeExternalId" : null,
          "attributeId" : 4,
          "attributeName" : "Szerokość opakowania [cm]",
          "type" : "NUMBER"
        },
        "values" : [ "21" ]
      } ],
      "labels" : [ {
        "id" : 1008,
        "name" : "WODA",
        "type" : "CUSTOM"
      } ],
      "mainCategory" : {
        "id" : 5,
        "name" : "WODA"
      },
      "otherCategories" : [ ]
    },
    "id" : 559,
    "offerPositionId" : 21010,
    "ordinalNo" : 1,
    "positionHash" : "1",
    "product" : {
      "externalId" : "XYZ12345/G",
      "productId" : null
    },
    "quantity" : 5.0,
    "saleUnitPrice" : {
      "currency" : "PLN",
      "gross" : 2.56,
      "metadata" : null,
      "net" : 2.08,
      "vat" : 23.0
    },
    "saleUnitsInfo" : [ {
      "baseUnit" : true,
      "baseUnitRate" : 1.0,
      "clientUnit" : true,
      "externalId" : "szt",
      "qty" : 5.0,
      "shortcut" : "szt",
      "unitId" : 1061
    } ]
  } ],
  "pickupAddress" : {
    "firstName" : "Jan",
    "lastName" : "Kowalski",
    "phone" : "500100200",
    "firmName" : "Firma Testowa Sp. z o.o.",
    "street" : "ul. Testowa 1",
    "zipCode" : "00-001",
    "city" : "Warszawa"
  },
  "productsSum" : {
    "currency" : "PLN",
    "gross" : 12.8,
    "metadata" : null,
    "net" : 10.4,
    "vat" : 2.4
  },
  "storeDTO" : {
    "externalId" : "T1H",
    "id" : 1002,
    "name" : "T1H"
  },
  "voucherCode" : ""
}

Logika gniazda - RESTAPI

Aby dodać Gniazdo o logice REST_API- należy:

podać Nazwę;
wybrać Typ gniazda;
wybrać Logikę gniazda - REST_API;
podać Adres URL serwisu zewnętrznego;
podać Metodę HTTP (GET lub POST);

Można również dodać maksymalnie dziesięć Nagłówków składających się z Klucza i Wartości.

Do podanego serwisu przesyłane będą dane Zamówienia w formacie json.

Daty przekazywane są w formacie: yyyy-MM-dd’T’HH:mm:ss.SSSXXX

Atrybuty powiązane z zamawianym Produktem są przekazywane, o ile mają włączoną co najmniej jedną z Widoczności atrybutów: Indeksacja i mapa strony i/lub Porównywarki zewnętrzne.

W celu prawidłowego działania gniazda konieczne jest odesłanie wartości kosztów dostawy:

net - wartość netto;
vat - informacja liczbowa o zastosowanej stawce VAT;
gross - wartość brutto;
currency - trzyliterowy skrót określający walutę, w której podano wartości.

Dodatkowo umożliwiono przetwarzanie komunikatów zwrotnych z metadanymi z komentarzem do naliczanej opłaty/opłaty dodatkowej. Komentarz taki prezentowany będzie w Podsumowaniu zamówienia w Koszyku w Sklepie.

Przykładowy fragment komunikatu zwrotnego, przy korzystaniu z Gniazda rozszerzeń typu Dodatkowe koszty dostawy:

{
  "currency": "PLN",
  "gross": 4.10,
  "metadata": {
    "comment": "Opłata dodatkowa"
  },
  "net": 4.10,
  "vat": 0
}

Logika gniazda - JavaScript

Aby dodać Gniazdo o logice JavaScript- należy:

podać Nazwę;
wybrać Typ gniazda;
wybrać Logikę gniazda - JavaScript;
podać Kod JavaScript;

Funkcja powinna nazywać się "calculate", przyjmować jako parametr obiekt "order" oraz zwracać wynik jako obiekt z wymaganymi polami: currency, gross, net, vat.

Przykładowy Kod JavaScript:

function calculate(order) {

let netVal = 11;
let vatVal = 23;
let grossVal = netVal * (1 + vatVal / 100);

  return {
    currency: order.orderCurrency,
    gross: grossVal,
    net: netVal,
    vat: vatVal,
    metadata: {
        comment: 'Opłata dodatkowa'
    }
  };
}

Przykładowy wynik:

{ "net": 17.8, "vat": 23, "gross": 21.89, "currency": "PLN" }

W przypadkach np. błędnej walidacji danych lub niezgodności parametrów z założeniami należy zwrócić obiekt z wartościami null:

{ net: null, gross: null, currency: null, vat: null }

Do wyliczenia za pomocą Gniazda o typie JavaScript przekazywane są analogiczne dane jak do Gniazd o typie REST API.

Koszty dostawy

Zastosowanie Gniazda rozszerzeń - Koszty dostawy pozwala na wyliczanie Kosztów dostawy zewnętrznie na podstawie przekazywanych danych dla dowolnej Metody dostawy.

Po skonfigurowaniu Gniazda rozszerzeń należy połączyć je z wybraną Metodą dostawy Administracja Konfiguracja. W tym celu dla wybranej własnej Metody dostawy należy w zakładce Koszty dostawy zmienić Typ kosztów dostawy na Zewnętrzny oraz wybrać odpowiednie Gniazdo rozszerzeń w polu Źródło danych.

Rysunek 3. Połączenie Metody dostawy z Gniazdem rozszerzeń - konfiguracja w Panelu Administracyjnym

Dodatkowe koszty dostawy

Zastosowanie Gniazda rozszerzeń - Dodatkowe koszty dostawy pozwala na dodawanie do dowolnej Metody dostawy dodatkowych opłat, które można wyliczyć zewnętrznie na podstawie przekazywanych danych.

Po skonfigurowaniu Gniazda rozszerzeń o typie Dodatkowe koszty dostawy należy połączyć je z wybraną Metodą dostawy Administracja Konfiguracja. W tym celu dla wybranej własnej Metody dostawy należy w zakładce Koszty dostawy dodać w opcji: Dodatkowe koszty dostawy (zewnętrzne) skonfigurowane Gniazdo rozszerzeń.

Rysunek 4. Połączenie Metody dostawy z Gniazdem rozszerzeń - konfiguracja w Panelu Administracyjnym

Rysunek 5. Przykładowy komentarz do kosztów dostawy przekazany przy pomocy Gniazda rozszerzeń o typie Dodatkowe koszty dostawy - widok w Koszyku w Sklepie

Minimalna wartość zamówienia

Zastosowanie Gniazda rozszerzeń pozwala na określenie Minimalnej wartości zamówienia na podstawie przekazywanych danych.

Do Gniazda przesyłane będą dane Zamówienia w formacie json analogicznie jak dla pozostałych typów Gniazd.

W komunikacie zwrotnym przy korzystaniu z Gniazda rozszerzeń typu Minimalna wartość zamówienia:

musi znaleźć się wartość: "minimumOrderValue", czyli Minimalna wartość zamówienia;
może znaleźć się wartość: "currentOrderValue" - gdy zwracana jest wartość "currentOrderValue", zastępuje ona lokalnie wyliczoną wartość Zamówienia, która służy do wyliczenia kwoty brakującej do przekroczenia Minimalnej wartości zamówienia. Może to mieć znaczenie np. gdy próg minimum dotyczy wartości Zamówienia tylko wybranych Produktów;
musi się znaleźć wartość "currency" - czyli waluta, w której przesyłane są wartości "minimumOrderValue" i "currentOrderValue";
może znaleźć się wartość metadanych "comment", czyli komentarz, który będzie wyświetlany jako wyjaśnienie przy kwocie brakującej do przekroczenia Minimalnej wartości zamówienia. Jako komentarz ten można dołączyć komunikat w formie tekstu, który ma być wyświetlany, lub mnemonik 'order.summary.minLogistic.comment.value', którego treścią, tłumaczoną na różne języki dostępne w Sklepie, można zarządzać w Tłumaczeniach interfejsu CMS Edycja treści.

{
    "minimumOrderValue": 100,
    "currentOrderValue": 80,
    "currency": "PLN",
    "metadata": {
        "comment": "Minimalna kwota dotyczy tylko wybranych produktów"
    }
}

Po skonfigurowaniu wyliczana dynamicznie Minimalna wartość zamówienia może zastąpić konfigurowaną w systemie:

ogólną Minimalną wartość zamówienia - która obowiązuje wszystkich Kupujących (lub odpowiednio Kupujących indywidualnych i Kupujących firmowych w przypadku kont typu HYBRID); Minimalną kwotę zamówienia w walucie bazowej można zmieniać w ustawieniach sprzedaży Administracja Konfiguracja Ustawienia sklepu Sprzedaż.
Minimalną wartość zamówienia określaną dla danej Metody dostawy w jej szczegółach w ustawieniu: Strategia minimalnej wartości zamówienia Administracja Konfiguracja Metody dostawy;

Jeśli ustawiona jest ogólna Minimalna kwota zamówienia w walucie bazowej oraz dla wybranej Metody dostawy ustawiono wartość Strategii minimalnej wartości zamówienia, podczas składania Zamówienia pod uwagę będzie brana większa z tych wartości, niezależnie od tego czy wartości te ustawione są w Panelu Administracyjnym czy też wyliczone na podstawie gniazda