API для интеграций

Что это и зачем

API для интеграций позволяет внешним системам добавлять данные в ваш CRM без входа в браузер:

• создавать записи (подтверждённые визиты);
• принимать онлайн-заявки (как с публичной страницы записи);
• добавлять товары на склад;
• читать справочники (услуги, мастера, слоты), искать клиента по телефону и просматривать список записей.

Типичные сценарии: форма на вашем сайте, обмен с 1С, скрипт на сервере, автоматизация (n8n, Make и т.п.).

Важно API не предназначен для массовой выгрузки базы клиентов. Чтение клиентов — только по номеру телефона. Список записей — с фильтрами и пагинацией.

Как открыть настройки

1. Войдите в CRM как владелец аккаунта: cp.gipix-lite.ru.
2. Откройте Интеграции (/integrations) — из меню или раздела Компания.
3. Перейдите на вкладку API.

Подробнее о других каналах (Telegram, MAX, звонки) — в Интеграциях.

Примечание Раздел Интеграции доступен владельцу на тарифе Pro и выше.

API-ключ

Создание

1. На вкладке API нажмите Создать ключ (или Перевыпустить ключ, если ключ уже был).
2. Откроется окно с полным ключом вида gpx_….
3. Нажмите Скопировать ключ и сохраните его в надёжном месте (менеджер паролей, настройки вашего сервера).

Ключ показывается один раз После закрытия окна полный ключ больше не отображается в CRM. В интерфейсе останется только префикс (gpx_…) для узнавания. Если ключ потерян — перевыпустите новый; старый перестанет работать.

Включение и отзыв

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

После изменения прав (какие методы разрешены) нажмите Сохранить внизу страницы интеграций.

Права (методы)

На вкладке API можно включить или отключить каждый метод отдельно:

Рекомендуется включать только то, что реально использует ваша интеграция.

Базовый адрес и авторизация

Базовый URL API:

https://cp.gipix-lite.ru/api/crm/v1

Авторизация — передайте ключ в заголовке запроса (предпочтительно):

Authorization: Bearer gpx_ВАШ_КЛЮЧ

Альтернатива:

X-GIPIX-API-Key: gpx_ВАШ_КЛЮЧ

Не вставляйте ключ в код сайта Ключ нельзя размещать в JavaScript на публичной странице — его увидит любой посетитель. Вызывайте API с вашего сервера (backend сайта, 1С, скрипт), а не из браузера клиента.

Только HTTPS На продакшене используйте https://cp.gipix-lite.ru. Не передавайте ключ по незашифрованному HTTP.

Методы API

Проверка ключа

GET /api/crm/v1/health
Authorization: Bearer gpx_ВАШ_КЛЮЧ

Ответ подтверждает, что ключ действителен, и показывает включённые права (запись, чтение, склад и т.д.).

Справочники (чтение)

GET /api/crm/v1/services
GET /api/crm/v1/masters
GET /api/crm/v1/booking/slots?date=2026-07-01

Слоты рассчитываются по настройкам онлайн-записи. Параметр master необязателен.

Клиент по телефону

GET /api/crm/v1/clients?phone=%2B79001234567

Без параметра phone запрос отклоняется. Полной выгрузки клиентов нет.

Список записей

GET /api/crm/v1/appointments?period=upcoming
GET /api/crm/v1/appointments?period=today
GET /api/crm/v1/appointments?period=past
GET /api/crm/v1/appointments?period=all
GET /api/crm/v1/appointments/123

Черновики (is_draft) в список не попадают.

Добавить запись

POST /api/crm/v1/appointments
Content-Type: application/json
Authorization: Bearer gpx_ВАШ_КЛЮЧ

Обязательные поля в теле (JSON):

Необязательно: customer_phone, master, master_ids, comment, estimated_price, car_vin, car_plate.

Запись создаётся подтверждённой (как из формы CRM).

Пример:

