Справочник API

createMxik

function createMxik(options?: MxikOptions): Mxik

Создаёт клиент. Все опции описаны в разделе Настройки клиента.

search

mxik.search(
  query: string,
  options?: PageOptions,
): Promise<Page<SearchItem>>

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

get

mxik.get(
  code: string,
  options?: RequestOptions,
): Promise<MxikDetails | null>

Полная карточка кода или null, если его не существует. См. Отдельный код.

filter

mxik.filter(
  filters: Filters,
  options?: PageOptions,
): Promise<Page<CatalogItem>>

Поиск по text, brand, code или barcode. См. По полям.

dvCert

mxik.dvCert(
  certNumber: string,
  options?: PageOptions,
): Promise<Page<CatalogItem>>

Коды, связанные с номером сертификата. См. По номеру сертификата.

card

mxik.card(
  code: string,
  options?: RequestOptions,
): Promise<MxikCard | null>

Карточка кода с названиями на одном языке, штрихкодом, кратким названием, льготой и упаковками или null, если кода не существует. См. Отдельный код.

searchSubpositions

mxik.searchSubpositions(
  query: string,
  options?: PageOptions,
): Promise<Page<CatalogItem>>

Поиск по типу товара, возвращает коды субпозиций без бренда. См. По типу товара.

children, childrenAll

mxik.children(
  code?: string,
  options?: ChildrenOptions,
): Promise<Page<CatalogNode>>

mxik.childrenAll(
  code?: string,
  options?: Omit<ChildrenOptions, 'page'>,
): AsyncGenerator<CatalogNode>

Без кода возвращает группы, с кодом — следующий уровень дерева под ним. Для кодов без потомков отклоняется с TypeError. См. Дерево.

stats, units, taxBenefits

mxik.stats(options?: RequestOptions): Promise<CatalogStats>
mxik.units(options?: RequestOptions): Promise<Unit[]>
mxik.taxBenefits(options?: RequestOptions): Promise<TaxBenefit[]>

Размер каталога, единицы измерения и льготы. См. Справочники.

searchAll, filterAll

mxik.searchAll(
  query: string,
  options?: AllOptions,
): AsyncGenerator<SearchItem>

mxik.filterAll(
  filters: Filters,
  options?: AllOptions,
): AsyncGenerator<CatalogItem>

type AllOptions = Omit<PageOptions, 'page'>

Проходят по всем страницам, запрашивая следующую по ходу перебора. См. Все результаты.

cache.clear

mxik.cache.clear(): Promise<void>

Удаляет результаты из кеша. Если кеш выключен, ничего не делает. См. Кеш.

createMemoryCache

function createMemoryCache(options?: MemoryCacheOptions): MemoryCache

interface MemoryCacheOptions {
  ttl?: number // мс, по умолчанию 1 час
  max?: number // записей, по умолчанию 500
}

interface MemoryCache extends MxikCache {
  readonly size: number
}

Кеш в памяти, который при превышении max вытесняет запись, дольше всего не использовавшуюся. cache: true создаёт его с настройками по умолчанию.

MxikCache

interface MxikCache {
  get: (key: string) => unknown // undefined, если записи нет
  set: (key: string, value: unknown) => unknown
  delete: (key: string) => unknown
  clear: () => unknown // вызывается из mxik.cache.clear()
}

Что принимает опция cache. Методы могут возвращать промисы. См. Свой кеш.

isMxikCode

function isMxikCode(value: unknown): value is string

Является ли value строкой ровно из 17 цифр. Существование кода не проверяет.

MxikError

class MxikError extends Error {
  status: number // HTTP-статус
  reason?: string // сообщение от API
}

Выбрасывается, когда API возвращает ошибку или ответ не в JSON. См. Ошибки.

Типы

Подключены прямо из исходного кода, поэтому всегда совпадают с опубликованным пакетом. Комментарии в них на английском.

import type { MxikCache } from './cache'

/**
 * Response language. The API supports only Russian and Uzbek (cyrillic),
 * any other value silently falls back to `uz`.
 */
export type Lang = 'ru' | 'uz'

