Magento API w praktyce: endpointy, integracje i bezpieczeństwo

Magento API pozwala zewnętrznym aplikacjom odczytywać lub zmieniać dane sklepu w granicach nadanych uprawnień. Typowy przepływ obejmuje produkty, ceny, stany, klientów i zamówienia, ale konkretne operacje zależą od wersji, modułów, typu wdrożenia i konfiguracji dostępu.

Samo istnienie endpointu nie gwarantuje, że obsłuży wymagany proces. Sprawdź metody, wymagane pola, uprawnienia i dostępność w referencji dla właściwego wydania Commerce. Jeśli rozważasz zmianę platformy, przewodnik po migracji Magento i Shopify pomaga uporządkować zakres przenoszonych danych.

Wybieramy interfejs według tego, kto inicjuje wymianę i jak system ma konsumować dane. REST udostępnia zasoby pod różnymi ścieżkami, takimi jak `/V1/...`, więc często pasuje do integracji zaplecza. GraphQL używa zwykle endpointu `/graphql`, a zapytanie określa, które obsługiwane pola klient chce otrzymać.

Przed implementacją sprawdź referencję właściwą dla Adobe Commerce PaaS, Magento Open Source albo Adobe Commerce as a Cloud Service, ponieważ dostępne endpointy mogą się różnić. Przy dużym katalogu zaplanuj paginację i zmierz czas odpowiedzi. REST często upraszcza przepływy ERP, ale sam wybór interfejsu nie rozwiązuje mapowania ani kolejkowania. Więcej o wariantach platformy opisujemy w materiale o doborze rozwiązań Magento.

Dla zewnętrznej integracji Magento Open Source lub Adobe Commerce PaaS utwórz osobną integrację i przyznaj jej dostęp tylko do wymaganych zasobów. W panelu administratora konfiguracja znajduje się zwykle w System > Extensions > Integrations; po ustawieniu uprawnień aktywuj integrację. Nazwy i rozmieszczenie elementów mogą zależeć od wersji.

W OAuth 1.0a używanym w PaaS aplikacja podpisuje żądania przy użyciu HMAC-SHA256. W procesie uczestniczą consumer key, consumer secret, access token i access token secret. Sam access token przesłany jako Bearer nie jest domyślnym sposobem autoryzacji w tym przepływie. Możliwość użycia tokenu integracji jako samodzielnego Bearer jest odrębnym ustawieniem i nie powinna zastępować prawidłowej konfiguracji klienta OAuth.

Używaj osobnych poświadczeń dla testów i produkcji, wymuszaj HTTPS i przechowuj sekrety w bezpiecznej konfiguracji serwera lub menedżerze sekretów. Nie umieszczaj ich w kodzie frontendu, repozytorium ani logach. Po zmianie wykonawcy lub podejrzeniu ujawnienia unieważnij dostęp i wygeneruj nowe dane.

Adobe Commerce as a Cloud Service korzysta z innego modelu uwierzytelniania niż OAuth 1.0a PaaS. Nie przenoś konfiguracji między tymi typami wdrożeń bez sprawdzenia właściwej dokumentacji. W PaaS procedurę opisuje dokumentacja Adobe dotycząca OAuth 1.0a, a szczegółowe błędy tego mechanizmu zebrano w tabeli błędów OAuth Adobe.

Rozpisz integrację jako przepływy konkretnych pól, a nie ogólną deklarację połączenia systemów. Dla każdego procesu ustal źródło wartości, kierunek synchronizacji, identyfikator rekordu i reakcję na konflikt.

Przykładowy przepływ zamówienia zaczyna się po zakupie w Magento. Integracja pobiera zamówienie i sprawdza, czy jego identyfikator zewnętrzny jest już zapisany w ERP; jeśli go nie ma, przekazuje pozycje, ilości, adres dostawy i uzgodnione kwoty. ERP odsyła identyfikator oraz status przyjęcia, a integracja aktualizuje status w Magento i zapisuje wynik wymiany.

