Логистика и маркетплейс

На странице описаны две группы:

/api/v1/integrations/logistic-company — справочник логистических компаний, поставщики, списки посылок и грузов вашей компании;
/api/v1/integrations/market-company — API для маркетплейсов: пункты выдачи, создание посылок, статус и переадресация.

Все запросы требуют заголовок x-api-token: YOUR_API_KEY. Данные о посылках и грузах ограничены клиентами вашей компании.

Логистические компании

Список логистических компаний

GET /api/v1/integrations/logistic-company/list

Возвращает активные компании типа LOGIST с их страной, городом, кодами, типами доставки и типами грузов.

Параметр	Тип	Описание
`isIntercity`	boolean	Только компании с межгородской доставкой (`true`) или без неё (`false`)
`isInternational`	boolean	Только компании с международной доставкой (`true`) или без неё (`false`)
`isCleaning`	boolean	Отбор по признаку `isCleaning` компании

Ответ 200 — массив компаний (без пагинации).

Компания по ID

GET /api/v1/integrations/logistic-company/{id}

Параметр	Где	Тип	Описание
`id`	path	integer, ≥ 1	ID компании

Ответ 200 — объект активной компании или null. Основные поля — как у карточки компании.

Страны и города

GET /api/v1/integrations/logistic-company/countries

Ответ 200: { "total": number, "data": [Country] } — все активные страны, у каждой — массив cities.

Поставщики

Поставщик (supplier) — отправитель посылок, зарегистрированный у вашей компании.

Поставщик по телефону

GET /api/v1/integrations/logistic-company/supplier/by-phone?phone=%2B996700000000

Параметр	Тип	Обязательный	Описание
`phone`	string	да	Телефон поставщика — точное совпадение. Символ `+` в query кодируйте как `%2B`

Ответ 200 — активный поставщик вашей компании или null:

json

{
  "id": 88,
  "name": "ИП Поставщик",
  "phone": "+996700000000",
  "address": "ул. Примерная, 1",
  "isActive": true,
  "companyId": 12,
  "cityId": 1
}

Посылки поставщика

GET /api/v1/integrations/logistic-company/supplier/{id}/parcels

Параметр	Где	Тип	Описание
`id`	path	integer	ID поставщика вашей компании
`page`, `pageSize`	query	integer	Пагинация. Без параметров возвращаются все посылки
`search`	query	string	Поиск — как у списка посылок
`statuses`	query	enum[]	Статусы посылки, см. фильтр по статусам
`isPayed`	query	boolean	Фильтр по оплате заказа

Ответ — как у списка посылок. Поставщик не найден или принадлежит другой компании — 404 с message: "Supplier not found".

Списки посылок и грузов

Список посылок

GET /api/v1/integrations/logistic-company/parcel/list

Список грузов

GET /api/v1/integrations/logistic-company/cargo/list

Оба списка возвращают { "total": number, "data": [...] } — посылки или грузы клиентов вашей компании. Посылки упорядочены по убыванию ID.

Общие параметры

Параметр	Тип	По умолчанию	Описание
`page`	integer, ≥ 1	`1`	Страница
`pageSize`	integer, ≥ 1	`10`	Размер страницы
`code`	integer, ≥ 1	—	Код одного клиента вашей компании
`codes`	integer[]	—	Коды нескольких клиентов: `codes=101&codes=102`. Если передан, `code` не учитывается
`search`	string	—	Строка поиска, см. ниже
`statuses`	enum[]	—	Статусы: `statuses=SENT&statuses=RECEIVED`
`isPayed`	boolean	—	`true` — только с оплаченным заказом, `false` — только с неоплаченным. Посылки и грузы без заказа не попадают ни в один из вариантов
`arrivedAtFinal`	boolean	—	Уточнение статусного фильтра, см. специальные наборы

Дополнительно:

у cargo/list — cargoTypes (enum[]: CARGO, CAR, PACKAGE, FREIGHT) — отбор по категории груза;
у parcel/list — strictArrived (boolean), см. специальные наборы.

Неизвестное значение в statuses или cargoTypes — 400.

Поиск (`search`)

Формат	Пример	Что ищется
`<название кода>-<код клиента>`	`INL-123`	Посылки или грузы клиента с кодом `123` (название кода — без учёта регистра)
Любая другая строка	`ABC12`	Посылки: трек-код, описание, название кода, имя или телефон клиента. Грузы: описание, название кода, имя или телефон клиента, название логистической компании, номер тягача. Если строка — целое число, дополнительно ищется клиент с таким кодом

