Compartir y Embed

Esta referencia cubre los endpoints autenticados y publicos del sistema de compartir.

Grupos de Endpoints

Grupo	Base
Contextos de compartir	/api/v1/share-contexts
Shares de dashboard	/api/v1/dashboards/:id/shares, /api/v1/dashboard-shares
Autenticacion externa por correo	/api/v1/share-auth
Portal externo autenticado	/api/v1/share-portal
Shares publicos por token	/api/v1/public/shares/:token
Generacion de embed (autenticado)	/api/v1/embed
Consumo de embed (publico)	/api/embed
Auditoria/analytics de compartir	/api/v1/share-events, /api/v1/share-analytics

1) Contextos de Compartir

Todos requieren JWT interno (Authorization: Bearer <access_token>).

Metodo	Endpoint	Descripcion
GET	/api/v1/share-contexts	Lista contextos de la compania
GET	/api/v1/share-contexts/:id	Detalla un contexto
POST	/api/v1/share-contexts	Crea contexto
PUT	/api/v1/share-contexts/:id	Actualiza contexto
PUT	/api/v1/share-contexts/:id/grants	Actualiza grants del contexto
DELETE	/api/v1/share-contexts/:id	Elimina contexto
GET	/api/v1/share-contexts/:id/members	Lista miembros
POST	/api/v1/share-contexts/:id/members	Agrega miembro (internal_user, group, external_email)
DELETE	/api/v1/share-contexts/:id/members/:memberId	Elimina miembro

Ejemplo: agregar miembro externo por correo

{
  "member_type": "external_email",
  "email": "cliente@empresa.com"
}

2) Shares de Dashboard

Tambien requieren JWT interno.

Metodo	Endpoint	Descripcion
GET	/api/v1/dashboards/:id/shares	Lista shares del dashboard
POST	/api/v1/dashboards/:id/shares	Crea share (link o embed)
GET	/api/v1/dashboard-shares	Lista shares de la compania (paginado)
PUT	/api/v1/dashboard-shares/:shareId	Actualiza share
DELETE	/api/v1/dashboard-shares/:shareId	Revoca share
GET	/api/v1/dashboards/:id/share-filter-candidates	Lista filtros candidatos para politicas
GET	/api/v1/dashboards/:id/embed-parameter-candidates	Lista parametros candidatos para embed

Payload de creacion (POST /api/v1/dashboards/:id/shares)

{
  "name": "Clientes externos",
  "share_type": "link",
  "share_context_id": "65f0f4d7b3f0b902f7f7e123",
  "expires_at": "2026-12-31T23:59:59.000Z",
  "embed_options": {
    "allowed_origins": ["https://portal.cliente.com"],
    "hide_header": true,
    "hide_controls": false
  },
  "share_filter_policies": [
    {
      "filter_slug": "status",
      "filter_kind": "multi_select",
      "mode": "selectable",
      "allowed_values": ["Activo", "Pendiente"]
    }
  ]
}

3) Autenticacion Externa por Correo (share-auth)

Publico (sin JWT interno).

Metodo	Endpoint	Descripcion
POST	/api/v1/share-auth/request	Solicita codigo de login
POST	/api/v1/share-auth/verify	Verifica codigo y devuelve tokens share_access / share_refresh
POST	/api/v1/share-auth/refresh	Renueva tokens externos
POST	/api/v1/share-auth/logout	Logout stateless

Request de codigo

{
  "company_slug": "acme",
  "email": "cliente@empresa.com"
}

Verify de codigo

{
  "company_slug": "acme",
  "email": "cliente@empresa.com",
  "code": "1234-5678"
}

Respuesta de verify

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "access_token_expires_in": 600,
  "refresh_token_expires_in": 604800,
  "user": {
    "id": "...",
    "email": "cliente@empresa.com",
    "status": "active"
  }
}

4) Portal Externo Autenticado (share-portal)

Requiere token externo (Authorization: Bearer <share_access_token>).

