Источники

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

Через методы API источников интеграция может управлять только своими источниками.
Интеграция идентифицируется посредством проверки переданного Access Token.
Каждый источник обладает уникальным кодом (external_id) и двух источников с одинаковым кодом быть не может.

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

API источников позволяет интеграции сообщить amoCRM в какой воронке должно быть создано неразобранное.

На данный момент созданные интеграцией источники учитываются:

  • если переданы через API чатов, при создании неразобранного
  • при настройке действия "Написать сообщение" в боте в .com аккаунтах (Если источник не создан, то его не будет в настройках этого действия)
  • при работе функционала "Написать первым" (у пользователя будет возможность выбирать через какой именно источник написать первым клиенту в карточке сделки)
  • отображаются в сделке в разделе статистика
  • источник может быть указан при создании сделки через API в _embedded[source][external_id]

Также через API источников интеграция может добавить варианты выбора номеров WhatsApp,
которые используются при настройке кнопки на сайт – СRM Plugin

Источнику можно указать свойство waba если интеграция работает с белым WhatsApp и настроено временное окно. Параметр даёт возможность управления шаблонами WhatsApp и использовании их в новом шаге "Отправить сообщение" в salesbot. После указания данного параметра следует подписаться на события отправки шаблона на утверждение. Получив такое событие интеграция может передать шаблон на одобрение в WhatsApp и в зависимости от результата изменить статус шаблона WhatsApp через API

Оглавление

Требования к интеграции для работы с API источников

Источники, создаваемые интеграцией отображаются в разделе настроек Digital Pipeline.
Пользователь может взаимодействовать с источником и интеграцией через интерфейс,
поэтому интеграции для работы с источниками требуется загруженный архив.
Таким образом с API источников могут взаимодействовать все интеграции за исключением типа "Внешняя интеграция".

Перед началом работы с API источников нужно удостоверится что интеграция соответствует следующим критериям:

  1. Интеграция обладает загруженным архивом (виджетом) и в файле manifest.json виджета указана возможность
    отображения виджета в интерфейсе добавления нового источника "locations":["lead_sources"]
  2. Для интеграций, которые работают с чатами: в канале чата должен быть прописан код виджета и ID интеграции.
    Подробности по работе с каналами указаны в блоке регистрация канала раздела API чатов.

Также у интеграции появляется новое свойство – "Поддерживается ли работа с множественными источниками".
Данный флаг стоит включить, когда интеграция полностью управляет источниками через API со своего бэкенда и создание источника со стороны amoCRM больше не требуется.
Если флаг не стоит – при установке интеграции будет создан источник на стороне amoCRM.

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

Метод

GET /api/v4/sources

Описание

Метод позволяет получить список источников интеграции.

Ограничения

Метод доступен с правами администратора. Возвращает не более 50 источников

GET параметры

Параметр Тип данных Описание
filter object Доступные поля фильтра смотрите ниже
filter[external_id] string|array Фильтр по внешнему идентификатору источника

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Список источников интеграций
204 У интеграции нет подконтрольных источников или поиск по фильтру не дал результатов
403 Интеграция не авторизована

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

Метод возвращает коллекцию моделей источников

