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

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

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

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

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

  • Вася Пупкин

    • Телефон: +79876543210

  • Алиса

  • Дарт Вейдер

    • Почта: vader@deathstar.com

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

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

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

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

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

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

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

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

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

  • value — например, "hello@yandex.ru".

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

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

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

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

"_id" : ObjectId("5b58ca64581c0dbc35d49598"), // Уникальный ID Контакта
"name" : "Артем"
"description" : "Моя тестовая учетка",
"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"
},
]
}

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

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

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

/api/clients/person/create

Метод: POST Тело запроса:

  • name (строка)

  • description (строка)

Возвращаемое значение: Контакт { _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 (строка)

Возвращаемое значение: обновленный объект Контакт { 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'}