A Termék API

Áttekintés

Egy Termék API forrás két irányban működik, és bármelyiket vagy mindkettőt használhatod:

• Lekérés — küldünk egy GET kérést egy általad birtokolt címre, a forrásnál beállított ütemezés szerint, te pedig visszaadod a teljes katalógusodat.
• Küldés — te POST-olod nekünk a megváltozott termékeket abban a pillanatban, amikor megváltoznak.

Az irányítópult API füle ugyanezt a leírást tartalmazza, a márkád valódi címeivel kitöltve, úgyhogy a bekötést érdemes ott kezdeni.

Lekérés — mi olvassuk be a címedet

A kérés, amit küldünk

Egyetlen GET. Nincs lapozás: add vissza az egészet egy válaszban.

Plusz minden további fejléc, amit a forráson beállítottál.

A címednek https-t kell használnia, az első kérésnél és minden átirányításnál. A privát és belső címeket elutasítjuk.

Amit visszaadsz

Egy alak van, akár vannak változatai a termékeidnek, akár nincsenek. Egy több ízben, kiszerelésben vagy színben kapható termék variants listát hordoz; egy olyan, aminek nincsenek változatai, a saját price és availability mezőjét viszi helyette.

{
  "products": [
    {
      "id": "whey-gold",
      "title": "Whey Gold fehérjepor",
      "link": "https://shop.example.com/products/whey-gold",
      "description": "Tejsavófehérje-koncentrátum hozzáadott emésztőenzimekkel.",
      "image": "https://shop.example.com/images/whey-gold.jpg",
      "brand": "Acme Nutrition",
      "category": "Fehérje > Tejsavó",
      "priority": 820,
      "attributes": {
        "Összetevők": ["tejsavófehérje-koncentrátum (tej)", "kakaó"],
        "Adagolás": "napi 1 adag (32 g)"
      },
      "search_terms": ["tejsavó", "fehérjeturmix"],
      "rule_keys": ["tejsavófehérje"],
      "variants": [
        {
          "id": "10803",
          "options": { "Íz": "Pisztácia", "Kiszerelés": "1 kg" },
          "price": "19 990 HUF",
          "availability": "in stock",
          "link": "https://shop.example.com/products/whey-gold?variant=10803",
          "attributes": {
            "Tápérték adagonként": { "Energia": "128 kcal", "Fehérje": "24 g" }
          },
          "priority": 950,
          "rule_keys": ["pisztácia"]
        },
        {
          "id": "10804",
          "options": { "Íz": "Pisztácia", "Kiszerelés": "2,3 kg" },
          "price": "39 990 HUF",
          "sale_price": "34 990 HUF",
          "availability": "out of stock"
        }
      ]
    },
    {
      "id": "SKU-1001",
      "title": "C-vitamin 1000 mg, 60 tabletta",
      "link": "https://shop.example.com/products/vitamin-c-1000",
      "description": "Nagy dózisú C-vitamin könnyen lenyelhető tablettában.",
      "price": "4990 HUF",
      "sale_price": "3990 HUF",
      "availability": "in stock",
      "brand": "Acme Health",
      "category": ["Vitaminok", "C-vitamin"],
      "attributes": {
        "Összetevők": ["aszkorbinsav", "csipkebogyó kivonat"],
        "Kiszerelés": "tabletta"
      },
      "rule_keys": ["aszkorbinsav"],
      "rules": ["A C-vitamin hozzájárul az immunrendszer normál működéséhez."]
    }
  ]
}

Időzítés és hibák

Beolvasásonként három próbálkozás (egyenként 30 másodperc, 5, majd 15 másodperc várakozással), de csak időtúllépésre, hálózati hibára és 5xx válaszra. Egy 4xx azonnal hibára fut. A válasz törzse legfeljebb 50 MB lehet, és legfeljebb 20 000 terméket tartalmazhat.

