Internal API overview

Internal API is for PROMANTA staff and JWT clients. Full promo inventory access via apps/api-external, prefix /v1/internal/.

Who this section is for

Audience: PROMANTA staff, app.promanta.ru developers, internal MCP tools. JWT with inventory_promo_codes.* — full project visibility.

How to work with this API

Mirrors Promo codes UI: dashboard → create incoming → upload file → import → monitor warehouse codes. Every request includes projectId.

Base URL

• Production: https://api-external.promanta.ru
• Local: http://localhost:7314

Authentication

JWT (Authorization: Bearer). Pass projectId in every data payload.

No API key — user session with RBAC only.

Request and response format

All methods are POST with JSON { "meta": {}, "data": {} }. Response: success, data, meta.

Methods by workflow

1. Project monitoring

Dashboard aggregates without full export.

• Project promo dashboard overview — POST /v1/internal/dashboard/overview

2. Supplier directory

Counterparties that send code files.

• List promo code suppliers — POST /v1/internal/promo-code-suppliers/list

3. Incoming: upload code file

UI chain: create → upload → import → poll get.

• Create incoming document — POST /v1/internal/promo-code-incoming/create
• Upload incoming file (multipart) — POST /v1/internal/promo-code-incoming/upload
• Signed URL for incoming file upload — POST /v1/internal/promo-code-incoming/upload-url
• Start promo codes import from file — POST /v1/internal/promo-code-incoming/import
• Incoming document details and import status — POST /v1/internal/promo-code-incoming/get
• List promo incoming documents — POST /v1/internal/promo-code-incoming/list

4. Warehouse codes

Lookup and code card after import, support investigations.

• Warehouse promo codes list — POST /v1/internal/inventory-promo-codes/list
• Quick promo code search — POST /v1/internal/inventory-promo-codes/search
• Single promo code card — POST /v1/internal/inventory-promo-codes/get

MCP

Same operations via MCP at /mcp/internal, /mcp/supplier, /mcp/platform.

Request example (smoke test)

{
  "meta": { "requestId": "smoke-001" },
  "data": { "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }
}

Response example

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