18 lipca 2017

Przedstawiamy nową dokumentację API Panelu Administracyjnego IAI-Shop.com oraz listę ostatnio wprowadzonych do API zmian

Dokumentacja API Panelu administracyjnego IAI-Shop.com przeszła duże zmiany wizualne, a wraz z nimi dodana została m.in. możliwość wyboru wersji API oraz oglądania różnic pomiędzy wersjami całego API, a także na poziomie poszczególnych bramek oraz ich metod. Pojawiło się również kilka nowych bramek pozwalających zarządzać grupami rabatowymi (DiscountGroups), kartami podarunkowymi (GiftCards), bonami towarowymi (Vouchers), cenami przekreślonymi towarów (ProductsMarketing), zestawami towarów (Bundles), kolekcjami towarów (Collections) oraz metod w bramkach Products, GetProducts, SetProducts, RMA, Orders, GetOrders, AddOrders, a także w Payments, gdzie dodana została m.in. metoda doCashback, dzięki której możliwe jest wykonanie zwrotu środków wpłaconych przez klientów za pomocą systemów płatności obsługujących funkcjonalność Cash back.

Nowy odświeżony wygląd dokumentacji API i możliwość wyboru interesującej nas wersji API

Dokumentacja API Panelu administracyjnego IAI-Shop.com przeszła duże zmiany wizualne, a wraz z nimi dodana została możliwość wyboru wersji całego API. Nowa odsłona prezentując zawsze domyślnie aktualny stan dokumentacji pozwala na sprawdzania zmian zarówno pomiędzy wersjami w całym API, jak i także na poziomie poszczególnych bramek oraz ich metod. Narzędzie to polecamy wszystkim developerom chcącym śledzić na bieżąco wprowadzane przez nas zmiany.

Dokumentacja API - Strona główna


Dokumentacja API - Changelog API

Poniżej przedstawiamy listę zmian wprowadzonych w API Panelu Administracyjnego w ostatnich miesiącach:

API-GetShopsData

Umożliwiliśmy pobieranie z panelu administracyjnego IAI-Shop.com konfiguracji ustawień opcji "Umieść towary gratisowe na fakturach VAT i paragonach" oraz listy dodanych do niego drukarek fiskalnych i drukarek dokumentów

W bramce API-GetShopsData dodaliśmy kilka nowych węzłów:

  • product_free_invoices, który zwraca opcję która została wybrana dla ustawienia Umieść towary gratisowe na fakturach VAT i paragonach znajdującego się w panelu administracyjnym IAI-Shop.com w dziale ADMINISTRACJA na stronie Konfiguracja wydruków i dalej Ustawienia wydruków dokumentów sprzedaży.
  • fiscal_printers, który zwraca listę drukarek fiskalnych dodanych w panelu administracyjnym IAI-Shop.com w dziale ADMINISTRACJA na stronie Konfiguracja wydruków i dalej Ustawienia drukarki fiskalnej
  • printers, który zwraca listę drukarek dokumentów (IAI Printer) dodanych w panelu administracyjnym IAI-Shop.com w dziale ADMINISTRACJA na stronie Konfiguracja wydruków i dalej Ustawienia drukarki dokumentów (IAI Printer)
  • vouchers, który zwraca informację czy sklep korzysta z aktywnych bonów towarowych
  • giftCards, który zwraca informację czy sklep korzysta z aktywnych karty podarunkowych

API-CheckServerLoad

Wszystkie atrybuty, które do tej pory nie były wymagane oznaczono jako wymagane

W bramce API-CheckServerLoad wszystkie atrybuty zostały oznaczone jako wymagane.

Zmiana z OR na AND w mechanizmie wyszukiwarki klientów w API

Dotychczas przy wyszukiwaniu przykładowego klienta "Jan Kowalski" wyniki wyszukiwania zawierały wszystkich Janów i Kowalskich. Obecnie po zmianie logiki wyszukiwania fraz składających się z dwóch i więcej słów, wyniki wyszukiwania będą zawierały tylko klientów o imieniu i nazwisku Jan Kowalski (Jan AND Kowalski) zamiast klientów o imieniu Jan lub nazwisku Kowalski (Jan OR Kowalski).

API-DiscountGroups

