API v1 — Документация

REST API для интеграции учётных систем поставщиков.
Базовый URL: https://demo.сразувточку.рф/api/v1

X-API-Key для тестирования

Автоматически подставляется из профиля текущего поставщика.
Можете заменить вручную.

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

Для критичных операций передавайте заголовок Idempotency-Key. При повторном запросе с тем же ключом в течение 24 часов вернётся кэшированный ответ.

GET/api/v1/distributor/health

Проверка работоспособности API от лица дистрибьютора. Возвращает общий статус, состояние подключения к БД и краткую информацию об учётной записи дистрибьютора.

Аутентификация: X-API-Key

Параметры запроса

/api/v1/distributor/health

X-API-Key

Idempotency-Key (опционально)

Пример ответа

{
  "data": {
    "status": "ok",
    "db": true,
    "dbInfo": {
      "now": "2026-08-29T13:12:09.475Z",
      "version": "PostgreSQL 15.x"
    },
    "timestamp": "2026-08-29T13:12:09.475Z",
    "env": "production",
    "distributor": {
      "id": "distributor-uuid",
      "name": "ООО \"Демо\"",
      "status": "ACTIVE"
    }
  }
}

POST/api/v1/distributor/catalog/sync

Выгрузка номенклатуры в каталог платформы. Максимальный размер запроса — 50 МБ. Поставщик загружает порциями и сам контролирует содержимое каждой порции. Сопоставление товаров происходит по штрихкодам (EAN). Если хотя бы один штрихкод из переданного массива уже существует — товар считается найденным, новые штрихкоды дополняются к карточке. Если совпадений нет — создаётся новая карточка товара со статусом PENDING (на проверке). Администрация вручную переводит карточку в ACTIVE или DISABLED.

Аутентификация: X-API-Key

Параметры запроса

/api/v1/distributor/catalog/sync

JSON body*

Картинки передаются в base64. Нераспарсенные изображения игнорируются. Размер запроса не более 50 МБ.

X-API-Key

Idempotency-Key (опционально)

Пример ответа

{
  "data": {
    "summary": {
      "processed": 1,
      "created": 1,
      "updated": 0,
      "skipped": 0,
      "errors": []
    }
  }
}

POST/api/v1/distributor/prices/sync

Выгрузка цен по видам цен. Автоматически создаёт вид цены, если он ещё не существует. Валюта всегда рубли (RUB).

Аутентификация: X-API-Key

Параметры запроса

/api/v1/distributor/prices/sync

JSON body*

X-API-Key

Idempotency-Key (опционально)

Пример ответа

{
  "data": {
    "summary": {
      "processed": 1,
      "created": 1,
      "updated": 0,
      "errors": []
    }
  }
}

POST/api/v1/distributor/stocks/sync

Выгрузка остатков по складам. Нулевые остатки не хранятся — позиция с нулевым количеством удаляется. Если склад не существует, он создаётся автоматически. Если передан необязательный org_kpp — склад ищется среди складов филиала с этим КПП (склад не создаётся автоматически).

Аутентификация: X-API-Key

Параметры запроса

/api/v1/distributor/stocks/sync

JSON body*

X-API-Key

Idempotency-Key (опционально)

Пример ответа

{
  "data": {
    "summary": {
      "processed": 1,
      "created": 1,
      "updated": 0,
      "deleted": 0,
      "errors": []
    }
  }
}

POST/api/v1/distributor/warehouse/sync

Выгрузка справочника складов дистрибьютора. Если склад с указанным GUID отсутствует — он создаётся, если существует — обновляется.

Аутентификация: X-API-Key

Параметры запроса

/api/v1/distributor/warehouse/sync

JSON body*

X-API-Key

Idempotency-Key (опционально)

Пример ответа

{
  "data": {
    "summary": {
      "processed": 1,
      "created": 1,
      "updated": 0,
      "errors": []
    }
  }
}

POST/api/v1/distributor/clients/sync

Выгрузка контрагентов и клиентов (торговых точек) из базы поставщика для сопоставления видов цен. Автоматически связывает клиента с контрагентом по ИНН/КПП. Данные являются внутренними и не затрагивают пользователей платформы напрямую.

Аутентификация: X-API-Key

Параметры запроса

/api/v1/distributor/clients/sync

JSON body*

X-API-Key

Idempotency-Key (опционально)

Пример ответа