SKU lub inny uzgodniony klucz powinien pozwalać odnaleźć ten sam produkt po obu stronach. Ustal również jednostki, waluty, podatki, zakres widoku sklepu i format dat. Przy zamówieniu określ zasady anulowania, moment potwierdzenia oraz postępowanie, gdy ERP odrzuci pozycję.

Jeśli zakres obejmuje ustalenie i wdrożenie przepływu z systemem zaplecza, integracja sklepu z ERP obejmuje analizę i wdrożenie uzgodnionych procesów.

Diagnozę zacznij od metody, endpointu, kodu HTTP, treści odpowiedzi, czasu i identyfikatora operacji. W logu zapisz bezpieczne dane potrzebne do odtworzenia problemu, ale pomiń tokeny, hasła i zbędne dane osobowe.

Kody HTTP zależą od wersji Commerce, endpointu, modułów oraz proxy lub innej warstwy pośredniej. Adobe publikuje przykładowe odpowiedzi REST, a osobno tabelę błędów OAuth; żadna pojedyncza tabela nie opisuje uniwersalnie wszystkich błędów każdej instalacji.

Ponawiaj tymczasowe błędy z rosnącym opóźnieniem i losowym rozrzutem, aby procesy nie wysyłały kolejnej fali żądań naraz. Przed powtórzeniem operacji tworzącej zamówienie, klienta lub dokument sprawdź, czy poprzednie żądanie nie zapisało już rekordu.

Magento nie zapewnia automatycznie idempotencji każdej operacji. Deduplikację trzeba zaprojektować w integracji albo potwierdzić dla konkretnego endpointu i modułu, na przykład przez zapamiętanie identyfikatora zdarzenia lub wyszukanie utworzonego obiektu. Po wyczerpaniu prób skieruj komunikat do kolejki błędnych operacji, a monitoring oprzyj na liczbie błędów, ponowień, czasie odpowiedzi i wieku najstarszego komunikatu.

Test odbiorowy powinien potwierdzić rezultat w obu systemach, a nie tylko kod 200 z Magento. Przygotuj poprawne i błędne dane, powtórzone komunikaty, większe partie oraz przerwane połączenie.

Dla zamówienia porównaj identyfikator, SKU, ilości, kwoty, podatki, adres dostawy i statusy. Dla stanów sprawdź magazyn, kanał sprzedaży i moment aktualizacji. Zapisz także, kto monitoruje przepływ, kiedy uruchamia alarm i jak tymczasowo zatrzymać synchronizację.

Rozjazdy najczęściej wynikają z niezgodnych identyfikatorów, reguł aktualizacji lub formatów. Przed ręczną korektą wielu rekordów sprawdź, czy problem nie dotyczy wspólnej reguły mapowania.

Perspektywa KC Mobile: samo połączenie z endpointem zwykle potwierdza tylko, że systemy mogą się komunikować. Wdrożenie wymaga też ustalenia, co zrobi pracownik sklepu, gdy ERP odrzuci zamówienie lub integracja zatrzyma produkt, i kto wznowi taką operację.

Zakres zależy od liczby procesów i jakości danych, a nie od samej liczby endpointów. Przed estymacją dzielimy prace na analizę, mapowanie, implementację, testy, uruchomienie i monitoring.

Na czas wpływają niestandardowe moduły, wiele widoków sklepu, brak dokumentacji systemu zewnętrznego, migracja istniejącej integracji i reguły cenowe zależne od klienta. Funkcje Adobe Commerce B2B mogą rozszerzać model danych oraz uprawnienia. Koszt określamy po analizie konkretnego zakresu i zależności.

• WooCommerce API: jak połączyć sklep z innymi systemami
• PrestaShop API: jak skonfigurować dostęp i bezpiecznie zintegrować sklep
• Magento Commerce development: jak zaplanować wdrożenie i integracje
• Wtyczki do Magento: jak dobrać rozszerzenie do potrzeb sklepu?