Nowe API Admin 3 - w pełni RESTowe, przygotowane do integracji no-code, z nową dokumentacją i wsparciem dla developerów

Prezentujemy nowe API Admin 3 w IdoSell. Jest ono w pełni RESTowe, przygotowane do integracji no-code, z nową dokumentacją i wsparciem dla developerów. Sprawdź, co się zmieniło.

IdoSell to pierwszy system SaaS w Polsce, który postawił na Otwarty SaaS, co oznacza, że każdy developer może samodzielnie rozszerzać system IdoSell bez limitów, opłat i formalności.

Najpopularniejszym API IdoSell jest tzw. API Admin, które umożliwia sterowanie panelem administracyjnym przez zewnętrzne programy np. automatyzujące operacje lub pobierające duże ilości informacji. Dotychczasowe API było oparte natywnie o protokół SOAP. Miało już kilka lat i powstało na długo przed pojawieniem się aktualnych potrzeb i standardów, w tym łatwego integrowania przez np. systemy no-code i low-code. Dlatego z dumą prezentujemy nowe, w pełni RESTowe, wersjonowane API Admin, oznaczone numerem 3.

Przez lata rozbudowywaliśmy API o kolejne elementy. To sprawiło, że wymagało ono lepszej dokumentacji i uspójnienia różnych elementów tj. zwracanie kodów błędów czy uwierzytelniania. Jednocześnie zdawaliśmy sobie sprawę, że zbyt wielka rewolucja wygeneruje mnóstwo potencjalnych problemów ze stabilnością oraz będzie wymagała znacznych inwestycji ze strony sprzedawców na przepisanie aplikacji. Mając jasno zdefiniowane cele, rozpoczęliśmy prace nad API Admin 3, które będą kontynuowane etapami w najbliższych miesiącach. Przyniosą one mnóstwo nowości dla developerów oraz merchantów.

Co nowego w API 3?

Najbardziej widoczną zmianą w API Admin 3 jest oparcie o standard REST, który zastąpił SOAP. W czasach, gdy tworzyliśmy API Admin 2, SOAP wydawał się najlepszym standardem. Dzisiaj ważniejsza jest wygoda integracji, niż formalna struktura danych. REST jest najpopularniejszym standardem, w który wpisaliśmy się i my. Nowe API Admin 3 będzie w pełni RESTowe. Poszliśmy nawet dalej i przygotowaliśmy natywne wsparcie pod obsługę integracji no-code / low-code np. przez systemy takie jak Zapier i Make.com. Z systemami tymi planujemy dodatkowo oficjalną integrację już w niedalekiej przyszłości.

Chcieliśmy, żeby dokumentacja API 3 możliwie czytelnie wyjaśniała, jak korzystać z poszczególnych metod. Dlatego stworzyliśmy kompletnie nową stronę dokumentacji API. Zawiera ona także nowy generator kodu wywołań API w różnych językach programowania. Pozwala również na testowanie wywołań API bezpośrednio ze strony dokumentacji np. danej bramki.

Nową dokumentację znajdziesz na stronie https://idosell.readme.io/reference/

Nowe uwierzytelnianie – zarządzanie kluczami zamiast użytkownikami

Dotychczasowe API Admin oparte było o tzw. użytkowników panelu, którym nadawało się uprawnienia jak do pracy z panelem administracyjnym i włączało się dostęp do API. Od teraz aplikacje mają swój dedykowany moduł uprawnień. Każda aplikacja powinna mieć swój klucz dostępowy z odpowiednio dobranymi uprawnieniami.

Klucze dodaje się w module ADMINISTRACJA / Klucze dostępowe do Admin API. Podczas każdego wywołania, wystarczy podać ten klucz. Dzięki temu, integracje typu no-code są bardzo proste. Dodatkowo istnieje możliwość wygenerowania tokenu dostępowego zgodnie z protokołem OAuth2. Wygenerowane klucze dla wygody developerów będą bezterminowe.

Zmieniliśmy też sposób przyznawania uprawnień. Dotychczasowy bazował na takich samych uprawnieniach jak panel administracyjny. Nowy sposób jest odmienny od uprawnień w panelu administracyjnym i opiera się o uprawnienia do podsystemów np. WMS, OMS, PIM, CRM itp.

Rewolucja trzymana w ryzach

