Hogyan kösd össze egyedi webshopodat az easySales-szel API-n át

Mikor van erre szükséged

Az easySales kész összekötőket kínál a szokásos webáruház-platformokhoz. Ha valami egyedit üzemeltetsz — házon belül fejlesztett boltot, vagy olyan platformot, amelyhez nincs integrációnk —, az API-n keresztül magad kötheted össze.

Ez fejlesztői feladat. Olyan kódot írsz, amely feltölti a katalógusodat az easySalesbe és átküldi a rendeléseket, az easySales pedig visszahív a boltodhoz, ha valami megváltozik. Az itt leírtakhoz semmilyen bővítményt nem kell telepíteni.

Hogyan működik a kapcsolat

Két hitelesítő adat vesz részt benne, és a leggyakoribb ok, amiért egy első integráció 403-at ad vissza, az, hogy összekeverik őket.

Minden íráshoz mindkettő kell. A hozzáférési token azt igazolja, ki hív; a webáruház-token azt mondja meg, melyik bolthoz tartoznak az adatok.

1. lépés — Add hozzá a webáruházat

Menj az Integrációk → Webáruházak menüpontra, kattints a Bejelentkezés a weboldalba gombra, töltsd ki az űrlapot, majd válaszd az API csempét és alatta az API V2 verziót.

2. lépés — Másold ki a webáruház-tokent

A varázsló Konfiguráció lépése egy 60 karakteres tokent mutat. Ezt a régi cikk soha nem említi, pedig minden írási hívásnak szüksége van rá.

A gombbal másold ki, ne gépeld át, és titokként tárold az alkalmazásodban. A webáruház létrehozásához kattints a Mentés gombra.

A bolt ezután megjelenik az Integrációk → Webáruházak oldalon, a kártyáján ugyanazzal a tokennel — később itt találod meg újra.

3. lépés — Hozz létre egy OAuth-klienst

Menj a Beállítások → API beállítások oldalra. Az OAuth-hitelesítő adatok itt találhatók.

Kattints az Új ügyfél létrehozása gombra, nevezd el arról a rendszerről, amelyik hívni fogja, és a Grant típus mezőt állítsd Website Grant értékre.

A Website Grant pontosan erre a feladatra készült: a webáruház-tokenedet hozzáférési tokenre váltja, böngészős átirányítás és felhasználói beavatkozás nélkül. Mentsd el, majd másold ki a megjelenő Ügyfél-azonosító és Titkos kulcs értéket.

4. lépés — Kérj hozzáférési tokent

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"
}

A válasz egy szokásos OAuth-törzs:

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

Minden további híváshoz Authorization: Bearer <access_token> formában küldd.

5. lépés — Töltsd fel a katalógusodat

Az alábbiak alap-URL-je https://easy-sales.com/api/v2.

A sorrend számít. A kategóriáknak és a jellemzőknek létezniük kell, mielőtt egy termék hivatkozna rájuk, különben a termékhívás elutasításra kerül.

1. POST /categories/save — a kategóriáid
2. POST /characteristics/save — a jellemzőid
3. POST /products/save — a termékeid

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" }]
  }
}

6. lépés — Tartsd szinkronban a készletet

A készlet az, aminek naprakésznek kell maradnia, és ez a legolcsóbb hívás ahhoz, hogy gyakran fusson. Egyszerre legfeljebb 100 sort küldj:

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 }
  ]
}

Minden SKU-nak léteznie kell már ezen a webáruházon; az ismeretleneket elutasítjuk, nem hozzuk létre.

7. lépés — Küldd be a rendeléseidet

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 }
    ]
  }
}

Ha ugyanazt az order_id értéket küldöd újra, a rendelés frissül, nem duplikálódik — így az újrapróbálkozás biztonságos.

8. lépés — Kapd vissza a változásokat

A boltodnak tudnia kell, ha egy rendelést kiszámláztak, fuvarlevelet kapott vagy státuszt váltott. Lekérdezés helyett iratkozz fel webhookra:

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"
}

Egyszerre egy eseményre iratkozol fel, ezért ismételd meg a hívást mindegyikre: order-created, order-updated, awb-created, invoice-created és delivery-status-updated.

Minden kézbesítés alá van írva, ezért ellenőrizd az aláírást, mielőtt megbíznál a tartalomban. Válaszolj gyorsan — a kérés néhány másodperc után lejár, és csak korlátozott számban ismételjük meg, ezért előbb nyugtázd, és utána dolgozd fel.

Korlátok

Ha valami hibára fut

Ami a mi oldalunkon hibára fut, az a Termékek → Online Áruházak → Webáruház hibák oldalon is megjelenik, a küldött adattal és egy újrapróbálkozás művelettel — ez általában gyorsabb, mint újrajátszani a hívást.

Hivatkozás

A teljes végpont-dokumentáció, minden mezővel és minden válasszal, a https://api.easy-sales.com címen érhető el.