Как search вида INL-123 сочетается с code/codes:

Ситуация	Результат
`codes` не передан, `code` не передан	Посылки клиента `123` вашей компании
`codes` передан и содержит `123`	Посылки только клиента `123`
`codes` передан и не содержит `123`	Пустой результат `{ "total": 0, "data": [] }`
`code` передан и не равен `123`	Пустой результат

Фильтр по статусам

Статусы посылки: AWAITING, RECEIVED, READYTOSHIP, COURIER_RECEIVED, SENT, REDIRECT_TO_PVZ, RECALL, ARRIVED, TRANSFERRED, COMPLETED, LOST — см. Жизненный цикл посылки. Статусы груза: RECEIVED, READYTOSHIP, SENT, TRANSFERRED, LOST.

В общем случае фильтр выбирает записи с текущим статусом из списка. Особенности parcel/list:

RECEIVED выбирает посылки, принятые на склад, который не является пунктом выдачи;
ARRIVED выбирает посылки в статусе ARRIVED и посылки в статусе RECEIVED на складе — пункте выдачи.

Специальные наборы статусов

Для типовых вкладок «Получено» и «В пути» используйте точные наборы статусов вместе с arrivedAtFinal. В любых других сочетаниях arrivedAtFinal и strictArrived не влияют на результат.

parcel/list

`statuses` (порядок не важен)	`arrivedAtFinal`	`strictArrived`	Что выбирается
`ARRIVED`, `RECEIVED`	`true`	—	Посылки, прибывшие в конечную точку: в пункт выдачи, на свой склад доставки, в постомат или к двери получателя
`ARRIVED`, `READYTOSHIP`, `RECALL`, `RECEIVED`, `REDIRECT_TO_PVZ`, `SENT`	`false`	—	Посылки в этих статусах, кроме прибывших в конечную точку
`ARRIVED`	`true`	`true`	Посылки в статусе `ARRIVED` в конечной точке, по которым создан заказ на оплату
`ARRIVED`, `READYTOSHIP`, `RECALL`, `RECEIVED`, `REDIRECT_TO_PVZ`, `SENT`	`false`	`true`	Посылки в этих статусах, кроме выбранных предыдущей строкой

cargo/list

`statuses` (порядок не важен)	`arrivedAtFinal`	Что выбирается
`RECEIVED`	`true`	Грузы, принятые на свой склад доставки или в пункт выдачи
`READYTOSHIP`, `RECEIVED`, `SENT`	`false`	Грузы в этих статусах, кроме выбранных предыдущей строкой

Пример

curlJavaScript (fetch)

bash

curl "https://api.inlog.ai/api/v1/integrations/logistic-company/parcel/list?page=1&pageSize=20&statuses=ARRIVED&statuses=RECEIVED&arrivedAtFinal=true&codes=123&isPayed=false" \
  -H "x-api-token: YOUR_API_KEY"

const url = new URL('https://api.inlog.ai/api/v1/integrations/logistic-company/parcel/list')
url.searchParams.set('page', '1')
url.searchParams.set('pageSize', '20')
url.searchParams.append('statuses', 'ARRIVED')
url.searchParams.append('statuses', 'RECEIVED')
url.searchParams.set('arrivedAtFinal', 'true')
url.searchParams.append('codes', '123')
url.searchParams.set('isPayed', 'false')

const { total, data } = await (await fetch(url, { headers: { 'x-api-token': 'YOUR_API_KEY' } })).json()

Элемент data у parcel/list содержит поля посылки (id, trackCode, description, weight, price, deliveryMethod, postomatId, postomatOrderId, createdAt и др.) и связанные объекты: currentStatus (с городами и складами отправления и назначения), statuses, client, order (с валютой), type, slot, currentWarehouseCompany, logisticCompany, expenses, receiptCity, deliveryCity, originWarehouse, deliveryWarehouse. Элемент cargo/list устроен аналогично.

Маркетплейс (`market-company`)

Пункты выдачи

Эндпоинт	Назначение
`GET /api/v1/integrations/market-company/opp/list`	Список пунктов выдачи
`GET /api/v1/integrations/market-company/opp/{id}`	Пункт выдачи по ID
`GET /api/v1/integrations/market-company/opp/city`	Список городов
`GET /api/v1/integrations/market-company/opp/city/{id}`	Город по ID

