App API

Az App API az a /apps-api/v1 alatti HTTP API, amellyel a szervered elérheti és módosíthatja egy bolt adatait. Minden kérés a kereskedő jóváhagyásából származó telepítési access tokent hordoz (lásd: Hitelesítés), és kizárólag ahhoz fér hozzá, amit a kereskedő jóváhagyott az adott telepítésnek. Új vagy még itt? Kezdj az Első API-hívásod oldallal.

Az App API éles originje még nincs közzétéve, így a példák a POLTURA_API változóból olvassák be.

A @poltura/app-sdk csomagban található PolturaClient minden route-ot lefed: new PolturaClient({ origin, accessToken, timeoutMs?, maximumResponseBytes?, fetch? }). Az origin egy route nélküli HTTPS-origin. A kérések 10 másodperc után timeouttal megszakadnak, hacsak nem állítasz be timeoutMs értéket (legfeljebb 60 másodpercre), az 1 MiB feletti válaszokat pedig elutasítja, kivéve, ha megemeled a maximumResponseBytes értékét (legfeljebb 8 MiB-ig). A kliens a tokent Authorization: Bearer headerként küldi, soha nem küld cookie-kat, és soha nem követi a redirecteket.

Egy írási művelet a teljes példából: mentés az app storage-ba a felülírt verzióval és egy idempotenciakulccsal.

export async function saveFeatured(
  client: PolturaClient,
  productIds: readonly string[],
  expectedVersion: number,
  idempotencyKey: string,
): Promise<StorageRecord> {
  const value = FeaturedProducts.parse({ productIds: [...productIds] });
  return client.storage.put(STORAGE_NAMESPACE, FEATURED_KEY, value, {
    expectedVersion,
    idempotencyKey,
  });
}

Route-okHivatkozás másolása

A listák fogadják a limit (1–100, alapértelmezett: 25) és cursor paramétereket, és a nextCursor értékkel válaszolnak: add át újra a következő oldal lekéréséhez, amíg az értéke null nem lesz. Ebben a szekcióban mindegyik route-hoz külön oldal is tartozik, paraméterekkel és példákkal.

CatalogueProduct: { id, title 1–500, handle 1–255, description legfeljebb 20000 vagy null, image, updatedAt }. A PublicProductWriteStatus értéke draft | published. A PublicMetadata legfeljebb 64 snake_case kulcsot tartalmazhat, az értékek legfeljebb 2000 karakteresek lehetnek. PublicTags: legfeljebb 32. A PublicOrder tartalmazza az orderNumber (1–64), a maximum 200 elemes items és a shippingAddress mezőket. A pénzösszegek formátuma { amount: "49.99", currency: "EUR" } a fő pénznemegységben; ne szorozd be 100-zal.

Egy írási művelet két kérésnek számít a telepítés kvótájában. Ha olyan mezőt írsz, amelyet a route nem engedélyez, a hívás invalid_input hibával meghiúsul. Minden írási művelet fogad egy Idempotency-Key headert, így az újrapróbált kérés csak egyszer fut le.

Storage-korlátokHivatkozás másolása

A namespace 1–64 karakteres lehet: kisbetűket, számjegyeket és _ karaktert tartalmazhat, és betűvel kell kezdődnie. A kulcs 1–128 karakteres lehet: betűket, számjegyeket, ., _ és - karaktereket tartalmazhat, és betűvel vagy számjeggyel kell kezdődnie. Ugyanazon idempotenciakulcs elküldése azonos bodyval az első választ adja vissza újra; eltérő bodyval viszont conflict hibával meghiúsul. Ha egy írási művelet expectedVersion értéke nem az aktuális verzió, a kérés stale_version hibával meghiúsul: olvasd be újra a rekordot, és próbáld meg ismét.

Backend-műveletekHivatkozás másolása

A műveletek épp fordítva működnek: egy worker meghívja a useAction(actionId) függvényt, a Poltura pedig egy aláírt POST kérést küld a { input, context } tartalommal a backendOrigin címedre. Ezek nem részei az App API-nak; lásd: Aláírt műveletek. Telepítésenkénti korlátok: percenként 60 hívás az adminfelületről és 300 a webáruházból, valamint percenként 10 hívás vásárlónként. Ha egy hívás nem tud lefutni, a worker a következő hibakódok egyikét kapja: not_declared, timeout, upstream, too_large vagy unavailable.

HibákHivatkozás másolása

A sikertelen hívások PolturaRequestError hibát dobnak code, status, requestId (segítségkéréskor ezt add meg) és rate_limited esetén retryAfterMs mezőkkel. Ha a kérésre egyáltalán nem érkezett válasz, a kód a következők egyike: response_too_large, invalid_response, request_failed, aborted vagy unavailable.

Az API hibaüzenetének bodyja { "error": { "code", "message", "requestId", "details"?, "retryAfterMs"? } }, az alábbi kódokkal:

Az OpenAPI 3.1 specifikáció az /openapi.json címen található, amelyet az SDK-val azonos sémákból generálunk.

További lépésekHivatkozás másolása

• Első API-hívásod: hogyan jut tokenhez a szervered, és egy lapozható terméklista.
• Hitelesítés: tokenek, frissítés és jogosultságok.