Неразобранное

Неразобранное – это системный статус воронки сделок.

Основная задача статуса – накапливать лиды из разных источников для их разбора менеджерами. Как можно видеть в интерфейсе в статусе неразобранное присутствует дополнительная фильтрация по источнику:

  • – Чаты (неразобранное данного типа нельзя создать через API, для этого нужно интегрировать источник чатов через отдельное комплексное API)
  • – Формы
  • – Звонки
  • – Почта (неразобранное данного типа нельзя создать через API, для интеграции такого рода рекомендуем использовать встроенные инструменты для работы с почтой amoCRM: парсинг, ящики для создания сущностей)

Для сделки, мы предусмотрели два типовых быстрых действия: «Принять», которое приводит к автоматическому переводу сделки в след. этап и «Отклонить», чтобы быстро удалить сделку из воронки.

Следующая особенность неразобранного заключается в том, что вместе с данными сделки могут быть переданы данные связанных контакта и компании и некоторых событий. При этом их не будет видно нигде, кроме как в самой карточке (к примеру, подобные контакты нельзя будет найти в списках контактов) пока сделка находится в статусе неразобранное. Но как только сделка будет Принята, то сущности автоматически будут созданы. Также можете связать сделку через API с уникальным идентификатором посетителя, о том как это работает вы можете прочитать тут.

Добавление в неразобранное

Метод позволяет добавлять неразобранное по одному или пакетно.

Общие параметры

Параметр Тип Описание
source_name string Название источника заявки
source_uid string Уникальный идентификатор заявки
pipeline_id int ID воронки, если параметр не передан, то заявка будет добавлена в неразобранное основной воронки
metadata array Массив, содержащий информацию о поступившей заявке. Его структура отличается для неразобранного типа Звонок и типа Форма
_embedded array Массив, содержащий информацию о создаваемых элементах сущностей.
_embedded[leads] array Массив, содержащий информацию для создания новой сделки. Может содержать все параметры и дополнительные поля, доступные для сделок для текущего аккаунта.
_embedded[contacts] array Массив, содержащий информацию для создания нового контакта. Может содержать все параметры и дополнительные поля, доступные для контактов для текущего аккаунта.
_embedded[companies] array Массив, содержащий информацию для создания новой компании. Может содержать все параметры и дополнительные поля доступные для компаний для текущего аккаунта.

Добавление неразобранного с типом входящий звонок (sip):

URL метода

POST /api/v4/leads/unsorted/sip

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

При добавлении заявки из входящего звонка минимальное количество полей 9:

  • – source_name
  • – source_uid
  • – metadata[uniq]
  • – metadata[duration]
  • – metadata[service_code]
  • – metadata[link]
  • – metadata[phone]
  • – metadata[called_at]
  • – metadata[from]

Рассмотрим параметры для sip

Параметр Тип Описание
metadata[uniq]
require
string Уникальный идентификатор звонка
metadata[from]
require
string Источник звонка
metadata[phone]
require
int Внешний номер телефона, с которого поступил звонок
metadata[called_at]
require
timestamp Дата и время звонка
metadata[duration]
require
int Продолжительность звонка
metadata[link]
require
string Ссылка на запись звонка
metadata[service_code]
require
string Код виджета или сервиса, через который был совершён звонок. Эта строка строго не регламентирована, но просим заполнять ее читаемым кодом, чтобы было ясно от какого поставщика пришла данная заявка. К примеру, можно использовать код виджета, «yandex», «twilio» и т.д..
metadata[is_call_event_needed] bool Флаг, если передан этот параметр, то после принятия неразобранного к сделке будет добавлено событие о совершённом звонке.

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


POST https://example.amocrm.ru/api/v4/leads/unsorted/sip
Content-Type: application/json

[
    {
        "request_id": 1,
        "source_name": "ОАО Коспромсервис",
        "source_uid": "a1fee7c0fc436088e64ba2e8822ba2b3",
        "pipeline_id": 2194576,
        "created_at": 1510261200,
        "_embedded": {
            "leads": [
                {
                    "name": "Тех обслуживание",
                    "visitor_uid": "5692210d-58d0-468c-acb2-dce7f93eef87",
                    "price": 5000,
                    "custom_fields_values": [
                        {
                            "field_id": 284785,
                            "values": [
                                {
                                    "value": "Кастомное поле"
                                }
                            ]
                        }
                    ],
                    "_embedded": {
                        "tags": [
                            {
                                "id": 263809
                            }
                        ]
                    }
                }
            ],
            "contacts": [
                {
                    "name": "Контакт для примера"
                }
            ],
            "companies": [
                {
                    "name": "ОАО Коспромсервис"
                }
            ]
        },
        "metadata": {
            "is_call_event_needed": true,
            "uniq": "a1fe231cc88e64ba2e8822ba2b3ewrw",
            "duration": 54,
            "service_code": "CkAvbEwPam6sad",
            "link": "https://example.com",
            "phone": 79998888888,
            "called_at": 1510261200,
            "from": "onlinePBX"
        }
    }
]

