> ## Documentation Index
> Fetch the complete documentation index at: https://suporte.deumboom.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GPS API V2

> API de leitura dos indicadores do GPS de Cultura: Index, Gap da Liderança, engajamento, módulos, valores e comparativo de ciclos.

A **GPS API V2** expõe os mesmos indicadores da plataforma em JSON estável, pronto para BI, data warehouse, dashboards internos e o conector MCP.

É uma API **somente leitura**. Os dados vêm dos resultados processados de um ciclo (a "fotografia" cultural). Para interpretar scores e faixas, use o [GPS de Cultura](/gps/visao-geral).

<Info>
  Autenticação: `Authorization: Bearer bvt_…` (token de API V2 com `gps:read`). Veja [APIs BOOM](/api/visao-geral).
</Info>

***

## Base e ciclos

```http theme={null}
GET https://api.deumboom.com/v2/gps/...
```

Antes de consultar um widget, liste os ciclos da empresa (único endpoint Core liberado para o token `bvt_`):

```http theme={null}
GET /core/v1/cycle/read-all/{companyId}
Authorization: Bearer bvt_…
```

Resposta (campos principais):

```json theme={null}
[
  {
    "cycleId": "019e88be-2759-7a5a-83ee-d2dce959d66b",
    "companyId": "019e0253-377f-7b31-8500-c7c061778fa9",
    "name": "Ciclo Junho/2026",
    "startDate": "2026-06-01",
    "endDate": "2026-06-30",
    "status": "COMPLETED"
  }
]
```

Use `cycleId`, `startDate` e `endDate` como `from` / `to` nas consultas V2.

***

## Filtros comuns

Presentes em **todos** os endpoints como query string (`@ModelAttribute`).

<ParamField query="companyId" type="uuid" required>
  Empresa dona do ciclo. Deve coincidir com a empresa do token.
</ParamField>

<ParamField query="from" type="date" required>
  Início do recorte (`YYYY-MM-DD`). Em geral, a data de início do ciclo.
</ParamField>

<ParamField query="to" type="date" required>
  Fim do recorte (`YYYY-MM-DD`). Em geral, a data de término do ciclo.
</ParamField>

Filtros de cluster (todos opcionais; repetir a chave ou enviar lista). Cada valor é o **UUID** do cluster:

| Query | Recorte |
| - | - |
| `allocations` | Alocações |
| `directorates` | Diretorias |
| `departments` | Departamentos |
| `businessUnits` | Unidades de negócio |
| `whiteLabelA` … `whiteLabelE` | White Labels |
| `collaborators` | Colaboradores específicos |

Exemplo:

```http theme={null}
GET /v2/gps/cycles/{cycleId}/index-cultura/score?companyId={companyId}&from=2026-06-01&to=2026-06-30&departments={deptId}
```

***

## Envelope de resposta

```json theme={null}
{
  "meta": {
    "requestId": "7c2e1c3a-9a1f-4c0e-9d2b-1a2b3c4d5e6f",
    "generatedAt": "2026-06-15T14:32:01-03:00",
    "timezone": "America/Sao_Paulo",
    "filters": {
      "companyId": "019e0253-377f-7b31-8500-c7c061778fa9",
      "from": "2026-06-01",
      "to": "2026-06-30",
      "cycleId": "019e88be-2759-7a5a-83ee-d2dce959d66b",
      "clusterFilters": {}
    }
  },
  "data": {
    "valor": 612.4
  },
  "errors": []
}
```

Scores do Index e dos módulos estão na **escala 0–1000**. Percentuais (gap, convergência, engajamento) vêm como número decimal. Detalhes das faixas: [Index de Cultura](/gps/index-de-cultura).

***

## Chaves canônicas

### `moduleKey`

