amoCRM у мобільному застосунку: OAuth 2.0, webhook'и та дзвінки

Проблема: інтеграція 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. Типи подій та підписка

Таблиця 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 з прив'язкою до контакту за номером телефону.

Що входить у роботу

• Документація з 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% — це економія на кожному проекті.

Чому курсорна пагінація краща за офсетну? Тому що при паралельних змінах даних офсет призводить до дублікатів або пропусків, а курсор завжди вказує на точне місце.

Інтеграція API в мобільний додаток: з чого почати

Запит йде, відповідь не приходить, timeout — 30 секунд. Користувач дивиться на спінер. Мережі немає — мобільна карта в метро. Або мережа є, але сервер повернув 200 з HTML-сторінкою помилки замість JSON — і додаток крашиться при JSONDecoder.decode(). Ми бачимо такі кейси на кожному другому проєкті. Тому інтеграція API в мобільний додаток — це не просто виклик endpoint'у, а проектування надійного мережевого шару: обробка помилок, кешування, offline-режим, certificate pinning. Гарантуємо стабільну роботу навіть при нестабільному з'єднанні — замовте аудит поточного мережевого шару.

Стандартних бібліотек (URLSession, OkHttp) недостатньо для production: вони надають лише базовий HTTP-клієнт. Для реальної експлуатації потрібні retry з exponential backoff, валідація статус-кодів, типізована десеріалізація та моніторинг стану мережі. Без цього додаток втрачає дані та користувачів. Ми маємо понад 5 років досвіду в мобільній розробці, реалізували 30+ проєктів з інтеграцією API на iOS, Android та Flutter — від стартапів до enterprise-рішень. Сертифіковані iOS/Android розробники гарантують якість коду.

Як вибрати протокол для інтеграції API?

REST залишається стандартом для більшості проєктів. Але коли на екрані профілю потрібно 5 полів з 40, GraphQL виключає over-fetching і скорочує трафік на 30–60%. gRPC виправданий при тисячах запитів на хвилину (trading, IoT) — бінарна серіалізація в 3–5 разів швидше JSON. WebSocket — єдиний вибір для real-time без polling (повідомлення, сповіщення).

Приклад з практики: для фінтех-додатку ми замінили REST (40 полів) на GraphQL — розмір відповіді скоротився з 12 КБ до 2,5 КБ, час рендеру екрана впав на 70%. Економія трафіку була значною при 100 000 активних користувачів.

Як забезпечити надійність з'єднання та offline-first?

Користувачі втрачають мережу в метро, ліфті, тунелі. Мобільний додаток зобов'язаний працювати без інтернету — хоча б у read-only режимі. Ми впроваджуємо патерн offline-first:

1. При відкритті екрану спочатку показуємо дані з локального кешу (Core Data / Room).
2. Паралельно виконуємо мережевий запит, оновлюємо UI після відповіді.
3. Якщо мережа недоступна — показуємо кешовані дані та позначку «немає з'єднання».
4. При відновленні мережі автоматично синхронізуємо зміни.

Для кешування HTTP-відповідей використовуємо URLCache (iOS) та OkHttp Cache (Android) з підтримкою Cache-Control. Для структурованих даних — SwiftData / Room. NWPathMonitor / ConnectivityManager.NetworkCallback відстежують стан мережі та тригерять оновлення. Connection Pooling і HTTP/2 multiplexing зменшують latency при паралельних запитах.

REST та вибір клієнтської бібліотеки

Alamofire (iOS) — де-факто стандарт для Swift-проєктів. Поверх URLSession додає request chaining, response validation, automatic retry, certificate pinning через ServerTrustManager. AF.request() з .validate() повертає помилку для будь-якого статус-коду поза 200–299. Без .validate() Alamofire вважає 404 та 500 успішними відповідями. З Swift Concurrency — async-версія через serializingDecodable.

Retrofit (Android) — анотаційний HTTP-клієнт поверх OkHttp. Інтерфейс з анотаціями компілюється в реалізацію. @GET, @POST, @Path, @Query, @Body — декларативний опис API. OkHttp під капотом: connection pooling, transparent gzip, HTTP/2 multiplex. HttpLoggingInterceptor — логування в debug-збірці. Authenticator — автоматичний refresh токена при 401. Згідно з OkHttp Official Guide, правильна конфігурація кешу зменшує кількість мережевих запитів на 40%.

Ktor (KMM/Flutter) — мультиплатформний HTTP-клієнт. На iOS працює через Darwin engine (URLSession), на Android — через OkHttp. Єдиний код для обох платформ при KMM-архітектурі.

GraphQL: коли REST не справляється

REST повертає фіксовану структуру. Екран профілю вимагає name, avatar, email — сервер віддає 40 полів. Over-fetching. GraphQL вирішує це: клієнт запитує рівно потрібні поля. Це критично для мобайлу, де трафік і час парсингу — реальні обмеження. Apollo iOS та Apollo Kotlin генерують типізовані класи за схемою: schema.graphql + query-файли → строгі типи на етапі компіляції. Subscriptions через WebSocket — real-time без polling. Обмеження: GraphQL складніше кешувати на рівні HTTP. Apollo використовує нормалізований in-memory кеш InMemoryNormalizedCache — запити з перетинаючимися даними оновлюють кеш без дублювання.

WebSocket: real-time без зайвого трафіку

Polling (setInterval кожні 5 секунд) — витрата батареї та трафіку. WebSocket — постійне двоспрямоване з'єднання. iOS: URLSessionWebSocketTask (нативний, iOS 13+). Android: OkHttp WebSocket. Обов'язкова обробка reconnect: при onFailure — експоненційний backoff (1с → 2с → 4с → 8с → максимум 60с). Socket.IO — надбудова з автоматичним reconnect, але для нових проєктів краще нативний WebSocket (менше залежностей). TLS 1.3 забезпечує безпеку з'єднання.

Чому важливий certificate pinning?

Корпоративний проксі може перехопити HTTPS через підміну сертифіката. Certificate pinning запобігає цьому: додаток приймає тільки конкретний сертифікат або публічний ключ. Alamofire: ServerTrustManager з PinnedCertificatesTrustEvaluator. OkHttp: CertificatePinner з SHA-256 хешем. Операційна складність: при ротації сертифіката старі версії додатку перестають працювати. Рішення — pinning на публічний ключ CA або підтримка кількох пінів з grace period. Правильне впровадження pinning гарантує захист від MITM-атак.

Що входить у роботу

Ми передаємо: вихідний код мережевого шару, документацію по використовуваних бібліотеках, інструкцію з ротації сертифікатів, підтримку протягом 2 тижнів після здачі.

Терміни та вартість

Реалізація мережевого шару з REST, retry, кешуванням та offline-режимом — 1–2 тижні. Додавання GraphQL або WebSocket — ще 1–2 тижні. gRPC — 2–3 тижні, включаючи кодогенерацію. Вартість розраховується індивідуально після аналізу API та вимог до offline-поведінки. Оцінимо проєкт за 1 день — зв'яжіться з нами для консультації. Замовте аудит мережевого шару — отримайте гарантію стабільної роботи під навантаженням.