API Magento 2 - podstawy

Magento ma rozbudowane REST API (od 2.x), GraphQL i legacy SOAP API pozwalające zewnętrznym systemom czytać i zapisywać dane sklepu. Ten poradnik pokazuje, jak skonfigurować integrację, utworzyć token i wykonać pierwszy request.

Magento Web API - przegląd

Magento eksponuje API pod dwoma protokołami:

Protokół	Bazowy URL	Format	Status
REST	`https://sklep.pl/rest/V1/...`	JSON / XML	Aktywny - preferowany.
SOAP	`https://sklep.pl/soap/`	XML	Legacy - używać tylko gdy konieczne.

W tym poradniku skupimy się na REST.

Typy autoryzacji

Magento Web API wspiera cztery sposoby autoryzacji:

Sposób	Cel
Admin Token	Token administratora - pełen dostęp do API. Do zewnętrznych integracji.
Customer Token	Token klienta - dostęp do danych konkretnego klienta (np. front PWA).
Guest Access	Część endpointów dostępna bez tokena (publiczne dane produktów).
OAuth 1.0a	Standardowy OAuth dla integracji wymagających autoryzacji 3rd party.

Najczęściej używamy Admin Token + Integration (dla backend-to-backend) lub OAuth (dla apps).

Krok 1. Tworzymy Integration

Ścieżka: System > Extensions > Integrations

Kliknij Add New Integration.

Integration Info

Pole	Wartość
Name	Nazwa integracji (np. ERP Sync 2026, Baselinker Connection).
Email	Email kontaktowy dla integracji.
Callback URL	URL który Magento wywoła po autoryzacji (dla OAuth). Można zostawić puste.
Identity link URL	URL przekierowania po pomyślnej autoryzacji (dla OAuth).
Your Password	Twoje hasło admina (potwierdzenie tożsamości).

API permissions (zakładka API)

Zaznacz uprawnienia które integracja będzie miała. Najczęstsze:

Permission	Co pozwala
`Catalog > Inventory`	Odczyt / zapis stanów magazynowych.
`Catalog > Products`	Odczyt / zapis produktów.
`Sales > Operations > Orders`	Odczyt / zapis zamówień.
`Customers > All Customers`	Odczyt / zapis klientów.
`Stores > Settings > Configuration`	Odczyt konfiguracji (rzadko zapis).

Zasada najmniejszych uprawnień: Zaznaczaj tylko te uprawnienia, których integracja faktycznie wymaga. Zaznaczenie Resource Access = All daje pełen dostęp do API - jeśli token wycieknie, atakujący może wykonać dowolną akcję w sklepie.

Zapisz przyciskiem Save & Activate.

Activate Integration

Po zapisaniu Magento poprosi o aktywację - wyświetli cztery klucze:

Klucz	Cel
Consumer Key	Klucz publiczny OAuth.
Consumer Secret	Klucz prywatny OAuth.
Access Token	Token do bezpośrednich requestów REST.
Access Token Secret	Sekret do OAuth.

Skopiuj wszystkie cztery - wyświetlają się tylko raz. Zapisz w bezpiecznym menedżerze haseł.

Wybór klucza: - Dla prostych integracji REST (backend → Magento) używaj Access Token jako Bearer.

Dla OAuth 1.0a używaj wszystkich czterech.

Krok 2. Pierwszy request REST

Test z Access Token jako Bearer token:

curl -X GET "https://twoj-sklep.pl/rest/V1/products?searchCriteria[pageSize]=5" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Odpowiedź - JSON z 5 produktami:

{
  "items": [
    {
      "id": 1,
      "sku": "PROD-001",
      "name": "Sample Product",
      "price": 99.99,
      ...
    }
  ],
  "search_criteria": {...},
  "total_count": 1234
}

Krok 3. Endpointy najczęściej używane

Products

Metoda	Endpoint	Cel
`GET`	`/V1/products?searchCriteria[...]`	Lista produktów (paginacja + filtry).
`GET`	`/V1/products/{sku}`	Pojedynczy produkt.
`POST`	`/V1/products`	Utworzenie produktu.
`PUT`	`/V1/products/{sku}`	Aktualizacja produktu.
`DELETE`	`/V1/products/{sku}`	Usunięcie produktu.

Orders

Metoda	Endpoint	Cel
`GET`	`/V1/orders?searchCriteria[...]`	Lista zamówień.
`GET`	`/V1/orders/{id}`	Pojedyncze zamówienie.
`POST`	`/V1/orders`	Utworzenie zamówienia (np. import).

Customers

Metoda	Endpoint	Cel
`GET`	`/V1/customers/search?searchCriteria[...]`	Lista klientów.
`GET`	`/V1/customers/{id}`	Pojedynczy klient.
`POST`	`/V1/customers`	Utworzenie klienta.

Stock (MSI)

Metoda	Endpoint	Cel
`GET`	`/V1/stockItems/{sku}`	Stan magazynowy produktu.
`PUT`	`/V1/products/{sku}/stockItems/{itemId}`	Aktualizacja stanu.
`POST`	`/V1/inventory/source-items`	Aktualizacja MSI (multi-source).

Pełna lista endpointów

Pełna i oficjalna dokumentacja API znajduje się online na stronie producenta tutaj

Search Criteria - filtry i paginacja

