Начисления по договорам
Все операции. Авторизация. Запросы и повторы.
Все пути в этом файле дополняют /api/v1 на домене организации.
Описание и ограничения
Назначение
Чтение уже сформированной абонплаты за конкретные периоды договора.
Поля и назначение
| Публичное поле | Формат и смысл | Доступ |
|---|---|---|
id, service_contract_id |
id |
только чтение |
period_date |
календарная дата периода | только чтение |
amount |
{amount: "100.99", currency: "RUB"} без float |
только чтение |
is_paid |
существующий учётный признак | только чтение |
Обязательность и null указаны в схемах каждой операции ниже.
Доступ и выборка
service_contract_charges:read, «Клиенты и поставщики → Просмотр», «Деньги → Просмотр», активная возможность API/договоров и доступ к текущему договору. Отдельное разрешение подключения service_contracts:read не требуется. Обе группы прав проверяются для мастерской договора: финансовое право только в другой мастерской не раскрывает начисления. Недоступный договор и чужой ID начисления по пути доступного договора дают 404.
Фильтры: filter[period_from], filter[period_to] — календарные даты Y-m-d с включёнными границами; filter[is_paid] — строки true/false. Можно задать одну границу периода. Даты не переводятся между часовыми поясами. Сортировки id/-id, пагинация page[size] до 100 и подписанный page[cursor]. Неизвестные параметры и неверные периоды отклоняются с 422.
Карточка не принимает параметров запроса и поддерживает ETag/304 после актуальной авторизации, включая отзыв финансового права. В ответе только пять полей из таблицы; связи и сведения о кассовых операциях не возвращаются.
Операции
| Метод | Путь | Назначение |
|---|---|---|
| GET | /service-contracts/{contract_id}/charges |
Начисления договора |
| GET | /service-contracts/{contract_id}/charges/{id} |
Начисление за период |
GET /service-contracts/{contract_id}/charges
Начисления договора.
Доступ. Разрешения подключения: service_contract_charges:read. Права сотрудника: «Клиенты и поставщики → Просмотр», «Деньги → Просмотр». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.
Параметры
| Имя | Где | Тип | Обязательно | null | Ограничения |
|---|---|---|---|---|---|
Authorization |
заголовок | строка | да | нет | Bearer <SERVICEAPP_TOKEN> |
contract_id |
путь | строка | да | нет | Шаблон: ^(?:[0-9]+)$ |
sort |
параметр запроса | строка | нет | нет | Допустимо: "id", "-id" |
page[size] |
параметр запроса | целое число | нет | нет | ≥ 1; ≤ 100 |
page[cursor] |
параметр запроса | строка | нет | нет | не более 8192 символов |
filter[period_from] |
параметр запроса | строка (дата) | нет | нет | — |
filter[period_to] |
параметр запроса | строка (дата) | нет | нет | — |
filter[is_paid] |
параметр запроса | строка | нет | нет | Допустимо: "true", "false" |
Ответы
| HTTP | Назначение и схема |
|---|---|
| 200 | Успех. Полная схема и пример |
| 401 | Требуется действующий Bearer. Коды и формат ошибки |
| 403 | Недостаточно допуска. Коды и формат ошибки |
| 404 | Не найдено или недоступно. Коды и формат ошибки |
| 422 | Ошибка входных данных. Коды и формат ошибки |
| 429 | Лимит запросов, Retry-After. Коды и формат ошибки |
| 503 | Временно недоступно. Коды и формат ошибки |
Каждый ответ содержит новый X-Request-Id в заголовке. Общие транспортные отказы и правила повтора действуют также при отказе до контроллера; см. ошибки.
Пример запроса
Запускается из каталога комплекта после настройки переменных в быстром старте. Замените демонстрационные идентификаторы 101 и UUID идентификаторами доступных записей. $RESOURCE_VERSION берётся из GET владельца версии, описанного выше. Для нового действия сохраните новый ключ; для повтора используйте прежний.
curl --silent --show-error --globoff \
"$API/service-contracts/101/charges" \
--header "Authorization: Bearer $SERVICEAPP_TOKEN" \
--header "Accept: application/json"
GET /service-contracts/{contract_id}/charges/{id}
Начисление за период.
Доступ. Разрешения подключения: service_contract_charges:read. Права сотрудника: «Клиенты и поставщики → Просмотр», «Деньги → Просмотр». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.
Параметры
| Имя | Где | Тип | Обязательно | null | Ограничения |
|---|---|---|---|---|---|
Authorization |
заголовок | строка | да | нет | Bearer <SERVICEAPP_TOKEN> |
contract_id |
путь | строка | да | нет | Шаблон: ^(?:[0-9]+)$ |
id |
путь | строка | да | нет | Шаблон: ^(?:[0-9]+)$ |
If-None-Match |
заголовок | строка | нет | нет | — |
Ответы
| HTTP | Назначение и схема |
|---|---|
| 200 | Успех. Полная схема и пример |
| 304 | Представление не изменилось, без тела. Условный GET |
| 401 | Требуется действующий Bearer. Коды и формат ошибки |
| 403 | Недостаточно допуска. Коды и формат ошибки |
| 404 | Не найдено или недоступно. Коды и формат ошибки |
| 422 | Ошибка входных данных. Коды и формат ошибки |
| 429 | Лимит запросов, Retry-After. Коды и формат ошибки |
| 503 | Временно недоступно. Коды и формат ошибки |
| HTTP | Заголовок ответа | Тип | Описание |
|---|---|---|---|
| 200 | ETag |
строка | |
| 304 | ETag |
строка |
Каждый ответ содержит новый X-Request-Id в заголовке. Общие транспортные отказы и правила повтора действуют также при отказе до контроллера; см. ошибки.
Пример запроса
Запускается из каталога комплекта после настройки переменных в быстром старте. Замените демонстрационные идентификаторы 101 и UUID идентификаторами доступных записей. $RESOURCE_VERSION берётся из GET владельца версии, описанного выше. Для нового действия сохраните новый ключ; для повтора используйте прежний.
curl --silent --show-error --globoff \
"$API/service-contracts/101/charges/101" \
--header "Authorization: Bearer $SERVICEAPP_TOKEN" \
--header "Accept: application/json"