Partner API

Partner API предназначен для банков, ботов, панелей реселлеров, внутренних систем обеспечения и других надежных межсерверных интеграций. Версия 10.5.0 — это первый машинный контракт, готовый к использованию в банке.

Базовый URL

https://p-api.model-gate.com

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

Authorization: Bearer mg_partner_...

Каждый ответ представляет собой JSON, включая 404, 405, 429, и 500и включает в себя X-Request-ID. Ответы используют Cache-Control: no-store; хост-партнер не использует сеансы PHP браузера. Все внешние временные метки имеют формат UTC RFC3339 (YYYY-MM-DDTHH:MM:SSZ).

Все POST, PATCH, и DELETE операции требуют уникального Idempotency-Key заголовок. Model Gate хранит зашифрованный результат в течение 7 дней, поэтому повторная попытка того же запроса возвращает исходный результат без повторного выполнения мутации. Повторное использование одного и того же ключа для другого метода/пути/тела возвращает HTTP. 409.

Запросы партнеров защищены ограничением поминутной ставки на уровне учетной записи, настроенным PARTNER_API_RATE_LIMIT_PER_MINUTE (по умолчанию 600). Ответы включают X-RateLimit-Limit, X-RateLimit-Remaining, и X-RateLimit-Reset; HTTP 429 также включает в себя Retry-After.

Создайте или повторно сгенерируйте ключ Partner API в профиле Model Gate. Полный токен носителя отображается только один раз при генерации/ротации, а Model Gate хранит только свой хэш SHA-256 плюс префикс отображения. Немедленно сохраните токен в секретном менеджере на стороне сервера; если он потерян, поверните его.

В профиле есть отдельный Белый список IP-адресов API. Если оно не пусто, запросы Partner API должны исходить от разрешенного точного адреса IPv4/IPv6 или префикса CIDR. Правила API бизнес-организации применяются в дополнение к личному правилу. Источник, отклоненный любым действующим белым списком, получает HTTP 403 с error.type = ip_not_allowed.

Для бизнес-аккаунтов учетные данные Partner API доступны только проверенному владельцу организации. Руководители сотрудников и назначение делегированных бизнес-учетных данных управляются на веб-панели, где можно проверить разрешения на групповое выполнение. Таким образом, бизнес-ключи, созданные партнером, используют владельца как владельца выставления счетов и субъекта учетных данных. Поставляемый group_id необходимо назвать активную группу, принадлежащую учетной записи; неизвестная/замороженная группа отклоняется с помощью HTTP 422 вместо того, чтобы молча создавать несгруппированный ключ.

Десятичные значения

Поля финансов и использования всегда представляют собой строки JSON:

{
  "spend_limit": "100.0000000000",
  "usage": "12.3456789000",
  "remaining": "87.6543211000",
  "usage_price_multiplier": "0.900000"
}

Используйте десятичную арифметику произвольной точности. Никогда не преобразуйте эти значения в float.

Возможности

• Создавайте, перечисляйте, обновляйте, вращайте, замораживайте, размораживайте и удаляйте ключи API.
• Настройте оценку использования для каждого ключа.
• Создавайте группы и управляйте ими.
• Перемещайте ключи между группами.
• Прочтите использование ключей и групп.
• Прочитайте завершенную историю запросов на ключ в порядке окончания с 1–100 страницами строк и разбивкой токенов/цен. Подробная история запросов хранится в горячем режиме API_REQUESTS_HOT_RETENTION_DAYS (по умолчанию 7 дней); долгосрочная финансовая выверка использует журнал балансовых транзакций.
• Чтение текущего баланса счета и транзакций баланса счета с помощью курсорной нумерации страниц.
• Читайте события аудита управления партнерами с помощью курсорной нумерации страниц.
• Опрос результатов асинхронного вывода.

Видеть все конечные точки Partner API полные примеры запросов и ответов.

Последние записи истории запросов включают: principal_user_id когда принципал учетных данных все еще существует, отдельно от владельца выставления счетов компании.

Машиночитаемый контракт

Контракт OpenAPI 3.1 поставляется с каждым выпуском как resources/contracts/partner-api.openapi.yaml. Рассматривайте его вместе с этими страницами Partner API как контракт на интеграцию с банком. Неизвестные поля JSON и неизвестные параметры запроса скорее отклоняются, чем молча игнорируются.