| Chave | Módulo |
| - | - |
| `proposito` | Propósito |
| `estrategia` | Estratégia |
| `estrutura` | Estrutura |
| `execucao_e_coordenacao` | Execução e Coordenação |
| `pessoas` | Pessoas |
| `comportamento` | Comportamento |
| `comunicacao_e_informacao` | Comunicação e Informação |
| `tecnologia_e_inovacao` | Tecnologia e Inovação |
| `centralidade_no_cliente` | Centralidade no Cliente |
| `governanca` | Governança |

Aliases legados ainda aceitos: `inteligencia_emocional`, `fluidez_organizacional`, `realizacao`, `gente`, `valores_solidos`, `transparencia_e_confianca`, `inovacao`, `foco_no_cliente`, `adaptabilidade`.

### `indicatorKey` (Cultura vs Resultados)

`receita` · `ltv` · `turnover` · `produtividade_por_colaborador` · `retrabalho_qualidade` · `brand_trust` · `lead_time_de_projetos_e_inovacao`

### `type` (clusters)

`hierarquia` · `departamento` · `alocacao` · `diretoria` · `unidade` · `white_label_a` · `white_label_b` · `white_label_c` · `white_label_d` · `white_label_e`

<Note>
  Endpoints de score por cluster aplicam **anonimato**: grupos com amostra insuficiente são omitidos.
</Note>

***

## Catálogo de endpoints

Todos os paths abaixo são relativos a `https://api.deumboom.com`. Método: **GET**. Parâmetros de path entre `{chaves}`.

### Index de Cultura

| ID | Path | O que devolve |
| - | - | - |
| `index_cultura_score` | `/v2/gps/cycles/{cycleId}/index-cultura/score` | Score global (`data.valor`, 0–1000) |
| `index_cultura_classification_scale` | `/v2/gps/cycles/{cycleId}/index-cultura/classification-scale` | Mesmo score, para a escala de classificação |
| `index_cultura_kpis` | `/v2/gps/cycles/{cycleId}/index-cultura/kpis` | `gapLideranca`, `convergenciaCultural`, `culturaVsResultados` |
| `index_cultura_evolution` | `/v2/gps/index-cultura/evolution` | `points[]` com `cycleName` e `score`. Query: `cycleIds` |
| `index_cultura_offenders_defenders` | `/v2/gps/cycles/{cycleId}/index-cultura/offenders-defenders` | Ofensores e defensores (`items[]`) |
| `index_cultura_capabilities_radar` | `/v2/gps/cycles/{cycleId}/index-cultura/capabilities-radar` | Radar de capacidades (`items[]`) |
| `index_cultura_module_scores` | `/v2/gps/cycles/{cycleId}/index-cultura/module-scores` | Score por módulo (`items[]`, nomes já normalizados) |
| `index_cultura_leadership_vs_employees` | `/v2/gps/cycles/{cycleId}/index-cultura/leadership-vs-employees` | `leadership`, `employees`, `current`, `target` por módulo |
| `index_cultura_cluster_scores` | `/v2/gps/cycles/{cycleId}/index-cultura/cluster-scores` | Scores por cluster. Query obrigatória: `type` |
| `index_cultura_cluster_evolution` | `/v2/gps/index-cultura/cluster-evolution` | Evolução por cluster. Query: `type`, `cycleIds` |

Exemplo — score global:

```bash theme={null}
curl -s "https://api.deumboom.com/v2/gps/cycles/${CYCLE_ID}/index-cultura/score" \
  -H "Authorization: Bearer ${BVT_TOKEN}" \
  --get \
  --data-urlencode "companyId=${COMPANY_ID}" \
  --data-urlencode "from=2026-06-01" \
  --data-urlencode "to=2026-06-30"
```

```json theme={null}
{
  "meta": { "timezone": "America/Sao_Paulo", "filters": { "cycleId": "…" } },
  "data": { "valor": 612.4 },
  "errors": []
}
```

Exemplo — liderança vs liderados:

```json theme={null}
{
  "data": {
    "items": [
      {
        "name": "Pessoas",
        "target": 700,
        "leadership": 720.1,
        "employees": 540.3,
        "current": 580.0
      }
    ]
  }
}
```

