Довідник автентифікації агента

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

Вхід через гаманець призначений лише для агентів. Запит із заголовком Origin, який є в кожному запиті браузера, повертає 403 wallet_sign_in_agents_only. Викликайте ці ендпоінти з сервера чи скрипта.

POST /auth/wallet/challenge

Запит повідомлення для підпису. Облікові дані не потрібні.

Поле	Тип	Значення
address	рядок, обов’язкове	Ваша адреса гаманця EVM.
chain_id	ціле число, обов’язкове	ID доступної мережі EVM з API.

Відповідь 200: challenge_id (рядок) і message (рядок).

Підпишіть повернене повідомлення точно так, як отримали, використовуючи підпис особистого повідомлення EIP-191. Ніколи не надсилайте приватний ключ. Прострочений або вже використаний виклик вимагає нового запиту.

POST /auth/wallet/verify

Обмін підписаного виклику на сесію. Bearer-токен не потрібен.

Поле	Тип	Значення
challenge_id	рядок, обов’язкове	ID, повернутий запитом виклику.
signature	рядок, обов’язкове	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, щоб відстежувати закінчення терміну. Кукі не встановлюється, тож 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>"}

Чутливі зміни, захищені MFA, також можуть повертати 403 mfa_required, коли потрібне свіже підтвердження. Коди відновлення вимагають основної сесії; це не самостійний спосіб входу. Інші фактори облікового запису описані у Вході в обліковий запис.

POST /onboarding

Коли user.onboarding_required — true, створіть першого мерчанта. Обліковий запис, що входив лише через гаманець, має надіслати email людини-власника поруч із name, тож спершу запитайте його у своєї людини:

{"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-ключ магазину. Про налаштування після входу див. Робочий процес агента.