Наценки

Все операции. Авторизация. Запросы и повторы.

Все пути в этом файле дополняют /api/v1 на домене организации.

Описание и ограничения

Назначение

Справочник наценок: чтение, создание, изменение и контролируемое удаление.

Поля и назначение

Обязательность и null указаны в схемах каждой операции ниже.

Доступ и выборка

reference:read/write/delete и «Справочники → Просмотр, Изменение, Удаление»; дополнительные ограничения связанных сущностей сохраняются. Значения финансовых справочников не дают права читать или проводить деньги.

Фильтры: q, calculation_type

Правила и связи

При создании обязательны name (непустая строка до 255 символов), calculation_type (fixed или percentage) и value. note — строка до 10000 символов или null, по умолчанию null. Для fixed значение value — денежный объект в валюте организации; для percentage — неотрицательная десятичная строка с точностью до двух знаков. Допускается не более 16 цифр до десятичной точки и двух после неё; избыточная точность не округляется. При смене calculation_type передайте новое value. Остальные поля изменяются частично.

Создание возвращает 201 с карточкой, изменение — 200. Удаление принимает {} и возвращает 200 с признаком удаления. Для изменения и удаления нужен If-Resource-Version наценки. Некорректные тип, точность или валюта возвращают 422. Наценку, используемую в акте, заказе или счёте, нельзя удалить: 409 RESOURCE_IN_USE. События markup.created, markup.updated и markup.deleted содержат идентификатор, версию и признак удаления. Повтор запроса возвращает сохранённый результат; наценки существующих документов не пересчитываются.

• Обновление справочника не меняет исторические суммы документов.
• Одинаковое имя само по себе не является уникальным бизнес-ключом; сопоставление интеграции задаётся явно.
• Idempotency-Key защищает создание и изменение, включая параллельные запросы; GET не создаёт записи по умолчанию.

Операции

GET /reference/markups

Список.

Доступ. Разрешения подключения: reference:read. Права сотрудника: «Справочники → Просмотр». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.

Параметры

Ответы

Каждый ответ содержит новый X-Request-Id в заголовке. Общие транспортные отказы и правила повтора действуют также при отказе до контроллера; см. ошибки.

Пример запроса

Запускается из каталога комплекта после настройки переменных в быстром старте. Замените демонстрационные идентификаторы 101 и UUID идентификаторами доступных записей. $RESOURCE_VERSION берётся из GET владельца версии, описанного выше. Для нового действия сохраните новый ключ; для повтора используйте прежний.

curl --silent --show-error --globoff \
  "$API/reference/markups" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json"

POST /reference/markups

Создание записи.

Доступ. Разрешения подключения: reference:write. Права сотрудника: «Справочники → Изменение». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.

Параметры

Тело запроса

Content-Type: application/json. Тело обязательно.

Ответы

Каждый ответ содержит новый X-Request-Id в заголовке. Общие транспортные отказы и правила повтора действуют также при отказе до контроллера; см. ошибки.

У принятого POST Location и meta.operation_id указывают на журнал операции; ETag отсутствует. При повторе запроса сохраняются исходные data/meta, добавляется Idempotency-Replayed: true. Версии передавайте по назначению, указанному в описании ресурса.

Пример запроса

Запускается из каталога комплекта после настройки переменных в быстром старте. Замените демонстрационные идентификаторы 101 и UUID идентификаторами доступных записей. $RESOURCE_VERSION берётся из GET владельца версии, описанного выше. Для нового действия сохраните новый ключ; для повтора используйте прежний.

curl --silent --show-error --globoff --request POST \
  "$API/reference/markups" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: example:v1-reference-markups-store:001" \
  --header "Content-Type: application/json" \
  --data-binary '@examples/requests/v1.reference.markups.store.json'

GET /reference/markups/{id}

Карточка.

Доступ. Разрешения подключения: reference:read. Права сотрудника: «Справочники → Просмотр». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.

Параметры

Ответы

Каждый ответ содержит новый X-Request-Id в заголовке. Общие транспортные отказы и правила повтора действуют также при отказе до контроллера; см. ошибки.

Пример запроса

Запускается из каталога комплекта после настройки переменных в быстром старте. Замените демонстрационные идентификаторы 101 и UUID идентификаторами доступных записей. $RESOURCE_VERSION берётся из GET владельца версии, описанного выше. Для нового действия сохраните новый ключ; для повтора используйте прежний.

curl --silent --show-error --globoff \
  "$API/reference/markups/101" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json"

POST /reference/markups/{id}/update

Изменение.

Доступ. Разрешения подключения: reference:write. Права сотрудника: «Справочники → Изменение». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.

Параметры

Тело запроса

Content-Type: application/json. Тело обязательно.

Ответы

Каждый ответ содержит новый X-Request-Id в заголовке. Общие транспортные отказы и правила повтора действуют также при отказе до контроллера; см. ошибки.

У принятого POST Location и meta.operation_id указывают на журнал операции; ETag отсутствует. При повторе запроса сохраняются исходные data/meta, добавляется Idempotency-Replayed: true. Версии передавайте по назначению, указанному в описании ресурса.

Пример запроса

Запускается из каталога комплекта после настройки переменных в быстром старте. Замените демонстрационные идентификаторы 101 и UUID идентификаторами доступных записей. $RESOURCE_VERSION берётся из GET владельца версии, описанного выше. Для нового действия сохраните новый ключ; для повтора используйте прежний.

curl --silent --show-error --globoff --request POST \
  "$API/reference/markups/101/update" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: example:v1-reference-markups-update:001" \
  --header "If-Resource-Version: $RESOURCE_VERSION" \
  --header "Content-Type: application/json" \
  --data-binary '@examples/requests/v1.reference.markups.update.json'

POST /reference/markups/{id}/delete

Удаление при отсутствии запрещённых зависимостей.

Доступ. Разрешения подключения: reference:delete. Права сотрудника: «Справочники → Удаление». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.

Параметры

Тело запроса

Content-Type: application/json. Тело обязательно.

Тело — пустой JSON-объект {}. Другие ключи не принимаются.

Ответы

Каждый ответ содержит новый X-Request-Id в заголовке. Общие транспортные отказы и правила повтора действуют также при отказе до контроллера; см. ошибки.

У принятого POST Location и meta.operation_id указывают на журнал операции; ETag отсутствует. При повторе запроса сохраняются исходные data/meta, добавляется Idempotency-Replayed: true. Версии передавайте по назначению, указанному в описании ресурса.

Пример запроса

Запускается из каталога комплекта после настройки переменных в быстром старте. Замените демонстрационные идентификаторы 101 и UUID идентификаторами доступных записей. $RESOURCE_VERSION берётся из GET владельца версии, описанного выше. Для нового действия сохраните новый ключ; для повтора используйте прежний.

curl --silent --show-error --globoff --request POST \
  "$API/reference/markups/101/delete" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: example:v1-reference-markups-destroy:001" \
  --header "If-Resource-Version: $RESOURCE_VERSION" \
  --header "Content-Type: application/json" \
  --data-binary '@examples/requests/v1.reference.markups.destroy.json'