RUEN

Переход с API v1 на API v2 для Каналов

Переход с каналов Channels API v1 на каналы Auths API v2 и связанные вебхуки

Это руководство поможет перевести интеграции, которые создают, получают, обновляют или удаляют каналы, а также слушают связанные с ними вебхуки.

Что меняется

Сущность та же — каналы. Меняется API:

ЧтоAPI v1API v2
Базовый URLhttps://api.pact.im/p1/...https://api.pact.im/api/p2/...
Вебхуки каналовДанные с entity: "channel", type: "qr_code" и похожими полями — см. Вебхуки v1Единый формат с "type": "auth" и "event": "create" | "update" | "delete" — см. События каналов
Способ подтверждения каналаМетоды request_code / confirm и данные из вебхуков (QR и т.п.)Подтвердить канал (QR, код или OAuth) и при необходимости Включить канал
API-методы каналов/p1/companies/:company_id/channels/.../api/p2/companies/:company_id/auths/... — см. Каналы

Аутентификация по-прежнему выполняется вашим приватным API-токеном. В v2 обычно передаётся параметр private_api_token в query-строке или в теле запроса — см. Аутентификация.

Соответствие эндпоинтов

ДействиеAPI v1 (Channels)API v2 (Auths)
СписокGET /p1/companies/:company_id/channelsКаналы компании — GET /api/p2/companies/:company_id/auths
Создание / подключениеPOST /p1/companies/:company_id/channelsСоздать канал — POST /api/p2/companies/:company_id/auths
Подтверждение (код / включение)POST .../channels/:id/request_code, POST .../channels/:id/confirmПодтвердить канал и Включить канал
Отключение / пауза—Отключить канал
Повторное включение—Включить канал
УдалениеDELETE /p1/companies/:company_id/channels/:idУдалить канал
Список по нескольким компаниям—Каналы (несколько компаний)

Параметры создания, специфичные для провайдера (токен, номер телефона, период синхронизации и так далее), описаны в разделе Создать канал.

Сценарии подтверждения (QR, код, OAuth)

В v1 подтверждение было разбросано по созданию канала, методам request_code и confirm, а также по данным вебхуков (например, QR-коды).

В v2:

  1. Выполните Создать канал для нужного провайдера.
  2. Пройдите сценарий, описанный в разделе Подтвердить канал:
    • QR — WhatsApp, Telegram Personal, MAX (qr в ответе и в вебхуках)
    • Код — WhatsApp / Telegram Personal, если передан phone_number
    • OAuth — Facebook, VK, Instagram Business, WhatsApp Business, Avito (oauth_provider_url)
  3. Используйте Включить канал, когда провайдер требует код подтверждения (например, сценарий с кодом у Telegram Personal).

Миграция вебхуков

События жизненного цикла каналов в v1 присылали данные с entity: "channel", type: "qr_code" и похожими структурами, описанными в разделе Вебхуки v1.

В v2 приходит единый формат с "type": "auth" и "event": "create" | "update" | "delete". Полные примеры и их значения описаны в разделе События каналов.

СитуацияСобытие канала в v2
Канал созданevent: create
Подключён / готов к работеevent: update со state: enabled
Отключёнevent: update со state: disabled
Удалёнevent: delete
Обновление QR, список страниц, прогресс OAuthevent: update (см. примеры в разделе событий каналов)

Чек-лист для обработчиков вебхуков

  1. Зарегистрируйте или обновите URL вебхука компании через Вебхуки компании (если вы ещё не получаете события v2).
  2. Научитесь принимать формат v2: event, type, object.
  3. Когда type === "auth", читайте состояние провайдера из object (а также pages / qr / oauth_provider_url, если они присутствуют).
  4. Перестаньте опираться в новой логике на поля, существовавшие только в v1: channel_id, channel_type, entity: "channel".
  5. Сохраняйте обработчики v1 только пока на старом API остаётся трафик; запланируйте их отключение после переключения.

Рекомендуемые шаги миграции

  1. Изучите обзор каналов в v2 — Каналы и объект канала (auth в API).
  2. Сопоставьте вызовы — замените каждый используемый эндпоинт Channels на соответствующий метод Auths из таблицы выше.
  3. Обновите создание и подтверждение — следуйте разделам Создать канал и Подтвердить канал для каждого поддерживаемого провайдера.
  4. Переключите вебхуки — реализуйте обработку Событий каналов; проверьте создание / подключение / отключение / удаление на тестовой компании.
  5. Проведите проверку — получите список каналов, создайте один тестовый канал, пройдите подтверждение, убедитесь в приходе вебхуков, затем удалите или отключите тестовый канал.
  6. Переключитесь — направьте продакшен-трафик на v2; уберите использование Channels v1, когда будете готовы.

Смежные разделы

НазадПартнерская программаДалееАутентификация

Поиск…

Начните вводить запрос