Перейти к основному содержимому

Быстрый старт

Интеграционный API нужен системам организации: CRM, биллингу, своему чат-клиенту, боту. Они читают обращения и управляют ими от имени сервисного аккаунта. Здесь — путь от доступа до первого обращения. Попробовать без своей установки можно в песочнице.

1. Получите сервисный аккаунт​

Сервисный аккаунт — клиент Keycloak с client credentials, привязанный к одной организации:

  • в песочнице стенда Shtab его выдают по запросу, вместе с client_id и секретом (как получить);
  • в своей установке его заводит администратор установки и назначает роль (аутентификация).

Секрет клиента храните как пароль: в менеджере секретов, не в репозитории и не в логах.

2. Получите токен​

export HELPDESK_URL=https://helpdesk.example.ru          # адрес установки, без пути
export TOKEN_URL=https://sso.example.ru/realms/helpdesk/protocol/openid-connect/token
export CLIENT_ID=svc-crm
read -rs CLIENT_SECRET && export CLIENT_SECRET            # секрет не попадает в историю

TOKEN=$(curl -sS "$TOKEN_URL" \
  -d grant_type=client_credentials \
  -d client_id="$CLIENT_ID" \
  --data-urlencode client_secret="$CLIENT_SECRET" | jq -r .access_token)

В песочнице адрес установки — https://helpdesk.shtab.io, выдача токена — https://helpdesk-sso.shtab.io/realms/helpdesk/protocol/openid-connect/token.

Токен живёт несколько минут. SDK получают и обновляют его сами, без SDK — запросите новый, когда API ответит 401.

3. Первый вызов​

Справочник категорий организации:

curl -sS "$HELPDESK_URL/api/integration/v1/categories" \
  -H "Authorization: Bearer $TOKEN"

Ответ — JSON со списком категорий. 401 — токен не принят (истёк, чужой realm, клиент не зарегистрирован сервисным аккаунтом), 403 — роли аккаунта не хватает права. Подробнее — ошибки.

4. Начните обращение​

Изменяющий вызов требует заголовок Idempotency-Key: уникальная строка на операцию, например UUID. Повтор с тем же ключом не выполнит операцию второй раз и вернёт первый ответ.

curl -sS "$HELPDESK_URL/api/integration/v1/conversations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
    "customer": {"namespace": "token:crm", "external_id": "client-42"},
    "subject": "Заказ 77",
    "text": "Здравствуйте! Где мой заказ?"
  }'

Клиент называется парой namespace и external_id. Для id из вашей системы — пространство token:<издатель>: тот же клиент, войдя в виджет по chat token этого издателя, увидит это обращение. Ответ — карточка обращения: id, номер HD-<n>, состояние и version для команд.

5. Дальше​

  • Справочник API — все операции, схемы и Playground.
  • SDK на Python, Go и JS берут на себя токен, ключи повторов, повторы и обход страниц.
  • Вебхуки — события обращений без опроса API.
  • Свой канал через Kafka — клиентский чат в своём интерфейсе.