Параметр Тип данных Описание
id int ID источника
name string Название источника
pipeline_id int ID воронки, воронка может быть архивной
external_id string Внешний идентификатор источника на стороне интеграции
default bool Является ли данный источник источником по-умолчанию. Поле не является обязательным
origin_code string
null
Код основного канала источника. Данный канал чата будет использоваться при инициализации общения. Поле не является обязательным.
services array Массив сервисов которые связаны с источником. На данный момент поддерживается только whatsapp. Данные из этого массива используются для отображения в CRM Plugin (кнопки на сайт). Поле не является обязательным.
services[0][type] string тип сервиса, на данный момент поддерживается только один тип: "whatsapp"
services[0][params] object Объект с настройками источника. Поле не является обязательным.
services[0][params][waba] bool Является ли источник белым whatsapp. Следует добавить для возможности работы с одобренными шаблонами whatsapp в salesbot в новом шаге отправки сообщения. Поле не является обязательным.
services[0][pages] string Для whatsapp сервиса содержит список элементов, которые можно выбрать при настройке CRM Plugin (кнопки на сайт)
services[0][pages][0][name] string Отображаемое пользователю название пункта в выпадающем списке при настройке кнопки на сайте
services[0][pages][0][id] string Идентификатор пункта в выпадающем списке (не отображается клиенту и пользователю)
services[0][pages][0][link] string Номер телефона, который будет указан в кнопке whatsapp и которому будет писать клиент на странице сайта. В CRM Plugin ссылка будет сформирована следующим образов: https://wa.me/{Указанный номер телефона}

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

{
    "_total_items": 2,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/sources"
        }
    },
    "_embedded": {
        "sources": [
            {
                "id": 9619,
                "name": "Номер отдела продаж",
                "pipeline_id": 1300,
                "external_id": "+17 912 100 00 00",
                "default": true,
                "origin_code": null,
                "services": [],
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/sources/9619"
                    }
                }
            },
            {
                "id": 4460,
                "name": "Лендинг",
                "pipeline_id": 1301,
                "external_id": "65bd500b-fd52-4599-ab58-943ce3dd058c",
                "default": false,
                "origin_code": "amo.ext.30490163_v2",
                "services": [],
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/sources/4460"
                    }
                }
            }
        ]
    }
}

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

Метод

GET /api/v4/sources/{id}

Описание

Метод позволяет получить список источников интеграции.

Ограничения

Метод доступен с правами администратора.

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Источник найден
204 У интеграции нет подконтрольных источников или источник удален
403 Интеграция не авторизована

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

Метод возвращает коллекцию моделей источников

Параметр Тип данных Описание
id int ID источника
name string Название источника
pipeline_id int ID воронки, воронка может быть архивной
external_id string Внешний идентификатор источника на стороне интеграции
default bool Является ли данный источник источником по-умолчанию. Поле не является обязательным
origin_code string
null
Код основного канала источника. Данный канал чата будет использоваться при инициализации общения. Поле не является обязательным.
services array Массив сервисов которые связаны с источником. На данный момент поддерживается только whatsapp. Данные из этого массива используются для отображения в CRM Plugin (кнопки на сайт). Поле не является обязательным.
services[0][type] string тип сервиса, на данный момент поддерживается только один тип: "whatsapp"
services[0][params] object Объект с настройками источника. Поле не является обязательным.
services[0][params][waba] bool Является ли источник белым whatsapp. Следует добавить для возможности работы с одобренными шаблонами whatsapp в salesbot в новом шаге отправки сообщения. Поле не является обязательным.
services[0][pages] string Для whatsapp сервиса содержит список элементов, которые можно выбрать при настройке CRM Plugin (кнопки на сайт)
services[0][pages][0][name] string Отображаемое пользователю название пункта в выпадающем списке при настройке кнопки на сайте
services[0][pages][0][id] string Идентификатор пункта в выпадающем списке (не отображается клиенту и пользователю)
services[0][pages][0][link] string Номер телефона, который будет указан в кнопке whatsapp и которому будет писать клиент на странице сайта. В CRM Plugin ссылка будет сформирована следующим образов: https://wa.me/{Указанный номер телефона}

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

{
    "id": 9619,
    "name": "Номер отдела продаж",
    "pipeline_id": 1300,
    "external_id": "+17 912 100 00 00",
    "default": true,
    "origin_code": null,
    "services": [],
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/sources/9619"
        }
    }
}

Добавление источников

Метод

POST /api/v4/sources

Описание

Метод позволяет добавлять источники пакетно.

Ограничения