Nowa bramka umożliwiająca zarządzanie grupami rabatowymi

Grupy rabatowe można wykorzystywać jak pewnego rodzaju "szablon cen", w którym można określić konkretne ceny dla wskazanych towarów. Grupę rabatową przypisuje się w całości do klienta, zamiast definiować ceny dla każdego klienta osobno, co znacząco zmniejsza ilość potrzebnych wywołań API. Bramka API-DiscountGroups powinna szczególnie zainteresować hurtownie internetowe, ponieważ z wykorzystaniem grup rabatowych można wprowadzić progi cenowe. A dzięki nim, tak posegmentować klientów, aby logujący się klient widział tylko i wyłącznie ceny z jego progu cenowego. Bramka API-DiscountGroups ułatwi Tobie zarządzanie cenami towarów w grupach rabatowych poprzez metody:

  • getDiscountGroups - która pozwala na pobranie informacji o grupach rabatowych dostępnych w panelu administracyjnym
  • addDiscountGroup - umożliwia dodanie nowej grupy rabatowej do panelu administracyjnego. Grupa rabatowa dodaje się domyślnie z ustawieniem "Rabat dla towarów - tak, ale różny dla poszczególnych grup"
  • setProductsToDiscountGroup - umożliwia dodanie towarów do grupy rabatowej i określenie ich ceny w grupie rabatowej. Metoda set nadpisuje dotychczasowe towary w grupie rabatowej
  • editDiscountGroups - umożliwia zmianę nazwy grupy rabatowej
  • deleteDiscountGroups - umożliwia usunięcie grupy rabatowej. Warunkiem wykonania operacji jest brak powiązań danej grupy z żadnym klientem. Aby sprawdzić powiązanych klientów z daną grupą, należy użyć metody getClientsAssignedToDiscountGroup
  • getClientsAssignedToDiscountGroup - zwraca listę identyfikatorów klientów przypisanych do wskazanej grupy rabatowej. Aby nadać klientom grupę rabatową, należy skorzystać z metody setClients w bramce API-Clients

API-GiftCards

Nowa bramka umożliwiająca zarządzanie kartami podarunkowymi

Do API dodaliśmy bramkę API-GiftCards, dzięki której możesz swobodnie tworzyć, edytować oraz zarządzać kartami podarunkowymi w swoim panelu administracyjnym IAI-Shop.com.

Więcej informacji na temat tworzenia i zarządzania kartami podarunkowymi znajdziesz na naszej stronie Karty podarunkowe i bony towarowe w sklepie internetowym. Szczegółowy opis bramki oraz wszystkich jej metod dostępny jest na stronie API-GiftCards.

API-Vouchers

Nowa bramka umożliwiająca zarządzanie bonami towarowymi

Do API dodaliśmy bramkę API-Vouchers, dzięki której możesz swobodnie tworzyć, edytować oraz zarządzać bonami towarówymi w swoim panelu administracyjnym IAI-Shop.com.

Więcej informacji na temat tworzenia i zarządzania bonów towarowych znajdziesz na naszej stronie Karty podarunkowe i bony towarowe w sklepie internetowym. Szczegółowy opis bramki oraz wszystkich jej metod dostępny jest na stronie API-Vouchers.

API-Products

Nowe metody w bramce oraz unikalne nazwy dostępnych w niej atrybutów

Do bramki API-Products dodaliśmy kilka nowych metod:

  • checkDeliveryTime - dzięki której możliwe jest pobieranie informacji o czasie, który jest potrzebny na przygotowanie towaru do wysyłki
  • delete - dzięki której możliwe jest usuwanie towarów z panelu administracyjnego IAI-Shop.com
  • get - dzięki której możliwe jest pobieranie informacji o nieusuniętych produktach znajdujących się w panelu administracyjnym IAI-Shop.com
  • getDescriptions - dzięki której możliwe jest pobieranie danych tekstowych wskazanego towaru, m.in. nazwa towaru, opis długi, opis krótki, metadane.
  • getIds - dzięki której możliwe jest pobieranie informacji o identyfikatorach towarów, identyfikatorach i nazwach rozmiarów na podstawie podanych w żądaniu kodów zewnętrznego systemu towarów
  • insert - dzięki której możliwe jest dodawanie nowych produktów do panelu administracyjnego IAI-Shop.com
  • insertAttachments - dzięki której możliwa jest edycja oraz dodawanie załączników do produktów w panelu administracyjnego IAI-Shop.com
  • insertImages - dzięki której możliwa jest edycja oraz dodawanie zdjęć do produktów w panelu administracyjnego IAI-Shop.com
  • update - dzięki której możliwa jest edycja produktów w panelu administracyjnego IAI-Shop.com
  • updateDescriptions - dzięki której możliwe jest przekazanie danych tekstowych wskazanego towaru, m.in. nazwa towaru, opis długi, opis krótki, metadane