A nulla termékkel visszatérő válasz hibának számít, így egy elromlott végpont soha nem ürítheti ki észrevétlenül a katalógust.

A termékobjektum

Kötelező

Nem kötelező

A változatobjektum

A variants minden eleme egy dolog, amit a vásárló meg tud venni. Csak az id kötelező.

attributes — a saját mezőid

Egy objektum, aminek az értékei szöveg, szám, logikai érték, ezek tömbje, vagy egy szint mélységű beágyazott objektum lehetnek — így tudsz például tápértéktáblázatot küldeni:

"attributes": {
  "Adagolás": "1 adag (32 g)",
  "Tápérték adagonként": { "Energia": "128 kcal", "Fehérje": "24 g", "Zsír": "2,2 g" }
}

Az egy szintnél mélyebb beágyazás az egész terméket érvénytelenné teszi — nem csak azt az egy mezőt.

rule_keys és rules

Mindkettőt tároljuk, de soha nem tesszük kereshetővé. Kizárólag a termékszabályok miatt léteznek.

• A rule_keys dönti el, mely szabályok vonatkoznak erre a termékre.
• A rules mondatait az AI szó szerint, minden alkalommal megkapja, amikor ez a termék megjelenik egy válaszban.

Ami nem kereshető

A price, a sale_price és az availability szándékosan soha nem része annak, amit az AI megtanult — folyamatosan változnak, és a válasz készítésekor olvassuk ki őket élőben a változatokról. Az AI nem tud rájuk keresni.

A search_terms ennek a tükörképe: kizárólag kereshető. Segít a keresésnek megtalálni a terméket, és az AI soha nem látja, így egy termék beceneve nem szivároghat bele egy mondatba.

Érvénytelen elemek

Az érvénytelen elemeket kihagyjuk, soha nem végzetesek — a futás folytatódik, és a jelentés felsorolja az első 50-et az indokkal. Ha ugyanaz az id kétszer szerepel egy küldeményben, az utolsó nyer.

Egyetlen változatot soha nem hagyunk ki önmagában. Ha egy termék bármelyik változata megbukik az ellenőrzésen, az egész termék kimarad a futásból, hogy a katalógusban soha ne legyen olyan termék, aminek csendben hiányzik a fele kiszerelése. A jelentés ezeket külön, „Terméket megállító változatok" néven számolja.

Küldés — te küldöd nekünk a változásokat

A végpont

POST https://yaplet.com/api/products/push/{sourceId}

A {sourceId} a forrás azonosítója — másold ki a Küldési cím másolása gombbal a Források fülön.

Hitelesítés

Küldd el a szervezeti API kulcsodat a Y-API-Key fejlécben. Ez a Beállítások → API oldalról származó kulcs, nem a forrás megosztott titka.

A törzs

const res = await fetch("https://yaplet.com/api/products/push/YOUR_SOURCE_ID", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Y-API-Key": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    mode: "merge",
    products: [
      {
        id: "SKU-1001",
        title: "Vitamin C 1000 mg, 60 tablets",
        link: "https://shop.example.com/products/vitamin-c-1000",
        price: "12.90 EUR",
        availability: "in stock",
        attributes: { Ingredients: ["ascorbic acid"] },
        rule_keys: ["ascorbic acid"],
      },
    ],
    deleted_ids: ["SKU-0999"],
  }),
});

const result = await res.json();
console.log(result.run_id, result.accepted);

curl -X POST "https://yaplet.com/api/products/push/YOUR_SOURCE_ID" \
  -H "Content-Type: application/json" \
  -H "Y-API-Key: YOUR_API_KEY" \
  -d '{
    "mode": "merge",
    "products": [
      {
        "id": "SKU-1001",
        "title": "Vitamin C 1000 mg, 60 tablets",
        "link": "https://shop.example.com/products/vitamin-c-1000",
        "price": "12.90 EUR",
        "availability": "in stock",
        "attributes": { "Ingredients": ["ascorbic acid"] },
        "rule_keys": ["ascorbic acid"]
      }
    ],
    "deleted_ids": ["SKU-0999"]
  }'

