Kotlin

Типизированный клиент для Pachca API на Kotlin. Построен на Ktor с корутинами (suspend), kotlinx.serialization и встроенным retry. Требуется Kotlin 2.2+ и Java 11+.

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

dependencyResolutionManagement {    repositories {        mavenCentral()        maven("https://jitpack.io")    }}

dependencies {    implementation("com.github.pachca:openapi:1.9.0")}

import com.pachca.sdk.PachcaClient val client = PachcaClient("YOUR_TOKEN")

// Получение профиляval response = client.profile.getProfile()// → User(id: Int, firstName: String?, lastName: String?, nickname: String, email: String?, phoneNumber: String?, department: String?, title: String?, role: UserRole, suspended: Boolean, inviteStatus: InviteStatus, inviterId: Int?, listTags: List<String>, customProperties: List<CustomProperty(id: Int, name: String, dataType: CustomPropertyDataType, value: String?)>, userStatus: UserStatus(emoji: String, title: String, expiresAt: OffsetDateTime?, isAway: Boolean, awayMessage: UserStatusAwayMessage(text: String)?)?, bot: Boolean, sso: Boolean, createdAt: OffsetDateTime, lastActivityAt: OffsetDateTime?, timeZone: String?, imageUrl: String?)

Инициализация

import com.pachca.sdk.PachcaClient // Стандартное подключениеval client = PachcaClient("YOUR_TOKEN") // С кастомным базовым URLval client = PachcaClient("YOUR_TOKEN", "https://custom-api.example.com/api/shared/v1")

Клиент реализует Closeable — закройте его после использования:

client.use { c ->    val profile = c.profile.getProfile()    println(profile.firstName)} // Или вручнуюclient.close()

Все методы

Запросы

Все методы — suspend-функции.

GET с параметрами:

import com.pachca.sdk.ChatAvailabilityimport com.pachca.sdk.ChatSortFieldimport com.pachca.sdk.SortOrderimport java.time.OffsetDateTime // Список чатовval lastMessageAtAfter = OffsetDateTime.parse("2025-01-01T00:00:00.000Z")val lastMessageAtBefore = OffsetDateTime.parse("2025-02-01T00:00:00.000Z")val response = client.chats.listChats(sort = ChatSortField.ID, order = SortOrder.DESC, availability = ChatAvailability.IS_MEMBER, archived = true, lastMessageAtAfter = lastMessageAtAfter, lastMessageAtBefore = lastMessageAtBefore, personal = false, limit = 1, cursor = "eyJpZCI6MTAsImRpciI6ImFzYyJ9")// → ListChatsResponse(data: List<Chat>, meta: PaginationMeta)

POST с телом запроса:

import com.pachca.sdk.ChatCreateRequestimport com.pachca.sdk.ChatCreateRequestChat // Создание чатаval request = ChatCreateRequest(    chat = ChatCreateRequestChat(        name = "🤿 aqua",        memberIds = listOf(123),        groupTagIds = listOf(123),        channel = true,        public = false    ))val response = client.chats.createChat(request = request)// → CreateChatResponse(data: Chat(id: Int, name: String, createdAt: OffsetDateTime, ownerId: Int, memberIds: List<Int>, groupTagIds: List<Int>, channel: Boolean, archived: Boolean, personal: Boolean, public: Boolean, lastMessageAt: OffsetDateTime, meetRoomUrl: String, avatarUrl: String?), meta: CreateChatResponseMeta(notFoundMemberIds: List<Int>, notFoundGroupTagIds: List<Int>))

Простой вызов по ID:

// Получение чатаval response = client.chats.getChat(id = 334)// → Chat(id: Int, name: String, createdAt: OffsetDateTime, ownerId: Int, memberIds: List<Int>, groupTagIds: List<Int>, channel: Boolean, archived: Boolean, personal: Boolean, public: Boolean, lastMessageAt: OffsetDateTime, meetRoomUrl: String, avatarUrl: String?)

Значение null

Необязательное поле, которое не задано, в запрос не попадает, поэтому метод обновления меняет только то, что вы передали. Некоторые поля API принимают null: например, null в oauth_client выключает у бота авторизацию от имени сотрудника, а в webhook.kind удаляет входящий вебхук. Чтобы отправить null, назовите поле в nullFields той же модели запроса так, как оно называется в Kotlin:

val request = BotUpdateRequest(    webhook = BotUpdateRequestWebhook(nullFields = setOf("kind")),)

nullFields есть у моделей запроса с такими полями, а в его описании перечислены имена, которые в нём можно указать. С другим именем SDK выбрасывает SerializationException и запрос не отправляет.

