Guia de Integracion de Embed

Este guia cubre el flujo completo para integrar embeds de dashboards y visualizaciones por API.

Resumen

La integracion tiene 3 pasos:

1. Cambiar api_key + api_secret por tokens JWT.
2. Generar un token de embed para dashboard o visualizacion.
3. Usar embed_url en un iframe (o consumir endpoints publicos de info/ejecucion).

Requisitos Previos

• Un usuario de integracion con API key activa.
• Tu company_slug.
• El resource_id objetivo (dashboard o visualizacion).
• Permiso para acceder al recurso.

Base URL por Entorno

Entorno	Base URL
Local	http://localhost:3100
Produccion	https://api.console.solucao42.com.br

Define una variable para reutilizar en los ejemplos:

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

El dominio de embed_url devuelto por la API sigue el FRONTEND_URL configurado en console-api.

Paso 1: Autenticacion con API Key

Usa la API key solo para obtener JWT. No la envies en llamadas normales.

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"
  }'

Respuesta esperada:

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "access_token_expires_in": 600,
  "refresh_token_expires_in": 604800,
  "user": {
    "_id": "...",
    "email": "integration@acme.com"
  }
}

Paso 2A: Generar 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": "sur" },
    "allowed_params": ["seller_id"],
    "required_params": ["region"],
    "expires_in": 3600
  }'

Paso 2B: Generar Embed de Visualizacion

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
  }'

Respuesta de generacion (dashboard y visualizacion):

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

Control de Parametros

Campo	Tipo	Descripcion
fixed_params	object	Parametros fijos en el token. No se pueden sobrescribir por query string.
allowed_params	string[]	Parametros permitidos por query string en la URL de embed.
required_params	string[]	Parametros obligatorios. Deben existir en fixed_params o query string.
expires_in	integer	Expiracion en segundos. Min: 60, max: 86400.

Paso 3: Incrustar con iframe

Usa solo embed_url devuelta por la API:

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

No copies el JSON completo de la respuesta en la URL. Copia solo el valor de embed_url.

Ejemplo de iframe:

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

Endpoints Publicos de Embed

Despues de generar el token, el consumo publico stateless esta disponible en:

Metodo	Endpoint	Uso
GET	/api/embed/d/:token/info	Metadatos del dashboard y politica de parametros
GET	/api/embed/d/:token/filters/:filter_slug/options	Resuelve opciones de filtros select y multi_select
POST	/api/embed/d/:token/execute	Ejecuta visualizaciones del dashboard
GET	/api/embed/v/:token/info	Metadatos de la visualizacion
POST	/api/embed/v/:token/execute	Ejecuta la visualizacion

Puedes enviar parametros permitidos por query string (ejemplo: ?seller_id=42).

Para filtros dinamicos, puedes enviar search:

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

Respuesta:

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

source puede ser static, dynamic o policy.

Errores Frecuentes

HTTP	error_code	Causa tipica
400	INVALID_ID	ID de recurso invalido
400	PARAMETER_VALIDATION_ERROR	Parametros faltantes o no permitidos
401	TOKEN_INVALID	Token de embed invalido
401	TOKEN_EXPIRED	Token de embed expirado
404	DASHBOARD_NOT_FOUND	Dashboard no encontrado
404	VISUALIZATION_NOT_FOUND	Visualizacion no encontrada

Buenas Practicas de Seguridad

• Nunca expongas api_key y api_secret en frontend.
• Genera URLs de embed solo desde tu backend.
• Usa expires_in corto para enlaces sensibles.
• Prefiere fixed_params para limitar el alcance de datos.
• Renueva JWT con POST /api/v1/auth/refresh cuando sea necesario.