Vents Hungary – Reseller API dokumentáció

A Reseller API egy JSON alapú, csak olvasható REST API, amellyel a partnerek lekérdezhetik a termékeket, az árakat, a kategóriákat és a saját partneradataikat.

Minden kérést HMAC-SHA256 aláírással kell hitelesíteni. Ehhez egy kulcspárra van szükség:

• Public key – nyilvános azonosító, a kérés fejlécében küldendő.
• Private key – titkos kulcs, ezzel képződik az aláírás. Soha ne küldd el és ne tedd közzé!

A kulcspárt magad hozhatod létre és törölheted ezen az oldalon, az API kulcsok szakaszban (ehhez be kell jelentkezned). A privát kulcs csak egyszer, a létrehozáskor jelenik meg – ekkor kell biztonságos helyre elmenteni, később már nem kérhető le újra.

Kötelező fejlécek

Az aláírás kiszámítása

Az aláírandó szöveg (payload) három sorból áll, sortörés (\n) elválasztóval:

{HTTP_METÓDUS}\n{ÚTVONAL}\n{IDŐBÉLYEG}

• HTTP_METÓDUS – nagybetűvel, pl. GET.
• ÚTVONAL – a kérés útvonala perjellel kezdve, query paraméterek nélkül, pl. /api/v1/products.
• IDŐBÉLYEG – ugyanaz az érték, amit a X-Api-Timestamp fejlécben küldesz.

Az aláírás ebből: hash_hmac("sha256", payload, private_key) – az eredmény hexadecimális karakterlánc.

GET\n/api/v1/products\n1747300000

Az API végpontonként korlátozza a kérések számát. A limitek API kulcsonként értendők. A limit túllépésekor a szerver 429 Too Many Requests választ ad.

A végpontok többsége GET metódusú; a /prices végpont POST metódussal is hívható (nagy SKU-lista lekérésére). Minden kérés a fenti módon hitelesítést igényel. Az alábbi útvonalak a Base URL-hez (https://webshop.vents.hu/api/v1) relatívak.

{
  "resource": "me",
  "id": 123,
  "email": "partner@pelda.hu",
  "firstname": "Anna",
  "lastname": "Kovács",
  "partner_code": "P-00123",
  "currency": "HUF",
  "payment_day": 15
}

{
  "data": [
    {
      "resource": "api_product",
      "name": "VENTS 100 Quiet ventilátor",
      "slug": "vents-100-quiet",
      "sku": "V100Q",
      "description": "Csendes axiális ventilátor...",
      "category": {
        "id": 4,
        "name": "Axiális ventilátorok",
        "slug": "axialis-ventilatorok"
      },
      "primary_image_url": "https://.../v100q.jpg",
      "images": [
        { "id": 11, "url": "https://.../v100q.jpg", "sort_order": 0 }
      ]
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "last_page": 14, "per_page": 100, "total": 1356 }
}

{
  "data": [
    {
      "resource": "api_price",
      "sku": "V100Q",
      "price": 12990.00,
      "sale_price": 10990.00,
      "discount_price": 9990.00,
      "quantity": 42,
      "in_stock": true
    }
  ]
}

{
  "skus": ["V100Q", "V125Q", "V150Q"]
}

{
  "data": [
    {
      "resource": "api_price",
      "sku": "V100Q",
      "price": 12990.00,
      "sale_price": 10990.00,
      "discount_price": 9990.00,
      "quantity": 42,
      "in_stock": true
    }
  ]
}

{
  "data": [
    {
      "resource": "api_category",
      "id": 1,
      "name": "Ventilátorok",
      "slug": "ventilatorok",
      "parent_id": null,
      "product_count": 320,
      "children": [
        {
          "resource": "api_category",
          "id": 4,
          "name": "Axiális ventilátorok",
          "slug": "axialis-ventilatorok",
          "parent_id": 1,
          "product_count": 86,
          "children": []
        }
      ]
    }
  ]
}

Hiba esetén a szerver a megfelelő HTTP státuszkóddal és egy message mezőt tartalmazó JSON objektummal válaszol.

{ "message": "Invalid signature." }

A /prices végpont árai a partner saját kedvezményeit is figyelembe veszik. A mezők jelentése:

A fizetendő ár meghatározásához a legalacsonyabb elérhető (nem null) értéket érdemes használni. Az árak mindig a partner pénznemében (HUF vagy EUR) értendők – ezt a /me végpont currency mezője adja meg.

Az alábbi példák a /api/v1/products végpont hívását mutatják be. Válaszd ki a kívánt programozási nyelvet, majd cseréld le a PUBLIC_KEY és PRIVATE_KEY értékeket a saját kulcsaidra.

PUBLIC_KEY="a_te_public_kulcsod"
PRIVATE_KEY="a_te_private_kulcsod"
METHOD="GET"
ENDPOINT="/api/v1/products"
TS=$(date +%s)

PAYLOAD=$(printf '%s\n%s\n%s' "$METHOD" "$ENDPOINT" "$TS")
SIG=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "$PRIVATE_KEY" | awk '{print $NF}')

curl "https://webshop.vents.hu/api/v1/products?per_page=50" \
  -H "X-Api-Key: $PUBLIC_KEY" \
  -H "X-Api-Timestamp: $TS" \
  -H "X-Api-Signature: $SIG" \
  -H "Accept: application/json"

Fontos: az aláírásba kerülő útvonal mindig query paraméterek nélkül értendő (/api/v1/products), akkor is, ha a kérés tartalmaz ?per_page=50 jellegű paramétert.

Az API kipróbálásához letölthető egy kész Postman kollekció, amely mind a négy végpontot tartalmazza. A HMAC-SHA256 aláírást a kollekció beépített pre-request szkriptje minden kérés előtt automatikusan kiszámítja – csak a kulcsokat kell megadni.

Postman kollekció letöltése

Beállítás

1. A Postmanben kattints az Import gombra, és válaszd ki a letöltött fájlt.
2. Nyisd meg a kollekciót, és a Variables fülön töltsd ki a következőket:

A timestamp és signature változókat nem kell kitölteni – ezeket a pre-request szkript minden kérésnél automatikusan beállítja.

Itt követheted nyomon, hogy az API-ban mikor milyen változás történt (új végpontok, fejlesztések, javítások).

Itt kezelheted a saját API kulcsaidat: új kulcspárt hozhatsz létre, és törölheted a feleslegessé váltakat. A kulcskezeléshez be kell jelentkezned.

A Reseller API hívásai csak partner fiókhoz tartozó kulccsal működnek. Ha a fiókod nem partner típusú, és API hozzáférésre van szükséged, keresd az ügyfélszolgálatot.