Compartilhamento e Embed

Esta referencia cobre os endpoints publicos e autenticados do sistema de compartilhamento.

Grupos de Endpoints

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

1) Contextos de Compartilhamento

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

Metodo	Endpoint	Descricao
GET	/api/v1/share-contexts	Lista contextos da empresa
GET	/api/v1/share-contexts/:id	Detalha um contexto
POST	/api/v1/share-contexts	Cria contexto
PUT	/api/v1/share-contexts/:id	Atualiza contexto
PUT	/api/v1/share-contexts/:id/grants	Atualiza grants do contexto
DELETE	/api/v1/share-contexts/:id	Remove contexto
GET	/api/v1/share-contexts/:id/members	Lista membros
POST	/api/v1/share-contexts/:id/members	Adiciona membro (internal_user, group, external_email)
DELETE	/api/v1/share-contexts/:id/members/:memberId	Remove membro

Exemplo: adicionar membro externo por email

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

2) Shares de Dashboard

Tambem exigem JWT interno.

Metodo	Endpoint	Descricao
GET	/api/v1/dashboards/:id/shares	Lista shares do dashboard
POST	/api/v1/dashboards/:id/shares	Cria share (link ou embed)
GET	/api/v1/dashboard-shares	Lista shares da empresa (paginado)
PUT	/api/v1/dashboard-shares/:shareId	Atualiza share
DELETE	/api/v1/dashboard-shares/:shareId	Revoga 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 criacao (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": ["Ativo", "Pendente"]
    }
  ]
}

3) Autenticacao Externa por Email (share-auth)

Publico (sem JWT interno).

Metodo	Endpoint	Descricao
POST	/api/v1/share-auth/request	Solicita codigo de login por email
POST	/api/v1/share-auth/verify	Verifica codigo e retorna tokens share_access / share_refresh
POST	/api/v1/share-auth/refresh	Renova 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"
}

Resposta 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)

Exige token externo (share_access) em Authorization: Bearer ....

Metodo	Endpoint	Descricao
GET	/api/v1/share-portal/contexts	Lista contextos acessiveis
GET	/api/v1/share-portal/:company_slug/contexts	Lista contextos com escopo da empresa
GET	/api/v1/share-portal/dashboards?context_id=...	Lista dashboards por contexto
GET	/api/v1/share-portal/:company_slug/dashboards	Lista dashboards da empresa (agregado por contextos)
GET	/api/v1/share-portal/dashboards/:id?context_id=...	Detalha dashboard
GET	/api/v1/share-portal/:company_slug/dashboards/:dashboard_slug?context_id=...	Detalha dashboard por slug
GET	/api/v1/share-portal/dashboards/:id/filters/:filter_slug/options?context_id=...&search=...	Resolve opcoes de filtro
GET	/api/v1/share-portal/:company_slug/dashboards/:dashboard_slug/filters/:filter_slug/options?context_id=...&search=...	Resolve opcoes de filtro por slug
POST	/api/v1/share-portal/dashboards/:id/execute	Executa dashboard
POST	/api/v1/share-portal/:company_slug/dashboards/:dashboard_slug/execute	Executa dashboard por slug

Execute (POST)

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

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

Sem autenticacao.

Metodo	Endpoint	Descricao
GET	/api/v1/public/shares/:token/resolve	Resolve token e informa requires_auth
GET	/api/v1/public/shares/:token/filters/:filter_slug/options?search=...	Resolve opcoes de filtro (select/multi_select)
POST	/api/v1/public/shares/:token/execute	Executa share quando requires_auth=false

Execute (POST) body

{
  "parameters": {
    "periodo_start": "2025-01-01",
    "periodo_end": "2025-12-31"
  }
}

6) Embed

6.1 Geracao de token/embed URL (JWT interno)

Metodo	Endpoint	Descricao
POST	/api/v1/embed/dashboards/:id	Gera embed de dashboard
POST	/api/v1/embed/visualizations/:id	Gera embed de visualizacao

Body suportado:

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

6.2 Consumo publico (stateless)

Metodo	Endpoint	Descricao
GET	/api/embed/d/:token/info	Metadados do dashboard
GET	/api/embed/d/:token/filters/:filter_slug/options?search=...	Opcoes de filtro dinamico no embed
POST	/api/embed/d/:token/execute	Executa dashboard
GET	/api/embed/v/:token/info	Metadados da visualizacao
POST	/api/embed/v/:token/execute	Executa visualizacao

7) Auditoria e Analytics de Compartilhamento

JWT interno.

Metodo	Endpoint	Descricao
GET	/api/v1/share-events	Lista eventos de compartilhamento/autenticacao
GET	/api/v1/share-events/:id	Detalha evento
GET	/api/v1/share-analytics	Retorna agregados de analytics

Opcoes Dinamicas para multi_select

Os 3 modos (publico, portal e embed) suportam endpoint de opcoes para filtros select e multi_select.

Resposta:

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

• source=static: opcoes estaticas do filtro.
• source=dynamic: opcoes de consulta SQL do filtro.
• source=policy: opcoes restringidas por politica do share.

Erros Mais Frequentes

error_code	Onde aparece	Significado
AUTH_REQUIRED	public/shares/:token/*	Share exige login externo
INVALID_CONTEXT_ID	share-portal/*	context_id ausente/invalido
FILTER_DISABLED_BY_POLICY	*/filters/:filter_slug/options	Filtro indisponivel pelas regras do share
DB_QUERY_ERROR	*/filters/:filter_slug/options	Falha na SQL de opcoes dinamicas
SHARE_FILTER_POLICY_VIOLATION	share-portal .../execute	Parametros violaram politica
TOKEN_INVALID	fluxos publicos/embed/portal	Token invalido ou expirado

Guias Relacionados

• Integracao de Compartilhamento
• Integracao de Embed
• Guia de Produto: Compartilhando Dashboards