SDK

SDK на Python, Go и JS/TS лежат в каталоге sdk/ комплекта поставки (helpdesk-<версия>.tar.gz, его выдаёт поставщик вместе с релизом). В публичные реестры пакеты не публикуются; их зависимости ставятся из публичных реестров или зеркала организации.

Язык	API-SDK	Установка
Python 3.11+	shtab_helpdesk_api-<версия>-py3-none-any.whl	pip install ./shtab_helpdesk_api-<версия>-py3-none-any.whl
JS/TS, Node.js 22.22+	shtab-helpdesk-api-<версия>.tgz	npm install ./shtab-helpdesk-api-<версия>.tgz
Go 1.26+	shtab-helpdesk-api-go-<версия>.tar.gz	распаковать и подключить через go mod edit -replace

Рядом — Kafka-SDK своего канала на тех же языках. Установка и полные примеры — в README каждого пакета. Вызов каждой операции через SDK на Python, Go и JS/TS — во вкладках справочника API, рядом с curl.

Что делает SDK

Каждый пакет содержит сгенерированный по integration.json клиент (по методу на операцию, имя метода — operationId) и тонкий слой поверх него:

• токен client credentials с обновлением;
• Idempotency-Key на каждый изменяющий вызов и тот же — на его повторы;
• повторы по retryable, outcome = unknown и 429 с Retry-After;
• обход страниц курсором;
• типизированная ошибка конверта (ошибки);
• загрузка файла клиента частями с продолжением после обрыва;
• проверка подписи вебхука.

Подключение

Python

import os

from shtab_helpdesk_api import Client, Credentials
from shtab_helpdesk_api.models import CustomerRef, StartIn

helpdesk = Client(
    'https://helpdesk.example.ru',
    Credentials(
        token_url='https://sso.example.ru/realms/helpdesk/protocol/openid-connect/token',
        client_id='svc-crm',
        client_secret=os.environ['HELPDESK_CLIENT_SECRET'],
    ),
)

conversation = helpdesk.start_conversation(
    StartIn(
        customer=CustomerRef(namespace='token:crm', external_id='client-42'),
        text='Здравствуйте! Где мой заказ?',
    )
)

Асинхронный клиент — AsyncClient.

JS/TS

import { HelpdeskApiClient } from '@shtab-helpdesk/api'

const helpdesk = new HelpdeskApiClient({
  baseUrl: 'https://helpdesk.example.ru',
  credentials: {
    tokenUrl: 'https://sso.example.ru/realms/helpdesk/protocol/openid-connect/token',
    clientId: 'svc-crm',
    clientSecret: process.env.HELPDESK_CLIENT_SECRET ?? '',
  },
})

const conversation = await helpdesk.startConversation({
  customer: { namespace: 'token:crm', external_id: 'client-42' },
  text: 'Здравствуйте! Где мой заказ?',
})

Go

client, err := api.New(api.Config{
	BaseURL: "https://helpdesk.example.ru",
	Credentials: api.Credentials{
		TokenURL:     "https://sso.example.ru/realms/helpdesk/protocol/openid-connect/token",
		ClientID:     "svc-crm",
		ClientSecret: os.Getenv("HELPDESK_CLIENT_SECRET"),
	},
})
if err != nil {
	return err
}

conversation, err := client.StartConversation(ctx, api.StartIn{
	Customer: api.CustomerRef{Namespace: "token:crm", ExternalID: "client-42"},
	Text:     "Здравствуйте! Где мой заказ?",
})

Один клиент на приложение: токен и соединения общие.

Загрузка файла клиента

uploadCustomerFile (Python — upload_customer_file, Go — UploadCustomerFile) открывает загрузку и шлёт части с Content-Range по chunk_size из ответа сервера (5 МиБ: части, кроме последней, принимаются только такого размера). После обрыва или 409 UPLOAD_OFFSET_MISMATCH SDK продолжает с received_bytes и возвращает attachment_id для POST conversations/{id}/messages. С тем же ключом повтора начала загрузки повторный вызов продолжает ту же загрузку.

Вебхуки

verifyWebhook(secret, signature, body) (Python — verify_webhook, Go — VerifyWebhook): секрет подписки, заголовок X-Helpdesk-Signature и сырое тело запроса дают разобранное событие или типизированную ошибку с причиной: подпись не сходится, метка старше допуска (по умолчанию 5 минут), заголовок битый, тело не событие, вид события неизвестен этой версии SDK. Подпись сравнивается за постоянное время. На ошибку отвечайте 401 и событие не обрабатывайте.

Модели событий (WebhookCustomerMessage, WebhookStateChanged и объединение WebhookEvent) сгенерированы из JSON Schema контрактов вебхуков тем же генератором, что и модели API. Готовый приёмник — examples/webhook пакета.

Лимит частоты и повторы

На 429 SDK ждёт Retry-After (не дольше потолка, по умолчанию 30 с) и повторяет с тем же Idempotency-Key. 429 повторяется у любого запроса, в том числе у части загрузки без ключа: лимит отказывает до выполнения. Исчерпав попытки (по умолчанию 4), SDK отдаёт ошибку API со статусом 429.

Методы операций принимают заголовки операции (Content-Range части загрузки) и байты тела (application/octet-stream) аргументами; файлы отчётов и выгрузок скачиваются потоком, как вложения.

Версии

SDK версионируются вместе с установкой: берите пакеты из комплекта той версии, с которой работаете. Версии сред — в матрице совместимости COMPATIBILITY.md комплекта.