Pular para o conteúdo principal

Como um Board Funciona

Esta página explica o modelo de dados de board e a mecânica por trás de cada operação de board: como tables e rows se relacionam, como colunas e células tipadas funcionam, como rich-text e anexos de arquivos se comportam, como comentários em rows e visibilidade são delimitados, como a autenticação de row funciona, e como filtragem, ordenação e exports são avaliados. Para uma orientação rápida e exemplos prontos para copiar e colar, comece pela introdução de Boards.

O modelo de dados​

Boards formam uma hierarquia de três níveis:

  • Board — o container de nível superior. Um board agrupa tables relacionadas.
  • Table — pertence a um board. Uma table define um conjunto de colunas e contém rows.
  • Row — um único registro em uma table. Uma row carrega um valor de célula para cada coluna, além de uma descrição em markdown e comentários opcionais.
Board
└── Table (columns: Name, Status, Owner, Notes…)
    ├── Row #1  (cells: "Acme", "In progress", …)
    ├── Row #2
    └── Row #3

Cada row tem dois identificadores: um _id interno (um object id de 24 caracteres usado na maioria dos endpoints) e um número de row amigável (o pequeno número sequencial mostrado no grid, por exemplo 42). Você pode buscar uma row por qualquer um dos dois.

Colunas e células​

Cada coluna de uma table tem um columnId, um label e um type. Os tipos de coluna incluem status, dropdown, labels, checkbox, text, paragraph, link, date, email, phone, website, number, location e users. Colunas status/dropdown/labels expõem suas options selecionáveis (cada uma com um optionId, label e cor); opções de status também carregam um statusGroup de TODO, IN_PROGRESS ou DONE.

Quando você lê uma row, recebe um array columns de células, cada uma indexada por columnId com um value. Células de link referenciam outras rows; células de lookup trazem valores extraídos de rows vinculadas.

Quando você escreve uma row, passa columns: [{ columnId, value }]. Alguns tipos de coluna têm semânticas de valor especiais:

  • Colunas de link recebem um array de strings de row-id. Passar [] limpa o link. As rows vinculadas devem existir na table de destino e no mesmo workspace.
  • Colunas de rich-text (paragraph) recebem uma string em markdown. O conteúdo é populado de forma assíncrona, então pode aparecer um instante após o retorno da escrita.

Lendo boards, tables e rows​

  • List boards — retorna cada board que seu token pode acessar, com um q opcional para filtrar por nome ou descrição.
  • Get a board / List tables / Get a table — explore a estrutura de um board e leia as definições de coluna de uma table.
  • List rows — retorna as rows de uma table. Suporta três query parameters que se combinam: q (busca case-insensitive nas colunas pesquisáveis), filter (um filtro JSON estruturado, abaixo) e sort.
  • Get a row — pelo id interno, ou pelo número da row usando o endpoint dedicado de número de row.

Filtrando rows​

O query parameter filter é uma string JSON com este formato:

{
  "match": "and",
  "conditions": [
    { "column_id": "<columnId>", "operator": "contains", "value": "acme" },
    { "column_id": "<statusColumnId>", "operator": "includes", "value": ["<optionId>"] }
  ]
}
  • match é and (padrão) ou or.
  • conditions é um array de até 20 condições. Cada uma nomeia um column_id, um operator e (para a maioria dos operadores) um value.
  • Os operadores válidos dependem do tipo da coluna:
    • 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 (os valores são option ids).
    • Checkbox: equals, not_equals, is_empty, is_not_empty.
    • Date: equals, before, after, between (o valor é um par [startISO, endISO]), além de operadores relativos sem valor como today, last_7_days, current_month, e is_empty / is_not_empty.

Um column id desconhecido ou um operador que não se aplica ao tipo da coluna retorna um 400.

Ordenando rows​

O query parameter sort é uma lista separada por vírgulas de entradas columnId:direction, onde a direção é asc (padrão) ou desc:

?sort=statusColumnId:asc,createdColumnId:desc
observação

A query string HTTP sort usa o formato columnId:direction. Alguns exemplos do SDK expressam a ordenação como um array de objetos { column, dir } — ambos descrevem a mesma ordenação, apenas em formatos diferentes.

Escrevendo rows​

  • Create a row — POST com uma description opcional em markdown e um array columns (que pode estar vazio). Retorna a row criada.
  • Update a row — PATCH com um array columns não vazio. Apenas as colunas que você envia são alteradas; o restante permanece intocado.
  • Delete a row — remove a row permanentemente.

Bots agem como usuários: uma ação que seu token executa pode disparar as automações do board, então escritas programáticas se integram aos mesmos workflows que seu time usa.

Descrição de row e colunas de rich-text​

Tanto a descrição de uma row quanto qualquer coluna de rich-text são markdown. Leia-as com o endpoint GET …/md correspondente, que retorna { "content": "…" }.

Para escrevê-las, faça POST de uma operation de replace, append ou prepend mais o content em markdown. Essas escritas são processadas de forma assíncrona e retornam HTTP 202 Accepted — o conteúdo é aplicado um instante depois.

Anexos de arquivos​

Células de coluna de arquivo e anexos de comentários podem ser baixados diretamente. Os endpoints de download transmitem os bytes brutos do arquivo (com os headers apropriados de content-type e nome de arquivo) em vez de retornar uma URL assinada.

Comentários em rows​

Rows suportam comentários encadeados, cada um com uma visibilidade:

  • internal — visível apenas para membros do workspace.
  • external — visível para todos com acesso à row, incluindo convidados.

List comments suporta paginação por cursor (after / before) e um filtro de visibility de all (padrão), internal ou external. Create a comment recebe content em HTML e uma visibility que assume internal por padrão.

Autenticando uma row​

Tables podem atuar como um armazenamento leve de credenciais. O endpoint authenticate recebe uma coluna de identificador + valor e uma coluna de senha + valor, e retorna a row correspondente (com as colunas de senha mascaradas) quando as credenciais são válidas:

  • 400 — nenhuma row corresponde ao identificador.
  • 401 — a senha está incorreta.

Isso permite que você construa verificações estilo login contra uma table de board sem expor a célula de senha.

Exportando a view de uma table​

O endpoint export renderiza a view de uma table para um arquivo. Você faz POST do viewId e de um format — CSV, XLSX, JSON, MARKDOWN, HTML, PDF, ZIP ou ICS — junto com filtros opcionais, ordenação, seleção de colunas e opções por formato.

Exports rodam de forma síncrona ou assíncrona dependendo do tamanho:

  • Exports pequenos retornam 200 OK com o arquivo renderizado inline (formatos de texto como UTF-8, formatos binários codificados em base64).
  • Exports grandes (e PDF/ZIP, que são sempre assíncronos, ou qualquer request com forceAsync: true) retornam 202 Accepted com um asyncJob que descreve o job e, quando pronto, uma downloadUrl. Você também pode fornecer uma webhookUrl para ser notificado quando o arquivo estiver pronto.

Autenticação e escopo​

Endpoints de board aceitam um Personal Access Token completo (cp_pat_) ou uma API key de integração (cp_key_), e exigem o escopo access_boards. Veja Autenticação para tipos de token e Tratamento de Erros para o formato padrão de erro.

Referência​