SDK Node.js

Пакет @inlog-sdk/postomat — типизированный клиент интеграционного API постоматов для Node.js. Страница описывает версию 1.1.0.

Установка

npm install @inlog-sdk/postomat

• Node.js 18 или новее (используется встроенный fetch).
• Пакет распространяется в формате ES-модулей (import), типы TypeScript входят в пакет.
• Используйте SDK только на сервере: он работает с токеном компании.

Создание клиента

import { createPostomatClient } from '@inlog-sdk/postomat'

const client = createPostomatClient({
  apiKey: 'YOUR_API_KEY', // храните токен в секретах сервера
  // baseURL по умолчанию — продакшн. Для тестового окружения:
  baseURL: 'http://api.test.postomat.inlog.ai/api/v1/integration/company',
  timeoutMs: 12_000,
  userAgent: 'my-company-integration/1.0.0',
  retry: { maxRetries: 3, baseDelayMs: 400, maxDelayMs: 5000 },
})

Параметры createPostomatClient

Параметр	Тип	По умолчанию	Описание
apiKey	string	—	Обязательный. Токен компании. Без него клиент бросает Error('apiKey is required')
baseURL	string	https://postomat-api-1.inlog.ai/api/v1/integration/company	Базовый URL интеграционного API
timeoutMs	number	12000	Таймаут одной попытки запроса, мс
retry.maxRetries	number	3	Максимум повторов
retry.baseDelayMs	number	400	Базовая задержка экспоненциального бэкоффа, мс
retry.maxDelayMs	number	5000	Верхняя граница задержки, мс
userAgent	string	postomat-sdk/1.x (+https://npmjs.com)	Заголовок User-Agent
authHeader	string	Authorization	Имя заголовка авторизации
authScheme	'Bearer' | ''	'Bearer'	Схема авторизации; '' — передавать токен без схемы
fetch	function	globalThis.fetch	Собственная реализация fetch

Ресурсы

Метод SDK	HTTP
orders.create(body, options?)	POST /order/create
orders.getById(id, query?, options?)	GET /order/{id}
orders.list(query, options?)	GET /order/list
orders.getDownCode(id, options?)	GET /order/{id}/down-code
orders.getUpCode(id, options?)	GET /order/{id}/up-code
orders.getSubtractCode(id, options?)	GET /order/{id}/subtract-code
postomats.list(query, options?)	GET /postomat/list
postomats.getById(id, query?, options?)	GET /postomat/{id}
cells.getFreeCells(postomatId, options?)	GET /cell/{postomatId}/free-cells
cities.list(query, options?)	GET /city
cities.getById(id, query?, options?)	GET /city/{id}
districts.list(query?, options?)	GET /district/list
utils.paginate(fetchPage, opts?)	Обход страниц (см. ниже)

Для справочника стран (GET /country) отдельного метода в SDK нет — вызывайте эндпоинт напрямую.

Параметры запросов и поля ответов совпадают с API — см. Заявки, Постоматы и ячейки, Справочники.

Параметры отдельного запроса (options)

Поле	Тип	Описание
idempotencyKey	string	Передаётся в заголовке Idempotency-Key (см. ограничения ниже)
headers	Record<string, string>	Дополнительные заголовки
timeoutMs	number	Таймаут этого запроса
signal	AbortSignal	Отмена запроса

Создание заявки

const order = await client.orders.create({
  toUserPhone: '+996700000000',
  postomatId: 'tz4a98xxat96iws9zmbrgj3a',
  sendMessage: true,
  customData: 'partner-order-12345',
})
console.log(order.id)

Передавайте sendMessage явно

В типе CreateOrderBody пакета поле sendMessage помечено как необязательное, но API требует его в каждом запросе. Без sendMessage запрос завершится ошибкой 400.

Списки и пагинация

Списки API возвращают данные в поле data: { total, data: [...] }. Типы пакета по умолчанию описывают поле items — передайте свой тип через параметр метода или читайте data:

import type { Order } from '@inlog-sdk/postomat'

const page = await client.orders.list<{ total: number; data: Order[] }>({ page: 1, pageSize: 50 })
page.data.forEach((order) => console.log(order.id))

utils.paginate перебирает элементы из поля items и останавливается, когда страница короче pageSize. Поэтому в fetchPage переложите data в items и используйте одинаковый размер страницы:

const pageSize = 50

for await (const order of client.utils.paginate(
  async (page) => {
    const res = await client.orders.list({ page, pageSize })
    return { items: res.data }
  },
  { pageSize },
)) {
  console.log(order.id)
}

Ошибки

Ошибки API и сети выбрасываются как ApiError:

Поле	Описание
status	HTTP-статус; 0 — сетевая ошибка или таймаут
message	Значение поля message из тела ответа — для бизнес-ошибок здесь код, например ORDER_NOT_FOUND
code	Значение поля code из тела ответа. У бизнес-ошибок API такого поля нет, поэтому code будет undefined; заполнено у ошибок валидации (FST_ERR_VALIDATION)
requestId	Значение заголовка ответа x-request-id, если он есть; сейчас API его не передаёт
details	Разобранное тело ответа

import { ApiError } from '@inlog-sdk/postomat'

try {
  await client.orders.getById('gfb0sfr5ahkhu9dns4bja2ly')
} catch (err) {
  if (err instanceof ApiError) {
    if (err.status === 404 && err.message === 'ORDER_NOT_FOUND') {
      // заявка не найдена
    } else if (err.status === 400) {
      console.error('Ошибка валидации:', err.message)
    } else {
      console.error('API error', err.status, err.message)
    }
  } else {
    throw err
  }
}

Каталог кодов — на странице Ошибки и ретраи.

Ретраи

SDK автоматически повторяет запрос:

• при ответах 429 и 5xx;
• при сетевых ошибках (кроме таймаута — таймаут сразу завершается ApiError со status: 0).

Задержка: baseDelayMs × 2^(попытка − 1), но не больше maxDelayMs. Если в ответе есть Retry-After, используется он (тоже не больше maxDelayMs). Ответы 4xx (кроме 429) не повторяются.

Ретраи и создание заявок

Ретраи применяются ко всем методам, включая orders.create. SDK передаёт idempotencyKey в заголовке Idempotency-Key, но API сейчас не удаляет дубликаты по этому заголовку: повтор после 5xx или обрыва соединения может создать вторую заявку.

Для создания заявок отключите автоповторы отдельным клиентом и перед ручным повтором проверяйте, не создалась ли заявка (по своему идентификатору в customData через orders.list):

const createClient = createPostomatClient({
  apiKey: 'YOUR_API_KEY',
  retry: { maxRetries: 0 },
})