Інтеграція amoCRM з мобільним застосунком

Інтеграція amoCRM з мобільним додатком

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

OAuth 2.0 та мультиаккаунт

amoCRM використовує Authorization Code Flow з особливістю: базовий 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.contacts — amoCRM створить і прив'яже в одному запиті.

Вебхуки та подіï

Вебхук amoCRM відправляє 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 секунд, інакше вважає доставку невдалою та повторює. Не робіть довгих операцій у вебхук-хендлері — прийміть, поставте в чергу, поверніть 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 тижні. Вебхуки, реєстрація дзвінків, push-уведомлення: плюс 3-5 днів. Вартість розраховується індивідуально.