Internal API — контур для сотрудников PROMANTA и JWT-клиентов. Полный доступ к промокодам проекта через apps/api-external, префикс /v1/internal/.
Для кого этот раздел
Для кого: сотрудники PROMANTA (операторы, аналитики, support), разработчики веб-приложения app.promanta.ru и внутренних MCP-инструментов. Доступ по JWT пользователя с правами inventory_promo_codes.* — полный обзор проекта, все поставщики и все коды.
Логика работы с API
Логика работы повторяет интерфейс раздела «Промокоды» в PROMANTA: сначала смотрите сводку → создаёте поступление → загружаете файл → запускаете импорт → контролируете склад кодов. В каждом запросе передаётся projectId активного проекта.
Базовый URL
- Production:
https://api-external.promanta.ru - Локально:
http://localhost:7314
Аутентификация
JWT (Authorization: Bearer). В каждом запросе передаётся projectId в data.
Ключ API не используется — только сессия пользователя с RBAC.
Формат запроса и ответа
Все методы — POST, JSON: { "meta": {}, "data": {} }. Ответ: success, data, meta (requestId, serverTime).
Методы по сценариям
1. Мониторинг проекта
Сводные цифры для дашборда — без выгрузки всей базы.
- Обзор показателей промокодов проекта —
POST /v1/internal/dashboard/overview
2. Справочник поставщиков
Контрагенты, от которых приходят файлы с кодами.
- Список поставщиков промокодов —
POST /v1/internal/promo-code-suppliers/list
3. Поступления: загрузка файла с кодами
Цепочка «как в UI»: создать документ → загрузить xlsx/csv → импорт → проверить статус. Между шагами опрашивайте incoming/get.
- Создание документа поступления —
POST /v1/internal/promo-code-incoming/create - Загрузка файла поступления (multipart) —
POST /v1/internal/promo-code-incoming/upload - Ссылка для загрузки файла поступления —
POST /v1/internal/promo-code-incoming/upload-url - Запуск импорта промокодов из файла —
POST /v1/internal/promo-code-incoming/import - Карточка поступления и статус импорта —
POST /v1/internal/promo-code-incoming/get - Список поступлений промокодов —
POST /v1/internal/promo-code-incoming/list
4. Склад промокодов
Поиск и карточка кода после импорта, расследование обращений клиентов.
- Список промокодов на складе —
POST /v1/internal/inventory-promo-codes/list - Быстрый поиск промокода —
POST /v1/internal/inventory-promo-codes/search - Карточка одного промокода —
POST /v1/internal/inventory-promo-codes/get
MCP
Те же операции доступны через MCP: /mcp/internal, /mcp/supplier, /mcp/platform с тем же ключом/JWT.
Пример запроса (smoke-test)
{
"meta": { "requestId": "smoke-001" },
"data": { "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }
}Пример ответа
{ "success": true, "data": { "totalCount": 211350, "byStatus": { "available": 125000 }, "asOf": "2026-07-13T12:00:00Z" } }cURL
curl -X POST "https://api-external.promanta.ru/v1/internal/dashboard/overview" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT" \
-d '{"data": { "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }}'