$payload = json_encode([
    "mode" => "merge",
    "products" => [[
        "id" => "SKU-1001",
        "title" => "Vitamin C 1000 mg, 60 tablets",
        "link" => "https://shop.example.com/products/vitamin-c-1000",
        "price" => "12.90 EUR",
        "availability" => "in stock",
        "attributes" => ["Ingredients" => ["ascorbic acid"]],
        "rule_keys" => ["ascorbic acid"],
    ]],
    "deleted_ids" => ["SKU-0999"],
]);

$ch = curl_init("https://yaplet.com/api/products/push/YOUR_SOURCE_ID");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Y-API-Key: YOUR_API_KEY",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode >= 200 && $httpCode < 300) {
    $result = json_decode($response, true);
    echo "Run: " . $result["run_id"];
} else {
    echo "Error " . $httpCode . ": " . $response;
}

import requests

url = "https://yaplet.com/api/products/push/YOUR_SOURCE_ID"
headers = {
    "Content-Type": "application/json",
    "Y-API-Key": "YOUR_API_KEY",
}
body = {
    "mode": "merge",
    "products": [
        {
            "id": "SKU-1001",
            "title": "Vitamin C 1000 mg, 60 tablets",
            "link": "https://shop.example.com/products/vitamin-c-1000",
            "price": "12.90 EUR",
            "availability": "in stock",
            "attributes": {"Ingredients": ["ascorbic acid"]},
            "rule_keys": ["ascorbic acid"],
        }
    ],
    "deleted_ids": ["SKU-0999"],
}

response = requests.post(url, headers=headers, json=body)

if response.ok:
    result = response.json()
    print("Run:", result["run_id"])
else:
    print("Error", response.status_code, response.text)

Amit visszakapsz

A sikeres küldés 202 Accepted választ ad:

{
  "run_id": "3f9d2c6e-1b7a-4c1e-9f0a-2d8e5b6c7a90",
  "status": "running",
  "received": 1,
  "accepted": 1,
  "invalid": 0,
  "report_url": "/api/products/push/YOUR_SOURCE_ID/runs/3f9d2c6e-1b7a-4c1e-9f0a-2d8e5b6c7a90"
}

Egy futás lekérdezése

GET https://yaplet.com/api/products/push/{sourceId}/runs/{runId}

Ugyanaz a Y-API-Key fejléc. Kérdezd le addig, amíg a status már nem "running", aztán olvasd ki a számlálókat, és ha a status "failed", az error és az error_code mezőket.

Küldési szabályok

• A merge csak az általad küldött azonosítókhoz nyúl. Minden más érintetlen marad.
• A deleted_ids termékazonosítók, nem változatazonosítók. Egy termék törlésével a változatai is törlődnek. Egy nem hozzád tartozó vagy nem létező azonosítót csendben figyelmen kívül hagyunk. Ha egy azonosító a products és a deleted_ids listában is szerepel, a termék nyer.
• A mode: "replace" törli a forrás minden olyan termékét, ami nincs benne a küldeményben.

Azok a termékek, amiknek a tartalma nem változott, semmibe nem kerülnek — nem indexeljük őket újra. Ha csak az árat, az akciós árat vagy az elérhetőséget módosítod, a sor frissül, de semmit nem indexelünk újra.

Egy sikeres küldés visszahozza azokat a termékeket is, amiket a forrás hibázása miatt rejtettünk el. Azt viszont nem indítja újra, ha az ütemezés három sikertelen beolvasás után leállt — arra csak a Beolvasás most való.

Hibák

Sebességkorlátok

Percenként 12 küldés forrásonként, és percenként 60 szervezetenként. Minden válasz tartalmazza az X-RateLimit-Limit, az X-RateLimit-Remaining és az X-RateLimit-Reset fejlécet.

Amin sokan elcsúsznak