Guia de Integracion de Compartir

Esta guia cubre los 3 flujos de compartir disponibles en la API:

1. Enlace publico (sin autenticacion externa).
2. Compartir por correo (codigo de un solo uso).
3. Embed (token stateless para iframe).

Resumen de Endpoints

Flujo	Endpoints principales
Enlace publico	GET /api/v1/public/shares/:token/resolve, POST /api/v1/public/shares/:token/execute
Correo (share portal)	POST /api/v1/share-auth/request, POST /api/v1/share-auth/verify, GET /api/v1/share-portal/...
Embed	POST /api/v1/embed/dashboards/:id, GET/POST /api/embed/d/:token/...
Opciones dinamicas de filtros	GET .../filters/:filter_slug/options (publico, portal y embed)

Flujo 1: Enlace Publico

Usalo cuando cualquier persona con el enlace puede acceder.

1) Crear share sin share_context_id

curl -X POST "$API_BASE_URL/api/v1/dashboards/DASHBOARD_ID/shares" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Enlace publico - ventas",
    "share_type": "link"
  }'

2) Resolver token

curl "$API_BASE_URL/api/v1/public/shares/SHARE_TOKEN/resolve"

3) Ejecutar dashboard compartido

curl -X POST "$API_BASE_URL/api/v1/public/shares/SHARE_TOKEN/execute" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "period_start": "2025-01-01",
      "period_end": "2025-12-31"
    }
  }'

Flujo 2: Compartir por Correo

Usalo cuando solo correos autorizados deben acceder al dashboard.

1) Crear contexto de compartir

curl -X POST "$API_BASE_URL/api/v1/share-contexts" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Clientes externos",
    "description": "Acceso externo para clientes"
  }'

2) Agregar miembro externo por correo

curl -X POST "$API_BASE_URL/api/v1/share-contexts/CONTEXT_ID/members" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "member_type": "external_email",
    "email": "cliente@empresa.com"
  }'

3) Crear share vinculado al contexto

curl -X POST "$API_BASE_URL/api/v1/dashboards/DASHBOARD_ID/shares" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Portal clientes",
    "share_type": "link",
    "share_context_id": "CONTEXT_ID",
    "share_filter_policies": [
      {
        "filter_slug": "status",
        "filter_kind": "multi_select",
        "mode": "selectable",
        "allowed_values": ["Activo", "Pendiente"]
      }
    ]
  }'

4) Usuario externo autentica con codigo

Solicitar codigo:

curl -X POST "$API_BASE_URL/api/v1/share-auth/request" \
  -H "Content-Type: application/json" \
  -d '{
    "company_slug": "acme",
    "email": "cliente@empresa.com"
  }'

Verificar codigo y obtener tokens:

curl -X POST "$API_BASE_URL/api/v1/share-auth/verify" \
  -H "Content-Type: application/json" \
  -d '{
    "company_slug": "acme",
    "email": "cliente@empresa.com",
    "code": "1234-5678"
  }'

5) Consumir portal compartido con share_access

Listar dashboards por empresa/contextos:

curl "$API_BASE_URL/api/v1/share-portal/acme/dashboards" \
  -H "Authorization: Bearer SHARE_ACCESS_TOKEN"

Ejecutar dashboard:

curl -X POST "$API_BASE_URL/api/v1/share-portal/acme/dashboards/DASHBOARD_SLUG/execute" \
  -H "Authorization: Bearer SHARE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "context_id": "CONTEXT_ID",
    "parameters": {
      "status": ["Activo"]
    }
  }'

Flujo 3: Embed

Usalo cuando el dashboard se renderiza en iframe.

1) Generar token/embed URL

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

2) Consumir endpoints publicos de embed

• GET /api/embed/d/:token/info
• POST /api/embed/d/:token/execute
• GET /api/embed/d/:token/filters/:filter_slug/options

Filtros Dinamicos (select / multi_select)

Cuando un filtro es dinamico (SQL), el frontend debe llamar el endpoint de opciones del modo actual:

• Publico: GET /api/v1/public/shares/:token/filters/:filter_slug/options
• Portal por correo: GET /api/v1/share-portal/.../filters/:filter_slug/options?context_id=...
• Embed: GET /api/embed/d/:token/filters/:filter_slug/options

Parametro opcional soportado:

• search: valor usado en la SQL dinamica del filtro.

Respuesta estandar:

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

source puede ser:

• static: opciones estaticas del filtro.
• dynamic: opciones cargadas desde SQL.
• policy: opciones restringidas por share_filter_policies.

Errores Comunes

HTTP	error_code	Causa tipica
401	AUTH_REQUIRED	El share exige autenticacion externa
401	TOKEN_INVALID	Token invalido/expirado
400	INVALID_CONTEXT_ID	context_id invalido en modo portal
403	FILTER_DISABLED_BY_POLICY	Filtro bloqueado por politica
400	DB_QUERY_ERROR	Fallo al ejecutar SQL de filtro dinamico
400	SHARE_FILTER_POLICY_VIOLATION	Parametros fuera de las reglas del share

Siguientes Pasos

• Integracion de Embed
• Referencia de Compartir
• Guia de Producto: Compartir Dashboards