API reference

createMxik

function createMxik(options?: MxikOptions): Mxik

Creates a client. All options are described in Client options.

search

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

Full-text search by name, brand, attributes or code. See By keyword.

get

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

Full card of a code, or null if it doesn't exist. See A single code.

filter

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

Search by text, brand, code or barcode. See By fields.

dvCert

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

Codes linked to a certificate number. See By certificate number.

card

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

Card of a code with names in one language, barcode, short name, tax benefit and packages, or null if it doesn't exist. See A single code.

searchSubpositions

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

Search by product type, returns sub-position codes without a brand. See By product type.

children, childrenAll

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

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

Groups when called without a code, otherwise the next level of the tree under code. Rejects with TypeError for codes without children. See Tree.

stats, units, taxBenefits

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

Catalog size, units of measurement and tax benefits. See Reference data.

searchAll, filterAll

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

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

type AllOptions = Omit<PageOptions, 'page'>

Go through every page, requesting the next one as you iterate. See All results.

cache.clear

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

Removes cached results. Does nothing when the cache is off. See Cache.

createMemoryCache

function createMemoryCache(options?: MemoryCacheOptions): MemoryCache

interface MemoryCacheOptions {
  ttl?: number // ms, default 1 hour
  max?: number // entries, default 500
}

interface MemoryCache extends MxikCache {
  readonly size: number
}

In-memory cache that evicts the least recently used entry beyond max. cache: true creates one with the defaults.

MxikCache

interface MxikCache {
  get: (key: string) => unknown // undefined when missing
  set: (key: string, value: unknown) => unknown
  delete: (key: string) => unknown
  clear: () => unknown // called by mxik.cache.clear()
}

What the cache option accepts. Methods may return promises. See Your own cache.

isMxikCode

function isMxikCode(value: unknown): value is string

Whether value is a string of exactly 17 digits. Doesn't check that the code exists.

MxikError

class MxikError extends Error {
  status: number // HTTP status
  reason?: string // message from the API
}

Thrown when the API returns an error or a response that isn't JSON. See Errors.

Types

Included from the source code, so they always match the published package.

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
}

Deprecated

MxikClient, createMxikClient(), fetchByKeyword(), fetchByParams(), fetchByBrand(), fetchByBarcode(), fetchByCode() and fetchByDvCert() return raw API responses and will be removed in 2.0. See Migrating from 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