curl -X POST 'https://cp.gipix-lite.ru/api/crm/v1/appointments' \
  -H 'Authorization: Bearer gpx_ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{
    "date": "2026-07-01",
    "time": "10:00",
    "customer_name": "Иван",
    "customer_phone": "+79001234567",
    "car_model": "Toyota Camry",
    "reason": "Диагностика"
  }'

Онлайн-запись

POST /api/crm/v1/online-booking

Правила те же, что у публичной онлайн-записи: обязательны дата, время, имя, телефон; автомобиль и услуга — если так настроено в Онлайн-записи.

Заявка попадает в CRM со статусом ожидает подтверждения; команде могут уйти уведомления (Telegram / MAX), если они настроены.

Пример:

curl -X POST 'https://cp.gipix-lite.ru/api/crm/v1/online-booking' \
  -H 'Authorization: Bearer gpx_ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{
    "date": "2026-07-01",
    "time": "10:00",
    "customer_name": "Иван",
    "customer_phone": "+79001234567",
    "car_model": "Toyota Camry",
    "reason": "Замена масла"
  }'

Добавить товар на склад

POST /api/crm/v1/warehouse/parts

Подробнее о складе в CRM — в Склад запчастей.

Пример:

curl -X POST 'https://cp.gipix-lite.ru/api/crm/v1/warehouse/parts' \
  -H 'Authorization: Bearer gpx_ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Масляный фильтр",
    "quantity": 5,
    "purchase_price": 320,
    "price": 490
  }'

Ответы и ошибки

При ошибке 429 в ответе есть поле retry_after (секунды до повтора) и заголовок Retry-After.

Лимиты запросов (антиспам)

Чтобы защитить CRM от перегрузки и перебора ключей, действуют лимиты на один API-ключ:

Актуальные цифры отображаются на вкладке API → Лимиты запросов в Интеграциях.

Безопасность

Что защищено:

• ключ в базе хранится как хэш — украсть его из БД нельзя;
• полный ключ не показывается повторно в интерфейсе;
• API не отдаёт полный список клиентов — только поиск по телефону;
• список записей — с фильтрами period и пагинацией, без выгрузки «всей истории» одним файлом;
• доступ только у владельца для создания ключа;
• есть лимиты и блокировка перебора неверных ключей.

Главный риск — утечка ключа. Тот, у кого есть ключ, может добавлять записи и товары от имени вашего сервиса, но не читать всю базу.

Рекомендации:

1. Храните ключ как пароль; не коммитьте в Git и не отправляйте в мессенджеры.
2. Вызывайте API только с сервера, не из браузера посетителя.
3. Включайте минимум прав (отключите склад, если не нужен).
4. При подозрении на утечку — Отозвать ключ и выпустить новый.
5. Выключайте API (API включён), когда интеграция не используется.

Частые вопросы

• Ключ не работает (401). Проверьте, что API включён, ключ скопирован целиком (с префиксом gpx_), в заголовке Authorization: Bearer … нет лишних пробелов.
• 403 на метод. Откройте вкладку API и убедитесь, что нужный переключатель (запись / онлайн / склад) включён; нажмите Сохранить.
• 429 — слишком много запросов. Подождите retry_after секунд или уменьшите частоту вызовов в интеграции.
• Онлайн-запись отклоняется. Сверьте настройки Онлайн-записи: график, закрытые дни, запись на сегодня, обязательность автомобиля и услуги.
• Можно ли выгрузить всех клиентов через API? Нет — только поиск по phone. Для выгрузки используйте разделы CRM (клиенты, отчёты).
• Как получить только сегодняшние записи? GET /api/crm/v1/appointments?period=today.

Связь с другими разделами

• Интеграции — Telegram, MAX, звонки, поставщики.
• Онлайн-запись — публичная страница и правила слотов.
• Склад запчастей — учёт остатков в CRM.
• Панель управления и записи — где появятся созданные записи.
• Обратная связь — если нужна помощь с нестандартной интеграцией.