API магазину

Публічні читальні виклики й товарний фід. Ключів не потрібно, реєстрації теж.

Що тут є

Два інтерфейси, і обидва призначені стороннім:

Машинний опис — OpenAPI 3.1. Каталог для автоматичного виявлення — /.well-known/api-catalog за RFC 9727.

Чого тут немає, і це навмисно

У магазину близько сорока адрес під /api/, і майже всі — його власна кухня: вхід за кодом, оформлення замовлення, створення платіжної сесії, вебхуки еквайрів, уся адміністративна частина. Вони не описані тут і не оголошені в каталозі.

Причина не в таємниці — код відкритий, адреси видно з будь-якої вкладки розробника. Причина в тому, що каталог API — це обіцянка: те, що в ньому оголошено, ми зобовʼязуємося не ламати без попередження. Внутрішні виклики таких зобовʼязань не мають і змінюються разом із вітриною. Оголосити їх означало б або збрехати про сталість, або сковати собі руки в магазині, якому кілька місяців.

Виклики вітрини

Питання про товар і його оцінка

GET /api/questions?sku=VW-T19

Повертає опубліковані питання й середню оцінку. Питання без відповіді магазину не віддається нікому: доки власник не відповів, це чернетка розмови, а не вміст сторінки.

rating дорівнює null, коли оцінок ще немає — саме null, а не нуль із середнім: «0,0 з 5» читається як оцінка, і то найгірша можлива.

Пошта того, хто питав, не публікується ніколи, у жодному полі.

Способи оплати

GET /api/pay/methods

Що саме налаштоване зараз. Порожній перелік означає, що онлайн-оплата не увімкнена; замовлення при цьому все одно оформлюються.

Стан

GET /api/health

Відповідає 200, коли каталог читається з бази, і 503, коли магазин працює на запасній копії каталогу. Про внутрішній устрій не повідомляє нічого.

Товарний фід

GET /feed.xml

YML — формат, який приймають українські майданчики. Збирається з бази під час запиту, тож ціни й залишки в ньому актуальні, а не такі, якими були на момент останньої збірки.

Одиниця пропозиції — варіант товару, а не товар: купують саме варіант, і ціна з залишком живуть на ньому.

Коли каталог недоступний, фід віддає 503, а не порожній документ. Це не дрібниця: валідний YML без жодної пропозиції майданчик читає як «товарів більше немає» і знімає їх із публікації.

Обмеження

Лічильників і ключів немає. Прохання: не частіше ніж раз на секунду. Фід кешується на годину — забирати його частіше сенсу немає, ви отримаєте ту саму відповідь.

Дані каталогу — назви, описи, фотографії, ціни — належать магазину. Використання у власному каталозі без домовленості не передбачене; для порівняння цін, агрегації чи дослідження — будь ласка.

Питання

Пишіть на контакти. Якщо вам потрібен виклик, якого тут немає, — скажіть, який і навіщо: додати простіше, ніж здається, а от відкликати оголошене вже ні.