Пагинация

Поля пагинации называются как в API, но в camelCase: meta.paginate.nextPage, prevPage, hasNext и hasPrev, а у методов поиска ещё meta.total. Какие поля приходят у каждого метода и как понять, что страницы закончились, описано в разделе Пагинация.

Ручная пагинация

var cursor: String? = nullvar hasNext = truewhile (hasNext) {    val response = client.chats.listChats(limit = 50, cursor = cursor)    if (response.data.isEmpty()) break    for (chat in response.data) {        println("${chat.id} ${chat.name}")    }    cursor = response.meta.paginate.nextPage    hasNext = response.meta.paginate.hasNext ?: true}

В модели поле hasNext имеет тип Boolean?. Если оно null, цикл идёт дальше и останавливается на пустой странице. Так же обходят страницы методы *All().

Автопагинация

Для каждого метода с пагинацией есть *All() вариант:

// Все чаты одним спискомval chats = client.chats.listChatsAll()println("Всего: ${chats.size}")

Доступные методы автопагинации:

Обработка ошибок

SDK выбрасывает два типа исключений:

ApiError

Возникает при ошибках 400, 403, 404, 409, 410, 422 с массивом errors в теле:

import com.pachca.sdk.ApiError try {    client.chats.createChat(request)} catch (error: ApiError) {    for (e in error.errors) {        println("${e.key}: ${e.message}")  // name: не может быть пустым        println(e.code)                    // blank    }}

Поля ApiErrorItem:

Код статуса ответа — в поле statusCode. Если ответ с ошибкой пришёл без тела или не в JSON, SDK тоже выбрасывает ApiError: с кодом статуса и пустым errors. Так бывает с ответом 404 без тела от метода GETПоток событий, когда история событий выключена, и со страницей прокси при 502.

OAuthError

Возникает при ошибке авторизации: 401, а также 403 с кодом insufficient_scope или role_forbidden и отказе при обмене кода на токен. Код — в поле error, список кодов — в разделе Ошибки авторизации:

import com.pachca.sdk.OAuthError try {    client.profile.getProfile()} catch (error: OAuthError) {    println(error.error)              // "insufficient_scope"    println(error.errorDescription)   // описание ошибки}

Поле error — перечисление OAuthErrorCode: его сравнивают с константой, например error.error == OAuthErrorCode.INSUFFICIENT_SCOPE, а строку кода даёт error.error.value.

Повторные запросы

Паузы между попытками, к каждой SDK добавляет случайную величину до 25%:

• 429 с заголовком Retry-After: срок из заголовка
• 429 без заголовка: 1 сек, 2 сек, 4 сек
• 5xx: ~10 сек, ~20 сек, ~40 сек
• Сетевая ошибка у GET, PUT и DELETE: ~10 сек, ~20 сек, ~40 сек

Таймаут запроса и сетевую ошибку у POST SDK не повторяет. Повторы делает плагин Ktor HttpRequestRetry.

Общие правила повторов — в разделе Повторные запросы.

Типы

Все типы — @Serializable data class'ы:

import com.pachca.sdk.* // Моделиval chat: Chatval message: Messageval user: User // Запросыval req: ChatCreateRequest // Перечисленияval key: AuditEventKey = AuditEventKey.USER_LOGINval availability: ChatAvailability = ChatAvailability.PUBLICval role: ChatMemberRole = ChatMemberRole.ADMINval status: TaskStatus = TaskStatus.DONE // Ошибкиval apiError: ApiErrorval oauthError: OAuthError

Перечисление в ответе — value class со строкой value: значение, которого SDK ещё не знает, приходит как есть, и isKnown у него false. Поэтому when по такому перечислению заканчивается веткой else. Строку значения возвращает и toString(), а имя константы даёт name.

Все перечисления SDK: AuditEventKey, AuditLoginGrantDenyReason, AuditLoginGrantDevicePlatform, BotCanEdit, BotEventName, BotTemplateEngine, BotTriggerOn, BotWebhookKind, BotWhoCanAdd, ChatActivity, ChatAvailability, ChatMemberRole, ChatMemberRoleFilter, ChatSortField, ChatSubtype, CustomPropertyDataType, DraftRepetitionInterval, DraftType, FileTarget, FileType, InviteStatus, MemberEventType, MessageEntityType, MessageSearchSort, MessageSortField, OAuthErrorCode, OAuthScope, OAuthTokenTypeHint, ReactionEventType, SearchEntityType, SearchSortOrder, SortOrder, TaskKind, TaskStatus, UserCreateRole, UserEventType, UserRole, UserRoleInput, ValidationErrorCode, VideoCallEventType, VoiceTranscriptStatus и WebhookEventType.

Тело вебхука

Тела событий вебхука описаны классами MessageWebhookPayload, ReactionWebhookPayload, ButtonWebhookPayload, ViewSubmitWebhookPayload, ChatMemberWebhookPayload, CompanyMemberWebhookPayload, LinkSharedWebhookPayload и VideoCallWebhookPayload. Их общий интерфейс WebhookPayloadUnion разбирается своим сериализатором: класс он выбирает по полям type и event. Разбирает тело Json из kotlinx.serialization, эта библиотека приходит в проект вместе с SDK:

import com.pachca.sdk.ButtonWebhookPayloadimport com.pachca.sdk.WebhookPayloadUnionimport kotlinx.serialization.json.Json val json = Json { ignoreUnknownKeys = true } // body — тело запроса строкойwhen (val payload = json.decodeFromString<WebhookPayloadUnion>(body)) {    is ButtonWebhookPayload -> println("${payload.messageId} ${payload.data}")    else -> {}}

Подпись проверяйте по исходному телу до разбора, как в разделе Безопасность. Те же классы отдают функции pollWebhookEvents и pollWebhookPayloads, которые забирают события из истории: пример — в разделе Пример поллинга.

Зависимости

Первые три пакета приходят в проект вместе с SDK и доступны в вашем коде: их типы есть в API SDK (JsonElement, Flow и HttpClient), поэтому отдельно их подключать не нужно. Остальные SDK использует внутри.

Примеры

Отправка сообщения:

import com.pachca.sdk.MessageCreateRequestimport com.pachca.sdk.MessageCreateRequestMessageimport com.pachca.sdk.PachcaClient val client = PachcaClient("YOUR_TOKEN") val request = MessageCreateRequest(message = MessageCreateRequestMessage(entityId = 334, content = "Вчера мы продали 756 футболок (что на 10% больше, чем в прошлое воскресенье)"))val response = client.messages.createMessage(request = request)// → Message(id: Int, entityType: MessageEntityType, entityId: Int, chatId: Int, rootChatId: Int, content: String, userId: Int, createdAt: OffsetDateTime, url: String, files: List<File(id: Int, key: String, name: String, fileType: FileType, url: String, width: Int?, height: Int?, durationMs: Int?)>, voiceContent: VoiceContent(durationMs: Int, waveform: String, transcript: String?, transcriptStatus: VoiceTranscriptStatus?)?, buttons: List<List<Button(text: String, url: String?, data: String?)>>?, thread: MessageThread(id: Long, chatId: Long)?, forwarding: Forwarding(originalMessageId: Int, originalChatId: Int, authorId: Int, originalCreatedAt: OffsetDateTime, originalThreadId: Int?, originalThreadMessageId: Int?, originalThreadParentChatId: Int?)?, parentMessageId: Int?, displayAvatarUrl: String?, displayName: String?, changedAt: OffsetDateTime?, deletedAt: OffsetDateTime?, important: Boolean)

Список сотрудников:

import com.pachca.sdk.PachcaClient val client = PachcaClient("YOUR_TOKEN") val response = client.users.listUsers(query = "Олег", limit = 1, cursor = "eyJpZCI6MTAsImRpciI6ImFzYyJ9")// → ListUsersResponse(data: List<User>, meta: PaginationMeta)

Создание напоминания:

import com.pachca.sdk.PachcaClientimport com.pachca.sdk.TaskCreateRequestimport com.pachca.sdk.TaskCreateRequestCustomPropertyimport com.pachca.sdk.TaskCreateRequestTaskimport com.pachca.sdk.TaskKindimport java.time.OffsetDateTime val client = PachcaClient("YOUR_TOKEN") val request = TaskCreateRequest(    task = TaskCreateRequestTask(        kind = TaskKind.REMINDER,        content = "Забрать со склада 21 заказ",        dueAt = OffsetDateTime.parse("2020-06-05T12:00:00.000+03:00"),        priority = 2,        performerIds = listOf(123),        chatId = 456,        allDay = false,        customProperties = listOf(TaskCreateRequestCustomProperty(id = 78, value = "Синий склад"))    ))val response = client.tasks.createTask(request = request)// → Task(id: Int, kind: TaskKind, content: String, dueAt: OffsetDateTime?, priority: Int, userId: Int, chatId: Int?, status: TaskStatus, createdAt: OffsetDateTime, performerIds: List<Int>, allDay: Boolean, customProperties: List<CustomProperty(id: Int, name: String, dataType: CustomPropertyDataType, value: String?)>)