Параметры opp/list:

Параметр	Тип	Обязательный	Описание
`page`	integer, ≥ 1	да	Страница
`pageSize`	integer, 1–500	да	Размер страницы
`ids`	integer[]	нет	Отбор по ID: `ids=40&ids=41`
`cityId`, `countryId`	integer	нет	Отбор по городу и стране
`withCity`, `withCountry`	boolean	нет	Добавить `city`, `country`
`latitude`, `longitude`	number	нет	Сортировка по расстоянию до точки; у элементов появляется `distance` (км), пункты без координат исключаются

Ответ opp/list: { "data": [...], "total": number }. Поля пункта выдачи: id, title, titleCN, titleEN, titleKY, address, lat, lng, schedule, schedules, cityId, countryId, createdAt, updatedAt. Для opp/{id} доступны withCity и withCountry.

Параметры opp/city: page и pageSize (обязательны, pageSize 1–500), withCountry. Возвращает все активные города: { "total", "data" }. Для opp/city/{id} доступен withCountry.

Создание посылки

POST /api/v1/integrations/market-company/parcel/create
Idempotency-Key: <уникальный ключ запроса>
Content-Type: application/json

Создаёт посылку для получателя — в постомат или в пункт выдачи. Получатель и отправитель регистрируются у вашей компании как клиент и поставщик (по номеру телефона; существующие записи переиспользуются).

Идемпотентность

Заголовок Idempotency-Key обязателен. Повторный запрос с тем же ключом в течение часа возвращает сохранённый ответ первого запроса и не создаёт новую посылку.

Поле	Тип	Обязательное	Описание
`deliveryMethod`	`POSTOMAT` \| `PICKUP`	да	Доставка в постомат или в пункт выдачи
`postomatId`	string	для `POSTOMAT`	ID постомата (см. Постоматы через платформу)
`warehouseId`	integer, ≥ 1	для `PICKUP`	ID пункта выдачи из `opp/list`
`createPostomatOrder`	boolean	нет, по умолчанию `false`	Для `POSTOMAT`: сразу создать заявку в постомат и вернуть код закладки
`trackCode`	string	нет	Трек-код. Если не передан, генерируется. Должен быть уникальным
`weight`	number, ≥ 0.01	да	Вес
`price`	number, ≥ 0	нет, по умолчанию `0`	Стоимость
`currency`	string, 3 символа	да	Код валюты ISO 4217, например `KGS`
`receiver`	object	да	Получатель, см. ниже
`sender`	object	да	Отправитель, см. ниже

Поля receiver и sender (все обязательные): name (string), phone (string), country (integer, ID страны), city (integer, ID города), address (string).

curlJavaScript (fetch)

bash

curl -X POST "https://api.inlog.ai/api/v1/integrations/market-company/parcel/create" \
  -H "x-api-token: YOUR_API_KEY" \
  -H "Idempotency-Key: 3f1c2b7e-order-12345" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMethod": "POSTOMAT",
    "postomatId": "tz4a98xxat96iws9zmbrgj3a",
    "createPostomatOrder": true,
    "weight": 1.2,
    "price": 1500,
    "currency": "KGS",
    "receiver": { "name": "Иван Иванов", "phone": "+996700000000", "country": 1, "city": 1, "address": "ул. Примерная, 1" },
    "sender": { "name": "Магазин", "phone": "+996700000000", "country": 1, "city": 1, "address": "ул. Складская, 5" }
  }'

import { randomUUID } from 'node:crypto'

const res = await fetch('https://api.inlog.ai/api/v1/integrations/market-company/parcel/create', {
  method: 'POST',
  headers: {
    'x-api-token': 'YOUR_API_KEY',
    'Idempotency-Key': randomUUID(), // сохраните ключ, чтобы повторить запрос с ним же
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    deliveryMethod: 'POSTOMAT',
    postomatId: 'tz4a98xxat96iws9zmbrgj3a',
    createPostomatOrder: true,
    weight: 1.2,
    price: 1500,
    currency: 'KGS',
    receiver: { name: 'Иван Иванов', phone: '+996700000000', country: 1, city: 1, address: 'ул. Примерная, 1' },
    sender: { name: 'Магазин', phone: '+996700000000', country: 1, city: 1, address: 'ул. Складская, 5' },
  }),
})
const result = await res.json()