Добавление заявки из веб-формы (forms):

В предпросмотре карточки заявки (полученной через веб-форму) в неразобранном отображается информация, полученная из массивов сущностей _embedded. При этом стоит учитывать существующий приоритет получения информации из этих массивов по типу сущности.

Приоритет типов сущностей для отображения информации в карточке заявки:

  1. Контакт
  2. Сделка
  3. Покупатель

Для отображения в карточке заявки берётся следующая информация.

  • – Название элемента сущности
  • – Теги
  • – Дополнительные поля и их значения

URL метода

POST api/v4/leads/unsorted/forms

При добавлении из веб-формы минимальное количество полей 7:

  • – source_name
  • – source_uid
  • – metadata[ip]
  • – metadata[form_id]
  • – metadata[form_name]
  • – metadata[form_page]
  • – metadata[form_sent_at]

Параметры для веб-формы:

Параметр Тип Описание
metadata[ip]
require
string IP адрес, с которого поступила заявка
metadata[form_id]
require
string Идентификатор формы. Эта строка строго не регламентирована, для вашего удобства можете передать ваш внутренний id.
metadata[form_name]
require
string Название формы
metadata[form_page]
require
string Адрес страницы, на котором расположена форма
metadata[form_send_at]
require
timestamp Дата и время отправки данных через форму
metadata[service_code] string Код виджета или сервиса. Эта строка строго не регламентирована, но просим заполнять ее читаемым кодом, чтобы было ясно от какого поставщика пришла данная заявка. К примеру, можно использовать код виджета, «formstack», «googleforms» и т.д..
metadata[referer] string Параметр содержит информацию, откуда был переход на страницу, где расположена форма.

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


POST https://example.amocrm.ru/api/v4/leads/unsorted/forms
Content-Type: application/json

[
    {
        "request_id": 123,
        "source_name": "ОАО Коспромсервис",
        "source_uid": "a1fee7c0fc436088e64ba2e8822ba2b3",
        "pipeline_id": 2194576,
        "created_at": 1510261200,
        "_embedded": {
            "leads": [
                {
                    "name": "Тех обслуживание",
                    "visitor_uid": "5692210d-58d0-468c-acb2-dce7f93eef87",
                    "price": 5000,
                    "custom_fields_values": [
                        {
                            "field_id": 284785,
                            "values": [
                                {
                                    "value": "Дополнительное поле"
                                }
                            ]
                        }
                    ],
                    "tags": [
                        {
                            "name": "Тег для примера"
                        }
                    ]
                }
            ],
            "contacts": [
                {
                    "name": 234,
                    "first_name": "123213",
                    "last_name": 234,
                    "custom_fields_values": [
                        {
                            "field_code": "PHONE",
                            "values": [
                                {
                                    "value": "+7912321323"
                                }
                            ]
                        }
                    ]
                }
            ],
            "companies": [
                {
                    "name": "ОАО Коспромсервис"
                }
            ]
        },
        "metadata": {
            "ip": "192.168.0.1",
            "form_id": "a1fee7c0fc436088e64ba2e8822ba2b3ewrw",
            "form_sent_at": 1510261200,
            "form_name": "CkKwPasdasdam6",
            "form_page": "https://example.com",
            "referer": "41561315"
        }
    }
]

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


{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads/unsorted?page=1"
        },
        "next": {
            "href": "https://example.amocrm.ru/api/v4/leads/unsorted?page=2"
        }
    },
    "_embedded": {
        "unsorted": [
            {
                "uid": "sdfsdgd1321rgf1czf1241az4a4ee6fb9c87a9773aa3e9db6c998a37f637",
                "account_id": 123312,
                "request_id": 123,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/unsorted/sdfsdgd1321rgf1czf1241az4a4ee6fb9c87a9773aa3e9db6c998a37f637"
                    }
                },
                "_embedded": {
                    "contacts": [
                        {
                            "id": 16548963,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.ru/api/v4/contacts/16548963"
                                }
                            }
                        }
                    ],
                    "leads": [
                        {
                            "id": 9971439,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.ru/api/v4/leads/9971439"
                                }
                            }
                        }
                    ],
                    "companies": [
                        {
                            "id": 16548961,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.ru/api/v4/companies/16548961"
                                }
                            }
                        }
                    ]
                }
            }
        ]
    }
}

URL метода

POST /api/v4/leads/sip

Параметры

