# Управление клиентами

Позволяет экспортировать, импортировать или синхронизировать вашу базу контактов. А также редактировать отдельную карточку клиента и его контактные данные.

В сервисе используется несколько слов для обозначения похожих сущностей. В интерфейсе Еадеска раздел называется «Клиенты», который состоит из контактов. В свою очередь, контакт включает в себя контактные данные, например, номер телефона. Схема такая:

Раздел «Клиенты»

* Вася Пупкин
  * Телефон: +79876543210
* Алиса
* Дарт Вейдер
  * Почта: <vader@deathstar.com>
  * Телеграм: @vader327

Подробнее о схеме данных ниже.

## Схема данных объекта «контакт»

Объект «контакт» состоит из набора полей:

**\_id** — уникальный идентификатор контакта

**name** — имя контакта

**description** — произвольное описание контакта

**segments** — массив уникальных идентификаторов сегментов. Пример:

```json
"segments": [ "638b6be911dc02025204f1c5" ],
```

**contacts** — массив контактных данных, каждый элемент которых содержит:

* id — уникальный идентификатор элемента контактных данных.
* value — например, "<hello@yandex.ru>".
* 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'}`