# Custom Fields API - Настройка пользовательских полей

## Введение

В данной статье будет рассказано, как можно создавать и настраивать пользовательские поля через DealApp API. Все методы, описанные ниже требуют авторизацию через пользователя с настроенными правами по обновлению пользователей. О том, как производить авторизацию, можно прочитать в статье

[Добавление и настройка пользователей через API](https://www.notion.so/API-0f64f7e87faa45b5a82e8042f987f454?pvs=21)

**Пользовательские поля (Custom Fields)** это дополнительные поля, которые добавляются к звонкам и другим объектам коммуникаций с клиентами (Client Interactions), таким как чаты и тикеты. Эти поля расширяют основную схему таких объектов для реализации дополнительной бизнес логики. По этим полям можно фильтровать список на странице Таблицы Коммуникаций и эти данные можно так же увидеть на странице оценки.

Примеры возможных значений в таких полях:

1. Проект или контракт по которому совершался звонок
2. Город из которого пришел звонок
3. Время последнего закрытия тикета
4. Кол-во закрытий тикета или дата последнего закрытия
5. Массив NPS с опросом клиента о качестве. Сценарий такой: диалог в тикете может открываться или закрываться несколько раз, каждое значение оценки записывается и может передаваться нам в виде массива.
6. Список тематик. При чем тематики могут иметь под-тематики, список которых будет зависеть от тематики

Значения пользовательских полей хранятся в объекте ClientInteraction в виде json поля custom\_fields. Данные хранятся как пары ключ-значения, где ключ используется для того, чтобы сопоставить значение с ресурсом Custom Field. Пример получения данных о Custom Field:

```
{
  "data": {
    "id": "16915806-8327-4899-9e1c-6a59474c877b",
    "type": "phone-calls",
    "attributes": {
      ...
      "custom-fields": {
        "opened_at": "2020-06-21T09:51:13.588Z",
        "reopen_count": 5,
        "sale_stage": "negotiations"
      }
    },
    "relationships": {
      "operator": {...}
    }
  }
}
```

## Методы API

### Пользовательские поля (custom\_fields)

#### GET /api/v1/custom\_fields

Возвращает список объектов пользовательских полей ([custom-fields](https://www.notion.so/custom-fields-5cd66a16b30e40a3875d7eaa86c1b054?pvs=21)) для вашей организации

Пример запроса:\
`curl -X GET -H @headers.txt https://api.dev.dealapp.io/api/v1/custom_fields`

```
{
  "data": [
    {
      "id": "0dce0ebb-8b2f-4c1d-a1d0-470658aab301",
      "type": "custom-fields",
      "attributes": {
        "name": "Closed",
        "field-type": "boolean",
        "key": "closed",
        "description": null,
        "options": [],
        "settings": {},
        "used-for-reviews": true,
        "used-for-filters": true
      },
      "relationships": {
        "depends-on": {
          "data": null
        }
      }
    },
    {
      "id": "12f19196-7ca6-4f85-b935-bb22c12a706c",
      "type": "custom-fields",
      "attributes": {
        "name": "Список тегов",
        "field-type": "string_array",
        "key": "tags_array",
        "description": null,
        "options": [],
        "settings": {},
        "used-for-reviews": true,
        "used-for-filters": true
      },
      "relationships": {
        "depends-on": {
          "data": null
        }
      }
    },
    {
      "id": "19026429-c69f-4c02-992b-703d6b0847a1",
      "type": "custom-fields",
      "attributes": {
        "name": "Список NPS",
        "field-type": "number_array",
        "key": "nps_array",
        "description": null,
        "options": [],
        "settings": {},
        "used-for-reviews": true,
        "used-for-filters": true
      },
      "relationships": {
        "depends-on": {
          "data": null
        }
      }
    },
    {
      "id": "4f290222-a594-4d29-a3ee-6707c0f1c919",
      "type": "custom-fields",
      "attributes": {
        "name": "Кол-во перезвонов",
        "field-type": "number",
        "key": "reopen_count",
        "description": null,
        "options": [],
        "settings": {},
        "used-for-reviews": true,
        "used-for-filters": true
      },
      "relationships": {
        "depends-on": {
          "data": null
        }
      }
    },
    {
      "id": "7118af32-4e6f-49ff-905e-f4fb1929c7b7",
      "type": "custom-fields",
      "attributes": {
        "name": "Рандомная дата",
        "field-type": "datetime",
        "key": "opened_at",
        "description": null,
        "options": [],
        "settings": {},
        "used-for-reviews": true,
        "used-for-filters": true
      },
      "relationships": {
        "depends-on": {
          "data": null
        }
      }
    },
    {
      "id": "9c831219-d8bf-406f-9b65-f46225d8e3f4",
      "type": "custom-fields",
      "attributes": {
        "name": "Подтема",
        "field-type": "string",
        "key": "subtopic",
        "description": null,
        "options": [],
        "settings": {},
        "used-for-reviews": true,
        "used-for-filters": true
      },
      "relationships": {
        "depends-on": {
          "data": null
        }
      }
    },
    {
      "id": "a9305929-ada0-4c5f-b824-7628a7aa4e6b",
      "type": "custom-fields",
      "attributes": {
        "name": "Тема",
        "field-type": "string",
        "key": "topic",
        "description": null,
        "options": [],
        "settings": {},
        "used-for-reviews": true,
        "used-for-filters": true
      },
      "relationships": {
        "depends-on": {
          "data": null
        }
      }
    },
    {
      "id": "660464e7-9e2b-4047-83a5-b3ef0bcf1444",
      "type": "custom-fields",
      "attributes": {
        "name": "Voronka",
        "field-type": "enum",
        "key": "sales_funnel",
        "description": "Voronka prodazh",
        "options": [
          "first contact",
          "negotiations",
          "done",
          "failed"
        ],
        "settings": {},
        "used-for-reviews": true,
        "used-for-filters": true
      },
      "relationships": {
        "depends-on": {
          "data": null
        }
      }
    }
  ],
  "links": {
    "self": "https://api.dev.dealapp.io/api/v1/custom_fields?page%5Bnumber%5D=1&page%5Bsize%5D=25",
    "first": "https://api.dev.dealapp.io/api/v1/custom_fields?page%5Bnumber%5D=1&page%5Bsize%5D=25",
    "prev": null,
    "next": null,
    "last": "https://api.dev.dealapp.io/api/v1/custom_fields?page%5Bnumber%5D=1&page%5Bsize%5D=25"
  },
  "meta": {
    "page": 1,
    "total-pages": 1,
    "total-count": 8
  }
}
```

#### POST /api/v1/custom\_fields

Создание пользовательского поля

Пример запроса:

```
curl -X POST \
     -H @headers.txt \
     --data '{
        "key": "city",
        "name": "Название",
        "field_type": "enum",
        "options": ["Москва", "Санкт-Петербург"]
      }' \
     -H "Content-Type: application/json" \
     https://api.dev.dealapp.io/api/v1/custom_fields
```

[Пример ответа:  ](#user-content-fn-1)[^1]

#### PUT /api/v1/custom\_fields

Обновление пользовательского поля, при обновлении реализовано частичное обновление полей объектов (можно указывать только те, которые обновляются). Однако `options` и select поля нужно определять полностью.

Пример запроса:

```
curl -X PUT \
     -H @headers.txt \
     --data '{
        "name": "Название Города",
        "options": ["Москва", "Санкт-Петербург", "Воронеж"]
      }' \
     -H "Content-Type: application/json" \
     https://api.dev.dealapp.io/api/v1/custom_fields
```

Пример ответа:

```
{
  "data": {
    "id": "f3c1c90c-f184-4c1c-8cca-be55d2d9d0e9",
    "type": "custom-fields",
    "attributes": {
      "name": "Название",
      "field-type": "enum",
      "key": "city",
      "description": null,
      "options": [
        "Москва",
        "Санкт-Петербург"
      ],
      "settings": {},
      "used-for-reviews": true,
      "used-for-filters": true
    },
    "relationships": {
      "depends-on": {
        "data": null
      }
    }
  }
}
```

Пример ответа:

```
{
  "data": {
    "id": "f3c1c90c-f184-4c1c-8cca-be55d2d9d0e9",
    "type": "custom-fields",
    "attributes": {
      "name": "Название",
      "field-type": "enum",
      "key": "city",
      "description": null,
      "options": [
        "Москва",
        "Санкт-Петербург"
      ],
      "settings": {},
      "used-for-reviews": true,
      "used-for-filters": true
    },
    "relationships": {
      "depends-on": {
        "data": null
      }
    }
  }
}
```

## Работа с зависимыми полями (select)

Custom Field со значением `field_type` `select` позволяют создавать поля с возможностью выбора вариантов, которые зависят от значения других полей с таким же типом. Так же значения поля `settings` в таких `select`Custom Field будут хранить объекты с полями `key`, `text` и `parent-key`. Поле key в этом объекте будет использоваться как id этого варианта ответа, `text` - для отображения варианта на UI, а `parent-key` будет задавать значение `key` в другом select поле, от которого зависит данное поле, при котором этот вариант должен отображаться в данном селекте на UI.

Пример такого объекта:

```
{
  "data": [
    {
      "id": "8cf921ee-9085-4959-acd0-c64dd4c3cb63",
      "type": "custom-fields",
      "attributes": {
        "name": "Child",
        "field-type": "select",
        "key": "children",
        "description": null,
        "options": [],
        "settings": [
          {
            "key": "child-1-1",
            "text": "Child 1.1",
            "parent-key": "parent-1"
          },
          {
            "key": "child-1-2",
            "text": "Child 1.2",
            "parent-key": "parent-1"
          },
          {
            "key": "child-2-1",
            "text": "Child 2.1",
            "parent-key": "parent-2"
          },
          {
            "key": "child-2-2",
            "text": "Child 2.2",
            "parent-key": "parent-2"
          }
        ],
        "used-for-reviews": true,
        "used-for-filters": true
      },
      "relationships": {
        "depends-on": {
          "data": {
            "id": "ac0f998e-d14f-479d-8498-d1c6f71e8282",
            "type": "custom-fields"
          }
        }
      }
    },
    {
      "id": "ac0f998e-d14f-479d-8498-d1c6f71e8282",
      "type": "custom-fields",
      "attributes": {
        "name": "Parent",
        "field-type": "select",
        "key": "parent",
        "description": null,
        "options": [],
        "settings": [
          {
            "key": "parent-1",
            "text": "Parent 1"
          },
          {
            "key": "parent-2",
            "text": "Parent 2"
          }
        ],
        "used-for-reviews": true,
        "used-for-filters": true
      },
      "relationships": {
        "depends-on": {
          "data": null
        }
      }
    }
  ]
}
```

Такая конфигурация задает 2 зависимых поля: Parent и Child. При выборе значения Parent 1 в поле Child будет возможность выбрать только Child 1.1 и Child 1.1. В целом зависимость значений будет выглядеть следующим образом.

```
├── Parent 1
|       ├── Child 1.1
|       └── Child 1.2
└── Parent 2
        ├── Child 2.1
        └── Child 2.2
```

select Custom Field работают точно так же как и остальные со следующими изменениями:

* добавлено поле depends\_on, которое обозначает поле от которого зависит это поле
* добавлено поле settings, в котором храниться массив с настройками возможных значения поля select

В settings хранится массив объектов, в каждом объекте есть следующие поля:

* key - ключ по которому будет проходить поиск
* text - текст, который соответствует значение key
* parent\_key - значение ключа key в select поле c depends\_on, по которому должно отображаться это поле
* **Пример скрипта, который создает зависимые поля через bash с помощью curl**

[^1]: Нет ответа


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wiki.qolio.ru/qolio-or-baza-znanii/integracii/podklyuchenie-po-api/custom-fields-api-nastroika-polzovatelskikh-polei.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.