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

Реальный Vendor API Hattrix: товары, заказы, ключи, вебхуки, импорт и логи интеграций.

Base URL

https://hattrix.ru/api/vendors

Health

https://hattrix.ru/health

Auth

JWT Bearer token

Формат

JSON over HTTPS

Быстрый старт (5 минут)

Минимальный сценарий интеграции: проверка health, авторизованный запрос товаров, создание товара и проверка логов вызовов API.

Пример запроса

bash

curl --request GET \
  --url https://hattrix.ru/health \
  --header 'Accept: application/json'

curl --request GET \
  --url 'https://hattrix.ru/api/vendors/products?page=1&limit=20' \
  --header 'Authorization: Bearer <JWT_ACCESS_TOKEN>'

curl --request POST \
  --url https://hattrix.ru/api/vendors/products \
  --header 'Authorization: Bearer <JWT_ACCESS_TOKEN>' \
  --header 'Idempotency-Key: 1d7e73f0-98f1-4f65-a2d4-3d11f955b2ba' \
  --header 'Content-Type: application/json' \
  --data '{"name":"Клюшка BAUER Nexus","price":12990,"stock":12}'

Примечания

- 1) Получите JWT access token через вход продавца или developer-участника организации.
- 2) Проверьте доступность API через GET /health.
- 3) Запросите список товаров GET /api/vendors/products?page=1&limit=20.
- 4) Создайте тестовый товар POST /api/vendors/products.
- 5) Проверьте последние вызовы в GET /api/vendors/integrations/logs.
- Для проверки лимитов смотрите раздел «Лимиты и квоты».

Формат ответа, пагинация и логи

Публичные list-endpoint обычно возвращают items/page/limit/total, а vendor-интеграции используют доменные ключи ответа: keys, jobs, webhooks, logs. Для диагностики используйте записи API-логов.

Параметр	Тип	Обязательный	Описание
items	array	for list	Список сущностей на текущей странице
page	integer	for list	Номер страницы (начинается с 1)
limit	integer	for list	Количество элементов на странице
total	integer	for list	Общее число элементов
logs	array	for /integrations/logs	Последние вызовы API с id, method, path, status и timeMs

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

json

