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

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

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

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

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

POST/api/v1/distributor/catalog/sync

Синхронизация номенклатуры (полная или дельта). Максимум 1000 товаров за запрос.

Аутентификация: X-API-Key + Idempotency-Key (рекомендуется)

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

/api/v1/distributor/catalog/sync

full — деактивирует отсутствующие SKU

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

{
  "data": {
    "summary": {
      "mode": "delta",
      "processed": 1,
      "created": 1,
      "updated": 0
    }
  }
}
POST/api/v1/distributor/prices/sync

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

Аутентификация: X-API-Key + Idempotency-Key (рекомендуется)

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

/api/v1/distributor/prices/sync

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

{
  "data": {
    "summary": {
      "processed": 1,
      "created": 1,
      "updated": 0,
      "errors": []
    }
  }
}
POST/api/v1/distributor/stocks/sync

Выгрузка остатков по складам. Если склад не указан — обновляется общий остаток.

Аутентификация: X-API-Key + Idempotency-Key (рекомендуется)

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

/api/v1/distributor/stocks/sync

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

{
  "data": {
    "summary": {
      "processed": 1,
      "updated": 1,
      "errors": []
    }
  }
}
GET/api/v1/distributor/orders

Получение заказов от торговых точек. Возвращает подзаказы с товарами, статусами и данными ТТ.

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

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

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

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

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

{
  "data": [
    {
      "id": "sub-order-uuid",
      "order_id": "order-uuid",
      "status": {
        "name": "Новый",
        "color": "#3B82F6"
      },
      "total_amount": "199.50",
      "order": {
        "store": {
          "name": "Магазин №1",
          "inn": "1234567890"
        },
        "address": {
          "city": "Москва",
          "address": "ул. Ленина, 1"
        }
      },
      "items": [
        {
          "quantity": 2,
          "price": "45.50",
          "offer": {
            "sku": "W-AQ-1500",
            "product": {
              "name": "Артезианская вода 1.5л",
              "brand": "AquaLife"
            }
          }
        }
      ]
    }
  ],
  "meta": {
    "total": 120,
    "page": 1,
    "limit": 50,
    "pages": 3
  }
}
POST/api/v1/distributor/orders/{id}/status

Изменение статуса подзаказа. Создаёт запись в истории статусов.

Аутентификация: X-API-Key + Idempotency-Key (обязательно)

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

/api/v1/distributor/orders//status

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

{
  "data": {
    "sub_order_id": "...",
    "new_status": "Подтверждён",
    "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

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

{
  "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

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

{
  "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.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