---

Visión General

Los proyectos son la unidad organizativa central en Blue. Contienen listas, tareas, campos personalizados, automatizaciones y todos los demás datos relacionados con el trabajo. Los proyectos pertenecen a empresas y tienen sus propios sistemas de permisos, plantillas y configuraciones.

Operaciones Disponibles

Operaciones Básicas de Proyectos

Operación	Descripción	Enlace
Create Project	Crear un nuevo proyecto o desde una plantilla	View Details →
List Projects	Consultar y filtrar proyectos	View Details →
Delete Project	Eliminar un proyecto de forma permanente	View Details →
Archive Project	Archivar/desarchivar proyectos	View Details →
Rename Project	Actualizar el nombre y el slug del proyecto	View Details →
Copy Project	Duplicar un proyecto existente	View Details →

Componentes del Proyecto

Componente	Descripción	Enlace
Lists	Gestionar listas de tareas dentro de proyectos	View Details →
Templates	Trabajar con plantillas de proyectos	View Details →
Activity	Rastrear la actividad y los cambios del proyecto	View Details →

Conceptos Clave

Estructura del Proyecto

• Los proyectos pertenecen a empresas
• Cada proyecto puede tener múltiples listas
• Las listas contienen tareas
• Los proyectos soportan campos personalizados, etiquetas y automatizaciones

Modelo de Permisos

Los proyectos tienen un sistema de permisos de múltiples niveles:

Nivel	Permisos
OWNER	Full control, can delete project
ADMIN	Manage project settings, users, and content
MEMBER	Create and edit content
CLIENT	Limited edit access
VIEW_ONLY	Read-only access
COMMENT_ONLY	Can only comment

Categorías de Proyectos

Los proyectos pueden ser categorizados para una mejor organización:

• CRM
• CRUZ_FUNCIONAL
• ÉXITO_DEL_CLIENTE
• DISEÑO
• INGENIERÍA
• GENERAL (predeterminado)
• RRHH
• TI
• MARKETING
• OPERACIONES
• PERSONAL
• ADQUISICIONES
• PRODUCTO
• VENTAS

Patrones Comunes

Creando un Proyecto Básico

mutation CreateProject {
  createProject(input: {
    name: "Q1 Marketing Campaign"
    companyId: "company-123"
    category: MARKETING
  }) {
    id
    name
    slug
  }
}

Consultando Proyectos con Filtros

query GetProjects {
  projectList(
    filter: {
      companyIds: ["company-123"]
      isArchived: false
      categories: [MARKETING, SALES]
    }
    sort: [{ field: updatedAt, direction: DESC }]
    take: 20
  ) {
    items {
      id
      name
      category
      todosCount
      todosDoneCount
    }
    pageInfo {
      hasNextPage
      total
    }
  }
}

Nota: La consulta projectList es el enfoque recomendado para consultar proyectos. Existe una consulta heredada projects, pero no debe usarse para nuevas implementaciones.

Gestionando Listas de Proyectos

# Get all lists in a project
query GetProjectLists {
  todoLists(projectId: "project-123") {
    id
    title
    position
    todosCount
  }
}

# Create a new list
mutation CreateList {
  createTodoList(input: {
    projectId: "project-123"
    title: "To Do"
    position: 1.0
  }) {
    id
    title
  }
}

Mejores Prácticas

1. Nomenclatura de Proyectos

   • Utilizar nombres claros y descriptivos
   • Evitar caracteres especiales que puedan afectar los slugs
   • Mantener los nombres por debajo de 50 caracteres

2. Gestión de Permisos

   • Comenzar con permisos mínimos
   • Usar el rol CLIENTE para partes interesadas externas
   • Auditar regularmente el acceso a los proyectos

3. Organización

   • Utilizar categorías para agrupar proyectos similares
   • Archivar proyectos completados en lugar de eliminarlos
   • Utilizar plantillas para tipos de proyectos repetitivos

4. Rendimiento

   • Utilizar paginación para listas de proyectos grandes
   • Filtrar por estado activo/archivado
   • Limitar el número de listas por proyecto (máx. 50)

Manejo de Errores

Errores comunes que podrías encontrar:

Código de Error	Descripción	Solución
PROJECT_NOT_FOUND	El proyecto no existe o no hay acceso	Verify project ID and permissions
COMPANY_NOT_FOUND	La empresa no existe	Check company ID
FORBIDDEN	Permisos insuficientes	Ensure proper role level
BAD_USER_INPUT	Error de validación (por ejemplo, nombre demasiado largo)	Check input validation requirements

Recursos Relacionados

• API de Registros - Gestión de tareas/registros dentro de proyectos
• API de Campos Personalizados - Agregar campos personalizados a proyectos
• API de Automatizaciones - Configuración de automatizaciones de proyectos
• API de Usuarios - Gestión de usuarios y permisos de proyectos