> ## Documentation Index
> Fetch the complete documentation index at: https://strattumai.mintlify.site/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

<CardGroup cols={2}>
  <Card title="Conta Airtable" icon="table">
    Acesso à conta Airtable com as bases que você quer sincronizar.
  </Card>

  <Card title="Personal Access Token" icon="key">
    Um Personal Access Token (PAT) com os escopos de leitura. O passo a passo está abaixo.
  </Card>
</CardGroup>

## Configuração

<Steps>
  <Step title="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`.
  </Step>

  <Step title="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).
  </Step>

  <Step title="Dê acesso às bases">
    Em **Access**, adicione as bases que o conector deve ler. O token só enxerga as bases explicitamente concedidas.
  </Step>

  <Step title="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)
  </Step>

  <Step title="Selecione bases e tabelas">
    Clique em **Testar Conexão** e, em seguida, escolha as bases e tabelas a sincronizar. Salve o conector.
  </Step>
</Steps>

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

<CardGroup cols={2}>
  <Card title="Guia de desenvolvimento local" icon="terminal" href="/data-pipelines/local-development">
    Configure o ambiente local completo com Prefect, worker e Docker Compose.
  </Card>

  <Card title="Quickstart — Data Pipelines" icon="rocket" href="/data-pipelines/quickstart">
    Ative conectores via Console strattum.ai sem precisar de ambiente local.
  </Card>
</CardGroup>