Вопросы и решение проблем

Ключи доступа

Я потерял client secret. Можно посмотреть его снова?

Нет. Он показывается один раз, при создании. Смените его, чтобы получить новый — но помните, что смена отключает всех клиентов, подключённых к вашей интеграции, во всех аккаунтах.

Меняются ли ключи после одобрения интеграции?

Нет. Одобрение ключи не затрагивает. Видимость тоже меняет только одобрение карточки: PRIVATE становится PUBLIC. Одобрение релиза делает код запускаемым, но не делает приложение публичным.

client_id не меняется никогда. secret и api_key меняются только тогда, когда вы сами их перевыпускаете: Перевыпустить ключи в панели заменяет оба ключа за один вызов; кнопки для смены только API-ключа в панели нет — это делается через API с regenerate_api_key: true. См. Смена ключей.

Что такое код приложения или интеграции?

Постоянный публичный slug, который хранится как system_id в API. В Моих приложениях вы сами выбираете его, проверяете доступность и занимаете до публикации. Это аналог кода виджета amoCRM; после сохранения переименовать его нельзя. Он же — {widget_code} в URL левого меню и значение bito.widget.code.

Можно обслуживать несколько клиентов одним API-ключом?

Нет. api_key принадлежит одному аккаунту. Для многих клиентов нужен OAuth, где у каждой установки своя пара токенов.

Авторизация

На каждый запрос приходит Integration is not installed

Интеграция создаётся неустановленной. Откройте её в списке Установлены на странице Интеграция и нажмите Установить — см. Создание интеграции. Та же ошибка возвращается после того, как клиент удалил интеграцию.

403 и You don't have permission to access from this IP

У интеграции заполнен ip_whitelist, а запрос пришёл с адреса, которого в списке нет. Добавьте адрес своего сервера (IPv4 или CIDR) или очистите список — см. Создание интеграции.

На каждый запрос приходит 401 Unauthorized

Проверьте по порядку: имя заголовка (api-key для ключа, Authorization: Bearer … для OAuth), что ключ содержит префикс username:, и что access-токену меньше 24 часов.

Access-токен перестал работать раньше 24 часов

Сессию за токеном завершили. Обычная причина — смена секрета, вторая по частоте — клиент удалил вашу интеграцию. Авторизуйтесь заново.

Invalid credentials при обмене кода авторизации

Либо код уже использован, либо ему больше 20 минут, либо не совпал client_secret. Код одноразовый — начните сценарий заново.

Обновление токена падает с Invalid credentials

Refresh-токен ротируется при каждом использовании. Если вы сохранили старый после успешного обновления, он уже мёртв. Сохраняйте новую пару в той же транзакции, где используете старую.

Вебхуки

Подписался, но ничего не приходит

Проверьте, что адрес https://, доступен из интернета и не находится во внутренней сети — Bito отклоняет loopback, RFC1918, link-local и адреса облачных метаданных. Затем проверьте, не было ли изменение массовой операцией: массовый импорт и групповые обновления не порождают вебхуков вообще.

Подпись никогда не совпадает

Почти наверняка вы считаете HMAC от повторно сериализованного тела. Считайте подпись по сырым байтам запроса, до любого JSON.parse. Ключ — секрет вашего клиента (client_secret); если вы его сменили, используйте новый. См. проверку подписи.

Событие пришло дважды / не по порядку / не пришло

Все три случая возможны by design. Доставка выполняется одной попыткой, без повторов и без гарантии порядка. Считайте вебхук поводом перечитать запись и периодически сверяйтесь полным чтением.

Интеграцию удалили, и вебхуки перестали работать

Удаление удаляет все вебхуки интеграции. При повторной установке подписка webhook_uri создаётся заново автоматически, а адреса, добавленные через webhook/subscribe, нужно подписать заново. Секрет подписи не меняется: это секрет вашего клиента (client_secret), и он меняется только при смене секрета.

Публикация

Сколько идёт проверка и что проверяют?

Bito отдельно проверяет карточку маркетплейса и релиз: тексты, права, публичные HTTPS lifecycle URL, архив и manifest, объявленные точки, install/uninstall и реальный путь проверки внутри Bito. Релиз проходит три этапа по порядку — код, карточка и проверка использования. См. Отправка на проверку и Проверка и публикация.

Заявку отклонили

Сначала определите, какой процесс отклонён. Причина карточки видна в Основной информации, причина релиза — у конкретной версии во вкладке Версии. Исправьте и повторно отправьте только этот процесс; общего состояния у карточки и релиза нет.

Релиз одобрен. Почему приложения нет в маркетплейсе?

Одобрение релиза делает код запускаемым, но не одобряет карточку. Отправьте карточку из Основной информации. При публикации виджета Bito также проверит, что текущий релиз одобрен модератором, а не только активирован локально.

После одобрения интеграция установится у всех?

Нет. Одобрение только добавляет её в маркетплейс. Каждый клиент устанавливает её сам, и каждая установка вызывает ваш хук установки.

Поведение API

Почему списки идут через POST, а не GET?

Потому что фильтры передаются телом JSON, а не строкой запроса: пагинация, диапазоны дат и вложенные фильтры плохо помещаются в URL. Чтение одной записи — GET, изменение — PUT, удаление — DELETE. Полная картина — в таблице методов.

Учтите: админский API Bito (тот, с которым работает веб-панель) принимает только POST. Здесь это правило не действует.

Удалил запись, а она всё равно возвращается

Bito использует мягкое удаление. Запись помечается удалённой, но не исчезает, и у большинства ресурсов есть эндпоинт get-deleted. Фильтруйте на своей стороне, если нужны только живые записи.

Как синхронизировать только изменения?

Большинство get-paging принимают фильтр updated_at. Храните время последней синхронизации и передавайте его — это намного дешевле, чем каждый раз перебирать всю коллекцию.

Идемпотентны ли запросы на запись?

Нет. Повторный create создаст вторую запись. Дедуплицируйте на своей стороне, прежде чем повторять запрос.

Не помогло? Напишите в поддержку.