REST API v1

Пользовательский API

Интеграция с CRM, сделками и канбаном Uptimo по персональному Bearer-токену upt_…. API подходит для форм сайта, телефонии, ботов, no-code сценариев и внутренних интеграций.

Выпустить токенСкачать OpenAPI YAML

Базовый URL

https://api.uptimo.cloud

Все внешние методы пользовательского API находятся под префиксом /user-api/v1.

Авторизация

Передавайте токен в каждом запросе:

Authorization: Bearer upt_...

Токен показывается только один раз при выпуске. В базе хранится SHA-256 хеш токена.

Ошибки

Ошибки возвращаются в JSON-формате NestJS. Поле message может быть строкой или массивом.

{
  "statusCode": 400,
  "message": "Колонка не найдена на доске",
  "error": "Bad Request"
}

Как получить токен

  1. Откройте личный кабинет → API и интеграции.
  2. Создайте токен. Можно указать понятное имя, например Сайт / формы.
  3. Скопируйте значение вида upt_... и сохраните его в своём сервисе.
  4. Если токен больше не нужен, отзовите его в личном кабинете.

Внутренние методы управления токенами в личном кабинете работают по обычной JWT-сессии: GET /user-api/tokens, POST /user-api/tokens, DELETE /user-api/tokens/:id. Для внешних интеграций используйте только Bearer-токен upt_….

Доступные методы

POST/user-api/v1/contacts/persons

Создать контакт

Создание физлица или сотрудника компании в CRM.

  • Обязательные поля: isClient, isCounterparty.
  • Без companyId обязательно поле legalStatus: ip, self_employed или individual.
  • values принимает дополнительные поля CRM, если они настроены.
POST/user-api/v1/deals/boards/{boardId}/cards

Создать сделку

Создание карточки сделки на вашей доске сделок.

  • Обязательное поле: title.
  • responsibleUserId — владелец доски или участник проекта.
  • crmPersonId и crmCompanyId должны принадлежать владельцу токена.
POST/user-api/v1/kanban/boards/{boardId}/cards

Создать задачу

Создание карточки на доске задач.

  • Обязательное поле: title.
  • assignedUserId — владелец доски или участник команды доски.
  • dueDate передаётся в ISO 8601, например 2026-12-31T12:00:00.000Z.

Контакты CRM

Метод создаёт персону в CRM. Если передать companyId, контакт будет сотрудником существующей компании. Если companyId не указан, обязательно передайте legalStatus.

companyIdUUID компании. Если указан, контакт создаётся как сотрудник компании.
legalStatusip, self_employed или individual. Нужен только без companyId.
firstName / lastName / middleNameИмя, фамилия и отчество, до 120 символов каждое.
positionДолжность сотрудника, до 300 символов.
phone / emailТелефон до 64 символов, email до 320 символов.
telegram / whatsappКонтакты в мессенджерах, до 128 символов.
isClient / isCounterpartyБулевы флаги типа контакта.
valuesОбъект с дополнительными полями CRM.
curl -X POST https://api.uptimo.cloud/user-api/v1/contacts/persons \
  -H "Authorization: Bearer upt_..." \
  -H "Content-Type: application/json" \
  -d '{
    "legalStatus": "individual",
    "firstName": "Иван",
    "lastName": "Петров",
    "email": "ivan@example.com",
    "phone": "+79990000000",
    "isClient": true,
    "isCounterparty": false,
    "values": {
      "source": "site-form"
    }
  }'

Сделки

Метод создаёт карточку сделки на указанной доске. Без listId и ответственного сделка попадает в колонку «Неразобранное». Если передать responsibleUserId без listId, сделка попадёт в первый обычный этап доски.

titleНазвание сделки, обязательно, до 500 символов.
descriptionОписание, до 20 000 символов.
responsibleUserIdID исполнителя Uptimo. Должен быть владельцем или участником проекта.
listIdUUID колонки. Если не передать, сработает логика этапа по ответственному.
amountRubСумма в рублях от 0 до 2 000 000 000, округляется до целого.
crmPersonId / crmCompanyIdUUID контакта или компании CRM, принадлежащие владельцу токена.
curl -X POST https://api.uptimo.cloud/user-api/v1/deals/boards/BOARD_ID/cards \
  -H "Authorization: Bearer upt_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Заявка с сайта",
    "description": "Клиент оставил форму обратной связи",
    "amountRub": 150000,
    "responsibleUserId": 12,
    "crmPersonId": "PERSON_UUID"
  }'

Задачи канбана

Метод создаёт задачу на доске канбана. Без listId и ответственного задача попадает в «Неразобранное». С assignedUserId без listId — в первый обычный этап.

titleНазвание задачи, обязательно, до 500 символов.
descriptionОписание, до 20 000 символов.
assignedUserIdID ответственного. Должен быть владельцем доски или участником команды.
dueDateСрок задачи в ISO 8601. Некорректная дата вернёт 400.
listIdUUID колонки канбана. Если не передать, сработает логика этапа.
curl -X POST https://api.uptimo.cloud/user-api/v1/kanban/boards/BOARD_ID/cards \
  -H "Authorization: Bearer upt_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Позвонить клиенту",
    "description": "Уточнить детали заявки",
    "assignedUserId": 12,
    "dueDate": "2026-12-31T12:00:00.000Z"
  }'

Коды ответов

201Объект создан. В ответе возвращается созданная карточка или контакт.
400Некорректные данные или бизнес-ошибка: колонка, сумма, дата, контакт.
401Нет заголовка Authorization, токен не начинается с upt_ или токен неверный.
403Нет доступа к доске, проекту или ответственному пользователю.
404Запрошенный объект не найден или недоступен текущему владельцу токена.