Клиенты и контрагенты

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

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

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

Назначение

Полноценное ведение клиентов, поставщиков и организаций: создание, изменение, контакты, реквизиты, поиск и связь с объектами обслуживания.

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

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

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

Карточка содержит ссылки только для чтения: links.edit (карточка панели), links.portal (вход в кабинет клиента), links.public=null. Ссылка портала сохраняет обычную клиентскую авторизацию; API не создаёт ссылку для входа без пароля. Для удалённого клиента все три ссылки равны null.

customers:read/write/delete и «Клиенты и поставщики → Просмотр, Изменение, Удаление». Реквизиты inn, kpp, ogrn, bank и internal_note читаются с обычным правом «Клиенты и поставщики → Просмотр» и изменяются с «Клиенты и поставщики → Изменение», включая очистку значением null. Фильтр по ИНН использует обычное право просмотра клиентов.

Фильтры: id, external_id, q, phone, email, inn, is_customer, is_supplier, updated_since, deleted.

GET списка и карточки с filter[deleted]=true выбирает только удалённых клиентов и требует одновременно разрешения подключения customers:read и customers:delete, а также права сотрудника «Клиенты и поставщики → Просмотр» и «Клиенты и поставщики → Удаление». Отсутствие любого из этих допусков — 403 FORBIDDEN; проверка прав выполняется до поиска конкретной карточки. При достаточных правах отсутствующая, чужая или недоступная запись — 404; неудалённая карточка с этим фильтром также возвращает 404. Без фильтра и с filter[deleted]=false доступны только неудалённые клиенты по обычным правам чтения. Разрешение подключения customers:write не заменяет customers:delete. Для удалённых клиентов действуют те же права просмотра; чтение версии перед restore не обходит авторизацию восстановления.

updated_at с точностью до секунды выбран основой version. Изменения внутри одной секунды могут иметь одинаковую версию. Поле не является моментом завершения транзакции или гарантированной границей уже видимых изменений; условия синхронизации описаны в правилах выборок.

Запросы и вложенные значения

При создании обязательны name длиной 1–255 символов и непустая строка phone до 255 символов. По умолчанию is_customer=true, is_supplier=false, contacts=[], custom_fields=[]. Хотя бы один из признаков клиента или поставщика должен быть true. Остальные необязательные контакты и реквизиты при отсутствии равны null. При изменении отсутствующие поля сохраняются. Для phone значения null, пустая строка, другой тип и превышение длины возвращают 422. Формат телефона не ограничен международной записью: допустима исходная непустая строка. Удаление и восстановление принимают {} и If-Resource-Version; восстановление возвращает 200 с карточкой или 409 при несовместимых связанных записях.

contacts — массив не более 100 объектов вида { "name": "Иван", "position": "Инженер", "phone": "+79990000000" }. Поля name (1–40 символов) и phone обязательны; position (до 40 символов или null) необязательно. Переданный массив полностью заменяет дополнительные контакты, [] очищает их, отсутствие поля сохраняет прежний список. Другие ключи не принимаются.

bank — объект только из name/bik/account/correspondent_account. При изменении присутствующие вложенные ключи изменяются, отсутствующие сохраняются; значение null очищает отдельный реквизит, bank=null очищает весь банк. Для contacts и bank внутренние имена не принимаются. Формат custom_fields описан в отдельном контракте и поддерживается при создании и изменении.

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

• Физические лица и организации хранятся в одном ресурсе клиентов. Поле company_name не даёт права менять принадлежность чужих документов.
• Телефон/email/ИНН помогают найти кандидатов, но неоднозначное совпадение не выбирается молча.
• Повтор создания с тем же external_id возвращает существующее соответствие либо конфликт данных, а не второго клиента.
• Для одного подключения у одного клиента может быть не более одного external_id одновременно. ID уникален в пределах подключения и типа ресурса; попытка связать второй ID с той же карточкой возвращает конфликт и не перезаписывает прежнее соответствие.
• Пароли, данные клиентских сессий, коды входа и отметки прочтения не принимаются и не возвращаются.
• Удаление проверяет связанные акты, договоры, оборудование и документы; клиентская история не уничтожается каскадно.

Пример входных данных

{
  "external_id": "crm-customer-104",
  "name": "ООО Северный сервис",
  "company_name": "ООО Северный сервис",
  "phone": "+79990000000",
  "inn": "7701234567",
  "kpp": "770101001",
  "is_customer": true,
  "is_supplier": false
}

Операции

GET /customers

Доступные клиенты; deleted=true требует одновременно права чтения и удаления.

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

Параметры

Ответы

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

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

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

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

POST /customers

Создание клиента с проверкой текущих прав при повторном запросе.

Доступ. Разрешения подключения: customers: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/customers" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: example:v1-customers-store:001" \
  --header "Content-Type: application/json" \
  --data-binary '@examples/requests/v1.customers.store.json'

GET /customers/{id}

Карточка клиента, включая реквизиты и внутреннюю заметку.

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

Параметры

Ответы

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

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

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

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

POST /customers/{id}/update

Изменить разрешённые поля. Отсутствующие ключи сохраняются; повтор проверяет текущий тариф.

Доступ. Разрешения подключения: customers: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/customers/101/update" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: example:v1-customers-update:001" \
  --header "If-Resource-Version: $RESOURCE_VERSION" \
  --header "Content-Type: application/json" \
  --data-binary '@examples/requests/v1.customers.update.json'

POST /customers/{id}/delete

Удаление клиента с проверкой связанных записей и сохранением истории. Тело запроса — {}.

Доступ. Разрешения подключения: customers: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/customers/101/delete" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: example:v1-customers-delete:001" \
  --header "If-Resource-Version: $RESOURCE_VERSION" \
  --header "Content-Type: application/json" \
  --data-binary '@examples/requests/v1.customers.delete.json'

POST /customers/{id}/restore

Восстановить удалённого клиента. Версия берётся из GET с filter[deleted]=true; тело запроса — {}.

Доступ. Разрешения подключения: customers: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/customers/101/restore" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: example:v1-customers-restore:001" \
  --header "If-Resource-Version: $RESOURCE_VERSION" \
  --header "Content-Type: application/json" \
  --data-binary '@examples/requests/v1.customers.restore.json'