Вход клиента

Создаёт или находит клиента внутри проекта текущей витрины и отправляет одноразовый код: звонком на телефон или письмом на email.

Параметры запроса

• phone (string, обязательно) — телефон или email клиента. Для телефона используйте нормализованный формат 7XXXXXXXXXX.

Пример запроса

{
    "phone": "79999999990"
}

Несмотря на историческое имя поля phone, в нём также можно передать email.

Ответ

При успешном действии возвращается HTTP 200.

{
    "message": "Password successfully send"
}

Код действует 5 минут и погашается после успешного входа.

Возможные ошибки

• 401 Application token is missing — не передан заголовок Token.
• 401 Application token is invalid — App Token неизвестен или выключен.
• 422 — поле phone отсутствует или имеет неверный формат.
• 429 — превышен лимит: до 3 запросов в час на контакт внутри проекта и до 20 запросов в час с одного IP.
• 500 Internal server error — код не удалось отправить.

Параметры запроса

• phone (string, обязательно) — телефон в цифровом формате или email, на который запрашивался код.
• password (обязательно) — одноразовый код из звонка или письма.
• device (string, необязательно, 3–50 символов) — имя устройства для токена, например storefront-web.

Пример запроса

{
    "phone": "79999999990",
    "password": "1111",
    "device": "storefront-web"
}

Ответ

При успешном действии возвращается HTTP 200 с объектом клиента и Bearer token.

{
    "counterparty": {
        "id": 1,
        "type": {
            "id": 2,
            "name": "Розница",
            "created_at": "2024-03-23T10:27:06.000000Z"
        },
        "manager": {
            "id": 1,
            "first_name": "Артём",
            "last_name": "Полищук",
            "middle_name": "Николаевич",
            "name": "Полищук Артём"
        },
        "avatar": null,
        "first_name": "Алексей",
        "last_name": "Петров",
        "middle_name": "Викторович",
        "birthday": "1980-04-02",
        "address": "630073, Новосибирская область, город Новосибирск, Новогодняя ул., д. 20/1, кв. 26",
        "phone_1": "79999999990",
        "phone_2": "78888888888",
        "email": "support@itecho.ru",
        "created_at": "2024-03-22T14:01:37.000000Z",
        "updated_at": "2024-03-23T10:48:33.000000Z",
        "favourite_products": [],
        "access_token": {
            "value": "2|k8InFzsVIDB3sumslYax1hWJcZDglKptEgIWzxWo21bdb3d6"
        }
    }
}

access_token.value — Bearer token клиента. Полный состав объекта описан на странице Профиль клиента.

Возможные ошибки

• 400 Send password before login. Password TTL is 5 minutes. — код не запрашивался, уже использован или истёк.
• 401 Application token is missing / Application token is invalid — проблема с App Token.
• 401 Указан неправильный пароль — неверный одноразовый код.
• 422 — параметры не прошли валидацию, например в системе нет указанного телефона или email.
• 429 — превышен лимит: до 5 попыток в минуту на контакт внутри проекта и до 30 попыток в минуту с одного IP.

Используется, когда miniapp получил у провайдера подписанное подтверждение контакта клиента. В ответе выдаётся обычный counterparty.access_token.value для дальнейшей работы с API Gigma.

Канонический маршрут находится в counterparty-контуре. Не используйте alias URL вида /api/miniapps/.../auth/....

Параметры пути

• provider — маршрут принимает max или telegram. Подписанный вход по контакту сейчас поддерживает max; для Telegram без подтверждения владения телефоном backend возвращает 422.

Параметры запроса

• phone (string, обязательно, до 32 символов) — телефон из подписанного contact payload. Backend нормализует его к 7XXXXXXXXXX.
• auth_date (integer, обязательно) — время подписи Unix в секундах, миллисекундах или микросекундах; значение не должно быть из будущего или старше настроенного TTL.
• hash (string, обязательно) — подпись contact payload, 64 hex-символа.
• init_data (string, обязательно, до 8192 символов) — подписанные init data miniapp.
• device (string, необязательно, до 255 символов) — имя устройства для токена, например max-miniapp.

Пример запроса

{
    "phone": "+79139277802",
    "auth_date": 1780000000,
    "hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "init_data": "auth_date=1780000000&user=%7B%22id%22%3A123456%7D&hash=...",
    "device": "max-miniapp"
}

Ответ

При успешном действии возвращается HTTP 200 с полным объектом клиента и access_token — так же, как при входе по коду. Ниже ответ сокращён:

{
    "counterparty": {
        "id": 1,
        "phone_1": "79139277802",
        "access_token": {
            "value": "2|k8InFzsVIDB3sumslYax1hWJcZDglKptEgIWzxWo21bdb3d6"
        }
    }
}

Возможные ошибки

• 401 Application token is missing / Application token is invalid — проблема с App Token.
• 401 miniapp_contact_auth_invalid — подпись, init_data или срок действия не прошли проверку.
• 422 — параметры запроса не прошли валидацию.
• 422 miniapp_contact_auth_not_supported — провайдер не поддерживает безопасный signed contact login, например Telegram без proof владения телефоном.
• 429 — превышен лимит 5 запросов в минуту.
• 503 miniapp_contact_auth_not_configured — на backend не настроен токен провайдера.