{
  "items": [
    {
      "id": "prd_2v9k9x",
      "name": "Клюшка BAUER Nexus",
      "price": 12990
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 187
}

Примечания

- Для vendor-интеграций сверяйте форму ответа с конкретным разделом документации.
- При page * limit > total список может быть пустым — это нормальное поведение.

Введение и базовый URL

Vendor API Hattrix работает через текущий backend проекта и проксируется фронтендом по пути /api/vendors. Все запросы выполняются по HTTPS и возвращают JSON.

Параметр	Тип	Обязательный	Описание
Base URL	string	yes	https://hattrix.ru/api/vendors
Health URL	string	no	https://hattrix.ru/health
Content-Type	header	yes	application/json
Accept	header	yes	application/json

HTTP-статусы

200Backend и база данных доступны

503Backend отвечает, но база данных недоступна или degraded

Пример запроса

bash

curl --request GET \
  --url https://hattrix.ru/health \
  --header 'Accept: application/json'

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

json

{
  "status": "ok",
  "timestamp": "2026-05-01T06:01:00.000Z"
}

Аутентификация

Для рабочих vendor-endpoint используйте JWT access token в формате Bearer. API-ключи создаются в разделе Developers, но текущие защищённые маршруты проекта проверяют именно JWT пользователя продавца или developer-участника.

Параметр	Тип	Обязательный	Описание
Authorization	header	yes	Bearer <JWT_ACCESS_TOKEN>
X-Org-Id	header	no	ID организации, если один пользователь работает с несколькими организациями

HTTP-статусы

200Токен принят, запрос выполнен

401JWT отсутствует, истёк или отозван

403Пользователь не продавец и не developer-участник организации

Пример запроса

bash

curl --request GET \
  --url https://hattrix.ru/api/vendors/products \
  --header 'Authorization: Bearer <JWT_ACCESS_TOKEN>'

Получение и обновление JWT

Перед вызовом vendor endpoint получите access token через /api/auth/login. Refresh token обновляет сессию, а /api/auth/me проверяет текущего пользователя и его vendor/developer контекст.

/api/auth/login, /api/auth/refresh, /api/auth/me, /api/auth/logout

Параметр	Тип	Обязательный	Описание
email	string	yes	Email продавца или developer-участника
password	string	yes	Пароль пользователя
token	response string	yes	JWT access token для Authorization header
refreshToken	response string	yes	Токен обновления access token
user.role	seller \| developer	for integrations	Роль пользователя в vendor dashboard
user.vendorId	number	for integrations	ID организации продавца

HTTP-статусы

200Успешный login/refresh/me/logout

400Не передан email/password или refreshToken

401Неверные credentials, истёкший или неверный токен

Пример запроса

bash

curl --request POST \
  --url https://hattrix.ru/api/auth/login \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "vendor@example.com",
    "password": "secret-password"
  }'

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

json

{
  "token": "<JWT_ACCESS_TOKEN>",
  "refreshToken": "<JWT_REFRESH_TOKEN>",
  "user": {
    "id": 42,
    "email": "vendor@example.com",
    "firstName": "Иван",
    "lastName": "Петров",
    "userType": "V",
    "role": "seller",
    "vendorId": 42
  }
}

Примечания

- Access token передавайте как Authorization: Bearer <JWT_ACCESS_TOKEN>.
- Для developer-участника role будет developer, а vendorId укажет организацию продавца.
- Не храните JWT в публичном JavaScript без защиты от XSS; для серверных интеграций храните токены в секретном хранилище.

Управление товарами (CRUD)

Получение списка товаров, создание, обновление и удаление карточек товаров продавца.

/api/vendors/products, /api/vendors/products/{id}

Параметр	Тип	Обязательный	Описание
name	string	yes	Название товара
price	number	yes	Цена в рублях
stock	number	no	Остаток на складе, по умолчанию 10
sku	string	no	Внешний SKU поставщика
description	string	no	Полное HTML/текстовое описание товара
shortDescription	string	no	Короткое описание для списков
listPrice	number	no	Старая цена/цена до скидки
status (body)	string	no	A — активен, D — выключен
categoryIds	number[]	no	Категории, к которым привязать товар
images	array	no	Массив изображений: path, alt
options	array	no	Опции товара и варианты (например, размер/хват)
page	query integer	no	Страница списка, минимум 1
limit	query integer	no	Размер страницы, 1..100
search	query string	no	Поиск по названию, описанию и product_code
status (query)	query string	no	Фильтр списка по статусу A/D
category_id	query integer	no	Фильтр списка по категории
sort_by	query string	no	timestamp \| price \| name
sort_order	query string	no	asc \| desc
Idempotency-Key	header	recommended for POST/PUT	Уникальный ключ для безопасных повторов

HTTP-статусы

200Список/карточка товара получены или товар обновлён

201Товар создан

400Некорректные поля товара

401/403Нет авторизации или прав продавца

404Товар не найден или не принадлежит продавцу

Пример запроса

bash

curl --request POST \
  --url https://hattrix.ru/api/vendors/products \
  --header 'Authorization: Bearer <JWT_ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Клюшка BAUER Nexus",
    "price": 12990,
    "stock": 12
  }'

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

json

{
  "id": 1024,
  "name": "Клюшка BAUER Nexus",
  "sku": "BAUER-NEXUS-77",
  "price": 12990,
  "listPrice": 14990,
  "stock": 12,
  "status": "A",
  "images": [
    {
      "id": 501,
      "path": "https://hattrix.ru/images/detailed/stick.jpg",
      "type": "M",
      "alt": "Клюшка BAUER Nexus"
    }
  ],
  "categories": [
    { "id": 12, "name": "Клюшки" }
  ]
}

