> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strattum.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Airtable

> Configure o conector Airtable para sincronizar bases, tabelas e registros com a plataforma strattum.ai.

O conector Airtable sincroniza registros de bases do Airtable com a infraestrutura strattum.ai. Você seleciona as bases e tabelas, e cada registro aparece no Data Catalog com os campos definidos na tabela de origem.

## Capacidades

* Sincroniza tabelas específicas das bases que você seleciona.
* Carga incremental por polling de webhook (modelo pull, sem necessidade de URL pública).
* Sincronização de comentários de registro, ativada automaticamente quando o escopo `data.recordComments:read` está presente no token.
* Cliente HTTP com rate limiting nativo (5 req/s por base, 50 req/s por token).

## Objetos suportados

| Objeto | O que vem |
| - | - |
| `bases` | Bases às quais o token tem acesso |
| `tables` | Tabelas de cada base selecionada, com seus campos e tipos |
| `records` | Registros das tabelas selecionadas, sincronizados incrementalmente |
| `comments` | Comentários de registro, quando o escopo `data.recordComments:read` está presente |

## Pré-requisitos

> **Conta Airtable**
>
> Acesso à conta Airtable com as bases que você quer sincronizar.

> **Personal Access Token**
>
> Um Personal Access Token (PAT) com os escopos de leitura. O passo a passo está abaixo.

## Configuração

**1. Crie um Personal Access Token**

Acesse [airtable.com/create/tokens](https://airtable.com/create/tokens) e clique em **Create new token**. Dê um nome como `strattum-sync`.

**2. Adicione os escopos de leitura**

No token, habilite os escopos:

```
schema.bases:read
data.records:read
webhook:manage
```

Para sincronizar comentários, adicione também `data.recordComments:read` (Opcional).

**3. Dê acesso às bases**

Em **Access**, adicione as bases que o conector deve ler. O token só enxerga as bases explicitamente concedidas.

**4. Adicione o conector no Console**

No menu lateral do Console, clique em **Conectores → + Nova Conexão** e selecione **Airtable**. Preencha os campos:

* **Nome do Conector** — identificador na lista de conectores (Obrigatório)
* **Personal Access Token (PAT)** — cole o token gerado, no formato `patXXXX...` (Obrigatório)

**5. Selecione bases e tabelas**

Clique em **Testar Conexão** e, em seguida, escolha as bases e tabelas a sincronizar. Salve o conector.

## Autenticação e escopos

A autenticação é por Personal Access Token, enviado como Bearer token em cada requisição.

| Escopo | Obrigatório | Para que serve |
| - | - | - |
| `schema.bases:read` | Obrigatório | Descobrir bases, tabelas e campos |
| `data.records:read` | Obrigatório | Ler os registros das tabelas |
| `webhook:manage` | Obrigatório | Registrar o webhook de polling para carga incremental |
| `data.recordComments:read` | Opcional | Sincronizar comentários de registro |

## Frequência de sync

O conector sincroniza **a cada 15 minutos**. O polling de webhook mantém a latência baixa: cada ciclo lê apenas as mudanças (add, update, remove) acumuladas desde a última leitura.

## Limitações conhecidas

* O token só acessa as bases explicitamente concedidas em **Access** — bases não concedidas ficam invisíveis.
* A sincronização de comentários depende do escopo `data.recordComments:read`; sem ele, comentários não são coletados.
* A API impõe rate limits de 5 req/s por base e 50 req/s por token; bases muito grandes podem levar mais de um ciclo para o backfill inicial.
* Campos calculados e anexos são lidos como os valores retornados pela API, sem download de arquivos binários.

## Troubleshooting

| Sintoma | Causa provável | O que fazer |
| - | - | - |
| Base não aparece para seleção | Base não concedida ao token | Adicione a base em **Access** no Personal Access Token |
| `401 Unauthorized` | Token inválido ou revogado | Gere um novo token com os escopos corretos e atualize o conector |
| Comentários não sincronizam | Escopo `data.recordComments:read` ausente | Adicione o escopo ao token e reconecte |
| Sync lento no primeiro ciclo | Rate limit da base durante o backfill | Aguarde; os próximos ciclos são incrementais e mais rápidos |

## Próximos passos

> **[Guia de desenvolvimento local](https://docs.strattum.ai/data-pipelines/local-development.md)**
>
> Configure o ambiente local completo com Prefect, worker e Docker Compose.

> **[Quickstart — Data Pipelines](https://docs.strattum.ai/data-pipelines/quickstart)**
>
> Ative conectores via Console strattum.ai sem precisar de ambiente local.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.