Guia de Integracao de Compartilhamento

Este guia cobre os 3 fluxos de compartilhamento disponiveis na API:

1. Link publico (sem autenticacao externa).
2. Compartilhamento por email (com autenticacao por codigo).
3. Embed (token stateless para iframe).

Visao Geral dos Endpoints

Fluxo	Endpoints principais
Link publico	GET /api/v1/public/shares/:token/resolve, POST /api/v1/public/shares/:token/execute
Email (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/...
Opcoes dinamicas de filtro	GET .../filters/:filter_slug/options (public, portal e embed)

Fluxo 1: Link Publico

Use quando o link pode ser acessado sem login externo.

1) Criar um share sem 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": "Link publico - vendas",
    "share_type": "link"
  }'

2) Resolver token

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

3) Executar dashboard compartilhado

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

Fluxo 2: Compartilhamento por Email

Use quando somente emails autorizados devem acessar o dashboard.

1) Criar contexto de compartilhamento

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": "Acesso externo para time de clientes"
  }'

2) Adicionar membro externo por email

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) Criar share vinculado ao 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": ["Ativo", "Pendente"]
      }
    ]
  }'

4) Usuario externo autentica por 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 e obter 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 compartilhado com share_access

Listar dashboards por empresa/contextos:

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

Executar 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": ["Ativo"]
    }
  }'

Fluxo 3: Embed

Use quando o consumo sera em iframe em outro produto.

1) Gerar 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": ["periodo_start", "periodo_end"],
    "required_params": ["periodo_start", "periodo_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)

Quando um filtro e dinamico (SQL), o frontend deve chamar o endpoint de opcoes do modo atual:

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

Parametro opcional suportado:

• search: string usada na query dinamica do filtro.

Resposta padrao:

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

source pode ser:

• static: opcoes fixas do filtro.
• dynamic: opcoes vindas da SQL do filtro.
• policy: opcoes restringidas por share_filter_policies.

Erros Comuns

HTTP	error_code	Causa comum
401	AUTH_REQUIRED	Share exige autenticacao externa
401	TOKEN_INVALID	Token invalido/expirado
400	INVALID_CONTEXT_ID	context_id invalido no portal
403	FILTER_DISABLED_BY_POLICY	Filtro bloqueado por politica do share
400	DB_QUERY_ERROR	Falha ao executar SQL de filtro dinamico
400	SHARE_FILTER_POLICY_VIOLATION	Parametros fora das regras de share

Proximos Passos

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