### Engajamento

| ID | Path | O que devolve |
| - | - | - |
| `engajamento_summary` | `/v2/gps/cycles/{cycleId}/engajamento/summary` | Resumo (engajado / instável / desengajado) |
| `engajamento_evolution` | `/v2/gps/engajamento/evolution` | Evolução por ciclo (`cycleIds`) |
| `engajamento_estimated_zones` | `/v2/gps/cycles/{cycleId}/engajamento/estimated-zones` | Zonas estimadas (ZEE) |
| `engajamento_cluster_distribution` | `/v2/gps/cycles/{cycleId}/engajamento/cluster-distribution` | Distribuição por cluster (`type`) |

Leitura das zonas: [Engajamento](/gps/engajamento).

### Gap da Liderança

| ID | Path | O que devolve |
| - | - | - |
| `gap_lideranca_score` | `/v2/gps/cycles/{cycleId}/gap-lideranca/score` | Score do gap |
| `gap_lideranca_classification_scale` | `/v2/gps/cycles/{cycleId}/gap-lideranca/classification-scale` | Escala de classificação |
| `gap_lideranca_evolution` | `/v2/gps/gap-lideranca/evolution` | Evolução (`cycleIds`) |
| `gap_lideranca_hierarchy_distribution` | `/v2/gps/cycles/{cycleId}/gap-lideranca/hierarchy-distribution` | Distribuição por nível hierárquico |

### Índice de Valor (Value Index)

| ID | Path | O que devolve |
| - | - | - |
| `value_index_score` | `/v2/gps/cycles/{cycleId}/value-index/score` | Score do índice |
| `value_index_classification_scale` | `/v2/gps/cycles/{cycleId}/value-index/classification-scale` | Escala |
| `value_index_evolution` | `/v2/gps/value-index/evolution` | Evolução (`cycleIds`) |
| `value_index_value_radar` | `/v2/gps/cycles/{cycleId}/value-index/value-radar` | Radar de valores |
| `value_index_value_scores` | `/v2/gps/cycles/{cycleId}/value-index/value-scores` | Scores individuais de valores |
| `value_index_cluster_heatmap` | `/v2/gps/cycles/{cycleId}/value-index/cluster-heatmap` | Heatmap por cluster (`type`) |
| `value_index_cluster_scores` | `/v2/gps/cycles/{cycleId}/value-index/cluster-scores` | Scores por cluster (`type`) |

### Cultura vs Resultados

| ID | Path | O que devolve |
| - | - | - |
| `resultados_global_influence` | `/v2/gps/cycles/{cycleId}/resultados/global-influence` | Influência global (`data.valor`) |
| `resultados_evolution` | `/v2/gps/resultados/evolution` | Evolução (`cycleIds`) |
| `resultados_kpi_impacts` | `/v2/gps/cycles/{cycleId}/resultados/kpi-impacts` | Impactos de KPIs (`items[]`) |
| `resultados_indicator` | `/v2/gps/cycles/{cycleId}/resultados/indicators/{indicatorKey}` | Detalhe de um indicador |

`indicatorKey` inválido → `400` com `"indicatorKey is invalid, verify!"`.

### Módulos

| ID | Path | O que devolve |
| - | - | - |
| `modulo_score` | `/v2/gps/cycles/{cycleId}/modulos/{moduleKey}/score` | Score do módulo |
| `modulo_classification_scale` | `/v2/gps/cycles/{cycleId}/modulos/{moduleKey}/classification-scale` | Escala do módulo |
| `modulo_evolution` | `/v2/gps/modulos/{moduleKey}/evolution` | Evolução (`cycleIds`) |
| `modulo_leadership_scores` | `/v2/gps/cycles/{cycleId}/modulos/{moduleKey}/leadership-scores` | Liderança, liderados e gap |
| `modulo_hierarchy_distribution` | `/v2/gps/cycles/{cycleId}/modulos/{moduleKey}/hierarchy-distribution` | Distribuição por NH |
| `modulo_dimension_products` | `/v2/gps/cycles/{cycleId}/modulos/{moduleKey}/dimension-products` | Produtos culturais da dimensão |
| `modulo_perception_products` | `/v2/gps/cycles/{cycleId}/modulos/{moduleKey}/perception-products` | Produtos culturais de percepção |