Примечания

- GET /api/vendors/products поддерживает пагинацию через page и limit.
- PUT /api/vendors/products/{id} обновляет карточку товара.
- DELETE /api/vendors/products/{id} удаляет товар продавца.
- Idempotency-Key полезен для повторов POST/PUT, если клиент не уверен, дошёл ли первый запрос.

Импорт товаров (CSV / JSON / URL)

Импорт поддерживает загрузку файла CSV/JSON и импорт по URL внешнего сайта. Процесс асинхронный: API возвращает jobId.

POST/api/vendors/integrations/import

Параметр	Тип	Обязательный	Описание
sourceType	enum	yes	csv \| json \| url
file	file	for csv/json	Файл импорта
sourceUrl	string	for url	Ссылка на внешний каталог

HTTP-статусы

202Import job поставлен в очередь

400Некорректный sourceType, sourceUrl или fileName

401/403Нет доступа к интеграциям продавца

Пример запроса

bash

curl --request POST \
  --url https://hattrix.ru/api/vendors/integrations/import \
  --header 'Authorization: Bearer <JWT_ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "sourceType": "url",
    "sourceUrl": "https://vendor.example.com/catalog.json"
  }'

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

json

{
  "job": {
    "id": 79,
    "sourceType": "url",
    "sourceUrl": "https://vendor.example.com/catalog.json",
    "status": "queued",
    "createdAt": "2026-05-01T06:11:00.000Z"
  }
}

Примечания

- Успешный запуск возвращает HTTP 202 Accepted.
- Не отправляйте одновременно больше 20 импортов на организацию.
- Историю импортов можно получить через GET /api/vendors/integrations/import-jobs.

Заказы и статусы

Отслеживайте заказы, фильтруйте их по статусу и подтверждайте смену статуса обработки, отправки и доставки.

GET/api/vendors/orders

Параметр	Тип	Обязательный	Описание
status	string	no	new \| confirmed \| shipped \| delivered \| canceled
from	string	no	Дата начала периода (ISO 8601)
to	string	no	Дата окончания периода (ISO 8601)
page	query integer	no	Страница списка, минимум 1
limit	query integer	no	Размер страницы, 1..100

HTTP-статусы

200Список заказов или заказ получен

200/204Заказ подтверждён через /orders/{id}/confirm

401/403Нет прав продавца

404Заказ не найден

Пример запроса

bash

curl --request GET \
  --url 'https://hattrix.ru/api/vendors/orders?status=confirmed&from=2026-05-01T00:00:00Z&to=2026-05-31T23:59:59Z&page=1&limit=20' \
  --header 'Authorization: Bearer <JWT_ACCESS_TOKEN>'

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

json

