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

Полноценный CRUD клиентов, доступный из вашего приложения.

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

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

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

• Вася Пупкин

  • Телефон: [phone]

• Алиса

• Дарт Вейдер

  • Почта: [e-mail]

  • Телеграм: @vader327

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

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

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

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

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

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

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

"segments": [ "638b6be911dc02025204f1c5" ],

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

• id — уникальный идентификатор элемента контактных данных.

• value — например, "[e-mail]".

• type — например "mail", необходимый для интерпретации value.

• service — например "mail", сервис для которого используется данное value.

• origin — например "chatra", сервис, который создал данный элемент контактных данных.

Пример контакта:

  "_id" : ObjectId("5b58ca64581c0dbc35d49598"), // Уникальный ID Контакта
  "name" : "Артем"
  "description" : "Моя тестовая учетка",
  "segments": [ "638b6be911dc02025204f1c5" ],  
  "accountId" : "5bed5057642820001e093322",
  "updatedAt" : 1548926978590,
  // Массив Контактных данных
  "contacts" : [  
     {
       "id" : "5bed5057642820001e090512",
        "value" : "[e-mail]",
        "type" : "mail",
        "service" : "mail"
        "origin" : "mail",
     },
     {
       "id" :  "5c52bd0a3e308a00367a7fac",
       "value" : "[e-mail]",
       "type" : "mail",
       "service" : "mail",
       "origin" : "manual"
     },
     {
       "id" :  "5c52bf6f3e308a00367a7fae",
       "value" : "phrw1oc544j18buxazs6tlg7q68vdfyin1emk06",
       "agent" : null,
       "type" : "id",
       "service" : "chatra",
       "origin" : "chatra"
     },
     {
       "id" :  "5c52c20b3e308a00367a7fb5",
       "value" : "[phone]",
       "type" : "phone",
       "service" : "phone",
       "origin" : "pbx"
     },
   ]
 }

Методы для работы с контактами

Все параметры считаются необязательными, если не указано иное.

Используются только GET/POST

/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'}