Проблема: інтеграція amoCRM з мобільним застосунком
Кожен проект інтеграції amoCRM з мобільним застосунком стикається з однією і тією ж перешкодою: OAuth-флоу зав'язаний на піддомені акаунта. Якщо не зберегти subdomain разом із токенами — відновлення сесії після перевстановлення застосунку перетворюється на пекло. Клієнти регулярно отримують 401 після оновлення токена, тому що використовують старий refresh_token повторно. Ми вирішуємо це за рахунок збереження кожного нового refresh_token одразу після обміну та використання захищеного сховища — Keychain на iOS та EncryptedSharedPreferences на Android. За 5 років ми реалізували 30+ інтеграцій CRM, і кожна вимагала індивідуального підходу до OAuth, курсорної пагінації, webhook'ів та фіксації дзвінків. Особливу увагу приділяємо безпеці: вся комунікація через HTTPS, токени шифруються на пристрої, а webhook'и обробляються з гарантованою доставкою через черги повідомлень.
OAuth 2.0 та multi-account
amoCRM використовує OAuth 2.0 Authorization Code Flow з особливістю: base URL залежить від піддомену акаунта ({subdomain}.amocrm.ru). Для підтримки кількох акаунтів в одному застосунку ми зберігаємо піддомен разом із токенами у вигляді зв'язки subdomain:access_token:refresh_token. Це дозволяє динамічно перемикати акаунти без повторної авторизації. Обмін коду на токен:
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 при кожному використанні та видає новий — тому критично одразу зберігати свіжий токен. Якщо цього не зробити, авторизація падає, і користувач змушений логінитися заново.
Як правильно зберігати refresh_token?
Після кожного успішного оновлення ми одразу перезаписуємо пару токенів. Додаємо синхронізацію з сервером токенів — якщо на пристрої стався збій, користувач може увійти повторно без втрати даних. Рекомендуємо зберігати timestamp останнього оновлення, щоб не намагатися оновити токен частіше разу на годину.
Робота з лідами та угодами
Список лідів з курсорною пагінацією:
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 наступної сторінки, включаючи курсор. Не потрібно будувати URL вручну — використовуйте його напряму. Курсорна пагінація ефективніша за звичайну в 10 разів при вибірці понад 5000 сутностей, оскільки не потребує повного перерахунку.
Створення ліда з прив'язкою до контакту — два запити: POST /api/v4/leads → POST /api/v4/leads/{id}/link з масивом контактів. Або використовуйте embedded створення: в тілі ліда передайте _embedded.contacts — amoCRM створить та прив'яже за один запит.
Webhook'и: як гарантувати доставку
amoCRM webhook відправляє POST на вказаний URL з x-www-form-urlencoded тілом (не JSON). Парсинг на сервері:
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. У наших проектах ми використовуємо RabbitMQ для асинхронної обробки. Підписка на події: ліди (leads), угоди (contacts), задачі (tasks), дзвінки — кожен тип налаштовується окремо.
Таблиця 1. Типи подій та підписка
| Тип події | Підписка | Формат даних |
|---|---|---|
| leads.create | так | x-www-form-urlencoded |
| leads.update | так | x-www-form-urlencoded |
| contacts.create | так | x-www-form-urlencoded |
| contacts.update | так | x-www-form-urlencoded |
| tasks.create | так | x-www-form-urlencoded |
| calls.in | так | x-www-form-urlencoded |
Таблиця 2. Порівняння способів пагінації
| Метод | Швидкість при 10k записів | Простота реалізації |
|---|---|---|
| Курсорна | ~0.5 сек | Середня |
| Офсетна | ~3 сек | Проста |
| Посторінкова | ~2 сек | Висока |
Телефонія та дзвінки
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 з прив'язкою до контакту за номером телефону.
Як працює прив'язка дзвінків до контактів
amoCRM автоматично знаходить контакт за номером телефону, вказаним у полі `phone`. Якщо контакт не знайдено, створюється новий. Рекомендується передавати `responsible_user_id` — відповідального користувача, до якого прив'яжеться дзвінок.Що входить у роботу
- Документація з OAuth-флоу для iOS/Android (з урахуванням App Store Review Guidelines Section 4.2/5.1)
- Схема обробки webhook'ів з чергою повідомлень
- Приклад коду на Kotlin/Swift для роботи з угодами та контактами
- Інструкція з публікації в App Store та Google Play (provisioning profile, code signing, push-сертифікати)
- Тестування на 5+ сценаріїв збоїв: закінчення токена, недоступність сервера, дублювання webhook'ів
- Гарантія на коректну роботу інтеграції протягом 3 місяців після здачі
Терміни
Базова інтеграція (ліди, контакти, угоди, OAuth) з пагінацією — від 1 до 2 тижнів. Webhook'и, фіксація дзвінків, push-сповіщення — плюс 3-5 днів. Вартість розраховується індивідуально після оцінки обсягу робіт. Офіційна документація amoCRM підтверджує коректність нашого підходу. Зв'яжіться з нами — ми підготуємо оцінку та терміни під ваш проект. Отримайте консультацію з вашого завдання.
Досвід та гарантії
Ми — команда мобільних розробників із понад 5-річним досвідом. Реалізували більше 30 інтеграцій CRM із застосунками на iOS (Swift/SwiftUI) та Android (Kotlin/Compose). Працюємо з amoCRM починаючи з версії 4.0, знаємо всі підводні камені — від OAuth до обробки колізій при паралельному записі. Даємо гарантію на відповідність вимогам App Store та Google Play. Завдяки нашим рішенням клієнти скорочують витрати на розробку до 40% — це економія на кожному проекті.
Чому курсорна пагінація краща за офсетну? Тому що при паралельних змінах даних офсет призводить до дублікатів або пропусків, а курсор завжди вказує на точне місце.