Интеграция amoCRM с мобильным приложением

Интеграция amoCRM с мобильным приложением

amoCRM (теперь kommo.com на международном рынке) — CRM с фокусом на воронку продаж и мессенджер-интеграции. REST API современный, с OAuth 2.0, курсорной пагинацией и webhook'ами. Из особенностей — авторизация привязана к поддомену аккаунта, что нужно учитывать при построении OAuth-флоу в мобильном приложении.

OAuth 2.0 и multi-account

amoCRM использует Authorization Code Flow с особенностью: base URL зависит от поддомена аккаунта клиента ({subdomain}.amocrm.ru). При разработке мобильного приложения для нескольких аккаунтов нужно хранить поддомен вместе с токенами.

Обмен кода на токен:

POST https://{subdomain}.amocrm.ru/oauth2/access_token
{
  "client_id": "...",
  "client_secret": "...",
  "grant_type": "authorization_code",
  "code": "...",
  "redirect_uri": "..."
}

access_token живёт 24 часа, refresh_token — 3 месяца. amoCRM аннулирует refresh_token при каждом использовании и выдаёт новый — нужно сохранять свежий токен после каждого обновления. Если пропустил и попытался использовать старый — авторизация падает, пользователь должен логиниться снова.

Работа с лидами и сделками

Список лидов с курсорной пагинацией:

suspend fun getLeads(cursor: String? = null): LeadsResponse {
    return api.getLeads(
        withQuery = mapOf(
            "contacts" to listOf("contacts"),
            "catalog_elements" to listOf("catalog_elements")
        ),
        cursor = cursor,
        limit = 50
    )
}

amoCRM возвращает _links.next.href с готовым URL следующей страницы включая cursor. Не нужно строить URL вручную — используй его напрямую.

Создание лида с привязкой к контакту — два запроса: POST /api/v4/leads → POST /api/v4/leads/{id}/link с массивом контактов. Или используй embedded создание: в теле лида передай _embedded.contacts — amoCRM создаст и привяжет за один запрос.

Webhook'и и события

amoCRM webhook отправляет POST на указанный URL с x-www-form-urlencoded телом (не JSON). Парсинг на сервере:

// Node.js
app.post('/webhook/amo', express.urlencoded({ extended: true }), (req, res) => {
    const event = req.body;
    // event.leads.update[0].id - ID изменённой сделки
    // event.leads.status_change[0].status_id - новый статус
    res.sendStatus(200);
});

amoCRM ждёт 200 OK в течение 10 секунд, иначе считает доставку неудачной и повторяет. Не делай долгих операций в webhook-хендлере — прими, поставь в очередь, верни 200.

Подписка на события: лиды (leads), сделки (contacts), задачи (tasks), входящие звонки — каждый тип настраивается отдельно в настройках интеграции amoCRM.

Телефония и звонки

amoCRM фиксирует звонки через POST /api/v4/calls:

{
  "direction": "outbound",
  "duration": 125,
  "source": "МоёПриложение",
  "link": "https://...",
  "phone": "+79001234567",
  "call_result": "Успешно",
  "call_status": 4,
  "responsible_user_id": 123456,
  "created_by": 123456
}

call_status: 1 — оставил сообщение, 2 — перезвонит, 3 — недозвон, 4 — переговорил. После звонка из мобильного приложения — автоматически создаётся запись в amoCRM с привязкой к контакту по номеру телефона.

Сроки

Базовая интеграция (лиды, контакты, сделки, OAuth) с пагинацией: 1-2 недели. Webhook'и, фиксация звонков, push-уведомления: плюс 3-5 дней. Стоимость рассчитывается индивидуально.