{
  "items": [
    {
      "id": "ord_91ab2c",
      "status": "confirmed",
      "total": 24580,
      "createdAt": "2026-05-03T12:45:00.000Z"
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 1
}

Примечания

- Подтверждение заказа выполняется через POST /api/vendors/orders/{id}/confirm.
- Рекомендуется валидировать допустимые переходы статусов на стороне интеграции.

История импортов

Endpoint возвращает последние import jobs продавца: статус очереди, количество обработанных товаров и ошибку, если импорт завершился неуспешно.

GET/api/vendors/integrations/import-jobs

Параметр	Тип	Обязательный	Описание
id	number	response	ID import job
sourceType	csv \| json \| url	response	Источник импорта
status	string	response	queued \| processing \| completed \| failed
processedCount	number	response	Сколько позиций обработано
errorMessage	string \| null	response	Текст ошибки при failed

HTTP-статусы

200История импортов получена

401/403Нет доступа к интеграциям продавца

Пример запроса

bash

curl --request GET \
  --url https://hattrix.ru/api/vendors/integrations/import-jobs \
  --header 'Authorization: Bearer <JWT_ACCESS_TOKEN>'

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

json

{
  "jobs": [
    {
      "id": 79,
      "sourceType": "url",
      "sourceUrl": "https://vendor.example.com/catalog.json",
      "fileName": null,
      "status": "queued",
      "processedCount": 0,
      "errorMessage": null,
      "createdAt": "2026-05-01T06:11:00.000Z"
    }
  ]
}

Примечания

- Используйте этот endpoint для polling после POST /api/vendors/integrations/import.
- Не опрашивайте чаще одного раза в несколько секунд, чтобы не создавать лишнюю нагрузку.

Жизненный цикл заказа

Базовая модель статусов: new → confirmed → shipped → delivered. Отмена (`canceled`) обычно допустима до доставки.

Параметр	Тип	Обязательный	Описание
new	status	no	Заказ создан и ожидает подтверждения
confirmed	status	no	Заказ подтверждён продавцом
shipped	status	no	Заказ передан в доставку
delivered	status	no	Заказ доставлен клиенту
canceled	status	no	Заказ отменён

Примечания

- Рекомендуется хранить у себя журнал переходов статусов с timestamp и id записи из интеграционных логов.
- При получении `order.status_changed` валидируйте переход статуса перед обновлением локальной БД.
- Событие `order.created` желательно обрабатывать идемпотентно по order.id.

Developer-доступ к организации

Продавец может пригласить внешнего разработчика в организацию. Developer получает доступ к интеграциям и работает в контексте vendorId продавца.

/api/vendors/developers/invites, /api/auth/register-developer-invite

Параметр	Тип	Обязательный	Описание
email	string	yes	Email разработчика для приглашения
inviteToken	response string	yes	Одноразовый токен приглашения
inviteLink	response string	yes	Ссылка регистрации developer-аккаунта
expiresAt	number	yes	Unix timestamp истечения приглашения

HTTP-статусы

201Приглашение создано или developer зарегистрирован

400Некорректный email/token/password

403Приглашать разработчиков может только seller

409Пользователь с таким email уже существует

Пример запроса

bash

curl --request POST \
  --url https://hattrix.ru/api/vendors/developers/invites \
  --header 'Authorization: Bearer <JWT_ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{"email":"developer@example.com"}'

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

json

{
  "success": true,
  "inviteToken": "4c83f0...",
  "inviteLink": "/vendor/register-developer?token=4c83f0...",
  "expiresAt": 1778256000
}

Примечания

- Developer-участник не становится продавцом; он получает роль developer в рамках организации.
- Для регистрации по invite используйте POST /api/auth/register-developer-invite.

Вебхуки

Подпишитесь на события `order.created` и `order.status_changed`. Вебхуки подписываются на URL и подписываются HMAC-сигнатурой.

/api/vendors/integrations/webhooks

Параметр	Тип	Обязательный	Описание
url	string	yes	HTTPS endpoint вашей системы
events[]	array	yes	Список событий для подписки
secret	string	auto	Генерируется при создании вебхука
X-Hattrix-Signature	header	yes	hex(HMAC_SHA256(raw_body, secret))
X-Hattrix-Timestamp	header	yes	Unix timestamp доставки события
X-Hattrix-Event	header	yes	Имя события (например, order.created)

HTTP-статусы

200Список вебхуков получен

201Вебхук создан, secret показан один раз

400URL вебхука невалиден

401/403Нет доступа к интеграциям

Пример запроса

bash

curl --request POST \
  --url https://hattrix.ru/api/vendors/integrations/webhooks \
  --header 'Authorization: Bearer <JWT_ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://merchant.example.com/hattrix/webhook",
    "events": ["order.created", "order.status_changed"]
  }'

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

json

{
  "webhook": {
    "id": 6,
    "url": "https://merchant.example.com/hattrix/webhook",
    "events": ["order.created", "order.status_changed"],
    "status": "active",
    "createdAt": "2026-05-01T06:20:00.000Z"
  },
  "secret": "whsec_***",
  "showOnce": true
}

Примечания

- Проверяйте подпись на исходном raw-body, а не на повторно сериализованном JSON.
- Отклоняйте события со старыми timestamp (например, старше 5 минут).
- См. раздел «Лимиты и квоты» для поведения при всплесках событий.

Формат payload вебхука

События доставляются JSON-пакетом с именем события, временем и объектом данных. Верификацию выполняйте по raw body.

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

json

{
  "event": "order.status_changed",
  "timestamp": "2026-05-01T07:12:00.000Z",
  "data": {
    "id": "ord_91ab2c",
    "status": "shipped",
    "previousStatus": "confirmed",
    "updatedAt": "2026-05-01T07:11:57.000Z"
  }
}

Примечания

- Поддерживайте дедупликацию вебхуков по паре (event, data.id, timestamp).
- Возвращайте 2xx только после успешной обработки; иначе Hattrix повторит доставку.
- Ограничьте время обработки одного webhook handler (например, до 3-5 секунд).

API-ключи организации

Управление API-ключами организации: просмотр, создание и отзыв ключей со scope read/write/full.

/api/vendors/api-keys

Параметр	Тип	Обязательный	Описание
name	string	yes	Название ключа, видимое в кабинете
scope	enum	yes	read \| write \| full

HTTP-статусы

200Список ключей получен или ключ отозван

201Ключ создан, secret показан один раз

400Не передано имя ключа

401/403Нет доступа к Developers

Пример запроса

bash

curl --request POST \
  --url https://hattrix.ru/api/vendors/api-keys \
  --header 'Authorization: Bearer <JWT_ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{"name":"ERP Integration","scope":"write"}'

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

json

{
  "key": {
    "id": 12,
    "name": "ERP Integration",
    "scope": "write",
    "status": "active",
    "createdAt": "2026-05-01T06:23:00.000Z"
  },
  "secret": "sk_live_***",
  "showOnce": true
}

Примечания

- Полное значение token показывается только один раз в момент создания.
- Рекомендуется регулярно ротировать ключи и ограничивать scope по принципу минимальных прав.

API-логи

Просмотр последних 100 API-вызовов для диагностики интеграции.

GET/api/vendors/integrations/logs

HTTP-статусы

200Возвращены последние 100 записей

401/403Нет доступа к логам интеграций

Пример запроса

bash

curl --request GET \
  --url https://hattrix.ru/api/vendors/integrations/logs \
  --header 'Authorization: Bearer <JWT_ACCESS_TOKEN>'

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

json

{
  "logs": [
    {
      "id": 101,
      "path": "/products",
      "method": "POST",
      "status": 201,
      "timeMs": 0,
      "at": "2026-05-01T06:24:00.000Z"
    }
  ]
}

Примечания

- Используйте id записи и путь из логов при обращении в поддержку.

Лимиты и квоты

Текущие лимиты: до 120 запросов в минуту и до 20 одновременных импортов. Актуальные значения возвращаются в заголовках ответа.

Параметр	Тип	Обязательный	Описание
X-RateLimit-Limit	header	yes	Общий лимит запросов в текущем окне
X-RateLimit-Remaining	header	yes	Оставшееся число запросов
X-RateLimit-Reset	header	yes	Unix timestamp сброса окна
Retry-After	header	for 429	Через сколько секунд повторить запрос

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

json

{
  "error": "Слишком много запросов. Пожалуйста, попробуйте позже."
}

Примечания

- При 429 используйте экспоненциальный backoff с jitter и учитывайте Retry-After.
- Параллельные импорты ограничены 20 активными job на организацию.

Коды ошибок

Backend возвращает JSON с полем `error`; для validation-ошибок дополнительно может быть `details`, а в development — stack/message.

Параметр	Тип	Обязательный	Описание
INVALID_REQUEST	4xx	no	Некорректный формат запроса или параметров
UNAUTHORIZED	401	no	Отсутствует или неверный Bearer token
FORBIDDEN	403	no	Недостаточно прав для выбранного scope
NOT_FOUND	404	no	Ресурс не найден
TOO_MANY_REQUESTS	429	no	Превышен лимит, безопасно повторять
INTEGRATION_ERROR	5xx	no	Временная ошибка сервиса, повторить позже

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

json

{
  "error": "Слишком много запросов. Пожалуйста, попробуйте позже."
}

Примечания

- Повторяйте только временные ошибки: 429 и часть 5xx.
- Для расследования передавайте в поддержку endpoint, method, время ошибки и запись из API-логов.
- См. раздел «Лимиты и квоты» для стратегии повторов.

Схемы основных объектов

Краткий справочник по структурам, которые чаще всего встречаются в ответах API. Поля могут расширяться без breaking changes.

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

json

{
  "Product": {
    "id": 1024,
    "name": "Клюшка BAUER Nexus",
    "sku": "BAUER-NEXUS-77",
    "description": "Полное описание",
    "shortDescription": "Короткое описание",
    "price": 12990,
    "listPrice": 14990,
    "stock": 12,
    "status": "A",
    "categories": [{ "id": 12, "name": "Клюшки" }],
    "images": [{ "id": 501, "path": "https://hattrix.ru/images/detailed/stick.jpg", "type": "M", "alt": "Клюшка" }]
  },
  "Order": {
    "id": 9101,
    "status": "N",
    "total": 24580,
    "customer": { "email": "customer@example.com", "name": "Анна Иванова" },
    "items": [{ "id": 1, "product": "Клюшка BAUER Nexus", "quantity": 2, "price": 12990, "productId": 1024 }],
    "createdAt": "2026-05-01T10:00:00.000Z"
  },
  "ApiKey": {
    "id": 12,
    "name": "ERP Integration",
    "scope": "write",
    "status": "active",
    "lastUsedAt": null,
    "createdAt": "2026-05-01T06:23:00.000Z"
  },
  "Webhook": {
    "id": 6,
    "url": "https://merchant.example.com/hattrix/webhook",
    "events": ["order.created", "order.status_changed"],
    "status": "active",
    "createdAt": "2026-05-01T06:20:00.000Z"
  },
  "ImportJob": {
    "id": 79,
    "sourceType": "url",
    "status": "queued",
    "processedCount": 0,
    "errorMessage": null
  }
}

Примечания

- Списки товаров и заказов возвращают pagination с page, limit, total и totalPages.
- Секреты api-key и webhook показываются только один раз при создании.
- Для совместимости не полагайтесь на порядок полей JSON.

Типовые сценарии интеграции

Рекомендуемые последовательности вызовов для ERP, складской системы, CRM и обработчика вебхуков.

Параметр	Тип	Обязательный	Описание
Первичная синхронизация каталога	workflow	no	login → GET products → POST/PUT products → GET logs
Импорт каталога по URL	workflow	no	login → POST integrations/import → polling import-jobs → разбор errorMessage
Обработка заказов	workflow	no	GET orders?status=N → GET orders/{id} → POST orders/{id}/confirm
Webhook-подключение	workflow	no	POST integrations/webhooks → сохранить secret → проверять HMAC raw body
Ротация доступа	workflow	no	POST api-keys → обновить интеграцию → POST api-keys/{id}/revoke

Примечания

- Каждый workflow должен иметь интеграционный тест на вашей стороне.
- Для операций записи используйте ограниченные ретраи и идемпотентность.
- После релиза первые сутки мониторьте 4xx/5xx, длительность запросов и количество failed import jobs.

Справочник endpoint'ов

Краткая карта API-методов для интеграции. Используйте как чеклист покрытия при запуске.

Параметр	Тип	Обязательный	Описание
POST /api/auth/login	Auth	no	Получить token и refreshToken
POST /api/auth/refresh	Auth	no	Обновить access token
GET /api/auth/me	Auth	JWT	Проверить текущего пользователя и роль
POST /api/auth/logout	Auth	JWT	Отозвать текущий access token
GET /health	public	no	Проверка доступности backend и базы данных
GET /api/vendors/products	Products	JWT	Список товаров продавца (page, limit)
POST /api/vendors/products	Products	JWT	Создание товара
PUT /api/vendors/products/{id}	Products	JWT	Обновление товара
DELETE /api/vendors/products/{id}	Products	JWT	Удаление товара
POST /api/vendors/integrations/import	Imports	JWT	Запуск импорта (csv/json/url), ответ 202
GET /api/vendors/integrations/import-jobs	Imports	JWT	Последние import jobs продавца
GET /api/vendors/orders	Orders	JWT	Список заказов и фильтры по статусу/периоду
POST /api/vendors/orders/{id}/confirm	Orders	JWT	Подтверждение заказа продавцом
POST /api/vendors/developers/invites	Developers	JWT seller	Создать приглашение разработчика
POST /api/auth/register-developer-invite	Developers	invite token	Зарегистрировать developer-участника
GET /api/vendors/integrations/webhooks	Webhooks	JWT	Список активных подписок вебхуков
POST /api/vendors/integrations/webhooks	Webhooks	JWT	Создание подписки на события
GET /api/vendors/api-keys	ApiKeys	JWT	Список API-ключей организации
POST /api/vendors/api-keys	ApiKeys	JWT	Создание ключа (секрет показывается один раз)
POST /api/vendors/api-keys/{id}/revoke	ApiKeys	JWT	Отзыв ключа
GET /api/vendors/integrations/logs	Logs	JWT	Последние 100 API-вызовов

Примечания

- Этот список синхронизирован с реальными маршрутами backend/src/routes/vendorRoutes.ts.
- Для production запуска убедитесь, что каждая нужная операция покрыта вашим интеграционным тестом.

Troubleshooting: частые проблемы

Быстрые сценарии диагностики при ошибках интеграции. Начинайте с endpoint, времени ошибки и логов API.

Параметр	Тип	Обязательный	Описание
401 UNAUTHORIZED	auth	no	Проверьте Bearer token, отсутствие лишних пробелов и срок действия ключа
403 FORBIDDEN	scope	no	Права ключа не соответствуют операции (например, read вместо write)
404 NOT_FOUND	resource	no	Проверьте id ресурса и организацию (X-Org-Id при мульти-аккаунте)
429 TOO_MANY_REQUESTS	quota	no	Примените backoff + jitter и уважайте Retry-After
Signature mismatch	webhook	no	HMAC считайте от raw body, а не от пересобранного JSON

Примечания

- При любой проблеме фиксируйте endpoint, method, время, HTTP-статус и тело ошибки.
- Если ошибка воспроизводится, приложите запись из /api/vendors/integrations/logs при обращении в поддержку.
- Для нестабильных сетевых ошибок используйте ограниченные ретраи с экспоненциальной паузой.

Changelog

v1.2.0 — добавлен импорт по URL и API-логи. v1.1.0 — события вебхуков. v1.0.0 — базовый релиз CRUD товаров и заказов.

Примечания

- v1.2.0: добавлены /api/vendors/integrations/import и /api/vendors/integrations/logs.
- v1.1.0: добавлены события вебхуков order.created и order.status_changed.
- v1.0.0: релиз CRUD товаров и списка заказов.

Чеклист перед запуском в production

Короткий контрольный список для безопасного запуска интеграции и снижения рисков в первые дни после релиза.

Примечания

- Проверены health-check, авторизация и получение товаров в production.
- Включено логирование endpoint, method, статуса, тела ошибки и Retry-After на вашей стороне.
- Реализована идемпотентность для create/update операций и webhook-обработчиков.
- Настроены алерты на рост 429/5xx и на количество неуспешных webhook-обработок.
- Проверена ротация API-ключей и ограничение прав по scope.
- Команда поддержки знает, где смотреть /api/vendors/integrations/logs.