Базовый URL#
| Среда | URL |
|---|---|
| Production | https://api.rentu.ru/api/external/v2 |
| Stage | https://stage-api.rentu.ru/api/external/v2 |
Stage это отдельный контур со своими данными и своими ключами. Ключ от production на stage не работает и наоборот.
Заголовки#
| Заголовок | Когда нужен | Значение |
|---|---|---|
Authorization | Все методы, кроме /auth/token | Bearer <access_token> |
Content-Type | Запросы с телом (POST) | application/json |
Accept | Всегда желательно | application/json |
Конверт ответа#
Успешный ответ всегда содержит success: true и данные в data:
{
"success": true,
"data": [ ... ],
"meta": {
"pagination": { "page": 1, "per_page": 100, "total": 1240 },
"time_zone": "Europe/Moscow"
}
}meta присутствует не везде, только там, где есть что сообщить: пагинация, таймзона,
параметры агрегации. Состав указан в описании конкретного метода.
Ошибка всегда содержит success: false и объект error:
{
"success": false,
"error": {
"code": "period_too_long",
"message": "Период превышает максимум тарифа: 31 день",
"details": {
"end_date": ["превышает допустимый период тарифа"]
}
}
}| Поле | Всегда? | Назначение |
|---|---|---|
code | да | Машиночитаемый код. Ветвиться нужно по нему |
message | да | Человекочитаемый текст на русском. Годится для лога и показа оператору |
details | нет | Карта «поле → список сообщений» для ошибок валидации |
Ветвиться по HTTP-статусу не стоит: одному статусу соответствует несколько кодов. Скажем, за 403 стоят и forbidden_sc (нет прав), и plan_required (нужен другой тариф), а реагировать на них надо по-разному.
Идентификаторы#
Идентификаторы непрозрачны, разбирать или предсказывать их не стоит.
Единственное исключение: id зоны подсчёта в /traffic_areas приходит целым числом,
потому что зоны живут в другом хранилище. Оно же передаётся в zone_id.
Деньги#
Все денежные суммы отдаются в копейках целым числом. Это касается и выручки, и среднего чека, и выручки на квадратный метр. Делить на 100 стоит только при показе человеку; для арифметики целые копейки удобнее и не теряют точность.
Совместимость#
Мы считаем обратно совместимыми и можем добавить без предупреждения:
- новое поле в объекте ответа;
- новое необязательное значение в перечислении, которое возвращается (не принимается);
- новый необязательный параметр запроса;
- новый метод.
Разбор ответа должен переживать появление незнакомого поля. Удаление поля, переименование или смена типа считаются несовместимым изменением. О таком предупредим заранее и опишем в разделе Изменения.