Saltar al contenido principal

Cómo funciona un Board

Esta página explica el modelo de datos de los boards y la mecánica detrás de cada operación: cómo se relacionan las tablas y las filas, cómo funcionan las columnas tipadas y las celdas, cómo se comportan el texto enriquecido y los archivos adjuntos, cómo se delimitan los comentarios de fila y su visibilidad, cómo funciona la autenticación de filas, y cómo se evalúan los filtros, el ordenamiento y las exportaciones. Para una orientación rápida y ejemplos listos para copiar y pegar, comienza con la introducción a Boards.

El modelo de datos​

Los Boards forman una jerarquía de tres niveles:

  • Board: el contenedor de nivel superior. Un board agrupa tablas relacionadas.
  • Tabla: pertenece a un board. Una tabla define un conjunto de columnas y contiene filas.
  • Fila: un único registro en una tabla. Una fila lleva un valor de celda por cada columna, además de una descripción en markdown y comentarios opcionales.
Board
└── Table (columns: Name, Status, Owner, Notes…)
    ├── Row #1  (cells: "Acme", "In progress", …)
    ├── Row #2
    └── Row #3

Cada fila tiene dos identificadores: un _id interno (un object id de 24 caracteres que se usa en la mayoría de los endpoints) y un número de fila legible para humanos (el pequeño número secuencial que se muestra en la cuadrícula, por ejemplo 42). Puedes obtener una fila por cualquiera de los dos.

Columnas y celdas​

Cada columna de una tabla tiene un columnId, un label y un type. Los tipos de columna incluyen status, dropdown, labels, checkbox, text, paragraph, link, date, email, phone, website, number, location y users. Las columnas status/dropdown/labels exponen sus options seleccionables (cada una con un optionId, label y color); las opciones de status también llevan un statusGroup de TODO, IN_PROGRESS o DONE.

Cuando lees una fila obtienes un array columns de celdas, cada una identificada por columnId con un value. Las celdas link referencian otras filas; las celdas lookup muestran valores extraídos de filas vinculadas.

Cuando escribes una fila pasas columns: [{ columnId, value }]. Algunos tipos de columna tienen una semántica de valor especial:

  • Columnas link toman un array de cadenas de row-id. Pasar [] borra el vínculo. Las filas vinculadas deben existir en la tabla de destino y en el mismo workspace.
  • Columnas de texto enriquecido (paragraph) toman una cadena en markdown. El contenido se carga de forma asíncrona, por lo que puede aparecer un instante después de que la escritura retorne.

Lectura de boards, tablas y filas​

  • List boards: devuelve cada board al que tu token puede acceder, con un q opcional para filtrar por nombre o descripción.
  • Get a board / List tables / Get a table: profundiza en la estructura de un board y lee las definiciones de columna de una tabla.
  • List rows: devuelve las filas de una tabla. Admite tres parámetros de consulta que se combinan entre sí: q (búsqueda sin distinción de mayúsculas/minúsculas en las columnas buscables), filter (un filtro JSON estructurado, más abajo) y sort.
  • Get a row: por id interno, o por número de fila usando el endpoint dedicado de número de fila.

Filtrado de filas​

El parámetro de consulta filter es una cadena JSON con esta forma:

{
  "match": "and",
  "conditions": [
    { "column_id": "<columnId>", "operator": "contains", "value": "acme" },
    { "column_id": "<statusColumnId>", "operator": "includes", "value": ["<optionId>"] }
  ]
}
  • match es and (predeterminado) u or.
  • conditions es un array de hasta 20 condiciones. Cada una nombra un column_id, un operator y (para la mayoría de los operadores) un value.
  • Los operadores válidos dependen del tipo de la columna:
    • Text: equals, not_equals, contains, not_contains, starts_with, ends_with, is_empty, is_not_empty.
    • Number: equals, not_equals, gt, gte, lt, lte, includes, not_includes, is_empty, is_not_empty.
    • Select (status / dropdown / labels): equals, not_equals, includes, not_includes, is_empty, is_not_empty (los valores son ids de opción).
    • Checkbox: equals, not_equals, is_empty, is_not_empty.
    • Date: equals, before, after, between (el valor es un par [startISO, endISO]), además de operadores relativos sin valor como today, last_7_days, current_month, y is_empty / is_not_empty.

