# Управление клиентами Позволяет экспортировать, импортировать или синхронизировать вашу базу контактов. А также редактировать отдельную карточку клиента и его контактные данные. В сервисе используется несколько слов для обозначения похожих сущностей. В интерфейсе Еадеска раздел называется «Клиенты», который состоит из контактов. В свою очередь, контакт включает в себя контактные данные, например, номер телефона. Схема такая: Раздел «Клиенты» * Вася Пупкин * Телефон: +79876543210 * Алиса * Дарт Вейдер * Почта: * Телеграм: @vader327 Подробнее о схеме данных ниже. ## Схема данных объекта «контакт» Объект «контакт» состоит из набора полей: **\_id** — уникальный идентификатор контакта **name** — имя контакта **description** — произвольное описание контакта **segments** — массив уникальных идентификаторов сегментов. Пример: ```json "segments": [ "638b6be911dc02025204f1c5" ], ``` **contacts** — массив контактных данных, каждый элемент которых содержит: * id — уникальный идентификатор элемента контактных данных. * value — например, "". * type — например "mail", необходимый для интерпретации value. * service — например "mail", сервис для которого используется данное value. * origin — например "chatra", сервис, который создал данный элемент контактных данных. Пример контакта: ```javascript "_id" : ObjectId("5b58ca64581c0dbc35d49598"), // Уникальный ID Контакта "name" : "Артем" "description" : "Моя тестовая учетка", "segments": [ "638b6be911dc02025204f1c5" ], "accountId" : "5bed5057642820001e093322", "updatedAt" : 1548926978590, // Массив Контактных данных "contacts" : [ { "id" : "5bed5057642820001e090512", "value" : "hello@yandex.ru", "type" : "mail", "service" : "mail" "origin" : "mail", }, { "id" : "5c52bd0a3e308a00367a7fac", "value" : "hello.yeah@gmail.com", "type" : "mail", "service" : "mail", "origin" : "manual" }, { "id" : "5c52bf6f3e308a00367a7fae", "value" : "phrw1oc544j18buxazs6tlg7q68vdfyin1emk06", "agent" : null, "type" : "id", "service" : "chatra", "origin" : "chatra" }, { "id" : "5c52c20b3e308a00367a7fb5", "value" : "+76630550012", "type" : "phone", "service" : "phone", "origin" : "pbx" }, ] } ``` ## Методы для работы с контактами Все параметры считаются необязательными, если не указано иное. {% hint style="info" %} Используются только GET/POST {% endhint %} ### /api/clients/person/create Метод: **POST**\ Тело запроса: * name (строка) * description (строка) * segments (массив строк, может быть пустым). При добавлении в тело запроса заполняет это поле у контакта, не может быть undefined/null, по умолчанию будет создан пустой массив. Возвращаемое значение: `Контакт { _id, name, description, accountId }` \ Обратите внимание: мы сначала создаем контакт, а контактные данные добавляем позже другим методом. ### /api/clients/person/read Метод: **GET**\ Параметры запроса (query string, query parameters): * id * search (регулярное выражение) — ищет в поле 'name' и 'сontacts.value' * type (строка) — один из поддерживаемых типов или список через запятую: \ id, mail, phone * service (строка) — один из поддерживаемых сервисов или список через запятую:\ mail, phone, facebook, vk, whatsapp, chatra, telegram, skype * offset (число, по умолчанию 0) — смещение результатов ответа * limit (число, по умолчанию 50) — ограничение на количество отдаваемых записей * needExistingRecords (любое значение) — если этот параметр передан, то будут возвращены только неудаленные контакты. Возвращаемое значение: `Array[ Контакт ]` — массив объектов контакта. ### /api/clients/person/update/:id= Метод: **POST**\ Параметры: * id (обязательный) Тело запроса: * name (строка) * description (строка) * segments (массив строк, может быть пустым). При добавлении в тело запроса заполняет это поле у контакта, не может быть undefined/null, по умолчанию будет создан пустой массив. Возвращаемое значение: обновленный объект `Контакт { result: contact }` или `{err: 'ENOT_FOUND'}`. ### **/api/clients/person/delete/:id=** При вызове этого метода для Контакта устанавливается `{status: 'deleted'}` Метод: **POST**\ Параметры: * id (обязательный) Возвращаемое значение: `{result: true}` или `{err: 'ENOT_FOUND'}`. ## Методы для работы с контактными данными ### **/api/clients/person/contacts/create/:contact\_id** Этот метод создает контактные данные и присоединяет их к контакту. Метод: **POST**\ Параметры: * contact\_id (обязательный) —ID контакта, к которому добавляются данные Тело запроса: * value (обязательный, строка) — значение * type (обязательный, строка) — один из поддерживаемых типов: \ id, mail, phone * service (обязательный, string) — один из поддерживаемых сервисов:\ mail, phone, facebook, vk, whatsapp, chatra, telegram, skype Возвращаемое значение: `созданный объект {result: {id, value, type, service, origin}}` ### **/api/clients/person/contacts/read** Метод: **GET**\ Параметры запроса, любое сочетание параметров: * contact\_id (строка) * id (строка) * value (строка) * search (регулярное выражение) — ищет среди value * type: (строка) — один или список через запятую из поддерживаемых типов * service: (строка) — один или список через запятую из поддерживаемых сервисов * not\_deleted: true (строка) — при передаче этого параметра будут возвращены только не удаленные контакты. Возвращаемое значение: `{ result: Array[ контактые данные ] }` или `{err: 'ENOT_FOUND'}`. ### **/api/clients/person/contacts/update/:id** Метод: **POST**\ Параметры: * id (обязательный, строка) Тело запроса: * value * type (обязательный, строка) — только один из поддерживаемых типов * service (обязательный, строка) — только один из поддерживаемых сервисов Возвращаемое значение: `{ result: контактные данные }` или `{err: 'ENOT_FOUND'}`. ### **/api/clients/person/contacts/delete/:id=** При вызове этого метода контактным данным устанавливается `{status: 'deleted'}` Метод: **POST**\ Параметры: * id (обязательный) Возвращаемое значение: `{result: true}` или `{err: 'ENOT_FOUND'}`. ## Возвращаемые ответы и ошибки Наш сервер возвращает следующие коды ответов: ``` 200 — когда запрос принят. ПРОВЕРЯЙТЕ ВОЗВРАЩАЕМЫЙ ОБЪЕКТ, там может быть ошибка 400 BAD_REQUEST — если пользователь прислал неправильные данные в запросе 401 UNAUTHORIZED — не авторизован 404 NOT_FOUND - вызван несуществующий метод 500 INTERNAL - при нормальной работе такого быть не должно, но всё возможно. ``` Для некоторых методов при статусе 200 необходимо проверять возвращаемый объект {err}. Например, если при запросе на обновление контакта запись с указанным id не найдена, то HTTP Status = 200 и `{err: 'ENOT_FOUND'}` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://help.yeahdesk.ru/docs/for-developers/http-api/contacts.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.