Метод доступен с правами администратора. Добавить одновременно можно не более 50 источников.

Заголовок запроса

Content-Type: application/json

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

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

Параметр Тип данных Описание
name string Название источника. Поле является обязательным
external_id string Внешний идентификатор источника, не может быть изменен после создания. Длина поля 36 символов, можно использовать любые печатные ascii символы и пробел
pipeline_id int ID воронки, к которой относится источник. Поле не является обязательным
default bool Является ли данный источник источником по-умолчанию. Поле не является обязательным
origin_code string Код основного канала источника. Данный канал чата будет использоваться при инициализации общения. Поле не является обязательным.
services array Массив сервисов которые связаны с источником. На данный момент поддерживается только whatsapp. Данные из этого массива используются для отображения в CRM Plugin (кнопки на сайт). Поле не является обязательным.
services[0][type] string тип сервиса, на данный момент поддерживается только один тип: "whatsapp"
services[0][params] object Объект с настройками источника. Поле не является обязательным.
services[0][params][waba] bool Является ли источник белым whatsapp. Следует добавить для возможности работы с одобренными шаблонами whatsapp в salesbot в новом шаге отправки сообщения. Поле не является обязательным.
services[0][pages] string Для whatsapp сервиса содержит список элементов, которые можно выбрать при настройке CRM Plugin (кнопки на сайт)
services[0][pages][0][name] string Отображаемое пользователю название пункта в выпадающем списке при настройке кнопки на сайте
services[0][pages][0][id] string Идентификатор пункта в выпадающем списке (не отображается клиенту и пользователю)
services[0][pages][0][link] string Номер телефона, который будет указан в кнопке whatsapp и которому будет писать клиент на странице сайта. В CRM Plugin ссылка будет сформирована следующим образов: https://wa.me/{Указанный номер телефона}

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

[
    {
        "name": "Номер отдела продаж",
        "pipeline_id": 1300,
        "external_id": "+17 912 100 00 00",
        "default": true,
        "services": [
            {
                "type": "whatsapp",
                "params": {
                    "waba": true
                },
                "pages": [
                    {
                        "id": "9121234565",
                        "name": "WhatsApp +9121234567",
                        "link": "+9121234567"
                    }
                ]
            }
        ]
    },
    {
        "name": "Лендинг",
        "external_id": "65bd500b-fd52-4599-ab58-943ce3dd058c",
        "origin_code": "amo.ext.30490163_v2"
    }
]

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Источники были успешно созданы
401 Интеграция не авторизована
400 Переданы некорректные данные. Подробности доступны в теле ответа

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

Метод возвращает коллекцию источников, которые были добавлены.

Параметр Тип данных Описание
id int ID источника
name string Название источника
pipeline_id int ID воронки, воронка может быть архивной
external_id string Внешний идентификатор источника на стороне интеграции
default bool Является ли данный источник источником по-умолчанию. Поле не является обязательным
origin_code string Код основного канала источника. Данный канал чата будет использоваться при инициализации общения. Поле не является обязательным.
services array Массив сервисов которые связаны с источником. На данный момент поддерживается только whatsapp. Данные из этого массива используются для отображения в CRM Plugin (кнопки на сайт). Поле не является обязательным.
services[0][type] string тип сервиса, на данный момент поддерживается только один тип: "whatsapp"
services[0][params] object Объект с настройками источника. Поле не является обязательным.
services[0][params][waba] bool Является ли источник белым whatsapp. Следует добавить для возможности работы с одобренными шаблонами whatsapp в salesbot в новом шаге отправки сообщения. Поле не является обязательным.
services[0][pages] string Для whatsapp сервиса содержит список элементов, которые можно выбрать при настройке CRM Plugin (кнопки на сайт)
services[0][pages][0][name] string Отображаемое пользователю название пункта в выпадающем списке при настройке кнопки на сайте
services[0][pages][0][id] string Идентификатор пункта в выпадающем списке (не отображается клиенту и пользователю)
services[0][pages][0][link] string Номер телефона, который будет указан в кнопке whatsapp и которому будет писать клиент на странице сайта. В CRM Plugin ссылка будет сформирована следующим образов: https://wa.me/{Указанный номер телефона}
request_id string Строка переданная при запросе или порядковый указатель, если параметр не передан

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