Ответ 200:

без заявки в постомат — объект посылки (id, trackCode, weight, price, postomatId, postomatOrderId, deliveryMethod, createdAt и др.), статус посылки — AWAITING;
с createPostomatOrder: true — объект { "parcel": {...}, "postomatOrder": {...}, "downCode": {...} | null }, где postomatOrder — заявка в постомат, а downCode — код закладки (может быть null, если код ещё недоступен; запросите его позже).

Заявка в постомат создаётся без SMS-уведомления получателя от InLog и с оплатой с баланса.

Ошибки: 400 — валидация или нет postomatId/warehouseId для выбранного способа доставки; 404 POSTOMAT_NOT_FOUND, 404 WAREHOUSE_NOT_FOUND; 409 TRACK_CODE_ALREADY_EXISTS — трек-код уже занят.

Посылка по трек-коду

GET /api/v1/integrations/market-company/parcel/track-code/{trackCode}

Ответ — в той же форме, что у создания: объект посылки или { parcel, postomatOrder, downCode }, если у посылки есть заявка в постомат. Посылка не найдена или не принадлежит вашей компании — 404 PARCEL_NOT_FOUND.

Статус посылки

GET /api/v1/integrations/market-company/parcel/track-code/{trackCode}/status

json

{ "trackCode": "TRK-000123", "status": "ARRIVED" }

`status`	Значение
`CREATED`	Посылка создана и ещё не прибыла
`ARRIVED`	Посылка прибыла в постомат или пункт выдачи
`TRANSFERRED_TO_CLIENT`	Посылка выдана получателю
`REDIRECTED`	Посылка переадресована и ожидает прибытия в новую точку

Не найдена — 404 PARCEL_NOT_FOUND.

Переадресация посылки

PUT /api/v1/integrations/market-company/parcel/track-code/{trackCode}/redirect
Content-Type: application/json

Тело — ровно одно из полей:

Поле	Тип	Описание
`toWarehouseId`	integer, ≥ 1	Новый пункт выдачи (ID из `opp/list`)
`toPostomatId`	string	Новый постомат

Ответ 200: { "message": "parcel redirected", "parcel": {...} }.

HTTP	`message`	Когда
`400`	—	Не передано ни одного поля или переданы оба
`404`	`PARCEL_NOT_FOUND`	Посылка не найдена или не принадлежит вашей компании
`404`	`COMPANY_NOT_FOUND` / `POSTOMAT_NOT_FOUND`	Целевой пункт выдачи или постомат не найден
`406`	`NOT_ACCEPTABLE`	Посылку в текущем статусе нельзя переадресовать: `READYTOSHIP`, `COURIER_RECEIVED`, `SENT`, `TRANSFERRED`, `COMPLETED`
`502`	`Postomat provider error`	Сервис постоматов временно недоступен

Заявки в постоматы

Эндпоинт	Назначение
`GET /api/v1/integrations/market-company/order/list`	Заявки в постоматы вашей компании
`GET /api/v1/integrations/market-company/order/{id}`	Посылка и её заявка в постомат по ID заявки

order/list: page и pageSize обязательны (pageSize 1–500); необязательные status (CREATED, DELIVERED, COMPLETED, SUBTRACTED) и флаги withToUser, withCell, withPostomat, withCurrentStatus, withStatuses, withRent, withPasswords. Ответ — { total, data } в формате API постоматов. Если сервис постоматов вернул ошибку — 500.

order/{id}: id — ID заявки в постомат. Возвращает посылку, в которой ваша компания указана компанией-партнёром, с полем postomatOrder. Для посылок, созданных через parcel/create, используйте посылку по трек-коду. Не найдено — 404 ORDER_NOT_FOUND.

Логистика и маркетплейс ​

Логистические компании ​

Список логистических компаний ​

Компания по ID ​

Страны и города ​

Поставщики ​

Поставщик по телефону ​

Посылки поставщика ​

Списки посылок и грузов ​

Список посылок ​

Список грузов ​

Общие параметры ​

Поиск (search) ​

Фильтр по статусам ​

Специальные наборы статусов ​

Пример ​

Маркетплейс (market-company) ​

Пункты выдачи ​

Создание посылки ​

Посылка по трек-коду ​

Статус посылки ​

Переадресация посылки ​

Заявки в постоматы ​