api rest¶

fonte

lê dados de qualquer endpoint http/rest. suporta paginação automática (page, offset, cursor e link header), autenticação embutida e interpolação de variáveis de pipeline em url, headers e corpo da requisição.

quando usar¶

consumir apis públicas ou internas com ou sem paginação
extrair dados de plataformas saas que não têm conector dedicado (erp, ecommerce, marketing, suporte)
puxar dados incrementalmente de uma api que expõe um campo de "atualizado em" (watermark)
integrar um endpoint de parceiro de negócio como fonte recorrente de um pipeline agendado

configuração¶

campos principais¶

campo	tipo	obrigatório	descrição
`url`	string	sim	endpoint http. suporta variáveis: `{{var_nome}}`
`method`	enum	sim	`GET`, `POST`, `PUT`, `PATCH`, `DELETE`
`headers`	lista	não	lista de pares `key / value` adicionados ao request
`query_params`	lista	não	parâmetros de query string (key / value / enabled)
`timeout`	number	não	timeout em segundos · padrão: `30`

autenticação¶

campo	tipo	descrição
`auth_type`	enum	`none`, `bearer`, `basic`, `oauth2`, `pipeline_var`
`bearer_token`	string	token fixo ou variável de pipeline (`{{ pipeline.token }}`) — usado em `bearer` e `pipeline_var`
`basic_user` / `basic_pass`	string	credenciais para `basic`
`oauth2_token_url` / `oauth2_client_id` / `oauth2_client_secret` / `oauth2_scope`	string	fluxo client-credentials para `oauth2`

api com login em duas etapas

se a api exige um endpoint de login separado (usuário/senha → token) antes das chamadas de dados, use um nó auth rest antes deste, e referencie o token gerado com auth_type = pipeline_var.

corpo da requisição¶

campo	tipo	descrição
`body_type`	enum	`none`, `json`, `form_data`, `x_www_form_urlencoded`, `raw`
`body_json`	string	payload json (quando `body_type = json` ou `raw`)
`body_params`	lista	pares key/value para form data / urlencoded

paginação¶

campo	tipo	padrão	descrição
`pagination_enabled`	bool	`false`	habilita busca de múltiplas páginas
`pagination_strategy`	enum	`page`	`page`, `offset`, `cursor` ou `link_header` — ver estratégias
`pagination_location`	enum	`query`	onde os campos de paginação são injetados: `query`, `body` ou `header` (ignorado em `link_header`)
`pagination_data_path`	string	—	caminho pontilhado até o array de dados: ex. `data.items`
`pagination_total_pages_field`	string	—	campo que indica total de páginas: ex. `meta.total_pages` (estratégias `page`/`offset`)
`pagination_total_records_field`	string	—	campo com total de registros (alternativa ao total de páginas, `page`/`offset`)
`pagination_has_more_field`	string	—	campo booleano indicando se há mais páginas (estratégias `cursor`/`link_header`, ou complemento em `page`/`offset`)
`pagination_request_fields`	lista	—	campos enviados por página — valor suporta `{{ page }}`, `{{ offset }}` ou `{{ cursor }}`
`pagination_start_page`	number	`1`	número da primeira página
`pagination_page_size`	number	—	tamanho de página usado para calcular `{{ offset }}` (estratégia `offset`)
`pagination_cursor_source`	enum	`response_field`	`response_field` (token no envelope) ou `last_record_field` (keyset/seek)
`pagination_cursor_path`	string	—	caminho do cursor no envelope da resposta: ex. `meta.next_cursor`
`pagination_cursor_record_field`	string	—	campo do último registro usado como cursor: ex. `id` (keyset/seek)
`pagination_concurrency`	number	`5`	requisições simultâneas na fase paralela (`page`/`offset` apenas — `cursor` e `link_header` são sempre sequenciais)
`max_pages`	number	`0`	limite de páginas (0 = sem limite)
`rate_limit_rps`	number	`5`	requisições por segundo
`request_interval_ms`	number	`0`	intervalo mínimo entre requisições em ms

extração incremental (watermark)¶

campo	tipo	descrição
`watermark_column`	string	coluna da resposta com timestamp/id crescente (ex: `updated_at`) — habilita extração incremental por alto-water-mark
`watermark_var`	string	nome da variável de pipeline injetada com o último valor visto (padrão: `watermark`)

não é cdc

a extração incremental via watermark é feita por polling (a cada execução, busca apenas registros acima do último valor conhecido) — não é captura de mudanças em log (cdc). funciona bem para apis que aceitam filtro por data/id de atualização.

estratégias de paginação¶

o conector suporta as formas mais comuns de paginação encontradas em apis rest:

estratégia	como funciona	paralelizável	uso típico
`page`	número de página (`page=2`)	sim, se total conhecido	maioria das apis internas/saas
`offset`	offset/limit (`offset=100&limit=50`)	sim, se total conhecido	apis de banco/relatórios
`cursor`	token opaco retornado pela resposta anterior	não — sequencial	stripe, apis de streaming de eventos
`link_header`	header http `Link: <url>; rel="next"` (rfc 5988)	não — sequencial	github, apis hypermedia/hateoas

as estratégias cursor e link_header são inerentemente sequenciais: cada requisição depende do resultado da anterior, então pagination_concurrency é ignorado.

offset/limit¶

