Crear un Registro

Crea un nuevo registro (tarea) en Blue con campos personalizados opcionales, etiquetas y asignaciones.

Crear un Registro

La mutación createTodo permite crear nuevos registros en Blue con opciones de configuración completas, incluidos campos personalizados, etiquetas, asignaciones y más. Los registros se pueden crear en listas específicas o colocarse automáticamente en la lista predeterminada.

Ejemplo Básico

Crea un registro simple con solo un título:

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

Ejemplo Avanzado

Crea un registro con todas las opciones disponibles:

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
    }
  }
}

Parámetros de Entrada

CreateTodoInput

Parámetro	Tipo	Requerido	Descripción
`todoListId`	String	No	ID de la lista de tareas a la que se añadirá el registro. Si no se proporciona, usa la primera lista de tareas en el proyecto
`title`	String!	✅ Sí	Título del registro (requerido)
`position`	Float	No	Posición personalizada en la lista. Si no se proporciona, usa el parámetro de colocación
`placement`	CreateTodoInputPlacement	No	Dónde colocar el registro si no se especifica la posición (SUPERIOR o INFERIOR)
`startedAt`	DateTime	No	Fecha/hora de inicio para el registro
`duedAt`	DateTime	No	Fecha/hora de vencimiento para el registro
`notify`	Boolean	No	Si se deben enviar notificaciones para esta creación de registro
`description`	String	No	Contenido de descripción HTML (será sanitizado)
`assigneeIds`	[String!]	No	Array de IDs de usuarios para asignar a este registro
`checklists`	[CreateChecklistWithoutTodoInput!]	No	Array de listas de verificación a crear con el registro
`customFields`	[CreateTodoInputCustomField]	No	Array de valores de campos personalizados
`tags`	[CreateTodoTagInput!]	No	Array de etiquetas para adjuntar al registro

Valores de CreateTodoInputPlacement

Valor	Descripción
`TOP`	Colocar en la parte superior de la lista (posición más alta)
`BOTTOM`	Colocar en la parte inferior de la lista (posición más baja)

CreateTodoTagInput

Parámetro	Tipo	Requerido	Descripción
`id`	String	No*	ID de la etiqueta existente a conectar
`title`	String	No*	Título de la etiqueta (crea nueva si no existe)
`color`	String	No	Color hexadecimal para la nueva etiqueta (por defecto es #4a9fff)

*Nota: Debe proporcionar id (para etiqueta existente) O title (para crear/encontrar por título)

CreateTodoInputCustomField

Parámetro	Tipo	Requerido	Descripción
`customFieldId`	String	No	ID del campo personalizado
`value`	String	No	Valor para el campo personalizado (ver guía de formato a continuación)

CreateChecklistWithoutTodoInput

Parámetro	Tipo	Requerido	Descripción
`title`	String!	✅ Sí	Título de la lista de verificación
`position`	Float	No	Posición de la lista de verificación dentro del registro

Formatos de Valores de Campos Personalizados

Al establecer valores de campos personalizados, utiliza estos formatos según el tipo de campo:

Tipo de Campo	Formato	Ejemplo
`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"`

Campos de Respuesta

La mutación devuelve un objeto Todo con detalles completos del registro:

Campo	Tipo	Descripción
`id`	String!	Identificador único para el registro
`uid`	String!	Identificador único alternativo
`title`	String!	Título del registro
`position`	Float!	Posición en la lista
`done`	Boolean!	Estado de finalización
`startedAt`	DateTime	Fecha/hora de inicio
`duedAt`	DateTime	Fecha/hora de vencimiento
`todoList`	TodoList	Detalles de la lista de tareas asociada
`users`	[User!]	Usuarios asignados
`tags`	[Tag!]	Etiquetas asociadas
`checklists`	[Checklist!]	Listas de verificación asociadas
`customFields`	[CustomFieldValue!]	Valores de campos personalizados

Permisos Requeridos

Los usuarios deben tener acceso adecuado al proyecto para crear registros:

Nivel de Acceso	Puede Crear Registros
`OWNER`	✅ Sí
`ADMIN`	✅ Sí
`MEMBER`	✅ Sí
`CLIENT`	✅ Sí
`COMMENT_ONLY`	❌ No
`VIEW_ONLY`	❌ No

La mutación requiere que el nivel de acceso del usuario al proyecto sea OWNER, ADMIN, MEMBER, o CLIENT. Los usuarios con roles VIEW_ONLY o COMMENT_ONLY no pueden crear registros.

Respuestas de Error

ProjectNotFoundError

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

Cuándo: No hay contexto de proyecto disponible para el usuario.

TodoListCreateTodoLimitError

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

Cuándo: La lista de tareas ya contiene 100,000 registros (límite máximo).

TodoListNotFoundError

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

Cuándo: La todoListId especificada no existe o el usuario carece de acceso.

CustomFieldValueParseError

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

Cuándo: El valor del campo personalizado no pasa la validación (por ejemplo, teléfono inválido, calificación fuera de rango).

Notas Importantes

Rendimiento

Cada lista de tareas puede contener hasta 100,000 registros
Crear registros activa múltiples procesos en segundo plano (webhooks, automatizaciones, indexación de búsqueda)
Las operaciones por lotes son más eficientes que crear registros uno a la vez

Lógica de Negocios

Manejo de Posición: La posición predeterminada es 65535.0 cuando no se especifica position ni placement
Lógica de Fechas:
- Si solo se proporciona duedAt, startedAt se establece al comienzo de ese día
- Si solo se proporciona startedAt, duedAt se establece al mismo valor
Creación de Etiquetas: Se crean automáticamente nuevas etiquetas si no existen con el título/color especificado
Selección de Lista: Si no se proporciona todoListId, se utiliza la primera lista de tareas en el proyecto

Efectos Secundarios

Crear un registro activa:

Creación de entrada en el registro de actividad
Notificaciones de webhook
Actualizaciones de índice de búsqueda
Ejecución de reglas de automatización (si están configuradas)
Notificaciones por correo electrónico/push (si notify: true)
Cálculos de campos personalizados de fórmula y duración de tiempo
Actualizaciones de análisis y gráficos

Puntos Finales Relacionados

Listar Registros: Consultar tareas para recuperar registros existentes
Actualizar Registro: Usar la mutación updateTodo para modificar registros
Listar Campos Personalizados: Consultar para obtener IDs de campos personalizados disponibles
Listar Etiquetas: Consultar para obtener IDs de etiquetas existentes
Listar Listas de Tareas: Consultar para obtener IDs de listas de tareas disponibles