API Гулливер ЦРМ

API ГулливерЦРМ предоставляет возможность интеграции с внешними системами для управления данными внутри приложения. В этом руководстве описаны доступные эндпойнты на настоящий момент, их параметры и примеры использования.

Общие принципы работы с API

• Субдомен: Каждый запрос должен быть выполнен на вашем субдомене, соответствующем (например, application.gullivercrm.com).
• Авторизация: Все запросы должны быть авторизованы с использованием токена доступа или другим специальным для ендпойнта методом.
• Эндпойнты возвращают ответы в формате JSON.
• Для обработки ошибок используются стандартные HTTP-коды:
  • 200 OK — запрос выполнен успешно.
  • 400 Bad Request — ошибка валидации или некорректные данные.
  • 401 Unauthorized — отсутствие авторизации.
  • 404 Not Found — ресурс не найден.
  • 500 Internal Server Error — внутренняя ошибка сервера.
• Добавление новых эндпоинтов осуществляется по необходимости для клиентов

---

API Эндпойнты

Добавление сделки через API

Описание

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

Метод

POST

URL

api/pipeline/deal/add/:name

Параметры URL

• name (обязательный) — источник сделки (например, tilda, webform и т.д.). Должен соответствовать источникам сделки

Тело запроса

Тело запроса должно содержать данные сделки в формате JSON. Пример тела запроса:

{
  "phone": "+375291234567", // международный формат
  "stage": "stageId", // id этапа на котором будут создаваться сделки
  "name": "Иван",
  "surname": "Иванов",
  "birth": "2025-03-12T21:00:00.000Z", // формат ISO 8601
  "contact": "ivanov@example.com",
  "customField1Id": "Значение1",
  "customField2Id": "Значение2",
  "secret": "secret-token" // скопировать из настроек интеграции
}

Ответ

В случае успешного выполнения запроса возвращается JSON-объект с сообщением:

{
  "statusCode": 200,
  "message": "Сделка успешно добавлена"
}

Пример запроса

curl -X POST "https://application.gullivercrm.com/pipeline/deal/add/tilda" \
-H "Content-Type: application/json" \
-d '{
  "phone": "+375291234567",
  "stage": "stageId",
  "name": "Иван",
  "surname": "Иванов",
  "birth": "2025-03-12T21:00:00.000Z",
  "contact": "ivanov@example.com",
  "customField1": "Значение1",
  "customField2": "Значение2",
  "secret": "34565756ggfe33345",
}'

Обработка ошибок

Если валидация данных не пройдена, возвращается ошибка 400 Bad Request с сообщением:

{
  "statusCode": 400,
  "message": "Validation failed!"
}

Если источник сделки (name) не найден, возвращается ошибка 404 Not Found.

---

Тестовый эндпойнт для добавления сделки

Описание

Этот эндпойнт предназначен для тестирования интеграции добавления сделки. Он не выполняет реальных действий, а только возвращает успешный ответ.

Метод

POST

URL

api/pipeline/deal/add/:name/test

Параметры URL

• name (обязательный) — источник сделки (например, tilda, webform и т.д.).

Ответ

В случае успешного выполнения запроса возвращается JSON-объект:

{
  "statusCode": 200,
  "message": "Test successfully"
}

Пример запроса

curl -X POST "https://api.example.com/deal/add/tilda/test" \
-H "Content-Type: application/json"

Вот пример документации для вебхуков, которые активируются автоматизациями, с учетом мультитенантной архитектуры и вашего кода:

---

Webhooks в ГулливерЦРМ

Вебхуки в ГулливерЦРМ позволяют автоматически отправлять данные на внешние системы при выполнении определенных условий (триггеров) в автоматизациях. Добавление вебхуков происходит при добавлении автоматизаций. Можно добавлять несколько вебхуков на один триггер.

Общие принципы работы с вебхуками

• Автоматизации: Вебхуки активируются только через автоматизации, которые состоят из триггеров (условий) и действий (экшенов). Вебхук является вариантом экшена
• Обработка ошибок: В случае ошибки при отправке вебхука, система логирует ошибку и может повторно попытаться отправить запрос (в зависимости от настроек автоматизации).

---

Вебхук: Активация внешнего URL

Описание

Этот экшен отправляет POST-запрос на указанный URL с данными, которые передаются в теле запроса. Вебхук активируется при выполнении условий триггера в автоматизации. В теле запроса передаются данные, которые формируются автоматически

Метод

POST

URL

https://requestb.in/xxxxxxxxx

Параметры запроса

• url (обязательный) — URL, на который будет отправлен запрос.

Тело запроса

Тело запроса содержит данные, которые передаются в вебхук и генерируются автоматически

Триггер

• Тип триггера: Изменение статуса ячейки (cellStatusUpdated).

Действие

• Тип действия: Активация вебхука.
• Параметры действия:
• URL: https://requestb.in/xxxxxxxxx

Результат

При изменении статуса ячейки система отправит POST-запрос на указанный URL с данными о событии.

---

Рекомендации по использованию вебхуков

1. Проверка URL: Убедитесь, что URL вебхука корректен и доступен извне.
2. Обработка ошибок: Настройте внешнюю систему для корректной обработки входящих запросов и возврата соответствующих HTTP-кодов.

---

P.s. 🧩🏆

Теперь вы можете добавлять вебхуки в свои автоматизации, следуя этому руководству. Удачи в автоматизации процессов! 🚀