### Defensores e ofensores

| ID | Path | O que devolve |
| - | - | - |
| `defenders_offenders_global_heatmap` | `/v2/gps/cycles/{cycleId}/defenders-offenders/global-indicators-heatmap` | Heatmap global |
| `defenders_offenders_leadership_heatmap` | `/v2/gps/cycles/{cycleId}/defenders-offenders/leadership-heatmap` | Heatmap da liderança |
| `defenders_offenders_cluster_module_heatmap` | `/v2/gps/cycles/{cycleId}/defenders-offenders/cluster-module-heatmap` | Por cluster × módulo (`type`) |
| `defenders_offenders_cluster_trait_heatmap` | `/v2/gps/cycles/{cycleId}/defenders-offenders/cluster-trait-heatmap` | Por cluster × traço (`type`) |

### Comparativo de ciclos

Query obrigatória: `cycleA`, `cycleB`, além de `companyId`, `from`, `to`.

| ID | Path | O que devolve |
| - | - | - |
| `cycle_comparison_index` | `/v2/gps/cycle-comparison/index` | Score A/B, `delta`, `deltaPercent` |
| `cycle_comparison_modules` | `/v2/gps/cycle-comparison/modules` | Módulos com `scoreA`, `scoreB`, variação |
| `cycle_comparison_leadership` | `/v2/gps/cycle-comparison/leadership` | Liderança × liderados por módulo |
| `cycle_comparison_clusters` | `/v2/gps/cycle-comparison/clusters` | Clusters entre os dois ciclos (`type` obrigatório) |

```json theme={null}
{
  "data": {
    "cycleA": { "score": 580.0 },
    "cycleB": { "score": 612.4 },
    "delta": 32.4,
    "deltaPercent": 5.6
  }
}
```

***

## Evolução e listas de ciclos

Endpoints de evolução aceitam `cycleIds` repetido ou separado por vírgula:

```http theme={null}
GET /v2/gps/index-cultura/evolution?companyId=…&from=2025-01-01&to=2026-06-30&cycleIds={id1}&cycleIds={id2}
```

***

## Permissões e isolamento

| | |
| - | - |
| Permissão | `gps:read` (token V2 ou JWT) |
| Escopo | Somente a empresa do token |
| Métodos | Apenas `GET` com token `bvt_` |
| Ciclos | O ciclo precisa pertencer à empresa do token |

***

## Perguntas frequentes

<AccordionGroup>
  <Accordion title="Qual a diferença entre a API V1 (/core/v1/gps) e a V2?">
    A V1 serve a plataforma interna (payloads de gráfico brutos). A V2 é o contrato estável para integrações: envelope único, chaves canônicas e recortes por cluster.
  </Accordion>

  <Accordion title="O score veio nulo. O que aconteceu?">
    O ciclo ainda não tem resultado processado para aquele widget, o recorte `from`/`to` está fora do período, ou o filtro de cluster zerou a amostra (incluindo a regra de anonimato).
  </Accordion>

  <Accordion title="Posso gravar ou recalcular o GPS por esta API?">
    Não. A V2 é somente leitura. O processamento do ciclo acontece na plataforma.
  </Accordion>

  <Accordion title="Como um agente (Claude) consome estes endpoints?">
    O conector MCP (`mcp-gps-v2`) encapsula este catálogo em ferramentas (`gps_v2_query`, `gps_list_cycles`). A API HTTP documentada aqui é a mesma fonte.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.