Consumindo Endpoints via Data API

Este guia mostra o fluxo completo para consumir endpoints de visualizacao via API key.

Visao Geral

O fluxo possui 3 etapas:

1. Trocar api_key + api_secret por tokens JWT.
2. Executar o endpoint (sync ou async).
3. Receber o resultado (imediato no sync, via polling no async).

Pre-requisitos

• Um usuario de integracao com API key ativa.
• company_slug da empresa.
• Um endpoint de visualizacao criado e ativo (criado pelo console).
• Permissao data_api:execute atribuida ao usuario de integracao.

Permissoes Necessarias

Endpoint	Permissao minima
POST /api/v1/data-api/:namespace/:slug/execute	data_api:execute
GET /api/v1/data-api/:namespace/:slug/jobs/:job_id	data_api:get_job

Essas permissoes estao incluidas nas politicas managed VisualizationViewer, VisualizationManager e DataAPIConsumer.

Para conferir as actions efetivas do usuario autenticado, use GET /api/v1/auth/permissions.

Base URL por Ambiente

Ambiente	Base URL
Local	http://localhost:3100
Producao	https://api.console.solucao42.com.br

export API_BASE_URL="http://localhost:3100"

Etapa 1: Autenticacao via API Key

Use a API key apenas para obter JWT. Nao envie API key nas chamadas seguintes.

curl -X POST "$API_BASE_URL/api/v1/auth/api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "company_slug": "acme",
    "api_key": "s42_xxxxxxxxx",
    "api_secret": "xxxxxxxxx"
  }'

Resposta esperada:

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "access_token_expires_in": 600,
  "refresh_token_expires_in": 604800,
  "user": { ... }
}

Guarde o access_token para as chamadas seguintes:

export TOKEN="eyJ..."

Etapa 2: Executar Endpoint (Sync)

Para endpoints configurados com execution_mode: sync:

curl -X POST "$API_BASE_URL/api/v1/data-api/default/vendas-por-regiao/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parameter_values": {
      "data_inicio": "2026-01-01",
      "regiao": "Sul"
    }
  }'

Resposta (HTTP 200):

{
  "columns": [
    { "name": "regiao", "type": "varchar" },
    { "name": "total", "type": "decimal" }
  ],
  "rows": [
    { "regiao": "Sul", "total": 150000.00 }
  ],
  "row_count": 1,
  "truncated": false,
  "max_rows": 10000,
  "executed_at": "2026-04-11T10:30:00Z"
}

informação

O timeout para execucao sync e de 60 segundos. Para queries mais longas, use endpoints no modo async.

Etapa 2 (alternativa): Executar Endpoint (Async)

Para endpoints configurados com execution_mode: async:

curl -X POST "$API_BASE_URL/api/v1/data-api/default/relatorio-mensal/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parameter_values": { "mes": "2026-03" },
    "callback_url": "https://meu-sistema.com/webhook/resultado"
  }'

Resposta (HTTP 202):

{
  "job_id": "507f1f77bcf86cd799439011",
  "status": "processing",
  "polling_url": "/api/v1/data-api/default/relatorio-mensal/jobs/507f1f77bcf86cd799439011"
}

Etapa 3: Polling do Resultado (Async)

curl "$API_BASE_URL/api/v1/data-api/default/relatorio-mensal/jobs/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer $TOKEN"

Enquanto processa:

{
  "job_id": "507f1f77bcf86cd799439011",
  "status": "processing",
  "result": null,
  "error": null,
  "created_at": "2026-04-11T10:30:00Z",
  "completed_at": null
}

Quando concluido:

{
  "job_id": "507f1f77bcf86cd799439011",
  "status": "completed",
  "result": {
    "columns": [...],
    "rows": [...],
    "row_count": 42,
    "truncated": false
  },
  "error": null,
  "created_at": "2026-04-11T10:30:00Z",
  "completed_at": "2026-04-11T10:30:45Z"
}

dica

Se callback_url foi informada, o sistema envia automaticamente um POST ao completar o job, evitando a necessidade de polling.

Tratamento de Erros

HTTP Status	Codigo	Causa
401	-	Token ausente ou invalido
403	FORBIDDEN	Sem permissao data_api:execute ou data_api:get_job
404	ENDPOINT_NOT_FOUND	Endpoint inexistente, inativo ou de outra company
408	EXECUTION_TIMEOUT	Query excedeu o timeout de 60s (use modo async)
422	-	Parametro invalido ou valor nao permitido (share context)
500	INTERNAL_ERROR	Erro interno na execucao da query

Refresh de Tokens

O access_token expira em 10 minutos. Para renovar:

curl -X POST "$API_BASE_URL/api/v1/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{ "refresh_token": "eyJ..." }'