{
    "_total_items": 2,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/sources"
        }
    },
    "_embedded": {
        "sources": [
            {
                "id": 9619,
                "name": "Номер отдела продаж",
                "pipeline_id": 1300,
                "external_id": "+17 912 100 00 00",
                "default": true,
                "origin_code": null,
                "services": [
                    {
                        "type": "whatsapp",
                        "params": {
                            "waba": true
                        },
                        "pages": [
                            {
                                "id": "9121234565",
                                "name": "WhatsApp +9121234567",
                                "link": "+9121234567"
                            }
                        ]
                    }
                ],
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/sources/9619"
                    }
                }
            },
            {
                "id": 4460,
                "name": "Лендинг",
                "pipeline_id": 1307,
                "external_id": "65bd500b-fd52-4599-ab58-943ce3dd058c",
                "default": false,
                "origin_code": "amo.ext.30490163_v2",
                "services": [],
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/sources/4460"
                    }
                }
            }
        ]
    }
}

Редактирование источников

Метод

PATCH /api/v4/sources

Описание

Метод позволяет редактировать источники пакетно.
Также вы можете добавить ID источника в метод для редактирования конкретного источника (/api/v4/sources/{id}).
При пакетном редактировании передается массив из объектов-источников, при редактировании одного источника, передается просто модель источника.

Ограничения

Метод доступен с правами администратора. Обновить одновременно можно не более 50 источников

Заголовок запроса

Content-Type: application/json

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

Внешний идентификатор источника (external_id) изменить нельзя, можно только создать новый источник с таким идентификатором

Параметр Тип данных Описание
id int ID источника, обязателен при пакетном обновлении
name string Название источника. Поле не является обязательным
pipeline_id int ID воронки, к которой относится источник. Поле не является обязательным
default bool Является ли данный источник источником по-умолчанию. Поле не является обязательным
origin_code string Код основного канала источника. Данный канал чата будет использоваться при инициализации общения. Поле не является обязательным.
services array Массив сервисов которые связаны с источником. На данный момент поддерживается только whatsapp. Данные из этого массива используются для отображения в CRM Plugin (кнопки на сайт). Поле не является обязательным.
services[0][type] string тип сервиса, на данный момент поддерживается только один тип: "whatsapp"
services[0][params] object Объект с настройками источника. Поле не является обязательным.
services[0][params][waba] bool Является ли источник белым whatsapp. Следует добавить для возможности работы с одобренными шаблонами whatsapp в salesbot в новом шаге отправки сообщения. Поле не является обязательным.
services[0][pages] string Для whatsapp сервиса содержит список элементов, которые можно выбрать при настройке CRM Plugin (кнопки на сайт)
services[0][pages][0][name] string Отображаемое пользователю название пункта в выпадающем списке при настройке кнопки на сайте
services[0][pages][0][id] string Идентификатор пункта в выпадающем списке (не отображается клиенту и пользователю)
services[0][pages][0][link] string Номер телефона, который будет указан в кнопке whatsapp и которому будет писать клиент на странице сайта. В CRM Plugin ссылка будет сформирована следующим образов: https://wa.me/{Указанный номер телефона}

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

В данном примере мы обновим 2 источника.
У одного изменим имя, у другого сменим воронку

[
    {
        "id": 9619,
        "name": "Номер отдела продаж"

    },
    {
        "id": 4460,
        "name": "Лендинг",
        "pipeline_id": 1307
    }
]

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Источники были успешно изменены
401 Интеграция не авторизована
400 Переданы некорректные данные. Подробности доступны в теле ответа

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

