Клиенты (Client)

Клиент - контрагент в рамках сделки на оказание услуг либо продажи продуктов средствами crm.
На текущий момент классифицируются на два вида:

  • физ. лица
  • юр. лица

Оба вида характеризуется набором дополнительных атрибутов, доступных в рамках выбранной сущности.

Запросы осуществляются на URL:

http://<domain.ru>/rest/client[parameters]

Обязательные параметры:

  • auth_key - токен авторизации для stateless доступа к сервису

Получение списка

Запросы на получение списка адресуются на один URI вне зависимости от предполагаемого типа получаемого результата и могу ограничиваться только набором общих для обоих видов атрибутов.

Запрос списка в сокращенном виде:

GET https://<domain.ru>/rest/client

Эквивалент запросу:

GET https://<domain>.ru/rest/client?page=1&per_page=10&sort=created_at

Возвращает список клиентов с учетом постраничного вывода. Первые десять записей, отсортированные в порядке убывания даты создания.
Возможно применение дополнительных параметров ограничения либо настройки выборки.

Допустимые параметры:
Таблица 1

Имя параметра Тип данных Описание
user_id integer Не обязательное. Вводит ограничение ответственного за клиента пользователя системы с id равное user
name string Не обязательное. Фильтр
%LIKE%
по атрибуту name сущности client
type unsigned integer{1} Не обязательное. Ограничивает выборку списка конкретным типом клиентов. Допустимые типы см. таблица 2
email string Не обязательное. Фильтр по атрибуту email без учета типа клиента
page unsigned integer Не обязательное. Ограничивает результат списком клиентов для страницы page с учетом per_page
per_page unsigned integer Не обязательное. Ограничивает результат списком клиентов в количестве per_page
sort string Не обязательное. Указатель на необходимость сортировки по конкретному атрибуту сущности см. описание сущности client. Доступны только общие атрибуты.
fields string Не обязательное. Указатель на необходимость выборки конкретных атрибутов сущности. см Сущность "client". Доступны только общие атрибуты.
expand string Не обязательное. Список связных сущностей, которые нужно развернуть
search string Не обязательное. Составной фильтр поиска по значащим текстовым полям/ На текущий момент alias для name
count_deals integer(0\1) Не обязательное. Добавляет в результирующую выборку данные о количестве сделок для клиента
count_offers integer(0\1) Не обязательное. Добавляет в результирующую выборку данные о количестве коммерческих предложений для клиента
count_contracts integer(0\1) Не обязательное. Добавляет в результирующую выборку данные о количестве договоров для клиента
count_invoices integer(0\1) Не обязательное. Добавляет в результирующую выборку данные о количестве счетов для клиента

Таблица 2 - Допустимые типы клиентов

Константа Значение Описание
common\models\Client::CLIENT_COMPANY 0x01 Указывает на то, что клиент является юр. лицом и имеет дополнительные атрибуты: company_address, bank_details
common\models\Client::CLIENT_PERSON 0x02 Указывает на то, что клиент является физ. лицом и имеет дополнительные атрибуты: person_details
 

Форматы ответов

1. Один кортеж, режим по-умолчанию

GET https://<domain>.ru/rest/client
{
  "response": {
    "items": [
      {
        "id": 123,
        "user": 12,
        "name": "ClientCompany ltd",
        "type": 1,
        "email": "clientcomp@clientcomp.com",
        "phone": "8(890)56-67-67",
        "real_address": "Moscow, red square 1",
        "description": "Additional descr for cur. client",
        "created_at": "20014-04-14 12:23:06",
        "updated_at": "20014-04-14 12:23:06" 
      }
      ]
  }
}

2. Запрос списка с выборкой количества договоров, счетов и КП

GET https://<domain>.ru/rest/client?count_offers=1&count_invoices=1&count_contracts=1
{
  "response": {
    "items": [
      {
        "id": 123,
        "user": 12,
        "name": "ClientCompany ltd",
        "type": 1,
        "email": "clientcomp@clientcomp.com",
        "phone": "8(890)56-67-67",
        "real_address": "Moscow, red square 1",
        "description": "Additional descr for cur. client",
        "created_at": "20014-04-14 12:23:06",
        "updated_at": "20014-04-14 12:23:06",
        "count_deals": 321,
        "count_offers": 123,
        "count_invoices": 345,
        "count_contracts": 78
      }
      ]
  }
}

