REST API CRM — примеры интеграции

Основные эндпоинты CRM API

Любая современная CRM предоставляет стандартный набор эндпоинтов для работы с основными сущностями. Вот что обычно доступно «из коробки»:

• GET /api/contacts — получение списка контактов с фильтрацией и пагинацией
• POST /api/deals — создание новой сделки (самый частый запрос при интеграции с формами)
• PUT /api/deals/{id} — обновление существующей сделки (например, смена статуса)
• GET /api/tasks — список задач (удобно для синхронизации с календарями)

На практике 80% интеграций сводятся к двум операциям: создать контакт/сделку при получении заявки и обновить статус при изменении в другой системе. Остальные эндпоинты — для более сложных сценариев вроде построения кастомных дашбордов или полной двусторонней синхронизации.

Аутентификация: как не наступить на грабли

Первое, с чем сталкивается любой разработчик при работе с API — аутентификация. И тут важно выбрать правильный подход с самого начала, иначе потом придётся переделывать.

• API Key — самый простой вариант. Подходит для серверных интеграций, где ключ хранится в безопасном месте. Не используйте его в клиентском JavaScript — ключ увидит любой, кто откроет DevTools
• OAuth 2.0 — стандарт для публичных приложений. Да, настройка сложнее, зато пользователи сами дают разрешения, а вы не храните их пароли
• JWT токены — идеальны для микросервисной архитектуры. Токен содержит информацию о пользователе и сам себя валидирует

Независимо от выбранного метода, токен передаётся в заголовке запроса:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Совет из практики: храните API-ключи в переменных окружения, а не в коде. Один случайный коммит в публичный репозиторий — и ваш ключ уже на GitHub, сканируемый ботами. Поверьте, такое случается чаще, чем хотелось бы.

Пример: создание контакта (Python)

Допустим, у вас есть форма обратной связи на сайте. Пользователь оставляет заявку — и вам нужно автоматически создать контакт в CRM. Вот как это делается на Python:

import requests



import os







# Ключ берём из переменных окружения, не хардкодим!



api_key = os.environ.get('CRM_API_KEY')







url = "https://api.crm-ai.ru/v1/contacts"



headers = {



    "Authorization": f"Bearer {api_key}",



    "Content-Type": "application/json"



}







# Данные из формы на сайте



data = {



    "name": "Иван Петров",



    "email": "ivan@example.com",



    "phone": "+7 701 123-45-67",



    "company": "ТОО Ромашка",



    "source": "website_form",  # откуда пришёл контакт



    "tags": ["новый", "сайт"]



}







response = requests.post(url, json=data, headers=headers)







if response.status_code == 201:



    contact = response.json()



    print(f"Контакт создан, ID: {contact['id']}")



else:



    print(f"Ошибка: {response.status_code} - {response.text}")

Обратите внимание: мы добавили поле source — это поможет потом в аналитике понять, откуда приходят лиды. Мелочь, но через полгода скажете спасибо.

Пример: получение сделок с фильтрацией (JavaScript)

Теперь представим другую задачу: нужно показать менеджеру его сделки в работе прямо в корпоративном портале. Для этого используем GET-запрос с параметрами фильтрации:

// Функция для получения сделок с фильтрами



async function getDeals(managerId, status = 'in_progress') {



  const params = new URLSearchParams({



    manager_id: managerId,



    status: status,



    limit: 50,



    sort: '-updated_at'  // минус означает сортировку по убыванию



  });







  const response = await fetch(



    `https://api.crm-ai.ru/v1/deals?${params}`,



    {



      method: 'GET',



      headers: {



        'Authorization': `Bearer ${process.env.CRM_API_KEY}`,



        'Content-Type': 'application/json'



      }



    }



  );







  if (!response.ok) {



    throw new Error(`HTTP ${response.status}: ${await response.text()}`);



  }







  const data = await response.json();







  // Возвращаем и сами сделки, и информацию о пагинации



  return {



    deals: data.items,



    total: data.total,



    hasMore: data.has_next_page



  };



}







// Использование



const { deals, total } = await getDeals('manager_123');



console.log(`Найдено ${total} сделок в работе`);

