Справочник входа агента

Все пути ниже используют https://platform.invoise.me/api/v1. Для JSON передавайте Content-Type: application/json. Запросам входа не нужен ключ идемпотентности.

Вход по кошельку — только для агентов. Запрос с заголовком Origin, как любой запрос из браузера, вернёт 403 wallet_sign_in_agents_only. Вызывайте эти эндпоинты с сервера или из скрипта.

POST /auth/wallet/challenge

Запросить сообщение для подписи. Авторизация не нужна.

Поле	Тип	Значение
`address`	string, обязательно	Адрес вашего EVM-кошелька.
`chain_id`	integer, обязательно	ID доступной EVM-сети из API.

Ответ 200: challenge_id и message, оба — строки.

Подпишите сообщение как есть через EIP-191 personal-message signing. Не отправляйте приватный ключ. Истёкший или использованный челлендж нужно запросить заново.

POST /auth/wallet/verify

Обменять подписанный челлендж на сессию. Bearer-токен не нужен.

Поле	Тип	Значение
`challenge_id`	string, обязательно	ID из ответа на запрос сообщения.
`signature`	string, обязательно	Подпись исходного сообщения, hex-строка.

{"challenge_id":"<challenge-id>","signature":"<0x-signature>"}

Ответ 200 с примерными значениями:

{
  "token": "<session-token>",
  "expires_at": "2026-09-21T10:00:00Z",
  "user": {
    "user_id": "<user-id>",
    "onboarding_required": true,
    "mfa_required": false
  }
}

Передавайте token как Authorization: Bearer <session-token>. Срок действия — expires_at. Cookie не устанавливается, поэтому bearer-запросам не нужен CSRF-заголовок.

Неверное или использованное доказательство может вернуть 401 unauthorized. Если после отправки одноразовой подписи случился таймаут, начните новый челлендж вместо бесконечного повтора подписи.

MFA, если включено

Вход по кошельку не обходит второй фактор. Если user.mfa_required равен true, подтвердите настроенный фактор с этой сессией до бизнес-запросов.

Для аккаунта с TOTP:

POST /api/v1/auth/totp/verify
Authorization: Bearer <session-token>
Content-Type: application/json

{"code":"<current-code>"}

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

POST /onboarding

Если user.onboarding_required равен true, создайте первого мерчанта. Аккаунт, вошедший только кошельком, должен передать рядом с name email владельца-человека, поэтому сначала спросите его:

{"name":"My merchant","email":"[email protected]"}

Отправьте запрос с bearer-сессией и Idempotency-Key. Email становится способом входа в этот же аккаунт. Invoise отправляет человеку уведомление: он открывает интерфейс, входит с этим email по одноразовому коду и попадает в аккаунт, созданный агентом.

Ошибка	Что означает
`400 email_required`	Нет `email`. Спросите его у своего человека.
`400 invalid_email`	Некорректный адрес.
`400 disposable_email`	Одноразовые почтовые адреса не принимаются. Укажите постоянный адрес.
`400 identity_already_linked`	Этот email уже принадлежит другому аккаунту. Попросите другой.

Дальнейшие шаги — в сценарии агента.

POST /auth/logout

Завершить текущую сессию. Передайте её bearer-токен. Успешный запрос возвращает 200; отозванная сессия больше не работает.

Для постоянной работы с платежами используйте API-ключ магазина. После входа продолжайте по сценарию агента.