3. Запрос списка с развернутой сущностью user

GET https://<domain>.ru/rest/client?expand=user
{
  "response": {
    "items": [
      {
        "id": 123,
        "user_id": 12,
        "user": {
          "id": 12,
          "username": "Sidor",
          "fname": "S. S.",
          "lname": "Sidorov",
          "email": "sidor@owncomp.com",
        },
        "name": "ClientCompany ltd",
        "type": 1,
        "email": "clientcomp@clientcomp.com",
        "phone": "8(890)56-67-67",
        "real_address": "Moscow, red square 1",
        "description": "Additional descr for cur. client",
        "created_at": "20014-04-14 12:23:06",
        "updated_at": "20014-04-14 12:23:06" 
      }
      ]
  }
}

Постраничный

X_Pagination_Total_Count: общее количество ресурсов;
X_Pagination_Page_Count: количество страниц;
X_Pagination_Current_Page: текущая страница (начиная с 1);
X_Pagination_Per_Page: количество ресурсов на страницу;

<https://<domain.ru>/rest/client?access-token=<auth-key>&page=1[&param=value[...]]>; rel=self,
<https://<domain.ru>/rest/client?access-token=<auth-key>&page=1[&param=value[...]]>; rel=next, 
<https://<domain.ru>/rest/client?access-token=<auth-key>&page=1[&param=value[...]]>; rel=last

Получение по идентификатору

Возвращает в качестве результата данные о клиенте в формате описания отдельного кортежа списка (см. Получение списка)

GET https://<domain.ru>/rest/client/<client_id:\i>

Набор дополнительных атрибутов может разниться в зависимости от того, какого типа сущность будет возвращена по указанному идентификатору (см. таблицу 2 "Допустимые типы клиентов").

Допустимые параметры:
Таблица 3

Имя параметра Тип данных Описание
fields string Указатель на необходимость конкретных атрибутов сущности. см Сущность "Client"
expand string Содержит список сущностей, которые требуется развернуть
count_offers integer(0\1) Не обязательное. Добавляет в результирующую выборку данные о количестве коммерческих предложений для клиента
count_contracts integer(0\1) Не обязательное. Добавляет в результирующую выборку данные о количестве договоров для клиента
count_invoices integer(0\1) Не обязательное. Добавляет в результирующую выборку данные о количестве счетов для клиента 

 

Добавление

POST https://domain.ru/rest/client

Таблица 4 - Атрибуты, используемые при добавлении

Атрибут Тип данных Замечания
user integer Не обязательное. Указывает на пользователя системы, ответственного за данного клиента. В случае, если не указано - используется пользователь от имени которого ведется добавление. Возможно введение запрета на переопределение данного атрибута для конкретных ролей
name string Обязательное. Имя клиента
type unsigned integer{1} Обязательное. см. таблица 2 "Допустимые типы клиентов"
email string Не обязательное
phone string Не обязательное
real_address string Не обязательное
description string Не обязательное
company_address string Не обязательное. Применяется только к сущности с типом 0х01 (client_company)
bank_details string Не обязательное. Применяется только к сущности с типом 0х01 (client_company)
person_details string Не обязательное. Применяется только к сущности с типом 0х02 (client_natural_person)

Формат ответов

В случае успешного выполнения запроса:

  • Сервер возвращает код ответа 200
  • В теле ответа приходит вновь добавленная сущность в формате запроса по идентификатору (см. Получение-по-идентификатору )

В случае ошибки возвращается код ответа, отличный от 200

Изменение

PUT https://domain.ru/rest/client/<client_id:\i>
PATCH https://domain.ru/rest/client/<client_id:\i>

Тело запроса формируется идентичным запросу на добавление. Формат ответов идентичен.
Набор атрибутов идентичен за исключением атрибута type изменение которого будет игнорироваться!

Удаление

Возможны случаи, когда прямое удаление клиента не возможно! Это связано с ограничениями консистентности данных.

DELETE https://domain.ru/rest/client/<client_id:\i>

Тело запроса отсутствует

Формат ответов

Возвращает код ответа от сервера 200 в случае успешного выполнения запроса либо отличный от него в случае возникновения ошибки.

Документация

© «Копирайт», 2017

Web-canape - быстрое создание сайтов и продвижение