Guia de Integracao de Embed

Este guia mostra o fluxo completo para integrar embeds de dashboards e visualizacoes por API.

Visao Geral

O fluxo possui 3 etapas:

1. Trocar api_key + api_secret por tokens JWT.
2. Gerar um token de embed para dashboard ou visualizacao.
3. Usar embed_url em um iframe (ou consumir endpoints publicos de info/execucao).

Pre-requisitos

• Um usuario de integracao com API key ativa.
• company_slug da empresa.
• resource_id (dashboard ou visualizacao).
• Permissao para acessar o recurso.

Base URL por Ambiente

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

Defina uma variavel para reutilizar nos exemplos:

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

O dominio de embed_url retornado na API segue o FRONTEND_URL configurado no console-api.

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": {
    "_id": "...",
    "email": "integration@acme.com"
  }
}

Etapa 2A: Gerar Embed de Dashboard

curl -X POST "$API_BASE_URL/api/v1/embed/dashboards/DASHBOARD_ID" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fixed_params": { "region": "sul" },
    "allowed_params": ["seller_id"],
    "required_params": ["region"],
    "expires_in": 3600
  }'

Etapa 2B: Gerar Embed de Visualizacao

curl -X POST "$API_BASE_URL/api/v1/embed/visualizations/VISUALIZATION_ID" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_params": ["start_date", "end_date"],
    "required_params": ["start_date", "end_date"],
    "expires_in": 1800
  }'

Resposta de geracao (dashboard e visualizacao):

{
  "embed_url": "<FRONTEND_URL>/embed/d/eyJ...",
  "token": "eyJ...",
  "expires_at": "2026-03-05T15:00:00.000Z"
}

Parametros de Controle

Campo	Tipo	Descricao
fixed_params	object	Parametros travados no token. Nao podem ser sobrescritos por query string.
allowed_params	string[]	Parametros permitidos na URL do embed.
required_params	string[]	Parametros obrigatorios. Devem existir em fixed_params ou query string.
expires_in	integer	Validade em segundos. Min: 60, max: 86400.

Etapa 3: Incorporar no iframe

Use apenas embed_url retornada pela API:

EMBED_URL=$(curl -s -X POST "$API_BASE_URL/api/v1/embed/dashboards/DASHBOARD_ID" ... | jq -r '.embed_url')
echo "$EMBED_URL"

Nao copie o JSON completo da resposta para a URL. Copie somente o valor de embed_url.

Exemplo de iframe:

<iframe
  src="<embed_url>"
  width="100%"
  height="600"
  frameborder="0"
  loading="lazy"
></iframe>

Endpoints Publicos de Embed

Depois de gerar o token, o consumo publico ocorre por endpoints stateless:

Metodo	Endpoint	Uso
GET	/api/embed/d/:token/info	Metadados do dashboard e politica de parametros
GET	/api/embed/d/:token/filters/:filter_slug/options	Resolve opcoes de filtros select e multi_select
POST	/api/embed/d/:token/execute	Executa as visualizacoes do dashboard
GET	/api/embed/v/:token/info	Metadados da visualizacao
POST	/api/embed/v/:token/execute	Executa a visualizacao

Voce pode enviar parametros permitidos via query string (ex.: ?seller_id=42).

Para filtros dinamicos, voce pode passar search:

curl "$API_BASE_URL/api/embed/d/EMBED_TOKEN/filters/status/options?search=ati"

Resposta:

{
  "filter_slug": "status",
  "options": [
    { "label": "Ativo", "value": "Ativo" }
  ],
  "source": "dynamic"
}

source pode ser static, dynamic ou policy.

Erros Comuns

HTTP	error_code	Causa comum
400	INVALID_ID	ID de recurso invalido
400	PARAMETER_VALIDATION_ERROR	Parametros faltando ou nao permitidos
401	TOKEN_INVALID	Token de embed invalido
401	TOKEN_EXPIRED	Token de embed expirado
404	DASHBOARD_NOT_FOUND	Dashboard nao encontrado
404	VISUALIZATION_NOT_FOUND	Visualizacao nao encontrada

Seguranca Recomendada

• Nunca exponha api_key e api_secret no frontend.
• Gere embeds no backend da sua aplicacao.
• Use expires_in curto para links sensiveis.
• Prefira fixed_params para restringir escopo de dados.
• Renove JWT via POST /api/v1/auth/refresh quando necessario.