Создаёт callback-сессию и возвращает номер, на который клиент должен позвонить со своего телефона.

Параметры запроса

• phone (string, обязательно) — телефон клиента. Backend нормализует значение к 7XXXXXXXXXX.
• client_nonce (string, обязательно) — секрет текущей попытки входа, 32–128 символов base64url.

Пример запроса

{
    "phone": "+7 (900) 123-45-67",
    "client_nonce": "R2xvYmFsTm9uY2VFeGFtcGxlMTIzNDU2Nzg5MA"
}

Ответ

При успешном действии возвращается HTTP 200.

{
    "session_token": "opaque-session-token",
    "callback_number": "79001000011",
    "expires_at": "2026-07-03T01:23:45+00:00"
}

• session_token — временный токен callback-сессии, а не Bearer token клиента.
• callback_number — номер, на который клиент должен позвонить с указанного телефона.
• expires_at — время окончания сессии. TTL составляет 5 минут.

IP не участвует в авторизации сессии: переход между Wi-Fi и мобильной сетью не прерывает вход.

Возможные ошибки

• 401 Application token is missing / Application token is invalid — проблема с App Token.
• 409 callback_auth_session_already_started — этот client_nonce уже использован. Начните новую попытку с новым значением.
• 409 callback_auth_challenge_already_active — для телефона уже создаётся звонок. Дождитесь окончания cooldown и повторите запрос с новым client_nonce.
• 422 — проверьте телефон и формат client_nonce.
• 429 callback_auth_rate_limited — повторите запрос через число секунд из заголовка Retry-After.
• 503 UCaller service unavailable. — сервис callback-звонков временно недоступен. Повторите запрос позже.

Возвращает текущее состояние callback-сессии. Этот метод никогда не возвращает Bearer token.

Параметры запроса

• session_token (string, обязательно, до 128 символов) — значение из ответа callback_auth/init.
• client_nonce (string, обязательно) — значение, переданное в callback_auth/init.

Пример запроса

{
    "session_token": "opaque-session-token",
    "client_nonce": "R2xvYmFsTm9uY2VFeGFtcGxlMTIzNDU2Nzg5MA"
}

Ответ

При успешном запросе API вернёт HTTP 200 OK.

{
    "status": "pending",
    "expires_at": "2026-07-03T01:23:45+00:00",
    "server_time": "2026-07-03T01:20:10+00:00",
    "remaining_seconds": 215
}

status	Что делать
pending	Повторите запрос через 3–5 секунд. Для таймера используйте server_time и remaining_seconds.
verified	Вызовите POST /api/counterparty/callback_auth/exchange до времени из expires_at. После подтверждения звонка окно обмена составляет не менее 120 секунд.
expired	Очистите данные сессии и начните новую попытку с новым client_nonce.

Возможные ошибки

• 401 Application token is missing / Application token is invalid — проблема с App Token.
• 404 Session not found — проверьте session_token, client_nonce и App Token. Если восстановить значения нельзя, начните вход заново.
• 422 — проверьте обязательные поля и их длину.
• 429 — уменьшите частоту polling и повторите запрос после паузы.

session_token привязан к проекту и Application, но не к IP. Он не заменяет Bearer token.

Обменивает подтверждённую callback-сессию на Bearer token клиента.

Параметры запроса

• session_token (string, обязательно, до 128 символов) — значение из ответа callback_auth/init.
• client_nonce (string, обязательно) — значение, переданное в callback_auth/init.
• device (string, опционально, до 255 символов) — название устройства или приложения для журнала сессий.

Пример запроса

{
    "session_token": "opaque-session-token",
    "client_nonce": "R2xvYmFsTm9uY2VFeGFtcGxlMTIzNDU2Nzg5MA",
    "device": "web"
}

Ответ

При успешном запросе API вернёт HTTP 200 OK.

{
    "access_token": "12|plainSanctumToken"
}

Сохраните access_token целиком, включая разделитель |. Следующий запрос выберите по карте интеграции: профиль клиента или заказы, оплаты и подписки.

Возможные ошибки

• 401 Application token is missing / Application token is invalid — проблема с App Token.
• 404 Session not found — session_token, client_nonce или App Token не относятся к одной сессии.
• 409 callback_auth_not_verified — звонок ещё не подтверждён. Вернитесь к проверке статуса.
• 410 callback_auth_expired — сессия истекла. Начните вход заново.
• 410 callback_auth_exchange_window_closed — окно повторной выдачи закрыто. Начните вход заново.
• 422 — проверьте обязательные поля и их длину.
• 429 — повторите запрос после паузы. Не используйте повторный exchange как способ создать второй активный токен.

Повторный exchange предназначен только для восстановления после потерянного ответа. В течение 60 секунд API отзывает предыдущий Bearer и выдаёт новый; после этого возвращает 410.

Параметры запроса

• from_all_devices (boolean, обязательно) — true, чтобы удалить все токены клиента; false, чтобы удалить только текущий токен.

Пример запроса

{
    "from_all_devices": true
}

Ответ

Для выхода со всех устройств:

{
    "message": "User successfully logout from all devices"
}

Для выхода только с текущего устройства:

{
    "message": "User successfully logout"
}

Возможные ошибки

• 401 Unauthenticated — Bearer token отсутствует или недействителен.
• 422 — from_all_devices отсутствует или не является boolean.