Версия — в пути: /v1. Внутри неё — только совместимые изменения: новые пути, новые необязательные
поля запроса, новые поля ответа, новые kind и code ошибок.
Несовместимое (убрать или переименовать поле, поменять смысл, сделать поле обязательным) — только в
/v2. Уходящий путь получает заголовки Deprecation: true и Sunset: <дата>
не меньше чем за 90 дней, дата и замена
появляются здесь.
Ваш код должен игнорировать незнакомые поля и обрабатывать незнакомый kind как
platform_unknown.
Изменения
Вебхуки подписок: заголовки X-Webhook-Subscription, X-Webhook-Delivery, X-Webhook-Timestamp, X-Webhook-Signature, User-Agent: webhooks/1.0. Дубли отсеивайте по id событий: повтор после неудачи может прийти с другим delivery_id. Idempotency-Key у создания задачи и подписки — рекомендуется. Ошибки /v1/webhooks: fields — список {loc, msg}. На странице ошибок — коды bad_ref, too_many_chats, bad_cursor, bad_idempotency_key, subscription_ended, subscription_not_active.
Вебхуки подписок: редакциям прежние заголовки X-Soroka-* и User-Agent: soroka-webhook приходят вместе с новыми X-Webhook-*. Бизнесу — без меток аккаунтов: нет account и X-Soroka-Account, group_by=account в учёте — только редакциям.
Вебхуки событий организации: право webhooks, пути /v1/webhooks (адреса, тестовое событие, журнал доставок, повтор), события task.done, task.partial, task.failed, quota.threshold, invoice.issued, monitor.hit, key.expiring; заголовки X-Webhook-*. Новые code: unknown_event, webhook_limit, webhook_disabled.
Документация /docs. В /v1/openapi.json — описания путей; ошибки разбора тела описаны как 400 с телом ошибки API (FastAPI-шных 422 нет и раньше не было).
Тарифы и кредиты: ошибка 402 payment_required с кодами credits_exhausted, trial_ended, read_only, subscription_cancelled, no_subscription, not_in_plan, plan_limit; оценка задачи POST /v1/jobs/estimate; тариф и остаток в GET /v1/me (billing); списанные кредиты задачи в result_summary.credits.
Лимит в минуту считается по календарной минуте UTC; X-RateLimit-Reset — секунд до начала следующей минуты.
Выдача без авторов-людей для бизнес-организаций; проверенным — author_hash вместо автора. Право сверх потолка организации — 403 auth_failed, code=edition_forbidden.
POST /v1/tg/resolve: сначала наш каталог (поле ответа source), fresh: true — мимо каталога.
Данные о людях — отдельными правами tg:people и vk:people.
Задачи /v1/jobs: список с фильтром status, progress.percent, отмена, файл результата json/csv/xlsx. ВКонтакте: коды ошибок vk_<номер>, пачка методов /v1/vk/batch.
Контракт v1: единая форма ошибок, курсорная пагинация, Idempotency-Key, подписки на события с доставкой потоком, страницами и вебхуком с подписью.
Белый список методов /v1/tg/call, аренды под чат, брокер прокси.