Gniazda rozszerzeń
W module - Gniazda rozszerzeń , 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.
| Usługa Gniazd rozszerzeń jest dostępna w katalogu usług dodatkowych (płatnych). W celu jej uruchomienia należy wykupić ją w Moich rozrachunkach . |
W celu śledzenia poprawności działania połączenia z Gniazdem rozszerzeń w module Audyt 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" . |
| 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;
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. Przykładowy komunikat:
{
"additionalData": {},
"clientExternalId": "XSmart",
"contractorExternalId": "XSmart",
"createDate": "2024-10-15T12:35:36.373Z",
"currencyRate": 1,
"deliveryAddress": null,
"deliveryCost": {
"currency": "PLN",
"gross": 12.00,
"metadata": null,
"net": 12.00,
"vat": 0.00
},
"deliveryDate": "2024-10-21T10:42:23.227Z",
"deliveryType": "ADDRESS_DELIVERY",
"id": 63,
"invoiceAddress": null,
"number": null,
"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,
"saleUnitPrice": {
"currency": "PLN",
"gross": 2.56,
"net": 2.08,
"vat": 23
},
"saleUnitsInfo": [
{
"baseUnit": true,
"baseUnitRate": 1,
"clientUnit": true,
"externalId": "szt",
"qty": 5,
"shortcut": "szt",
"unitId": 1061
}
]
}
],
"pickupAddress": null,
"storeDTO": {
"externalId": "T1H",
"id": 1002,
"name": "T1H"
},
"voucherCode": ""
}| 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. |
| Usługa Gniazd rozszerzeń jest dostępna w katalogu usług dodatkowych (płatnych). W celu jej uruchomienia należy wykupić ją w Moich rozrachunkach . |
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 . 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.
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 . 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ń.
