Changelog и версионирование API в Италии
Версии API по датам, политика устаревания и недавние изменения — REST API в Италии.
Архитектура — Модель версионирования API в Италии
Мы используем версии API с датами: Accept-Version: 2026-03-15. Внутри версии изменения только аддитивные (новые поля, новые эндпойнты, новые значения enum за opt-in флагами). Ломающие изменения выходят как новая датированная версия. Аккаунт привязан к версии, активной на момент регистрации, если вы явно не обновитесь. Изменения канала SdI версионируются отдельно и публикуются в payload счёта.
Как подключить — Политика устаревания
Устаревания анонсируются не менее чем за 12 месяцев тремя каналами: баннер в дашборде, ежемесячный changelog по email и заголовок Sunset в ответах затронутых эндпойнтов. Мы никогда не удаляем поля молча. По окончании жизни старая версия отвечает 410 Gone с заголовком Link на гид по миграции. IVA 22% и другие налоговые поля рынка Италии стабильны в v1 и v2.
Эксплуатация и пограничные случаи — Недавние изменения (фрагмент)
2026-03-15: добавлен partial_ok на заказах, новое событие order.partially_shipped. 2026-01-10: добавлен идентификатор подтверждения SdI в payload счёта. 2025-11-04: idempotency-ключи стали обязательны на POST /v1/orders (breaking; v2). Полный changelog на /docs/changelog с RSS и Atom. Дополнения схемы Sistema di Interscambio (SdI) non-breaking в pinned-версиях.
Частые вопросы
Как pinned версии?
Дефолт аккаунта на момент регистрации; per-request override через Accept-Version. Тестируйте новую версию заголовком прежде чем менять дефолт.
Как вы анонсируете изменения?
Баннер в дашборде, ежемесячный email и заголовок Sunset на затронутых эндпойнтах. Никогда не меняем поведение молча в pinned-версии.
Есть ли RSS-лента?
Да — /docs/changelog.rss и Atom-лента /docs/changelog.atom.
Сколько поддерживаются старые версии?
Минимум 24 месяца с релиза преемника; уведомление за 12 месяцев до EOL.
Изменения канала SdI?
Отслеживаются в том же changelog. IVA 22% и другие налоговые поля стабильны в v1 и v2.