Справочник API: обзор и базовый URL

Обзор REST API MeerPartners: базовый URL и версия /api/v1, формат ответов и ошибок, аутентификация, пагинация, Swagger и группы эндпоинтов.

Справочник описывает REST API платформы MeerPartners — для интеграции бизнеса (постбэк, ключи, депозиты) и для embed-SDK инфлюенсера. Это технический раздел: примеры точные, эндпоинты и поля взяты из боевого кода. Если вы только начинаете — сначала прочитайте Аутентификацию и Постбэк.

Базовый URL и версия

Все версионируемые методы живут под префиксом /api/v1:

https://api.meerpartners.com/api/v1

Адрес зависит от оператора

https://api.meerpartners.com — пример. Базовый домен задаёт оператор платформы (на self-hosted-инсталляции он будет свой). Точный адрес для вашей интеграции возьмите в кабинете бизнеса на странице Интеграция или у вашего менеджера. Дальше в справочнике мы указываем только путь (/api/v1/...).

Вне версии работают только трекинговые edge-эндпоинты — у них короткие пути для скорости и совместимости с рекламными системами:

Путь	Назначение
`GET /r/{code}`	Редирект по трекинг-ссылке (302).
`GET /p/{code}.gif`	Пиксель-фоллбэк (1×1 GIF) для атрибуции без редиректа.

Подробности — на странице Трекинг и постбэк.

Формат ответов

Тело запросов и ответов — JSON (Content-Type: application/json), кодировка UTF-8.
Денежные суммы и ставки передаются строками (NUMERIC), а не числами с плавающей точкой — чтобы не терять копейки. Например "amount": "1500.00".
Валюты — трёхбуквенный ISO-код в верхнем регистре: RUB, USD, EUR.
Даты и время — ISO 8601 в UTC (например 2026-06-14T12:30:00Z).

Формат ошибок

Любая ошибка возвращается единым конвертом. У каждой ошибки есть стабильный машиночитаемый code — на него и завязывайте логику, а не на текст message (текст может меняться и локализуется).

Пример ошибки

{
  "error": {
    "code": "POSTBACK_BAD_SIGNATURE",
    "message": "Подпись неверна",
    "details": {}
  }
}

error.codestringrequired

Стабильный код ошибки (например KYC_REQUIRED, INSUFFICIENT_BALANCE). Не меняется между релизами.

error.messagestringrequired

Человекочитаемое описание. Может меняться и локализоваться — не парсите его.

error.detailsobjectoptional

Дополнительный контекст ошибки. Присутствует не всегда (например при 429 — { "limit": ..., "window_seconds": ... }). Если контекста нет, поле может отсутствовать.

Ошибки валидации тела запроса возвращаются с HTTP 422 и кодом VALIDATION_ERROR; в details — список проблемных полей.

Частые HTTP-коды

Код	Когда
`200` / `201` / `202` / `204`	Успех (создано / принято в обработку / без тела).
`400`	Некорректный запрос (например устаревший `X-Timestamp`).
`401`	Нет/невалидна аутентификация (токен, подпись).
`403`	Нет прав (чужой tenant, недостаточная роль, embed-скоуп).
`404`	Ресурс не найден.
`409`	Конфликт (дубликат, занятый slug, повтор подписи).
`422`	Ошибка валидации тела.
`429`	Превышен лимит запросов (см. Лимиты).
`5xx`	Ошибка на стороне платформы или временная недоступность зависимости.

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

API использует три механизма — выбор зависит от того, кто и зачем обращается:

Механизм	Кто использует	Как передаётся
MeerID OIDC → JWT	Вход людей в кабинеты	Обмен на JWT через `POST /api/v1/auth/meerid/exchange`
JWT Bearer	Кабинеты и embed-SDK	`Authorization: Bearer <access_token>`
tenant_api_key (HMAC)	S2S: постбэк, token-exchange	Заголовки `X-Api-Key-Id`, `X-Timestamp`, `X-Signature` (+ `X-Tenant-Id`)

Access-токен живёт 15 минут, refresh — 30 дней; ротация через POST /api/v1/auth/refresh. Полное описание схем, подпись HMAC и примеры — на странице Аутентификация и в разделе Auth.

Пагинация

Списочные эндпоинты используют offset-пагинацию через query-параметры:

skipintegeroptional

Сколько записей пропустить от начала. По умолчанию 0, минимум 0.

limitintegeroptional

Размер страницы. По умолчанию 50 (для некоторых списков — 100), максимум зависит от эндпоинта (обычно 200, для ссылок — 500).

В ответе списочных методов рядом с массивом данных возвращается total — общее число записей, удовлетворяющих фильтру (для расчёта количества страниц).

Форма списочного ответа

{
  "items": [ /* ... */ ],
  "total": 137
}

items или data

Имя массива зависит от группы: эндпоинты инфлюенсера возвращают items, эндпоинты бизнеса — чаще data. Поле total присутствует в обоих случаях. Точная форма указана на странице каждой группы.

Интерактивная документация (Swagger)

Когда платформа запущена в режиме отладки (DEBUG), доступен интерактивный Swagger UI и OpenAPI-схема:

Путь	Что это
`GET /api/docs`	Swagger UI (Try it out).
`GET /api/openapi.json`	Машиночитаемая OpenAPI-схема.

В проде Swagger выключен

На боевом окружении DEBUG отключён, поэтому /api/docs недоступен (404) — это сделано намеренно, чтобы не раскрывать схему публично. Ориентируйтесь на этот справочник.