Заметьте, что мы сразу обрабатываем ошибки и возвращаем информацию о пагинации. В реальных проектах это критично — никто не хочет загружать 10 000 сделок одним запросом.

Обработка ошибок: что может пойти не так

API — это не волшебная палочка. Запросы падают, токены протухают, сервера иногда лежат. Хорошая новость: HTTP-коды ошибок стандартизированы, и по ним сразу понятно, что произошло.

• 400 Bad Request — вы отправили что-то не то. Обычно в теле ответа есть подробности: какое поле некорректно, чего не хватает
• 401 Unauthorized — токен невалидный или истёк. Первым делом проверьте, не опечатались ли вы в заголовке Authorization
• 403 Forbidden — токен рабочий, но у вас нет прав на это действие. Возможно, нужно запросить дополнительные разрешения у администратора
• 429 Too Many Requests — вы слишком усердствуете. Подождите и повторите (подробнее про rate limiting ниже)
• 500 Internal Server Error — проблема на стороне сервера. Если повторяется — пишите в поддержку с ID запроса

Важно: всегда логируйте тело ответа при ошибках. Фраза «API вернул 400» ничего не говорит, а вот {"error": "email", "message": "Invalid email format"} — совсем другое дело.

Rate Limiting: как не заDDoSить CRM

Любой уважающий себя API ограничивает количество запросов. Это защита и для сервера, и для вас — случайный бесконечный цикл не положит всю систему.

Типичные лимиты выглядят примерно так:

• Базовый план: 100 запросов в минуту — хватает для большинства интеграций
• Бизнес план: 1000 запросов в минуту — для высоконагруженных сценариев

Чтобы отслеживать лимиты, API возвращает специальные заголовки в каждом ответе:

X-RateLimit-Limit: 100        // ваш лимит



X-RateLimit-Remaining: 73     // сколько осталось



X-RateLimit-Reset: 1679012400 // когда счётчик сбросится (Unix timestamp)

Если всё-таки получили 429, не паникуйте. Правильный паттерн — exponential backoff: подождать 1 секунду, повторить. Если опять 429 — подождать 2 секунды, потом 4, 8 и так далее. Вот простая реализация:

async function fetchWithRetry(url, options, maxRetries = 3) {



  for (let attempt = 0; attempt < maxRetries; attempt++) {



    const response = await fetch(url, options);







    if (response.status !== 429) {



      return response;



    }







    // Ждём с экспоненциальной задержкой



    const delay = Math.pow(2, attempt) * 1000;



    console.log(`Rate limited, waiting ${delay}ms...`);



    await new Promise(resolve => setTimeout(resolve, delay));



  }







  throw new Error('Max retries exceeded');



}

Чек-лист перед выходом в продакшен

Перед тем как деплоить интеграцию, пробегитесь по этому списку. Поверьте, лучше потратить 10 минут сейчас, чем ночь на дебаг в продакшене:

• API-ключи вынесены в переменные окружения (не в код!)
• Реализована обработка всех HTTP-ошибок (особенно 429 и 5xx)
• Настроено логирование запросов и ответов (пригодится для дебага)
• Есть механизм повторных попыток с exponential backoff
• Таймауты выставлены адекватно (обычно 10-30 секунд)
• Протестировано на тестовом окружении (если есть sandbox API)

Подводя итоги

REST API — это мост между CRM и остальными системами вашего бизнеса. Да, первая интеграция всегда вызывает вопросы: как авторизоваться, что делать с ошибками, не забанят ли за частые запросы. Но стоит один раз разобраться — и следующие интеграции пишутся уже на автомате.

Главное помнить три вещи:

1. Безопасность прежде всего — храните ключи правильно, используйте HTTPS, не светите токенами в логах
2. Ошибки неизбежны — ваш код должен их корректно обрабатывать, а не падать с невнятным исключением
3. API — это договор — читайте документацию, следите за версиями, не полагайтесь на недокументированное поведение

Если что-то пошло не так — не стесняйтесь писать в поддержку. Хороший вопрос с примером запроса и ответа решается в разы быстрее, чем «у меня ничего не работает».