Создание записи

Создайте новую запись (дело) в Blue с необязательными пользовательскими полями, тегами и назначениями.

Создание записи

Мутация createTodo позволяет создавать новые записи в Blue с обширными параметрами настройки, включая пользовательские поля, теги, назначения и многое другое. Записи могут быть созданы в конкретных списках или автоматически помещены в список по умолчанию.

Простой пример

Создайте простую запись с только заголовком:

mutation CreateRecord {
  createTodo(
    input: {
      title: "New Task"
    }
  ) {
    id
    title
    position
  }
}

Расширенный пример

Создайте запись со всеми доступными опциями:

mutation CreateRecordAdvanced {
  createTodo(
    input: {
      todoListId: "clm4n8qwx000008l0g4oxdqn7"
      title: "Product Launch Planning"
      placement: TOP
      description: "<p>Complete product launch preparation including marketing materials and documentation.</p>"
      startedAt: "2025-01-15T09:00:00Z"
      duedAt: "2025-02-01T17:00:00Z"
      notify: true
      assigneeIds: ["user_123", "user_456"]
      tags: [
        { id: "tag_existing_123" }
        { title: "Priority", color: "#ff4b4b" }
        { title: "Marketing" }
      ]
      customFields: [
        {
          customFieldId: "cf_budget_123"
          value: "50000 USD"
        }
        {
          customFieldId: "cf_status_456"
          value: "In Progress"
        }
      ]
      checklists: [
        {
          title: "Pre-launch Checklist"
          position: 1
        }
      ]
    }
  ) {
    id
    uid
    title
    position
    startedAt
    duedAt
    todoList {
      id
      title
    }
    users {
      id
      fullName
    }
    tags {
      id
      title
      color
    }
  }
}

Входные параметры

CreateTodoInput

Параметр	Тип	Обязательный	Описание
`todoListId`	String	Нет	ID списка дел, в который нужно добавить запись. Если не указано, используется первый список дел в проекте
`title`	String!	✅ Да	Заголовок записи (обязательный)
`position`	Float	Нет	Пользовательская позиция в списке. Если не указано, используется параметр размещения
`placement`	CreateTodoInputPlacement	Нет	Где разместить запись, если позиция не указана (ВВЕРХУ или ВНИЗУ)
`startedAt`	DateTime	Нет	Дата/время начала для записи
`duedAt`	DateTime	Нет	Дата/время окончания для записи
`notify`	Boolean	Нет	Нужно ли отправлять уведомления о создании этой записи
`description`	String	Нет	HTML-содержимое описания (будет очищено)
`assigneeIds`	[String!]	Нет	Массив ID пользователей, которым нужно назначить эту запись
`checklists`	[CreateChecklistWithoutTodoInput!]	Нет	Массив контрольных списков для создания с записью
`customFields`	[CreateTodoInputCustomField]	Нет	Массив значений пользовательских полей
`tags`	[CreateTodoTagInput!]	Нет	Массив тегов для прикрепления к записи

Значения CreateTodoInputPlacement

Значение	Описание
`TOP`	Разместить в верхней части списка (высшая позиция)
`BOTTOM`	Разместить в нижней части списка (низшая позиция)

CreateTodoTagInput