Un id de columna desconocido o un operador que no aplica al tipo de columna devuelve un 400.

Ordenamiento de filas​

El parámetro de consulta sort es una lista separada por comas de entradas columnId:direction, donde direction es asc (predeterminado) o desc:

?sort=statusColumnId:asc,createdColumnId:desc
nota

La cadena de consulta HTTP sort usa la forma columnId:direction. Algunos ejemplos del SDK expresan el ordenamiento como un array de objetos { column, dir }: ambos describen el mismo orden, solo que con formas distintas.

Escritura de filas​

  • Create a row: POST con una description opcional en markdown y un array columns (que puede estar vacío). Devuelve la fila creada.
  • Update a row: PATCH con un array columns no vacío. Solo cambian las columnas que envías; el resto queda intacto.
  • Delete a row: elimina la fila de forma permanente.

Los bots actúan como usuarios: una acción que realiza tu token puede disparar las automatizaciones del board, así que las escrituras programáticas se integran con los mismos flujos de trabajo que usa tu equipo.

Descripción de fila y columnas de texto enriquecido​

Tanto la descripción de una fila como cualquier columna de texto enriquecido son markdown. Léelas con el endpoint GET …/md correspondiente, que devuelve { "content": "…" }.

Para escribirlas, haz POST de una operation de replace, append o prepend más el content en markdown. Estas escrituras se procesan de forma asíncrona y devuelven HTTP 202 Accepted: el contenido se aplica un instante después.

Archivos adjuntos​

Las celdas de columnas de archivo y los adjuntos de comentarios se pueden descargar directamente. Los endpoints de descarga transmiten los bytes crudos del archivo (con los headers de content-type y nombre de archivo correspondientes) en lugar de devolver una URL firmada.

Comentarios de fila​

Las filas admiten comentarios en hilo, cada uno con una visibilidad:

  • internal: visible solo para los miembros del workspace.
  • external: visible para todos con acceso a la fila, incluidos los invitados.

List comments admite paginación por cursor (after / before) y un filtro de visibility de all (predeterminado), internal o external. Create a comment toma content en HTML y una visibility que por defecto es internal.

Autenticación de una fila​

Las tablas pueden funcionar como un almacén ligero de credenciales. El endpoint authenticate toma una columna identificadora + valor y una columna de contraseña + valor, y devuelve la fila coincidente (con las columnas de contraseña enmascaradas) cuando las credenciales son válidas:

  • 400: ninguna fila coincide con el identificador.
  • 401: la contraseña es incorrecta.

Esto te permite construir verificaciones de tipo inicio de sesión contra una tabla de un board sin exponer la celda de contraseña.

Exportación de una vista de tabla​

El endpoint export renderiza una vista de tabla a un archivo. Haces POST del viewId y un format (CSV, XLSX, JSON, MARKDOWN, HTML, PDF, ZIP o ICS) junto con filtros, ordenamiento, selección de columnas y opciones por formato opcionales.

Las exportaciones se ejecutan de forma síncrona o asíncrona según el tamaño:

  • Las exportaciones pequeñas devuelven 200 OK con el archivo renderizado en línea (los formatos de texto como UTF-8, los formatos binarios codificados en base64).
  • Las exportaciones grandes (y PDF/ZIP, que siempre son asíncronas, o cualquier solicitud con forceAsync: true) devuelven 202 Accepted con un asyncJob que describe el trabajo y, una vez listo, un downloadUrl. También puedes proporcionar un webhookUrl para que te notifiquen cuando el archivo esté listo.

Autenticación y alcance​

Los endpoints de board aceptan un Personal Access Token completo (cp_pat_) o una clave de API de integración (cp_key_), y requieren el alcance access_boards. Consulta Autenticación para los tipos de token y Manejo de errores para la forma estándar de error.

Referencia​