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

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

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

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

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

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

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

Оглавление

• Требования к интеграции для работы с API источников
• Получение списка источников
• Получение источника по ID
• Добавление источников
• Редактирование источников
• Удаление источников

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

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

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

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

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

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

Метод

GET /api/v4/sources

Описание

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

Ограничения

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

GET параметры

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

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

{
    "_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 коды ответа

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

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

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

{
    "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": "Номер отдела продаж",
        "pipeline_id": 1300,
        "external_id": "+17 912 100 00 00",
        "default": true,
        "services": [
            {
                "type": "whatsapp",
                "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 коды ответа

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

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

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

{
    "_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",
                        "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) изменить нельзя, можно только создать новый источник с таким идентификатором

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

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

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

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

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

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

{
    "_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": 9619
    },
    {
        "id": 4460
    }
]

HTTP коды ответа

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

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

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

{
    "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"
}