{
  "data": {
    "summary": {
      "processed_counterparties": 1,
      "created_counterparties": 1,
      "updated_counterparties": 0,
      "processed_clients": 1,
      "created_clients": 1,
      "updated_clients": 0,
      "errors": []
    }
  }
}

POST/api/v1/distributor/setDefaultTypePrice

Установка основного вида цен дистрибьютора. Этот вид цен будет использоваться для неавторизованных пользователей и клиентов, для которых не удалось подобрать индивидуальный вид цены. Метод может быть вызван до выгрузки цен.

Аутентификация: X-API-Key

Параметры запроса

/api/v1/distributor/setDefaultTypePrice

JSON body*

X-API-Key

Idempotency-Key (опционально)

Пример ответа

{
  "data": {
    "default_price_type_id": "price-type-uuid",
    "price_type": "Опт"
  }
}

GET/api/v1/distributor/store-links

Список связей (договоров) с торговыми точками. Торговая точка подаёт заявку на заключение договора при оформлении заказа; пока связь не одобрена, её подзаказы висят в статусе «Ожидает подтверждения связи» и не попадают в выгрузку заказов. Поддерживает фильтр по статусу (PENDING | ACTIVE | REJECTED) и пагинацию.

Аутентификация: X-API-Key

Параметры запроса

/api/v1/distributor/store-links?page=1&limit=50

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

Оставьте пустым для всех статусов

Страница*

Лимит*

X-API-Key

Idempotency-Key (опционально)

Пример ответа

{
  "data": [
    {
      "id": "link-uuid",
      "status": "PENDING",
      "rejection_reason": null,
      "requested_at": "2026-09-14T10:00:00.000Z",
      "approved_at": null,
      "contract_number": null,
      "contract_date": null,
      "price_type": null,
      "store": {
        "id": "store-uuid",
        "name": "Магазин №1",
        "inn": "1234567890",
        "kpp": "123456001",
        "counterparty": {
          "name": "ООО \"Магазин\"",
          "inn": "1234567890"
        }
      }
    }
  ],
  "meta": {
    "total": 12,
    "page": 1,
    "limit": 50,
    "pages": 1
  }
}

POST/api/v1/distributor/store-links/status

Одобрение или отклонение заявки торговой точки на заключение договора. Связь идентифицируется по link_id или по ИНН точки (store_inn). При approve можно сразу передать реквизиты договора (contract_number, contract_date) — поставщик заполняет их при заключении договора. После одобрения ожидающие подзаказы точки автоматически переводятся в статус «Новый» и становятся доступны в выгрузке заказов. При reject обязателен rejection_reason.

Аутентификация: X-API-Key

Параметры запроса

/api/v1/distributor/store-links/status

JSON body*

X-API-Key

Idempotency-Key (опционально)

Пример ответа

{
  "data": {
    "id": "link-uuid",
    "status": "ACTIVE"
  }
}

GET/api/v1/distributor/orders

Получение заказов от торговых точек. Возвращает подзаказы с товарами, статусами, данными клиента, контактными данными получателя (contact_name, contact_phone, contact_email), датой доставки (delivery_date), комментарием (comment), причиной отмены (rejection_reason) и GUID склада, с которого будет осуществляться отправка каждой позиции. Склад выбирается автоматически на основе актуальных остатков на момент оформления заказа.

Аутентификация: X-API-Key

Параметры запроса

/api/v1/distributor/orders?page=1&limit=50

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

Оставьте пустым для всех статусов

Страница*

Лимит*

X-API-Key

Idempotency-Key (опционально)

Пример ответа

{
  "data": [
    {
      "id": "sub-order-uuid",
      "order_id": "order-uuid",
      "status": {
        "name": "Новый",
        "color": "#3B82F6"
      },
      "total_amount": "199.50",
      "rejection_reason": null,
      "order": {
        "store": {
          "name": "Магазин №1",
          "inn": "1234567890"
        },
        "address": {
          "city": "Москва",
          "address": "ул. Ленина, 1"
        },
        "contact_name": "Иванова Анна",
        "contact_phone": "+79001234567",
        "contact_email": "zakup@magazin.ru",
        "delivery_date": "2026-09-10T00:00:00.000Z",
        "comment": "Доставка до 12:00"
      },
      "items": [
        {
          "quantity": 2,
          "price": "45.50",
          "distributor": {
            "id": "distributor-uuid",
            "name": "ООО \"Демо\""
          },
          "warehouse": {
            "id": "warehouse-uuid",
            "external_id": "warehouse-guid-1",
            "name": "Основной склад"
          },
          "product": {
            "name": "Артезианская вода 1.5л",
            "brand": "AquaLife",
            "barcodes": [
              "4601234567890"
            ]
          }
        }
      ]
    }
  ],
  "meta": {
    "total": 120,
    "page": 1,
    "limit": 50,
    "pages": 3
  }
}