Параметр Описание
metadata[from] Источник звонка
metadata[phone] Внешний номер телефона, с которого поступил звонок
metadata[called_at] Дата и время звонка
metadata[duration] Продолжительность звонка
metadata[service_code] Код виджета или сервиса, через который был совершён звонок. Эта строка строго не регламентирована, но просим заполнять ее читаемым кодом, чтобы было ясно от какого поставщика пришла данная заявка. К примеру, можно использовать код виджета, «yandex», «twilio» и т.д..
URL метода

POST /api/v4/leads/forms

Параметры

Параметр Описание
metadata[form_id] Идентификатор формы. Эта строка строго не регламентирована, для вашего удобства можете передать ваш внутренний id.
metadata[form_page] Адрес страницы, на котором расположена форма

Определение неразобранного как Дубль

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

Принятие неразобранных заявок

Метод для принятия неразобранных заявок.

URL метода

POST /api/v4/leads/unsorted/{uid}/accept

GET Параметры

Параметр Тип Описание
uid string uid неразобранной заявки

Параметры

Параметр Тип Описание
user_id int id пользователя аккаунта, от имени которого будут созданы сделки/контакты/компании
status_id int Статус сделок, которые будут созданы в результате принятия неразобранного

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


POST https://example.amocrm.ru/api/v4/leads/unsorted/3cvd1de2ebfsd152fd6a465cd3e586cbdba6827/accept
Content-Type: application/json

{
   user_id: 123123,
   status_id: 30846280
}

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


Content-Type:application/hal+json

{
    "uid": "3cvd1de2ebfsd152fd6a465cd3e586cbdba6827",
    "pipeline_id": 31634,
    "category": "mail",
    "created_at": 1589165593,
    "_embedded": {
        "leads": [
            {
                "id": 9944789,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/9944789"
                    }
                }
            }
        ],
        "contacts": [
            {
                "id": 16522451,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/contacts/16522451"
                    }
                }
            }
        ],
        "companies": []
    }
}

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

Параметр Тип Описание
uid string Уникальный идентификатор заявки
pipeline_id int ID воронки
category string Категория заявки – sip, mail, forms, chats
created_at timestamp Дата создания
_embedded[companies] array Массив, содержащий id созданной компании
_embedded[leads] array Массив, содержащий id созданных сделок
_embedded[contacts] array Массив, содержащий id созданных контактов

Отклонение неразобранных заявок

Метод для отклонения неразобранных заявок.

URL метода

DELETE /api/v4/leads/unsorted/{uid}/decline

GET Параметры

Параметр Тип Описание
uid string uid неразобранной заявки

JSON Параметры

Параметр Тип Описание
user_id int id пользователя, от имени которого будет отклонена заявка

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


DELETE https://example.amocrm.ru/api/v4/leads/unsorted/98bc1d1de2f960a2ad0e34b52823/decline
Content-Type: application/json

{
    "user_id": 123123
}

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


Content-Type:application/hal+json

{
    "uid": "98bc1d1de2f960a2ad0e34b52823",
    "pipeline_id": 1394576,
    "category": "mail",
    "created_at": 1589115506,
    "_embedded": {
        "leads": [
            {
                "id": 9937533,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/9937533"
                    }
                }
            }
        ],
        "contacts": [
            {
                "id": 163141,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/contacts/163141"
                    }
                }
            }
        ]
    }
}

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

Параметр Тип Описание
uid string Уникальный идентификатор заявки
pipeline_id int ID воронки
category string Категория заявки – sip, mail, forms, chats
created_at
require
timestamp Дата создания
_embedded[companies] array Массив, содержащий id созданной компании
_embedded[leads] array Массив, содержащий id созданных сделок
_embedded[contacts] array Массив, содержащий id созданных контактов

Связь неразобранного со сделкой

Метод позволяет привязать неразобранное категории chat к существующей сделке.

URL метода

POST /api/v4/leads/unsorted/{uid}/link

GET параметры

Параметр Тип Описание
uid string Уникальный идентификатор заявки

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

Параметр Тип Описание
link object Объект, содержащий id-сущности и тип сущности
link[entity_id] int Идентификатор сущности
link[entity_type] string Тип сущности: leads, contacts, companies

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


POST https://example.amocrm.ru/api/v4/leads/unsorted/d7faa21ce091fe0da05d8d4c2075090c1e9bfd4/link
Content-Type: application/json

{
    "link": {
        "entity_id": 93144801,
        "entity_type": "leads"
    }
}

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


{
    "uid": "d7faa21ce091fe0da05d8d4c2075090c1e9bfd4",
    "_embedded": {
        "leads": [
            {
                "id": 93144801,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/93144801"
                    }
                }
            }
        ]
    }
}

Список неразобранных заявок

Метод для получения списка неразобранных заявок с возможностью фильтрации и постраничной выборки. Ограничение по максимально возвращаемым на одной странице данным – 250 заявок.

URL метода

GET /api/v4/leads/unsorted

Query параметры запроса

