GPS API V2

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.

Autenticação: Authorization: Bearer bvt_… (token de API V2 com gps:read). Veja APIs BOOM.

Base e ciclos

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_):

GET /core/v1/cycle/read-all/{companyId}
Authorization: Bearer bvt_…

Resposta (campos principais):

[
  {
    "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).

uuid

required

Empresa dona do ciclo. Deve coincidir com a empresa do token.

date

required

Início do recorte (YYYY-MM-DD). Em geral, a data de início do ciclo.

date

required

Fim do recorte (YYYY-MM-DD). Em geral, a data de término do ciclo.

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:

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

Envelope de resposta

{
  "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.

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

Endpoints de score por cluster aplicam anonimato: grupos com amostra insuficiente são omitidos.

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:

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"

{
  "meta": { "timezone": "America/Sao_Paulo", "filters": { "cycleId": "…" } },
  "data": { "valor": 612.4 },
  "errors": []
}

Exemplo — liderança vs liderados:

{
  "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.

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)

{
  "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:

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

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.

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

Posso gravar ou recalcular o GPS por esta API?

Não. A V2 é somente leitura. O processamento do ciclo acontece na plataforma.

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.

Visão geral

GPS

Sensores

Cadastros

Base e ciclos

Filtros comuns

Envelope de resposta

Chaves canônicas

`moduleKey`

`indicatorKey` (Cultura vs Resultados)

`type` (clusters)

Catálogo de endpoints

Index de Cultura

Engajamento

Gap da Liderança

Índice de Valor (Value Index)

Cultura vs Resultados

Módulos

Defensores e ofensores

Comparativo de ciclos

Evolução e listas de ciclos

Permissões e isolamento

Perguntas frequentes

​Base e ciclos

​Filtros comuns

​Envelope de resposta

​Chaves canônicas

​moduleKey

​indicatorKey (Cultura vs Resultados)

​type (clusters)

​Catálogo de endpoints

​Index de Cultura

​Engajamento

​Gap da Liderança

​Índice de Valor (Value Index)

​Cultura vs Resultados

​Módulos

​Defensores e ofensores

​Comparativo de ciclos

​Evolução e listas de ciclos

​Permissões e isolamento

​Perguntas frequentes

Base e ciclos

Filtros comuns

Envelope de resposta

Chaves canônicas

`moduleKey`

`indicatorKey` (Cultura vs Resultados)

`type` (clusters)

Catálogo de endpoints

Index de Cultura

Engajamento

Gap da Liderança

Índice de Valor (Value Index)

Cultura vs Resultados

Módulos

Defensores e ofensores

Comparativo de ciclos

Evolução e listas de ciclos

Permissões e isolamento

Perguntas frequentes