> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brainchat.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Conectar via API
> Sincronize automaticamente uma tabela com uma fonte externa via REST ou GraphQL.
# Conectar via API
Conecte sua tabela a uma fonte externa (CRM, ERP, sistema próprio) para mantê-la sempre atualizada — sem cópia manual e sem código.
***
## Quando usar
Use a integração via API quando:
* Os dados mudam frequentemente (estoque, preços)
* A fonte de verdade vive em outro sistema (CRM, ERP)
* Você precisa que o Agente de IA leia dados sempre atualizados
* Precisa importar grandes volumes em lotes paginados
Para **Pipefy**, há uma integração nativa mais simples — veja [Sincronizar com Pipefy](/dados/tabelas-pipefy).
***
## Passo a passo
Em **Tabelas**, clique em **Nova Tabela → Conectar via API → Configurar URL manualmente**.
| Campo | Descrição |
| ------------------------------- | ------------------------------------------------------------------- |
| **URL** | Endpoint da API (ex: `https://api.meusistema.com/produtos`) |
| **Método** | `GET` ou `POST` |
| **Headers** | JSON com headers HTTP, normalmente `Authorization` e `Content-Type` |
| **Body Template** (apenas POST) | Corpo da requisição em JSON, com placeholders dinâmicos |
### Placeholders disponíveis no body
| Placeholder | Substituído por |
| ------------ | -------------------------------------------------------- |
| `{{cursor}}` | Cursor de paginação atual |
| `{{since}}` | Timestamp ISO da última sincronização (modo incremental) |
| `{{page}}` | Número da página atual |
| `{{offset}}` | Offset atual |
| Campo | Descrição |
| ----------------- | ------------------------------------------------------------------------------------- |
| **Response Path** | Caminho até o array de registros (ex: `data.items`, `results`, `data.products.edges`) |
| **ID Field** | Nome do campo em cada objeto que será o ID externo (ex: `id`, `sku`) |
O Brainchat usa o **ID Field** para detectar registros existentes (atualiza em vez de duplicar).
Escolha o tipo de paginação que sua API suporta:
| Tipo | Descrição | Parâmetros |
| ----------- | ------------------------------------------- | ----------------------------------------- |
| **Nenhuma** | API retorna tudo em uma resposta | — |
| **Cursor** | API retorna um cursor para a próxima página | `cursorField`, `cursorParam` |
| **Offset** | API aceita `offset=` e `limit=` | `offsetParam`, `pageSize` |
| **Page** | API aceita `page=N` | `pageParam`, `pageSize`, `totalPagesPath` |
| Configuração extra | O que faz |
| -------------------- | --------------------------------------------------- |
| **Page Size** | Quantos registros por página |
| **Max Pages** | Limite de segurança (default 100) |
| **Total Pages Path** | Caminho até o total de páginas (paginação por page) |
| Modo | Comportamento |
| --------------- | ------------------------------------------------------------------ |
| **Full** | Recarrega tudo. Registros que sumiram da fonte são removidos. |
| **Append** | Apenas insere/atualiza. Não remove registros antigos. |
| **Incremental** | Busca só o que mudou desde a última sync (usa `incrementalField`). |
### Modo incremental
No modo incremental, defina:
* **Campo incremental** — coluna na resposta que indica quando o registro foi atualizado (ex: `updated_at`)
* **Janela de overlap (minutos)** — segurança para não perder edições no limite (default 10 min)
O Brainchat envia o timestamp da última sync no placeholder `{{since}}`.
Defina a periodicidade da sincronização automática:
| Frequência | Quando roda |
| --------------------- | ----------------------------------------- |
| **Manual** | Apenas quando você clica em "Sincronizar" |
| **A cada 15 minutos** | A cada 15 min (mínimo recomendado) |
| **A cada 30 minutos** | A cada 30 min |
| **Hourly** | Toda hora |
| **Every 6h** | A cada 6 horas |
| **Daily** | Uma vez por dia (horário configurável) |
| **Weekly** | Uma vez por semana (dia + horário) |
Você pode definir um **limite máximo de execuções** (útil para sync de 1 vez por importação inicial).
Use **Testar conexão** para validar o setup. Se OK, salve. A primeira sync roda imediatamente.
***
## Status de sincronização
O card da tabela mostra o status atual:
| Status | Significado |
| ----------- | --------------------------------------------------- |
| **idle** | Aguardando próxima sincronização |
| **syncing** | Sincronização em andamento |
| **synced** | Última sincronização concluída com sucesso |
| **partial** | Sync parcial — interrompida e pode ser retomada |
| **error** | Falha — verifique o erro detalhado e a configuração |
***
## Retomar carga interrompida
Se uma sync grande for interrompida (timeout, limite de páginas, erro temporário), o status fica **partial** e o Brainchat guarda em `sync_resume`:
* Cursor da última página processada
* Quantas páginas já foram baixadas
* Quantos registros já foram inseridos
* Timestamp do início
Basta clicar em **Continuar sincronização** que ele retoma de onde parou — sem reprocessar o que já foi feito.
***
## Boas práticas
* Comece com **Max Pages baixo** (5–10) para testar antes de liberar uma carga completa.
* Use **modo incremental** sempre que a API suportar `updated_at` — é muito mais barato e rápido.
* Defina **Response Path** com cuidado — caminho errado faz a sync retornar zero registros.
APIs externas com **rate limit** podem rejeitar muitas chamadas seguidas. Use Page Size razoável (50–100) e prefira modo incremental.
***
## Próximo passo
Integração nativa com Databases e Pipes do Pipefy — sem precisar montar a query GraphQL.