wprowadzając jednocześnie unikalność nazwy wszystkich dostępnych atrybutów.

API-GetProducts

Możliwość pobrania informacji o cenach przekreślonych towarów oraz ich rozmiarów

W bramce API-GetProducts dodane zostały węzły:

  • strikethrough_retail_price
  • strikethrough_wholesale_price

odpowiedzialne za zawracanie informacji o przekreślonych cenach detalicznych i hurtowych towarów jak i ich poszczególnych rozmiarów

API-SetProducts

Możliwość ustawiania cen przekreślonych dla towarów oraz ich rozmiarów

W bramce API-SetProducts dodane zostały węzły:

  • strikethrough_retail_price
  • strikethrough_retail_price_net
  • strikethrough_wholesale_price
  • strikethrough_wholesale_price_net

odpowiedzialne za ustawianie przekreślonych cen detalicznych i hurtowych zarówno dla całych towarów jak ich poszczególnych rozmiarów.

API-ProductsMarketing

Zarządzaj cenami przekreślonymi oraz strefami marketingowymi

Do API dodaliśmy bramkę API-ProductsMarketing, dzięki której możesz swobodnie zarządzać cenami przekreślonymi towarów oraz strefami marketingowymi, w których będą wyświetlane towary.

Więcej informacji na temat nowego sposobu zarządzania cenami przekreślonymi znajdziesz na naszej stronie Swobodne zarządzanie cenami przekreślonymi towarów. Szczegółowy opis bramki oraz wszystkich jej metod dostępny jest na stronie API-ProductsMarketing.

API-Bundles

Twórz zestawy towarów oraz dodawaj do nich składowe, ustawiaj ich ilości lub je z nich usuwaj

Do API dodaliśmy bramkę API-Bundles, dzięki której możesz swobodnie tworzyć zestawy towarów, dodawać do nich składowe, ustawiać im odpowiednie ilości lub je z nich usuwać.

Więcej informacji na temat tworzenia zestawów i zarządzania ich składowymi znajdziesz na naszej stronie Zestawy towarów (konfiguratory). Szczegółowy opis bramki oraz wszystkich jej metod dostępny jest na stronie API-Bundles.

API-Collections

Twórz kolekcje towarów oraz dodawaj do nich składowe, ustawiaj ich ilości lub je z nich usuwaj

Do API dodaliśmy bramkę API-Collections, dzięki której możesz swobodnie tworzyć kolekcje towarów, dodawać do nich składowe, ustawiać im odpowiednie ilości lub je z nich usuwać.

Więcej informacji na temat tworzenia zestawów i zarządzania ich składowymi znajdziesz na naszej stronie Kolekcje towarów (inspiracje, stylebooki). Szczegółowy opis bramki oraz wszystkich jej metod dostępny jest na stronie API-Collections.

API-Rma

Metoda get została rozszerzona o zwracanie informacji o loginie osoby zgłaszającej reklamację oraz nazwie reklamowanego towaru

Do działającej w bramce API-Rma metody get dodano w odpowiedzi dwa atrybuty client_login i product_name odpowiedzialne za zawracanie loginu klienta zgłaszającego reklamację i nazwy reklamowanego towaru oraz dodatkowo usunięto atrybut client_id zwracający identyfikator klienta zgłaszającego reklamację.

API-Orders

Nowe metody w bramce oraz unikalne nazwy dostępnych w niej atrybutów