Dotychczasowe mechanizmy takie jak statystyki, zapis żądań i odpowiedzi API pozostały niezmienione. Podobnie będą działali użytkownicy utworzeni na potrzeby dostępu do API Admin 2. Nie ma już możliwości dodania nowych. Struktura bramek, parametrów, nazwy (nawet gdy planowane są ich zmiany) pozostały celowo takie same jak w API Admin 2. Zabieg taki zmniejszy ilość potrzebnych zmian na przepisanie aplikacji z API Admin 2 na SOAP. Obecna rewizja oznaczona jest „v1”. W kolejnych rewizjach wprowadzimy zmiany do nazw i podziału bramek, które bardziej uporządkują strukturę.

Podczas etapu testowego wyeliminowaliśmy możliwie najwięcej znanych i napotkanych błędów. W tym przypadku większość została usunięta również w dotychczasowym API Admin 2.

Wspólne testy z wybranymi developerami

Nowe API 3 tworzymy z myślą o developerach. Dlatego zaprosiliśmy trzy zespoły developerów do pilotażowej współpracy. W ramach projektu przepisali swoje dotychczasowe aplikacje tak, żeby od razu wykorzystywały API 3. Według wniosków z pilotażu przepisanie było możliwe w krótkim czasie i obyło się bez większych trudności. Aplikacje są od razu gotowe do współpracy z najnowszym API.

"Nowe REST API IdoSell to krok naprzód w doskonaleniu naszej pracy w tym środowisku. Dzięki nowym mechanizmom autoryzacji oraz zastosowaniu nowej warstwy walidacji danych wejściowych, nasi deweloperzy zyskują większą efektywność w codziennym działaniu. Dodatkowo, nowe API charakteryzuje się usprawnionymi odpowiedziami, co stanowi istotny kamień milowy w naszej pracy z tym interfejsem programistycznym." mówi Konrad Kur, CEO SoftwareLogic.co, firmy produkującej m.in. aplikację widgetu z gratisami fffrree.com

"Nowa dokumentacja jest dużo wygodniejsza." mówi Jakub Malczak Software Architect w Firmie 9BYTES - producenta oprogramowania WMS EasyStorage, które wspiera sklepy w logistyce magazynowej od przyjęcia towaru do wydania. Jest to szybka, przejrzysta i chwalona przez klientów aplikacja wyróżniająca się na rynku e-commerce. WMS EasyStorage pozwala trzymać towar na dowolnej liczbie lokalizacji, w rożnych strefach, przyjmować dostawy na palety, kartony i bezpośrednio na półki, zbierać zamówienia grupowo na różne sposoby i przez wielu operatorów jednocześnie. Intuicyjne inwentaryzacje (także w czasie kompletacji) minimalizują liczbę błędów oraz eliminują nieefektywną pracę operatorów w magazynie. Na koniec dnia statystyki pozwalają odpowiednio sprawdzić wydajność pracowników w każdym z obszarów. EasyStorage jest zintegrowany z najpopularniejszymi systemami ERP na rynku (Insert, Comarch, IdoSell).

"Przepisanie pierwszej aplikacji na Admin API 3 przebiegło bardzo sprawnie. Samo dostosowanie i testy zajęły mi 2 godziny. Aplikacja którą przygotowałem, integruje Chat GPT z IdoSell, dzięki czemu umożliwia sprzedawcom przetwarzanie tekstu przy użyciu modeli GPT. Masowe operacje na produktach i menu, takie jak generowanie opisów, parafrazowanie pod kątem SEO, tłumaczenie oraz korygowanie błędów, mogą być wykonane przy skróceniu wymaganego czasu nawet o 90%." mówi Damian Wrzos, CEO CashCode sp. z o.o.

Dalsze plany

Dotychczasowe API 2 będzie utrzymywane do 31 grudnia 2024 r. Od teraz rozwijane będzie wyłącznie nowe API 3. Poza poprawkami krytycznymi nie należy spodziewać się ulepszeń, nawet do potwierdzonych nieprawidłowości. Te będą usuwane tylko w API 3. Dlatego prosimy, żeby przełączenia dokonać nie później niż do końca października 2024 r.

API IdoSell to nie tylko Admin API. Oferujemy także dedykowane API dla kurierów, marketplaces, do składania zamówień (Customer API), a także dla centrów fulfillment (Fulfillment API). W pierwszej fazie pozostaną one bez zmian, ale z czasem zostaną przepisane analogicznie i będą umieszczone w jednej dokumentacji ze wspólnym mechanizmem uwierzytelniania.