Metodo	Endpoint	Descripcion
GET	/api/v1/share-portal/contexts	Lista contextos accesibles
GET	/api/v1/share-portal/:company_slug/contexts	Lista contextos por company slug
GET	/api/v1/share-portal/dashboards?context_id=...	Lista dashboards por contexto
GET	/api/v1/share-portal/:company_slug/dashboards	Lista dashboards de la compania (agregado por contextos)
GET	/api/v1/share-portal/dashboards/:id?context_id=...	Detalla dashboard
GET	/api/v1/share-portal/:company_slug/dashboards/:dashboard_slug?context_id=...	Detalla dashboard por slug
GET	/api/v1/share-portal/dashboards/:id/filters/:filter_slug/options?context_id=...&search=...	Resuelve opciones de filtro
GET	/api/v1/share-portal/:company_slug/dashboards/:dashboard_slug/filters/:filter_slug/options?context_id=...&search=...	Resuelve opciones por slug
POST	/api/v1/share-portal/dashboards/:id/execute	Ejecuta dashboard
POST	/api/v1/share-portal/:company_slug/dashboards/:dashboard_slug/execute	Ejecuta dashboard por slug

Execute (POST) body

{
  "context_id": "65f0f4d7b3f0b902f7f7e123",
  "parameters": {
    "status": ["Activo"]
  }
}

5) Shares Publicos por Token (/api/v1/public)

Sin autenticacion.

Metodo	Endpoint	Descripcion
GET	/api/v1/public/shares/:token/resolve	Resuelve token y devuelve requires_auth
GET	/api/v1/public/shares/:token/filters/:filter_slug/options?search=...	Resuelve opciones de filtro (select/multi_select)
POST	/api/v1/public/shares/:token/execute	Ejecuta share cuando requires_auth=false

Execute (POST) body

{
  "parameters": {
    "period_start": "2025-01-01",
    "period_end": "2025-12-31"
  }
}

6) Embed

6.1 Generacion de token/embed URL (JWT interno)

Metodo	Endpoint	Descripcion
POST	/api/v1/embed/dashboards/:id	Genera embed de dashboard
POST	/api/v1/embed/visualizations/:id	Genera embed de visualizacion

Body soportado:

{
  "fixed_params": { "region": "sur" },
  "allowed_params": ["seller_id"],
  "required_params": ["region"],
  "expires_in": 3600
}

6.2 Consumo publico stateless

Metodo	Endpoint	Descripcion
GET	/api/embed/d/:token/info	Metadatos del dashboard
GET	/api/embed/d/:token/filters/:filter_slug/options?search=...	Opciones dinamicas de filtro en embed
POST	/api/embed/d/:token/execute	Ejecuta dashboard
GET	/api/embed/v/:token/info	Metadatos de visualizacion
POST	/api/embed/v/:token/execute	Ejecuta visualizacion

7) Auditoria y Analytics de Compartir

Requiere JWT interno.

Metodo	Endpoint	Descripcion
GET	/api/v1/share-events	Lista eventos de compartir/autenticacion
GET	/api/v1/share-events/:id	Detalla evento
GET	/api/v1/share-analytics	Devuelve analytics agregados

Opciones Dinamicas para multi_select

Los 3 modos (publico, portal y embed) exponen endpoint de opciones para filtros select y multi_select.

Respuesta:

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

• source=static: opciones estaticas del filtro.
• source=dynamic: opciones de SQL del filtro.
• source=policy: opciones restringidas por politica del share.

Errores Frecuentes

error_code	Donde aparece	Significado
AUTH_REQUIRED	public/shares/:token/*	El share exige login externo
INVALID_CONTEXT_ID	share-portal/*	context_id ausente/invalido
FILTER_DISABLED_BY_POLICY	*/filters/:filter_slug/options	Filtro no disponible por politica
DB_QUERY_ERROR	*/filters/:filter_slug/options	Falla SQL de opciones dinamicas
SHARE_FILTER_POLICY_VIOLATION	share-portal .../execute	Parametros violan politica
TOKEN_INVALID	public/embed/portal	Token invalido o expirado

Guias Relacionadas

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