Версии и совместимость
На эти правила можно опираться, когда вы пишете интеграцию: они говорят, что лагерь обещает не ломать и к чему ваша CRM должна быть готова.
Версия — в адресе
Текущая версия — v1: https://partners.zvezdnyy-burabai.edu.kz/ext/v1.
- В v1 поля и адреса только добавляются. Ничего не удаляется, не переименовывается и не меняет смысла.
- Если когда-нибудь понадобится изменение, ломающее совместимость, оно выйдет как v2 по новому
адресу (
/ext/v2), а v1 продолжит работать параллельно с ней. - Описание API строится из кода сервера, и сборка сервера не пропускает изменений, ломающих совместимость v1. Справочник на этом сайте строится из того же описания.
Что может появиться — и ваша CRM должна это пережить
| Что | Как к этому готовиться |
|---|---|
| Новые поля в ответах | Пропускайте незнакомые поля. Не используйте строгую проверку схемы ответа, которая падает на лишнем поле |
| Новые значения в списках значений (статус брони, состояние счёта, способ оплаты) | Обрабатывайте незнакомое значение как «другое», не падайте |
| Новые типы событий | Пропускайте незнакомый тип; на вебхук отвечайте 200 |
| Новые коды ошибок | Обрабатывайте незнакомый код по статусу ответа HTTP (см. Ошибки) |
| Новые адреса | Ничего делать не нужно |
| Новые необязательные поля в запросах | Ничего делать не нужно: не передали — работает как раньше |
Если вы генерируете клиент по описанию OpenAPI, включите в генераторе режим, при котором незнакомые значения перечислений не вызывают ошибку (часто это настройка «open enums» или «allow unknown enum values»).
Что не меняется никогда
codeошибки — по нему можно ветвиться (текстmessage— может меняться).- Имена существующих полей и их смысл.
- Формат денег, дат, времени и номеров (см. Форматы данных).
- Способ подписи вебхуков
v1(см. Вебхуки). Проверяйте именно значенияv1и пропускайте другие пары в заголовкеZb-Signature.
Строгость к вашим запросам
Незнакомое поле в теле запроса — отказ 422 invalid_input с именем поля в message, а не
молчаливый пропуск: опечатка в имени поля не должна превратиться в «ничего не поменялось». Поэтому
не отправляйте «лишних» полей «на всякий случай».
Как узнать об изменениях
Новые возможности появляются в справочнике API и в этом руководстве. Описание API можно скачать в справочнике и сравнивать версии у себя. Вопросы о планах — администратору лагеря.