Версіонування

Версія входить у шлях: /api/public/v1/.... Наразі доступна одна версія — v1, і вона стабільна.

Що вважається ламкою

Ми не випускаємо в межах v1 зміни, які можуть зламати робочу інтеграцію:

• видалення або перейменування ендпоінта, поля відповіді чи параметра;
• зміна типу поля (наприклад, рядок → число) або формату значення;
• нове обов'язкове поле в тілі запиту;
• звуження допустимих значень;
• зміна коду помилки для вже описаної ситуації.

Такі зміни виходять лише новою версією шляху — /api/public/v2/....

Що може змінюватися без зміни версії

Зміни, які не ламають коректно написаного клієнта, виходять у v1 будь-коли:

• нові ендпоінти;
• нові необов'язкові поля у відповідях;
• нові необов'язкові параметри запиту;
• нові значення в довідниках (типи кузовів, дозволи, валюти);
• уточнення тексту в полі message помилки.

Звідси два правила для інтеграції:

1. Ігноруйте невідомі поля у відповідях замість того, щоб падати на них.
2. Не покладайтеся на порядок ключів у JSON і на точні формулювання message — розгалужуйтесь за code (Помилки).

Непрозорі значення

Курсор пагінації (nextCursor) — непрозорий рядок. Його внутрішній формат не є частиною контракту й може змінитися в межах v1. Передавайте назад рівно те, що отримали, і не розбирайте його.

Припинення підтримки

Якщо колись з'явиться v2, попередня версія:

• продовжить працювати щонайменше 6 місяців після виходу нової;
• почне надсилати заголовки Deprecation і Sunset із датою вимкнення;
• лишиться описаною в документації з позначкою про застарілість.

Про такі зміни ми повідомляємо власників активних ключів заздалегідь і фіксуємо їх у журналі змін.

Рекомендація

Прив'язуйте інтеграцію до версії явно (тобто до /api/public/v1), а не збирайте шлях динамічно. Перехід на наступну версію має бути вашим свідомим рішенням, а не наслідком випадкової зміни конфігурації.