← Назад в блог
Integrations2026-07-09

API versioning для B2B: как обновлять контракты без боли

Практика API-версионирования для B2B-интеграций: backward compatibility, deprecation policy и миграция клиентов.

API контракты и документация

Главный принцип

Новая версия API не должна внезапно ломать текущих интеграторов.

Versioning подходы

  • URI versioning (/v1, /v2)
  • Header-based versioning
  • Contract-first с OpenAPI

Deprecation policy

  • уведомление минимум за 90 дней
  • migration guide
  • тестовый sandbox для новой версии

Что контролировать

  • процент клиентов на каждой версии
  • ошибки по endpoint версиям
  • дедлайн принудительного вывода legacy

Migration plan без остановки интеграций

Самая частая ошибка — выпустить v2, но не дать клиентам понятный путь миграции. В B2B это почти всегда приводит к конфликту между sales и engineering: бизнес обещал сроки, интегратор не успел обновиться, а старая версия уже "на удаление".

Рабочий план миграции:

  1. Зафиксировать изменения контракта: какие поля добавлены, какие deprecated, какие поведения изменились.
  2. Сделать machine-readable changelog в OpenAPI (deprecated: true, x-sunset-date).
  3. Открыть sandbox c v2 и тестовыми ключами.
  4. Для ключевых клиентов провести migration call на 30 минут: что ломается и как перейти.

Backward compatibility: правила, которые реально работают

Ниже минимальный набор, который снижает риск поломки клиентов:

  • Никогда не менять тип существующего поля (string -> number) в рамках одной версии.
  • Никогда не менять семантику enum без новой версии.
  • Новые поля — только optional.
  • Ошибки API — через стабильный формат (code, message, details), чтобы клиентские обработчики не ломались.

Пример безопасной эволюции:

{
  "id": "deal_123",
  "status": "qualified",
  "amount": 12000,
  "currency": "USD",
  "metadata": {
    "source": "web_form"
  }
}

В следующем релизе можно добавить owner, probability, но нельзя удалить status без версии.

Коммуникация deprecation

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

Рекомендуемый цикл:

  • T-90: письмо + changelog + migration guide.
  • T-60: reminder + отчёт по клиентам, кто ещё на legacy.
  • T-30: персональные уведомления ответственным интеграторам.
  • T-7: финальное предупреждение.
  • T0: переключение и read-only окно для legacy (если возможно).

KPI управления версиями

Чтобы это не осталось "процессом ради процесса", фиксируйте метрики:

  • Adoption v2 (% ключей API на новой версии).
  • Time-to-migrate по сегментам клиентов.
  • Error rate на v1 vs v2.
  • Количество тикетов поддержки на 1000 запросов.

Если после запуска v2 support-трафик растёт, значит migration guide недостаточно конкретный.

FAQ

Нужно ли поддерживать две версии долго?
Да, если у вас enterprise-клиенты. Обычно 3-6 месяцев реалистично, меньше — только при жёстких договорах.

Можно ли делать "скрытую" breaking change без новой версии?
Технически можно, но бизнес-стоимость почти всегда выше: инциденты, эскалации, потеря доверия интеграторов.

Где хранить политику версионирования?
В публичной docs + в репозитории (/docs/api-versioning.md) с owner и датами sunset.