Jak połączyć własny sklep z easySales przez API

Kiedy tego potrzebujesz

easySales ma gotowe konektory do popularnych platform sklepowych. Jeśli prowadzisz coś własnego — sklep zbudowany wewnętrznie albo platformę, do której nie mamy integracji — możesz podłączyć go samodzielnie przez API.

To zadanie dla programisty. Napiszesz kod, który wyśle Twój katalog do easySales i przekaże zamówienia, a easySales odezwie się do Twojego sklepu, gdy coś się zmieni. Nic z tego nie wymaga instalowania wtyczki.

Jak działa to połączenie

W grę wchodzą dwa poświadczenia, a ich pomylenie to najczęstszy powód, dla którego pierwsza integracja zwraca 403.

Oba są potrzebne przy każdym zapisie. Token dostępu potwierdza, kto wywołuje; token strony mówi, do którego sklepu należą dane.

Krok 1 — Dodaj stronę

Wejdź w Integracje → Strony internetowe, kliknij Połącz do strony internetowej, wypełnij formularz, a następnie wybierz kafelek API i wersję API V2 pod nim.

Krok 2 — Skopiuj token strony

Krok Konfiguracja w kreatorze pokazuje 60-znakowy token. To ten, o którym stary artykuł w ogóle nie wspomina, i ten, którego potrzebuje każde wywołanie zapisu.

Skopiuj go przyciskiem, zamiast przepisywać ręcznie, i przechowuj jako sekret w swojej aplikacji. Kliknij Zapisz, aby utworzyć stronę.

Sklep pojawia się teraz w Integracje → Strony internetowe i ma ten sam token na swojej karcie — tam znajdziesz go później.

Krok 3 — Utwórz klienta OAuth

Wejdź w Ustawienia → Ustawienia API. Tam znajdują się poświadczenia OAuth.

Kliknij Utwórz nowego klienta, nazwij go po systemie, który będzie wywoływał, i ustaw Typ grantu na Website Grant.

Website Grant jest zbudowany dokładnie do tego zadania: wymienia Twój token strony na token dostępu, bez przekierowania w przeglądarce i bez udziału użytkownika. Zapisz i skopiuj Identyfikator klienta oraz Sekretny, które się pojawią.

Krok 4 — Pobierz token dostępu

POST https://easy-sales.com/oauth/token
Content-Type: application/json

{
  "grant_type":    "website",
  "client_id":     "your-client-id",
  "client_secret": "your-client-secret",
  "website_token": "your-60-character-website-token",
  "scope":         "add-products update-products update-stock add-orders update-orders read-orders"
}

Odpowiedź to standardowe ciało OAuth:

{
  "token_type":    "Bearer",
  "expires_in":    31536000,
  "access_token":  "eyJ0eXAiOiJKV1Qi...",
  "refresh_token": "def50200a1b2c3..."
}

Wysyłaj go jako Authorization: Bearer <access_token> w każdym kolejnym wywołaniu.

Krok 5 — Wyślij swój katalog

Bazowy adres dla wszystkiego poniżej to https://easy-sales.com/api/v2.

Kolejność ma znaczenie. Kategorie i cechy muszą istnieć, zanim produkt będzie mógł się do nich odwołać, inaczej wywołanie produktu zostanie odrzucone.

1. POST /categories/save — Twoje kategorie
2. POST /characteristics/save — Twoje atrybuty
3. POST /products/save — Twoje produkty

POST https://easy-sales.com/api/v2/products/save
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "website_token": "your-60-character-website-token",
  "product": {
    "product_website_id": "10231",
    "sku": "TS-BLK-M",
    "name": "Black T-shirt, size M",
    "sale_price": 79.99,
    "full_price": 99.99,
    "stock": 24,
    "type": "simple",
    "tax_rate": 21,
    "url": "https://my-shop.example.com/p/ts-blk-m",
    "images": ["https://my-shop.example.com/img/ts-blk-m.jpg"],
    "categories": ["cat-778"],
    "characteristics": [{ "id": "char-12", "value": "Black" }]
  }
}

Krok 6 — Utrzymuj stany magazynowe w zgodzie

Stan magazynowy musi być aktualny i jest to najtańsze wywołanie, które można wykonywać często. Wyślij do 100 wierszy naraz:

PATCH https://easy-sales.com/api/v2/stocks/bulk
Authorization: Bearer <access_token>

{
  "website_token": "your-60-character-website-token",
  "data": [
    { "sku": "TS-BLK-M", "stock": 24 },
    { "sku": "TS-BLK-L", "stock": 0 }
  ]
}

Każdy SKU musi już istnieć na tej stronie; nieznane są odrzucane, a nie tworzone.

Krok 7 — Prześlij swoje zamówienia

POST https://easy-sales.com/api/v2/orders/save
Authorization: Bearer <access_token>

{
  "website_token": "your-60-character-website-token",
  "order": {
    "order_id": "SO-100244",
    "order_date": "2026-09-09 14:31:00",
    "order_total": 179.98,
    "status": "new",
    "payment_mode": "card",
    "shipment_tax": 21,
    "billing_address":  { "country": "RO", "city": "Cluj-Napoca", "street": "Str. Memorandumului 4" },
    "shipping_address": { "country": "RO", "city": "Cluj-Napoca", "street": "Str. Memorandumului 4" },
    "order_products": [
      { "product_website_id": "10231", "sku": "TS-BLK-M", "name": "Black T-shirt, size M",
        "quantity": 2, "price": 79.99, "total": 159.98 }
    ]
  }
}

Wyślij ponownie ten sam order_id, a zamówienie zostanie zaktualizowane, a nie zduplikowane — dzięki temu ponowne próby są bezpieczne.

Krok 8 — Odbieraj zmiany z powrotem

Twój sklep musi wiedzieć, kiedy zamówienie zostało zafakturowane, ma list przewozowy albo zmienia status. Zamiast odpytywać, zasubskrybuj webhook:

GET https://easy-sales.com/api/v2/webhooks
Authorization: Bearer <access_token>

POST https://easy-sales.com/api/v2/webhooks/order-updated
Authorization: Bearer <access_token>

{
  "url":    "https://my-shop.example.com/hooks/easysales",
  "secret": "a-shared-secret-of-at-least-24-characters"
}

Subskrybujesz po jednym zdarzeniu naraz, więc powtórz wywołanie dla każdego z order-created, order-updated, awb-created, invoice-created i delivery-status-updated.

Każda dostawa jest podpisana, więc zweryfikuj podpis, zanim zaufasz treści. Odpowiadaj szybko — żądanie wygasa po kilku sekundach i jest ponawiane ograniczoną liczbę razy, więc najpierw potwierdź, a przetwarzaj później.

Limity

Kiedy coś zawiedzie

Wszystko, co zawiedzie po naszej stronie, trafia też do Produkty → Sklepy Online → Błędy strony internetowej, wraz z ładunkiem i akcją ponowienia, co zwykle jest szybsze niż odtwarzanie wywołania.

Dokumentacja

Pełna dokumentacja endpointów, z każdym polem i każdą odpowiedzią, jest opublikowana pod adresem https://api.easy-sales.com.