Параметр Описание
page Страница выборки
limit Кол-во выбираемых строк (системное ограничение 250)
filter[uid] Массив, содержащий в себе uid неразобранных сделок
filter[category] Массив, содержащий в себе категории, по которым необходима выборка (sip, mail, forms, chats)
filter[pipeline_id] Идентификатор воронки, из которой необходимо сделать выборку

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


GET https://example.amocrm.ru/api/v4/leads/unsorted?filter[uid]=e02f8d49ce77014f92ce2a498fb033cefde74f5de1a5d3980a2a2d108037

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


Content-Type:application/hal+json

{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads/unsorted?filter[uid]=98fb033cefde74f5de1a5d3980a2a2d108037"
        }
    },
    "_embedded": {
        "unsorted": [
            {
                "uid": "98fb033cefde74f5de1a5d3980a2a2d108037",
                "source_uid": null,
                "source_name": "UIS",
                "category": "sip",
                "pipeline_id": 2194576,
                "created_at": 1583156937,
                "metadata": {
                    "from": "7999999999",
                    "phone": 7999999999,
                    "called_at": 1583156916,
                    "duration": "0",
                    "link": null,
                    "service_code": "uis_widget"
                },
                "account_id": 123312,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/unsorted/98fb033cefde74f5de1a5d3980a2a2d108037"
                    }
                },
                "_embedded": {
                    "contacts": [
                        {
                            "id": 13176707,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.ru/api/v4/contacts/13176707"
                                }
                            }
                        }
                    ],
                    "leads": [
                        {
                            "id": 7002787,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.ru/api/v4/leads/7002787"
                                }
                            }
                        }
                    ],
                    "companies": []
                }
            }
        ]
    }
}

Основные параметры ответа

Параметр Тип Описание
uid string Уникальный идентификатор заявки
pipeline_id int ID воронки
category string Категория заявки – sip, mail, forms, chats
created_at timestamp Дата создания
_embedded[unsorted] array Массив, содержащий список неразобранных. Каждое неразобранное содержит следующие базовые параметры

Поиск неразобранного по uid

Метод позволяет получить неразобранное по уникальному идентификатору

URL метода

GET /api/v4/leads/unsorted/{uid}

GET параметры

Параметр Описание
uid Уникальный идентификатор неразобранного

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


GET https://example.amocrm.ru/api/v4/leads/unsorted/c123e6864630b3a2aa9b76775fc010c97e5f627

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


Content-Type:application/hal+json

{
    "uid": "c123e6864630b3a2aa9b76775fc010c97e5f627",
    "source_uid": null,
    "source_name": "UIS",
    "category": "sip",
    "pipeline_id": 1394576,
    "created_at": 1583156937,
    "metadata": {
        "from": "79999999999",
        "phone": 313910,
        "called_at": 1583156916,
        "duration": "0",
        "link": null,
        "service_code": "uis_widget"
    },
    "account_id": 123321,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads/unsorted/c123e6864630b3a2aa9b76775fc010c97e5f627"
        }
    },
    "_embedded": {
        "contacts": [
            {
                "id": 1376707,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/contacts/1376707"
                    }
                }
            }
        ],
        "leads": [
            {
                "id": 3402787,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/3402787"
                    }
                }
            }
        ],
        "companies": []
    }
}

Каждое неразобранное содержит следующие базовые параметры

Сводная информация о неразобранных заявках

Метод для получения агрегированной информации о неразобранных заявках с возможностью фильтрации по дате.

URL метода

GET /api/v4/leads/unsorted/summary

Параметры запроса

Параметр Тип Описание
filter[pipeline_id] int|[]int ID воронки. Можно передать массив из идентификаторов
filter[created_at] []timestamp Дата создания неразобранного. Необходимо передать массив с датой “от” и “до”

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


GET https://example.amocrm.ru/api/v4/leads/unsorted/summary?filter[created_at][]=1589176500,1589176560&filter[pipeline_id]=2194576

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


Content-Type:application/hal+json

{
    "total": 168,
    "accepted": 6,
    "declined": 2,
    "average_sort_time": 34521,
    "categories": {
        "sip": {
            "total": 31
        },
        "mail": {
            "total": 41
        },
        "forms": {
            "total": 27
        },
        "chats": {
            "total": 69
        }
    }
}

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

Параметр Тип Описание
total int Общее количество неразобранных заявок
accepted int Общее количество принятых заявок
declined int Общее количество непринятых заявок
average_sort_time timestamp Среднее время разбора заявки в секундах
categories[sip] int Количество неразобранных заявок, полученных через входящие звонки
categories[mail] int Количество неразобранных заявок, полученных через почту
categories[forms] int Количество неразобранных заявок, полученных через веб-формы
categories[chat] int Количество неразобранных заявок, полученных через чаты

Смотрите также

КОДЫ ОШИБОК API