Do bramki API-Order dodaliśmy kilka nowych metod:

  • changeCourier - dzięki której możliwa jest zmiana kuriera, który ma dostarczyć zamówienie do klienta
  • changeDeliveryAddress - dzięki której możliwa jest zmiana adresu dostawy użytego w zamówieniu w panelu administracyjnym IAI-Shop.com
  • changeShippingCosts - dzięki której możliwa jest zmiana kosztów dostawy w zamówieniu w panelu administracyjnym IAI-Shop.com
  • get - dzięki której możliwe jest pobieranie informacji o zamówieniach znajdujących się w panelu adminiastracyjnym IAI-Shop.com
  • insert - dzięki której możliwe jest dodawanie zamówień detalicznych lub hurtowych do sklepu w panelu administracyjnym IAI-Shop.com
  • setSerialNumbers - dzięki której możliwe jest dodawanie numerów seryjnych do towarów znajdujących się w zamówieniu w panelu administracyjnym IAI-Shop.com
  • update - dzięki której możliwa jest edycja zamówienia (m.in. zmiana towarów w zamówieniu, zmiana statusu zamówienia) w panelu administracyjnym IAI-Shop.com

API-GetOrders

Możliwość pobrania informacji o użytych w zamówieniach bonach towarowych i kartach podarunkowych

Do metody pobierającej informacje o zamówieniach znajdujących się w panelu administracyjnym IAI-Shop.com dodaliśmy dwa parametry voucherNumber oraz giftCardNumber, które zwracają informację o użytych w zamówieniach bonach towarowych oraz kartach podarunkowych.

API-AddOrders

Możliwości oznaczania towaru w zamówieniu jako towaru gratisowego

Do bramki API-AddOrders w węźle products dodaliśmy nowy atrybut product_free dzięki któremu możesz wskazać, że dodawany do zamówienia towar jest towarem gratisowym.

API-Payments

Nowa metoda doCashback do zlecenia zwrotu wpłat

Do bramki API-Payments dodaliśmy nową metodę doCashback, dzięki której możliwe jest wykonanie zwrotu środków wpłaconych przez klientów za pomocą systemów płatności obsługujących funkcjonalność Cash back. Więcej na temat możliwości IAI-Shop w zakresie automatycznego zwracania środków na konto klientów za pomocą panelu administracyjnego Twojego sklepu znajdziesz na stronie Cash back – błyskawiczne wypłaty środków za zamówienia i zwroty przez system płatności.

Umożliwiliśmy zarządzanie wpłatami do zamówień i zwrotów za pomocą tych samych metod

Wpłatami do zamówień i zwrotów możesz już zarządzać za pomocą tych samych metod. W API-Payments służą to tego metody:

  • set
  • get
  • confirm
  • cancel

Aby to było możliwe, musisz w parametrze source_type żądania powyższych metod przekazać odpowiednio: order (dla zamówienia) lub return (dla zwrotu) oraz podać numer płatności, której żądanie dotyczy. Numer płatności składa się z ID numerycznego zamówienia lub zwrotu oraz liczby porządkowej płatności [payment ordinal number], np. 1234-1.

Szczegółowy opis metody doCashback oraz pozostałych metod do zarządzania płatnościami dostępny jest na stronie API-Payments.

Nowe parametry paymentVoucherKey oraz giftCardPIN w metodzie addPayment do opłacania zamówienia za pomocą wskazanego bonu towarowego lub karty podarunkowej

Do metody addPayment dodaliśmy dodatkowe parametry paymentVoucherKey oraz giftCardPIN, dzięki którym możliwe jest dodanie wpłaty z salda konkretnego numeru bonu towarowego lub karty podarunkowej wraz z podaniem jej wymaganego PIN'u.

API-EppDocuments

Metoda get została rozszerzona o możliwości pobierania również dokumentów wpłat i wypłat

Do działającej w bramce API-EppDocuments metody get odpowiedzialnej za pobieranie dokumentów sprzedaży oraz dokumentów magazynowych dodana została możliwość pobierania również dokumentów wpłat i wypłat.

API-OrdersDocuments

Usunięto atrybuty oznaczone jako przestarzałe

W bramce API-OrdersDocuments ze wszystkich dostępnych metod usunięto atrybuty type oraz doc_copy_type oznaczone do tej pory jako DEPRECATED.