Метод возвращает коллекцию источников, которые были изменены.

Параметр Тип данных Описание
id int ID источника
name string Название источника
pipeline_id int ID воронки, воронка может быть архивной
external_id string Внешний идентификатор источника на стороне интеграции
default bool Является ли данный источник источником по-умолчанию. Поле не является обязательным
origin_code string Код основного канала источника. Данный канал чата будет использоваться при инициализации общения. Поле не является обязательным.
services array Массив сервисов которые связаны с источником. На данный момент поддерживается только whatsapp. Данные из этого массива используются для отображения в CRM Plugin (кнопки на сайт). Поле не является обязательным.
services[0][type] string тип сервиса, на данный момент поддерживается только один тип: "whatsapp"
services[0][params] object Объект с настройками источника. Поле не является обязательным.
services[0][params][waba] bool Является ли источник белым whatsapp. Следует добавить для возможности работы с одобренными шаблонами whatsapp в salesbot в новом шаге отправки сообщения. Поле не является обязательным.
services[0][pages] string Для whatsapp сервиса содержит список элементов, которые можно выбрать при настройке CRM Plugin (кнопки на сайт)
services[0][pages][0][name] string Отображаемое пользователю название пункта в выпадающем списке при настройке кнопки на сайте
services[0][pages][0][id] string Идентификатор пункта в выпадающем списке (не отображается клиенту и пользователю)
services[0][pages][0][link] string Номер телефона, который будет указан в кнопке whatsapp и которому будет писать клиент на странице сайта. В CRM Plugin ссылка будет сформирована следующим образов: https://wa.me/{Указанный номер телефона}
request_id string Строка переданная при запросе или порядковый указатель, если параметр не передан

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

{
    "_total_items": 2,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/sources"
        }
    },
    "_embedded": {
        "sources": [
            {
                "id": 9619,
                "name": "Номер отдела продаж",
                "pipeline_id": 1300,
                "external_id": "+17 912 100 00 00",
                "default": true,
                "origin_code": null,
                "services": [],
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/sources/9619"
                    }
                }
            },
            {
                "id": 4460,
                "name": "Лендинг",
                "pipeline_id": 1307,
                "external_id": "65bd500b-fd52-4599-ab58-943ce3dd058c",
                "origin_code": "amo.ext.30490163_v2",
                "default": false,
                "services": [],
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/sources/4460"
                    }
                }
            }
        ]
    }
}

Удаление источников

Метод

DELETE /api/v4/sources

Описание

Метод позволяет удалить источники пакетно.
Также вы можете добавить ID источника в метод для удаления конкретного источника (/api/v4/sources/{id}).
При пакетном удалении передается массив из объектов-источников, при удалении одного источника, тело запроса передавать не требуется.

Ограничения

Метод доступен с правами администратора.

Заголовок запроса

Content-Type: application/json

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

Параметр Тип данных Описание
id int ID источника, обязателен при пакетном удалении

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

[
    {
        "id": 9619
    },
    {
        "id": 4460
    }
]

HTTP коды ответа

Код ответа Условие
204 Источники были успешно удалены
401 Интеграция не авторизована
400 Не удалось найти источники при пакетном удалении. Подробности доступны в теле ответа
404 У интеграции нет подконтрольных источников или источник не найден (при указании конкретного источника)

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

Метод возвращает данные, если источники не были найдены при пакетном удалении

Параметр Тип данных Описание
request_id string Строка переданная при запросе или порядковый указатель, если параметр не передан

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

{
    "errors": [
        {
            "request_id": "0",
            "errors": {
                "code": "EntityNotFound",
                "path": "id",
                "detail": "source with id = 31075178 not found"
            }
        }
    ],
    "title": "Bad Request",
    "type": "https://httpstatus.es/400",
    "status": 400,
    "detail": "Invalid request items"
}