Вход клиента

Gigma найдёт клиента внутри проекта текущего приложения или создаст нового, а затем отправит одноразовый код: звонком на телефон или письмом на 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 — код не удалось отправить.

Передайте тот же телефон или email и одноразовый код. В ответе Gigma вернёт профиль клиента и Bearer.

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

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

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

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

Ответ

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

{
    "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": "630000, Новосибирск, ул. Примерная, д. 1",
        "phone_1": "79999999990",
        "phone_2": "78888888888",
        "email": "client@example.com",
        "created_at": "2024-03-22T14:01:37.000000Z",
        "updated_at": "2024-03-23T10:48:33.000000Z",
        "favourite_products": [],
        "access_token": {
            "value": "2|exampleCounterpartyToken"
        }
    }
}

Используйте counterparty.access_token.value как Bearer клиента. Полный состав профиля описан на странице «Профиль клиента».

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

• 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.

Канонический маршрут находится в counterparty-части API. Не используйте alias вида /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 приложения.
• device (string, необязательно, до 255 символов) — название устройства, например max-app.

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

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

Ответ

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

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

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

• 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 — провайдер не поддерживает безопасный вход по подписанному контакту.
• 429 — превышен лимит 5 запросов в минуту.
• 503 miniapp_contact_auth_not_configured — на backend не настроен токен провайдера.

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

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

• 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 клиента.
• 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.

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

• 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 клиента.

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

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

• 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 отсутствует или недействителен.
• 422 — from_all_devices отсутствует или не является boolean.