POST/api/v1/distributor/orders/{id}/status

Изменение статуса подзаказа. Создаёт запись в истории статусов. При переводе в статус «Отменён» необходимо передать rejection_reason — причина сохраняется в заказе и показывается покупателю.

Аутентификация: X-API-Key

Параметры запроса

/api/v1/distributor/orders//status

ID подзаказа*

JSON body*

X-API-Key

Idempotency-Key (опционально)

Пример ответа

{
  "data": {
    "sub_order_id": "...",
    "new_status": "Отменён",
    "rejection_reason": "Отсутствие товара на складе",
    "history_id": "...",
    "changed_at": "2026-04-25T12:00:00Z"
  }
}

GET/api/v1/distributor/orders/{id}/messages

Получение истории сообщений по подзаказу. Автоматически создаёт комнату чата, если её нет.

Аутентификация: X-API-Key

Параметры запроса

/api/v1/distributor/orders//messages?page=1&limit=20

ID подзаказа*

Страница

Лимит

X-API-Key

Idempotency-Key (опционально)

Пример ответа

{
  "data": [
    {
      "id": "msg-uuid",
      "sender_role": "DISTRIBUTOR",
      "text": "Заказ собран, ожидайте доставку",
      "created_at": "2026-04-25T12:00:00Z",
      "user": {
        "email": "distributor@srazu.ru"
      }
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "pages": 1
  }
}

POST/api/v1/distributor/orders/{id}/messages

Отправка сообщения клиенту по подзаказу.

Аутентификация: X-API-Key

Параметры запроса

/api/v1/distributor/orders//messages

ID подзаказа*

JSON body*

X-API-Key

Idempotency-Key (опционально)

Пример ответа

{
  "data": {
    "id": "msg-uuid",
    "room_id": "room-uuid",
    "sender_role": "DISTRIBUTOR",
    "text": "Заказ подтверждён, ожидайте доставку",
    "created_at": "2026-04-25T12:00:00Z",
    "user": {
      "email": "distributor@srazu.ru"
    }
  }
}

Changelog

v1.0.22026-09-04

POST /api/v1/distributor/stocks/sync — добавлен опциональный параметр org_kpp: склад ищется по филиалу поставщика с этим КПП (склад не создаётся автоматически, при отсутствии филиала позиция попадает в errors)
GET /api/v1/distributor/orders — в ответ добавлены contact_name, contact_phone, contact_email, delivery_date, comment (контакты получателя и параметры доставки) и rejection_reason (причина отмены)
POST /api/v1/distributor/orders/{id}/status — добавлен параметр rejection_reason: обязателен при переводе в статус «Отменён», сохраняется в заказе и истории статусов

v1.0.12026-08-30

GET /api/v1/distributor/orders — в ответе каждой позиции заказа добавлен объект warehouse с GUID склада (external_id), с которого осуществляется отправка
При оформлении заказа склад фиксируется в позиции на основе актуальных остатков

v1.0.02026-04-25

Релиз API v1 для интеграции поставщиков
POST /api/v1/distributor/catalog/sync — синхронизация номенклатуры (full/delta, до 1000 SKU)
POST /api/v1/distributor/prices/sync — выгрузка цен с автосозданием типов цен
POST /api/v1/distributor/stocks/sync — выгрузка остатков по складам
GET /api/v1/distributor/orders — получение заказов от ТТ с пагинацией и фильтром по статусу
POST /api/v1/distributor/orders/{id}/status — изменение статуса подзаказа с записью в историю
GET /api/v1/distributor/orders/{id}/messages — история чата по подзаказу
POST /api/v1/distributor/orders/{id}/messages — отправка сообщения торговой точке
Аутентификация по X-API-Key с проверкой активности поставщика
Поддержка Idempotency-Key для защиты от дублей (TTL 24ч)
CORS для кросс-доменных запросов
Валидация входных данных через Zod