Większość endpointów GET przyjmuje search criteria w query string:

?searchCriteria[filterGroups][0][filters][0][field]=sku
&searchCriteria[filterGroups][0][filters][0][value]=PROD-001
&searchCriteria[filterGroups][0][filters][0][conditionType]=eq
&searchCriteria[pageSize]=10
&searchCriteria[currentPage]=1
&searchCriteria[sortOrders][0][field]=created_at
&searchCriteria[sortOrders][0][direction]=DESC

Operatory (conditionType)

Operator	Znaczenie
`eq`	Równe
`neq`	Nierówne
`gt`	Większe
`gteq`	Większe lub równe
`lt`	Mniejsze
`lteq`	Mniejsze lub równe
`like`	LIKE SQL (% jako wildcard)
`in`	IN (lista wartości)
`nin`	NOT IN
`from` / `to`	Zakres (typowe dla dat)

Przykład: produkty zmienione od daty X

?searchCriteria[filterGroups][0][filters][0][field]=updated_at
&searchCriteria[filterGroups][0][filters][0][value]=2026-01-01 00:00:00
&searchCriteria[filterGroups][0][filters][0][conditionType]=gt
&searchCriteria[pageSize]=100
&searchCriteria[currentPage]=1

Customer Token - autoryzacja klienta

Dla integracji z PWA / aplikacjami mobilnymi używasz Customer Token (klient się loguje swoim emailem i hasłem):

curl -X POST "https://twoj-sklep.pl/rest/V1/integration/customer/token" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "[email protected]",
    "password": "haslo123"
  }'

Odpowiedź:

"abc123def456..."  // token klienta

Token używasz tak samo jak Admin Token (Bearer), ale ma ograniczone uprawnienia - tylko do danych tego klienta.

Pułapki i ograniczenia

Rate limiting

Magento nie ma natywnego rate limit, ale serwer (Nginx / fail2ban) może odrzucać requesty po zbyt wielu próbach. Dla intensywnych integracji:

Używaj paginacji (pageSize) - nigdy nie pobieraj wszystkich rekordów jednym requestem.
Backoff - przy 5xx czekaj i retryuj.
Concurrent requests - max 5 - 10 równoległych, więcej może obciążyć serwer.

Cache i konsystencja

Niektóre endpointy zwracają cache'owane dane (np. produkty z Full Page Cache). Po zmianach zarządzaj cache - patrz Cache i indeksery.

Response time

Magento API jest zauważalnie wolniejsze od dedykowanych systemów (zwykle 100-500ms / request). Dla wielu requestów rozważ:

Endpointy batch (gdzie dostępne).
Bulk API Magento (/rest/all/async/bulk/V1/...) - asynchroniczne operacje masowe.
Bezpośredni dostęp do bazy (tylko dla read-only - z poszanowaniem schema).

Najczęstsze problemy

401 Unauthorized

Sprawdź Bearer token w nagłówku (Authorization: Bearer XYZ - z dużą "B").
Token mógł zostać dezaktywowany w System > Extensions > Integrations.
Brakuje uprawnienia w integracji do konkretnego endpointu.

403 Forbidden

Integracja nie ma uprawnień do tego endpointu. Dodaj odpowiedni resource w System > Extensions > Integrations > [twoja integracja] > Edit > API.

400 Bad Request

Najczęściej:

Body JSON nie pasuje do oczekiwanego schema (sprawdź Swagger).
Wymagane pola pominięte.
Wartości w złym formacie (data ISO 8601, liczba zamiast stringa, etc.).

404 Not Found

Sprawdź URL - czy poprawny pattern (/rest/V1/products/{sku} nie /rest/V1/product/{sku}).
Sprawdź bazę - czy zasób (np. SKU) faktycznie istnieje.
Sprawdź store code - niektóre endpointy wymagają /rest/{storeCode}/V1/... zamiast /rest/V1/....

500 Internal Server Error

Sprawdź logi:

var/log/exception.log
var/log/system.log

Najczęściej błąd w danych (referencje do nieistniejących encji, zła konstrukcja JSON).

Token wygasł

Magento Admin Tokens wygasają po pewnym czasie (Stores > Configuration > Services > OAuth > Access Token Lifetime). Integracje z System > Extensions > Integrations mają dłuższy okres - można też ustawić "never expire" (Customer Token Lifetime = 0).

CORS errors z frontu PWA

Magento zwraca dane bez CORS headers. Dla frontu PWA / SPA:

Skonfiguruj reverse proxy (Nginx) który dodaje CORS headers do /rest/.
Lub: skonfiguruj Magento_GraphQl zamiast REST (lepsze wsparcie CORS).

GraphQL API - alternatywa

Magento 2.3+ ma GraphQL API (od Magento_GraphQl). Lepsze dla:

Frontów PWA (jeden request zamiast wielu REST).
Dokładnej selekcji pól (tylko to, co potrzebne).
Mniej requestów.

Endpoint: /graphql.

Konsola: https://twoj-sklep.pl/graphql w przeglądarce → GraphQL playground.

Wymaga osobnego poradnika - w tej dokumentacji nie omawiamy szczegółów GraphQL.

Powiązane

Cache i indeksery - API zwraca cache'owane dane
Bezpieczeństwo panelu admina - tokeny to credentials