# Версии и совместимость

На эти правила можно опираться, когда вы пишете интеграцию: они говорят, что лагерь обещает не
ломать и к чему ваша CRM должна быть готова.

## Версия — в адресе

Текущая версия — **v1**: `https://partners.zvezdnyy-burabai.edu.kz/ext/v1`.

- В v1 поля и адреса **только добавляются**. Ничего не удаляется, не переименовывается и не меняет
  смысла.
- Если когда-нибудь понадобится изменение, ломающее совместимость, оно выйдет как **v2** по новому
  адресу (`/ext/v2`), а v1 продолжит работать параллельно с ней.
- Описание API строится из кода сервера, и сборка сервера не пропускает изменений, ломающих
  совместимость v1. Справочник на этом сайте строится из того же описания.

## Что может появиться — и ваша CRM должна это пережить

| Что                                     | Как к этому готовиться                                                      |
| --------------------------------------- | --------------------------------------------------------------------------- |
| Новые поля в ответах                    | Пропускайте незнакомые поля. Не используйте строгую проверку схемы ответа, которая падает на лишнем поле |
| Новые значения в списках значений (статус брони, состояние счёта, способ оплаты) | Обрабатывайте незнакомое значение как «другое», не падайте |
| Новые типы событий                      | Пропускайте незнакомый тип; на вебхук отвечайте `200`                       |
| Новые коды ошибок                       | Обрабатывайте незнакомый код по статусу ответа HTTP (см. [Ошибки](/partners/errors)) |
| Новые адреса                            | Ничего делать не нужно                                                      |
| Новые необязательные поля в запросах    | Ничего делать не нужно: не передали — работает как раньше                   |

Если вы генерируете клиент по описанию OpenAPI, включите в генераторе режим, при котором
незнакомые значения перечислений не вызывают ошибку (часто это настройка «open enums» или «allow
unknown enum values»).

## Что не меняется никогда

- `code` ошибки — по нему можно ветвиться (текст `message` — может меняться).
- Имена существующих полей и их смысл.
- Формат денег, дат, времени и номеров (см. [Форматы данных](/partners/formats)).
- Способ подписи вебхуков `v1` (см. [Вебхуки](/partners/webhooks#шаг-3-проверять-подпись)).
  Проверяйте именно значения `v1` и пропускайте другие пары в заголовке `Zb-Signature`.

## Строгость к вашим запросам

Незнакомое поле в теле запроса — отказ `422 invalid_input` с именем поля в `message`, а не
молчаливый пропуск: опечатка в имени поля не должна превратиться в «ничего не поменялось». Поэтому
не отправляйте «лишних» полей «на всякий случай».

## Как узнать об изменениях

Новые возможности появляются в [справочнике API](/api) и в этом руководстве. Описание API можно
скачать в справочнике и сравнивать версии у себя. Вопросы о планах — администратору лагеря.