Links

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

Полноценный CRUD клиентов, доступный из вашего приложения.
Позволяет экспортировать, импортировать или синхронизировать вашу базу контактов. А также редактировать отдельную карточку клиента и его контактные данные.
В сервисе используется несколько слов для обозначения похожих сущностей. В интерфейсе Еадеска раздел называется «Клиенты», который состоит из контактов. В свою очередь, контакт включает в себя контактные данные, например, номер телефона. Схема такая:
Раздел «Клиенты»
  • Вася Пупкин
    • Телефон: +79876543210
  • Алиса
  • Дарт Вейдер
Подробнее о схеме данных ниже.

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

Объект «контакт» состоит из набора полей:
_id — уникальный идентификатор контакта
name — имя контакта
description — произвольное описание контакта
segments — массив уникальных идентификаторов сегментов. Пример:
"segments": [ "638b6be911dc02025204f1c5" ],
contacts — массив контактных данных, каждый элемент которых содержит:
  • id — уникальный идентификатор элемента контактных данных.
  • value — например, "[email protected]".
  • type — например "mail", необходимый для интерпретации value.
  • service — например "mail", сервис для которого используется данное value.
  • origin — например "chatra", сервис, который создал данный элемент контактных данных.
Пример контакта:
"_id" : ObjectId("5b58ca64581c0dbc35d49598"), // Уникальный ID Контакта
"name" : "Артем"
"description" : "Моя тестовая учетка",
"segments": [ "638b6be911dc02025204f1c5" ],
"accountId" : "5bed5057642820001e093322",
"updatedAt" : 1548926978590,
// Массив Контактных данных
"contacts" : [
{
"id" : "5bed5057642820001e090512",
"value" : "[email protected]",
"type" : "mail",
"service" : "mail"
"origin" : "mail",
},
{
"id" : "5c52bd0a3e308a00367a7fac",
"value" : "[email protected]",
"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 (строка)
  • 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'}
Last modified 5mo ago