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

Все запросы к Chat Center API требуют валидного Bearer-токена в заголовке Authorization.

Получение токена

Перейдите в timevisit.ru/ui/integrations/ и создайте интеграцию типа HTTP API. После создания client_id и client_secret будут отправлены на вашу электронную почту.

Получите JWT-токен через Keycloak:

curl -X POST https://timevisit.ru/auth/realms/std/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=<ваш-client_id>" \
  --data-urlencode "client_secret=<ваш-client_secret>"

Успешный ответ — HTTP 200:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 300,
  "token_type": "Bearer",
  "scope": "webhook notification"
}

Поле access_token — Bearer-токен для запросов к API. Срок действия указан в expires_in в секундах; в примере это 5 минут. Кешируйте токен и обновляйте до истечения срока.

Ошибка invalid_client

Если сервер не принимает client_id или client_secret, он возвращает HTTP 401:

{
  "error": "invalid_client",
  "error_description": "Invalid client or Invalid client credentials"
}

Проверьте действующую пару client_id / client_secret из письма для одной интеграции HTTP API. Запрос токена должен идти на https://timevisit.ru/auth/realms/std/protocol/openid-connect/token.

Ошибки OAuth2 содержат поля error и error_description; формат ошибок самого HTTP API описан в справочнике.

Использование токена

Передавайте токен в каждом запросе:

Authorization: Bearer <ваш-токен>

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

curl -X POST https://timevisit.ru/unotice-openapi-client/api/v1/notifications \
  -H "Authorization: Bearer <ваш-токен>" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": { "value": "79001234567" },
    "notificationText": "Текст уведомления",
    "externalId": "my-unique-id-001"
  }'

Успешный ответ — HTTP 202:

{
  "notificationId": "550e8400-e29b-41d4-a716-446655440000"
}

Уведомление принято к обработке. Этот ответ не подтверждает доставку: конечный статус DELIVERED или FAILED приходит через webhook. Зарегистрируйте webhook до отправки уведомления.

Scopes

Scope	Назначение
notification	Отправка уведомлений
webhook	Управление webhook

Идемпотентность

При повторном запросе с тем же externalId в рамках одной интеграции API вернёт тот же notificationId без повторной отправки. Поле externalId рекомендуется указывать всегда — это позволяет безопасно ретраить запросы при получении ответов 500/503 и сетевых ошибках. Для нового уведомления используйте новый externalId.