CRM API: начало работы

CRM API предназначен для серверной интеграции APX Chat с ERP, CDP, сайтом, телефонией и другими внешними системами. API работает с данными встроенной CRM организации и не проксирует методы AmoCRM или Bitrix24.

Базовый URL: https://api.apx.chat/api/v1/crm

Интерактивная схема доступна в Swagger UI, исходный контракт — в OpenAPI JSON.

Авторизация и изоляция организации#

Токен выпускается в кабинете: Настройки → API-токены. Как выбрать scopes и срок действия — в описании API-токенов. Передавайте токен ровно одним способом:

X-Api-Token: tok_xxxxxxxxxxxxx
Authorization: Bearer tok_xxxxxxxxxxxxx

X-Api-Key принимается только для совместимости со старыми интеграциями; в новом коде используйте X-Api-Token. Организация и стабильный applicationId определяются по токену. API не принимает tenant ID от клиента и не позволяет токену выбрать другую организацию.

Каждый маршрут требует указанный scope. Дополнительные scopes защищают контакты, денежные значения и дополнительные поля. Если у организации подключён внешний CRM-провайдер, маршруты данных возвращают 409 crm_provider_not_supported. Проверить совместимость заранее можно через GET /capabilities.

Первый запрос:

js⌄

APX: X-Api-Token⌄

⧉Скопировать код

const url = "https://api.apx.chat/api/v1/crm/contacts?limit=50";

const response = await fetch(url, {
  method: "GET",
  headers: {
    "X-Api-Token": "tok_xxxxxxxxxxxxx",
  },
});

const data = await response.json();
console.log(data);

Успешный ответ имеет поля data и, для списков, meta. API не добавляет внешний wrapper { status, data }:

{
  "data": [],
  "meta": {
    "hasMore": false,
    "nextCursor": null
  }
}

Разделы документации#

• Контакты, компании, сделки, задачи, поиск и аудит
• Воронки, теги, операторы и настройки CRM
• Дополнительные поля
• Синхронизация и CRM webhooks
• Фоновые операции, импорт и вложения
• Ошибки, лимиты и совместимость

Рекомендуемый цикл интеграции#

1. Выпустите отдельное приложение с минимальными scopes, сроком действия и CIDR allowlist.
2. Проверьте GET /capabilities и выполните начальную загрузку через cursor-пагинацию.
3. Сохраните externalId, UUID и version каждого связанного ресурса.
4. Используйте webhook для быстрой реакции и change feed для гарантированного восстановления.
5. Для mutation-запросов используйте Idempotency-Key, для конкурентных изменений — CAS.
6. Ротируйте credential заранее, используя 24-часовой grace period.

Официальный клиентский SDK пока не публикуется. Генерируйте типизированный клиент из OpenAPI JSON или вызывайте HTTP API напрямую.

Для ручных проверок в репозитории лежит готовая Postman-коллекция: docs/crm-api/postman/. Импортируйте collection.json вместе с environment.json и задайте baseUrl и apiToken. Оба файла и docs/crm-api/openapi.json генерируются из кода командой npm run crm-api:artifacts в каталоге server — править их вручную бессмысленно, CI сверяет содержимое с реализацией.