export interface MxikOptions {
  /** Default response language. @default 'ru' */
  lang?: Lang
  /** Default page size for paginated methods. @default 20 */
  pageSize?: number
  /** Request timeout in ms, `0` disables it. @default 10_000 */
  timeout?: number
  /** @default 'https://tasnif.soliq.uz/api/cls-api' */
  baseURL?: string
  /** Custom fetch implementation (tests, proxies, edge runtimes). */
  fetch?: typeof globalThis.fetch
  /** Extra headers sent with every request. */
  headers?: Record<string, string>
  /**
   * Caches successful results, errors are never cached. Off by default.
   * `true` uses `createMemoryCache()`: in memory, 1 hour TTL, 500 entries.
   */
  cache?: boolean | MxikCache
}

export interface RequestOptions {
  lang?: Lang
  signal?: AbortSignal
}

export interface PageOptions extends RequestOptions {
  /** 1-based page number. @default 1 */
  page?: number
  size?: number
}

export interface Page<T> {
  items: T[]
  /** Total number of matching records across all pages. */
  total: number
  /** 1-based page number. */
  page: number
  size: number
  hasNext: boolean
}

export interface Filters {
  /** Full-text match over code, name, brand and attributes. */
  text?: string
  /** Brand name, partial and case-insensitive. */
  brand?: string
  /** Exact 17-digit MXIK code. */
  code?: string
  /** Product barcode (GTIN). When set, the API ignores all other filters. */
  barcode?: string
}

/** Item returned by `search()`. */
export interface SearchItem {
  mxikCode: string
  name: string
  fullName: string
  description: string | null
  /** Barcode (GTIN). */
  internationalCode: string | null
  label: string
  groupCode: string
  groupName: string
  classCode: string
  className: string
  positionCode: string
  positionName: string
  subPositionCode: string
  subPositionName: string
  brandCode: string
  brandName: string | null
  attributeName: string | null
  usePackage: string
  categoryUnitId: string | null
  categoryUnitName: string | null
  unitsName: string | null
  surveyCategoryId: string | null
  nonChangeable: string
  lgotaId: string | null
  lgotaName: string | null
  recommendedCategoryUnitName: string | null
  recommendedUnitsName: string | null
  packageName: string | null
  useCard: string
  property: string | null
  categoryCode: string
  categoryName: string
  mnnName: string | null
}

/** Item returned by `filter()` and `dvCert()`. */
export interface CatalogItem {
  mxikCode: string
  mxikName: string
  groupCode: string
  groupName: string
  classCode: string
  className: string
  positionCode: string
  positionName: string
  subPositionCode: string
  subPositionName: string
  brandCode: string
  brandName: string
  attributeName: string
  /** Barcode (GTIN). */
  internationalCode: string | null
  unitCode: string | null
  unitName: string | null
  commonUnitCode: string | null
  commonUnitName: string | null
  label: number
  myProduct: number
  units: unknown
  packages: unknown
}

export interface MxikPackage {
  code: number
  mxikCode: string
  packageType: string
  nameRu: string
  nameUz: string
  nameLat: string
}

/** Full card of a single MXIK code, names in every language. */
export interface MxikDetails {
  id: string
  pkey: string | null
  parentPkey: string | null
  mxikCode: string
  groupNameRu: string
  groupNameUz: string
  groupNameLat: string | null
  classNameRu: string
  classNameUz: string
  classNameLat: string | null
  positionNameRu: string
  positionNameUz: string
  positionNameLat: string | null
  subPositionNameRu: string
  subPositionNameUz: string
  subPositionNameLat: string | null
  brandName: string
  attributeNameRu: string
  attributeNameUz: string
  attributeNameLat: string | null
  description: string | null
  isActive: string
  /** `dd.MM.yyyy HH:mm:ss` */
  createdAt: string
  /** `dd.MM.yyyy HH:mm:ss` */
  updatedAt: string
  updatedBy: string | null
  status: number
  packageNames: MxikPackage[]
}

export interface ChildrenOptions extends PageOptions {
  /** Filter children by name. */
  text?: string
}

/** One entry of the catalog tree: a group, class, position, sub-position, brand or code. */
export interface CatalogNode {
  /**
   * 3 digits for a group, then 5 for a class, 8 for a position,
   * 11 for a sub-position, 14 for a brand and 17 for a code.
   */
  code: string
  /** `null` for the "no brand" entry of a sub-position. */
  name: string | null
  /** Number of codes under this node. */
  count: number
  /** Barcode (GTIN), only on 17-digit codes. */
  internationalCode?: string | null
}