{
  "pagination_enabled": true,
  "pagination_strategy": "offset",
  "pagination_page_size": 100,
  "pagination_request_fields": [
    { "key": "offset", "value": "{{ offset }}", "enabled": true },
    { "key": "limit", "value": "100", "enabled": true }
  ],
  "pagination_total_records_field": "total"
}

{{ offset }} é calculado automaticamente como (página_atual - página_inicial) × pagination_page_size.

cursor / token (sequencial)¶

{
  "pagination_enabled": true,
  "pagination_strategy": "cursor",
  "pagination_cursor_source": "response_field",
  "pagination_cursor_path": "meta.next_cursor",
  "pagination_request_fields": [
    { "key": "cursor", "value": "{{ cursor }}", "enabled": true }
  ],
  "pagination_has_more_field": "meta.has_more"
}

variante keyset/seek — quando a api não devolve um cursor no envelope, mas espera o id/timestamp do último registro (ex: starting_after da stripe):

{
  "pagination_strategy": "cursor",
  "pagination_cursor_source": "last_record_field",
  "pagination_cursor_record_field": "id",
  "pagination_request_fields": [
    { "key": "starting_after", "value": "{{ cursor }}", "enabled": true }
  ]
}

link header (rfc 5988)¶

{
  "pagination_enabled": true,
  "pagination_strategy": "link_header"
}

a primeira requisição usa query_params/pagination_request_fields normalmente; a partir da segunda, o conector segue a url completa do header Link: <url>; rel="next" da resposta anterior — nenhum campo é reconstruído manualmente. termina quando a resposta não traz mais rel="next" (ou quando pagination_has_more_field indica false).

paginação via body ou header¶

por padrão os campos de pagination_request_fields vão na query string. algumas apis exigem que a paginação viaje no corpo json (POST com {"page": 2}) ou em um header customizado:

{
  "pagination_enabled": true,
  "pagination_strategy": "page",
  "pagination_location": "body",
  "method": "POST",
  "pagination_request_fields": [
    { "key": "page", "value": "{{ page }}", "enabled": true },
    { "key": "pageSize", "value": "100", "enabled": true }
  ]
}

exemplos¶

get simples sem paginação¶

{
  "url": "https://api.exemplo.com/v1/produtos",
  "method": "GET",
  "auth_type": "bearer",
  "bearer_token": "{{ pipeline.token }}",
  "pagination_enabled": false
}

get com paginação por número de página¶

{
  "url": "https://api.exemplo.com/v1/pedidos",
  "method": "GET",
  "auth_type": "bearer",
  "pagination_enabled": true,
  "pagination_data_path": "data",
  "pagination_total_pages_field": "pagination.last_page",
  "pagination_request_fields": [
    { "key": "page", "value": "{{ page }}", "enabled": true },
    { "key": "per_page", "value": "100", "enabled": true }
  ],
  "pagination_start_page": 1,
  "pagination_concurrency": 5
}

post com body json e variável de pipeline¶

{
  "url": "https://api.exemplo.com/v1/relatorio",
  "method": "POST",
  "auth_type": "bearer",
  "body_type": "json",
  "body_json": "{\"data_inicio\": \"{{data_inicio}}\", \"data_fim\": \"{{data_fim}}\"}"
}

autenticação via variável de pipeline (token de um auth rest anterior)¶

{
  "url": "https://api.interna.com/dados",
  "method": "GET",
  "auth_type": "pipeline_var",
  "bearer_token": "{{ pipeline.token }}"
}

extração de dados aninhados¶

o campo pagination_data_path usa notação pontilhada para navegar no json, mesmo quando a paginação está desabilitada:

// resposta da api:
{
  "status": "ok",
  "data": {
    "items": [ {...}, {...} ],
    "pagination": { "total": 500, "last_page": 5 }
  }
}

// configuração:
{
  "pagination_data_path": "data.items",
  "pagination_total_pages_field": "data.pagination.last_page"
}

como funciona a paginação concorrente¶

nas estratégias page e offset, a paginação opera em duas fases:

fase 1 — sequencial: busca a primeira página para descobrir total_pages ou total_records
fase 2 — paralela: busca as páginas restantes em concorrência controlada por pagination_concurrency

quando o total de páginas não é conhecido (total_pages_field vazio), a fase 2 usa fallback sequencial, parando ao receber uma página vazia, status 404, ou quando pagination_has_more_field indica false.

nas estratégias cursor e link_header não há fase paralela: cada requisição depende do resultado da anterior (cursor extraído da resposta, ou url do header Link), então a busca é sempre sequencial.

fase 1:  página 1  →  descobre total: 10 páginas
fase 2:  páginas 2-10  →  busca concorrente (5 em paralelo)
resultado: 10 páginas × 100 registros = 1.000 registros

modo sample

ao testar o nó no builder, a paginação é desabilitada automaticamente. apenas a primeira página é buscada para validar a configuração.

variáveis de pipeline¶

qualquer campo de string aceita interpolação com {{nome_da_variavel}}:

url: https://api.exemplo.com/v1/{{entidade}}/relatorio
body_json: {"data_inicio": "{{data_inicio}}"}

as variáveis são resolvidas em tempo de execução a partir das variáveis configuradas no pipeline — incluindo tokens gerados por um nó auth rest anterior no mesmo fluxo.