Параметр	Тип	Обязательный	Описание
`id`	String	Нет*	ID существующего тега для подключения
`title`	String	Нет*	Заголовок тега (создает новый, если не существует)
`color`	String	Нет	Шестнадцатеричный цвет для нового тега (по умолчанию #4a9fff)

*Примечание: Вы должны предоставить либо id (для существующего тега), ЛИБО title (для создания/поиска по заголовку)

CreateTodoInputCustomField

Параметр	Тип	Обязательный	Описание
`customFieldId`	String	Нет	ID пользовательского поля
`value`	String	Нет	Значение для пользовательского поля (см. руководство по формату ниже)

CreateChecklistWithoutTodoInput

Параметр	Тип	Обязательный	Описание
`title`	String!	✅ Да	Заголовок контрольного списка
`position`	Float	Нет	Позиция контрольного списка внутри записи

Форматы значений пользовательских полей

При установке значений пользовательских полей используйте эти форматы в зависимости от типа поля:

Тип поля	Формат	Пример
`CHECKBOX`	"true", "1", or "checked" for checked	`"true"`
`COUNTRY`	Country name or ISO code	`"United States"` or `"US"`
`CURRENCY`	Amount with optional currency	`"50000 USD"`
`DATE`	YYYY-MM-DD or date range	`"2025-01-15"` or `"2025-01-15,2025-01-20"`
`NUMBER`	Numeric value	`"42"`
`PERCENT`	Numeric value (% optional)	`"75"` or `"75%"`
`RATING`	Numeric value within range	`"4"` (if max is 5)
`PHONE`	International phone format	`"+1234567890"`
`SELECT_SINGLE`	Custom field option ID	`"option_123"`
`SELECT_MULTI`	Comma-separated option IDs	`"option_1,option_2"`
`LOCATION`	Latitude,longitude	`"40.7128,-74.0060"`
`EMAIL`	Valid email address	`"user@example.com"`
`URL`	Valid URL	`"https://example.com"`
`TEXT`	Plain text value	`"Any text content"`

Поля ответа

Мутация возвращает объект Todo с полными деталями записи:

Поле	Тип	Описание
`id`	String!	Уникальный идентификатор записи
`uid`	String!	Альтернативный уникальный идентификатор
`title`	String!	Заголовок записи
`position`	Float!	Позиция в списке
`done`	Boolean!	Статус завершения
`startedAt`	DateTime	Дата/время начала
`duedAt`	DateTime	Дата/время окончания
`todoList`	TodoList	Подробности связанного списка дел
`users`	[User!]	Назначенные пользователи
`tags`	[Tag!]	Связанные теги
`checklists`	[Checklist!]	Связанные контрольные списки
`customFields`	[CustomFieldValue!]	Значения пользовательских полей

Необходимые разрешения

Пользователи должны иметь соответствующий доступ к проекту для создания записей:

Уровень доступа	Может создавать записи
`OWNER`	✅ Да
`ADMIN`	✅ Да
`MEMBER`	✅ Да
`CLIENT`	✅ Да
`COMMENT_ONLY`	❌ Нет
`VIEW_ONLY`	❌ Нет

Мутация требует, чтобы уровень доступа пользователя к проекту был OWNER, ADMIN, MEMBER или CLIENT. Пользователи с ролями VIEW_ONLY или COMMENT_ONLY не могут создавать записи.

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

ProjectNotFoundError

{
  "errors": [{
    "message": "Project was not found.",
    "extensions": {
      "code": "PROJECT_NOT_FOUND"
    }
  }]
}

Когда: Нет доступного контекста проекта для пользователя.

TodoListCreateTodoLimitError

{
  "errors": [{
    "message": "Todo list has reached the maximum number of todos.",
    "extensions": {
      "code": "TODO_LIST_CREATE_TODO_LIMIT_ERROR"
    }
  }]
}

Когда: Список дел уже содержит 100,000 записей (максимальный лимит).

TodoListNotFoundError

{
  "errors": [{
    "message": "Todo list was not found.",
    "extensions": {
      "code": "TODO_LIST_NOT_FOUND"
    }
  }]
}

Когда: Указанный todoListId не существует или у пользователя нет доступа.

CustomFieldValueParseError

{
  "errors": [{
    "message": "Invalid phone number format",
    "extensions": {
      "code": "CUSTOM_FIELD_VALUE_PARSE_ERROR"
    }
  }]
}

Когда: Значение пользовательского поля не прошло валидацию (например, неверный телефон, рейтинг вне диапазона).

Важные заметки

Производительность

Каждый список дел может содержать до 100,000 записей
Создание записей запускает несколько фоновых процессов (вебхуки, автоматизации, индексация поиска)
Пакетные операции более эффективны, чем создание записей по одной

Логика бизнеса

Обработка позиции: Позиция по умолчанию - 65535.0, когда ни position, ни placement не указаны
Логика даты:
- Если указано только duedAt, то startedAt устанавливается на начало этого дня
- Если указано только startedAt, то duedAt устанавливается на то же значение
Создание тегов: Новые теги автоматически создаются, если они не существуют с указанным заголовком/цветом
Выбор списка: Если todoListId не указано, используется первый список дел в проекте

Побочные эффекты

Создание записи вызывает:

Создание записи в журнале активности
Уведомления вебхуков
Обновления индекса поиска
Выполнение правил автоматизации (если настроено)
Уведомления по электронной почте/Push (если notify: true)
Расчеты пользовательских полей формул и временных интервалов
Обновления аналитики и графиков

Связанные конечные точки

Список записей: Запрос дел для получения существующих записей
Обновить запись: Используйте мутацию updateTodo для изменения записей
Список пользовательских полей: Запрос для получения доступных ID пользовательских полей
Список тегов: Запрос для получения существующих ID тегов
Список списков дел: Запрос для получения доступных ID списков дел