export interface MxikCardPackage {
  code: number
  parentCode: number | null
  mxikCode: string
  /** Package name, e.g. `шт. (пачка) 20 грамм`. */
  name: string
  unitId: number | null
  unitName: string | null
  /** Amount of `unitName` in the package. */
  parentValue: number | null
  containerCode: number | null
  containerName: string | null
  type: string
  isUnitPackage: string
  /** `dd.MM.yyyy HH:mm:ss` */
  createdAt: string
  createdBy: string | null
  children: MxikCardPackage[]
}

/** Card of a single code from `card()`, names in the requested language. */
export interface MxikCard {
  mxikCode: string
  mxikName: string
  /** Abbreviated name. */
  shortName: string | null
  groupCode: string
  groupName: string
  classCode: string
  className: string
  positionCode: string
  positionName: string
  subPositionCode: string
  subPositionName: string
  brandCode: string
  brandName: string | null
  attributeName: string | null
  /** Barcode (GTIN). */
  internationalCode: string | null
  unitCode: string | null
  unitName: string | null
  commonUnitCode: string | null
  commonUnitName: string | null
  /** Tax benefit id, see `taxBenefits()`. */
  lgotaId: number | null
  lgotaName: string | null
  /** International non-proprietary name, for medicines. */
  mnnName: string | null
  label: number
  useCard: number
  myProduct: number
  units: unknown
  packages: MxikCardPackage[] | null
}

/** Size of the catalog, from `stats()`. */
export interface CatalogStats {
  groupCount: number
  classCount: number
  positionCount: number
  subPositionCount: number
  brandCount: number
  mxikCount: number
}

/** Unit of measurement, from `units()`. */
export interface Unit {
  id: number
  name: string
}

/** Tax benefit (льгота / imtiyoz), from `taxBenefits()`. */
export interface TaxBenefit {
  id: number
  nameRu: string
  nameUz: string
  nameLatn: string
  docNum: number
  /** Document date, ms since epoch. */
  docDate: number
  docNameRu: string
  docNameUz: string
  docNameLatn: string
  oldId: number | null
}

Устаревшее

MxikClient, createMxikClient(), fetchByKeyword(), fetchByParams(), fetchByBrand(), fetchByBarcode(), fetchByCode() and fetchByDvCert() возвращают сырые ответы API и будут удалены в 2.0. См. Переход с 1.1.

import type { CatalogItem, MxikPackage, SearchItem } from '../types'

/** Raw API envelope. @deprecated Use the unwrapped results of `createMxik()`. */
export interface ResponseSchema<Data> {
  success: boolean
  code: number
  reason: string
  data: Data | null
  recordTotal?: number
  errors: any
}

/** Raw paginated API envelope. @deprecated Use `Page<T>` from `createMxik()`. */
export interface ResponseSchemaWithContent<Data> {
  success: boolean
  code: number
  reason: string
  data: {
    content: Data | null
    empty: boolean
    first: boolean
    last: boolean
    number: number
    numberOfElements: number
    size: number
    totalElements: number
    totalPages: number
    pageable: {
      offset: number
      pageNumber: number
      pageSize: number
      paged: boolean
      unpaged: boolean
      sort: ResponseSort
    }
    sort: ResponseSort
  }
  errors: any
}

/** @deprecated */
export interface ResponseSort {
  empty: boolean
  sorted: boolean
  unsorted: boolean
}

/** @deprecated Use `SearchItem`. */
export type SearchResultItem = SearchItem

/** @deprecated Use `CatalogItem`. */
export type DvCertItem = CatalogItem

/** @deprecated Use `CatalogItem`. */
export interface ByParamsResultItem extends CatalogItem {
  [key: string]: any
}

/** @deprecated Use `MxikPackage`. */
export type PackageName = MxikPackage

Справочник API ​

createMxik ​

search ​

get ​

filter ​

dvCert ​

card ​

searchSubpositions ​

children, childrenAll ​

stats, units, taxBenefits ​

searchAll, filterAll ​

cache.clear ​

createMemoryCache ​

MxikCache ​

isMxikCode ​

MxikError ​

Типы ​

Устаревшее ​