api rest

fonte

lê dados de qualquer endpoint http/rest. suporta paginação automática, autenticação via vault e interpolação de variáveis de pipeline.

---

casos de uso

• consumir apis públicas ou internas com paginação
• extrair dados de plataformas saas (crm, erp, ecommerce)
• integrar webhooks de terceiros como fonte de dados

---

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
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, api_key, pipeline_var
credential_id	uuid	id da credencial no vault (para bearer, basic, api_key)
bearer_token	string	referência a variável de pipeline (apenas quando auth_type = pipeline_var)

corpo da requisição

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

paginação

campo	tipo	padrão	descrição
pagination_enabled	bool	false	habilita busca de múltiplas páginas
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
pagination_total_records_field	string	—	campo com total de registros (alternativa ao total de páginas)
pagination_request_fields	lista	—	campos de query que variam por página (chave / valor com {{ page }})
pagination_start_page	number	1	número da primeira página
pagination_concurrency	number	5	requisições simultâneas na fase paralela
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

---

exemplos

get simples sem paginação

{
  "url": "https://api.exemplo.com/v1/produtos",
  "method": "GET",
  "auth_type": "bearer",
  "credential_id": "uuid-da-credencial",
  "pagination_enabled": false
}

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

{
  "url": "https://api.exemplo.com/v1/pedidos",
  "method": "GET",
  "auth_type": "api_key",
  "credential_id": "uuid-da-credencial",
  "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",
  "credential_id": "uuid-da-credencial",
  "body_type": "json",
  "body_json": {
    "data_inicio": "{{data_inicio}}",
    "data_fim": "{{data_fim}}"
  }
}

autenticação via variável de pipeline

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

---

extração de dados aninhados

o campo pagination_data_path (ou data_path) usa notação pontilhada para navegar no json:

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

a paginação opera em duas fases:

1. fase 1 — sequencial: busca a primeira página para descobrir total_pages ou total_records
2. 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 ou status 404.

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.

---

credenciais suportadas

configure a credencial no vault antes de usar o conector:

auth_type	campos da credencial
bearer	token
basic	username, password
api_key	key, header_name (padrão: X-API-Key)

→ veja como criar credenciais em credential vault

---

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.