Skip to content

PUBLIC_API.md

Latest commit

 

History

History
250 lines (191 loc) · 7.24 KB

PUBLIC_API.md

File metadata and controls

250 lines (191 loc) · 7.24 KB
Raw

Публичный API

Пакет Ozon

npm i @seller-sdk/ozon
import { OzonClient } from "@seller-sdk/ozon";

const ozon = new OzonClient({ clientId, apiKey });

Пакет самостоятельный: он не устанавливает seller-sdk, отдельный core или будущие marketplace-пакеты.

Пакет Wildberries

npm i @seller-sdk/wb
import { WbClient, WbValues } from "@seller-sdk/wb";

const wb = new WbClient({ token: process.env.WB_API_TOKEN! });
const result = await wb.general.getPing();
const tariffOptions = await wb.general.getTariffConstructorOptions({
  query: { locale: WbValues.GetV1TariffConstructorOptionsLocale.Ru },
});

Пакет включает все 286 операций из локального официального Swagger и не устанавливает Ozon или umbrella-пакет.

Пакет Yandex Market

npm i @seller-sdk/ym
import { YmClient, YmValues } from "@seller-sdk/ym";

const ym = new YmClient({ apiKey: process.env.YM_API_KEY! });
await ym.orders.getBusinessOrders({
  path: { businessId: 123456 },
  body: { statuses: [YmValues.OrdersOrderStatusType.Processing] },
});

Пакет содержит 165 операций официального Partner API snapshot.

Общий пакет

npm i seller-sdk
import { Marketplace, SellerClient } from "seller-sdk";

const seller = new SellerClient({
  marketplace: Marketplace.Ozon,
  credentials: { clientId, apiKey },
});

Поддерживаемые маркетплейсы образуют закрытый типизированный набор:

export const Marketplace = {
  Ozon: "ozon",
  Wb: "wb",
  Ym: "ym",
} as const;

Литералы "ozon", "wb" и "ym" также допустимы. Произвольная строка не принимается.

Реестр маркетплейсов

Marketplace связывает credentials и конкретный client type:

export interface MarketplaceRegistry {
  ozon: {
    credentials: OzonCredentials;
    client: OzonClient;
  };
  wb: {
    credentials: WbCredentials;
    client: WbClient;
  };
  ym: {
    credentials: YmCredentials;
    client: YmClient;
  };
}
const seller = new SellerClient({
  marketplace: Marketplace.Wb,
  credentials: { token: process.env.WB_API_TOKEN! },
});

await seller.wb.items.getContentObjectParentAll({
  query: { locale: "ru" },
});

Публичный конструктор не использует marketplace: string или универсальный Record<string, string> для credentials.

Области Ozon

Каждая операция доступна через предметную область:

await ozon.products.list(input);
await ozon.postings.fbs.list(input);
await ozon.finance.accruals.byDay(input);
await ozon.warehouses.listWarehouses(input);

ozon.domains предоставляет тот же полный registry, когда области нужно перечислить или передать одним объектом.

Плоские методы вроде ozon.listProducts() не входят в публичный API.

Версии

По умолчанию используйте метод без версии:

await ozon.warehouses.listWarehouses(input); // сейчас v2
await wb.general.getNews(input); // сейчас v2

Для намеренной фиксации контракта используйте явную версию:

await ozon.warehouses.listWarehousesV2(input);
await wb.general.getV2News(input);

Алиас наследует @deprecated, если маркетплейс пометил выбранный endpoint устаревшим.

У YM текущие официальные operationId уже не содержат V1/V2, поэтому ym.orders.getBusinessOrders(...) одновременно является точным и рекомендуемым именем. Версия сохраняется только в HTTP path.

Конфигурация клиента

const ozon = new OzonClient(
  { clientId, apiKey },
  {
    timeoutMs: 30_000,
    deadlineMs: 60_000,
    maxRetries: 2,
    onResponse(metadata) {
      observe(metadata);
    },
  },
);
Опция Значение по умолчанию Назначение
timeoutMs 30_000 Тайм-аут одной попытки
deadlineMs 60_000 Общий дедлайн со всеми повторами
maxRetries 2 Повторы безопасной операции после первой попытки
onResponse — Observer HTTP-метаданных

Опции отдельного запроса

await ozon.products.list(input, {
  signal,
  timeoutMs: 10_000,
  deadlineMs: 30_000,
  maxRetries: 1,
});

Опции запроса переопределяют client defaults. Мутации всегда выполняются одной попыткой.

Пагинация

for await (const page of ozon.products.listPages(input)) {
  console.log(page.result?.items);
}

for await (const product of ozon.products.listAll(input)) {
  console.log(product.offer_id);
}

Generic helpers paginateOzonPages, paginateOzonItems и collectOzonItems экспортируются из @seller-sdk/ozon и seller-sdk.

Прямой запрос к API

const result = await ozon.rawRequest<{ result: unknown }>(
  "POST",
  "/v1/new-operation",
  body,
  { retrySafety: "safe" },
);

Путь ограничен https://api-seller.ozon.ru. Ответ содержит data и lastResponse, но не получает endpoint-specific runtime validation.

Ошибки

Пакеты экспортируют стабильные SDK errors:

SellerSdkError;
ConfigurationError;
ApiError;
AuthenticationError;
RateLimitError;
NetworkError;
TimeoutError;
ResponseValidationError;
toSellerSdkErrorDetails;

ApiError содержит status, operationId, requestId, apiCode, apiMessage и retryAfterMs, когда Ozon передал соответствующие значения. toSellerSdkErrorDetails(error) преобразует любую пойманную ошибку в единый сериализуемый SellerSdkErrorDetails. Структурное распознавание поддерживает ошибки всех focused-пакетов без зависимости от конкретной копии core. SafeShape-specific error types не являются частью публичного API.

Динамическая конфигурация

Данные из env, JSON и внешних источников считаются unknown и проходят runtime-валидацию перед созданием клиента. TypeScript сам по себе не защищает динамическую конфигурацию.