Antes de consumir um relatório pela API, você precisa saber quais existem na sua instância, qual identificador usar e quais filtros cada um aceita. Uma única chamada responde as três perguntas — este artigo mostra como ler a resposta.
Neste artigo
- Antes de começar
- Listar os relatórios
- Como ler o objeto filters
- Relatórios padrão da plataforma
- Problemas comuns
Antes de começar
- As credenciais da sua instância, reunidas em Comece por aqui: credenciais para integrar com a API da Engage, e um token gerado em Passo 2 — Obtendo o access_token (POST /auth).
- O usuário de serviço precisa da permissão Gerenciar relatórios.
- Teste em homologação:
https://sandbox.engage.bz/api/v1.
Listar os relatórios
GET https://sandbox.engage.bz/api/v1/{customer_id}/reports/legacy
Authorization: Bearer {access_token}No Postman: pasta 05 - Relatórios, request Listar relatórios disponíveis. O request já guarda o identificador do primeiro relatório na variável reportId.
Resposta da listagem de relatórios no Postman: categoria, guid_report, permissão e o objeto filters de um relatório
Cada item de results descreve um relatório:
| Campo | O que é |
|---|---|
guid_report | Identificador global do relatório — o recomendado para a chamada de consumo |
id | Identificador numérico, próprio desta instância |
description | Nome do relatório, igual ao da tela. Pode vir com o prefixo [BETA] |
category | Grupo do relatório, como "Relatórios de Progresso e Desempenho" |
permission | false quando o perfil do usuário do token não tem o relatório liberado |
filters | Os filtros que o relatório aceita — veja abaixo |
mandatory_filters | Filtros obrigatórios, quando houver |
url_article | Link para o artigo de ajuda daquele relatório |
Importante
Prefira sempre o guid_report. O id muda de uma instância para outra — o que funciona em homologação não funciona em produção. O GUID dos relatórios padrão é o mesmo em todas as instâncias.
Como ler o objeto filters
O objeto filters traz dezenas de opções can_filter_by_..., e só as marcadas como true valem para aquele relatório. Cada uma corresponde a um parâmetro da chamada de consumo:
Opção em filters | Parâmetro que você envia |
|---|---|
can_filter_by_competition | competitionId |
can_filter_by_track | trackId |
can_filter_by_round | roundId |
can_filter_by_activity_id | activityId |
can_filter_by_user | user |
can_filter_by_group | group |
can_filter_by_user_status | userStatus |
can_filter_by_<nome>_date | <nome>StartDate e <nome>EndDate, em camelCase |
can_filter_by_show_inactive_track | showInactiveTrack |
Dica
Não monte a tabela de filtros à mão — leia o objeto filters da sua instância. Ele reflete o relatório na versão atual. Os nomes e valores aceitos por cada parâmetro estão em Parâmetros de filtro dos relatórios.
Relatórios padrão da plataforma
Os GUIDs abaixo são os mesmos em todas as instâncias. Confirme sempre pela listagem antes de usar em produção.
Progresso e desempenho
| Relatório | GUID |
|---|---|
| 01 - Desempenho dos Usuários nos Ambientes | D138910F-C410-4D84-904F-4BDBA40A2C67 |
| 02 - Desempenho dos Usuários nas Trilhas | 76D0ACBD-2D50-4A6C-A16E-6E1CBE16862C |
| 03 - Desempenho dos Usuários nos Módulos | 3EF43BAD-A6EC-4EE7-B3E9-764E07160C80 |
| 04 - Desempenho dos Usuários nas Atividades | EB382BE7-0443-4C33-B1B0-0E227D88B065 |
| 05 - Matriz de Módulos e Usuários por Ambiente | DDF16B0D-F32C-4C1F-9676-C80D95D9A6AA |
Atividades e respostas
| Relatório | GUID |
|---|---|
| 06 - Respostas Atividade Formulário | ED4242C0-AB87-4150-BC8D-36E353CDF5F4 |
| 07 - Respostas Atividade Pergunta | A1A4A801-B56B-44E6-B4C4-770EED14E356 |
| 08 - Respostas Atividade Minigame | 88548E61-2C4E-4B57-A664-F1000B44617E |
| 09 - Respostas Atividade Prática | 32670305-0873-4C64-B2B5-E8D50BEE73C9 |
| 25 - Atividades Vinculadas aos Módulos | 13710EDA-118F-45EE-A3AC-86237AD96293 |
Interação e comunicação
| Relatório | GUID |
|---|---|
| 10 - Comentários do Canal Direto | E922316B-C8B9-4CA1-AA2C-F3EA4B1C7D5C |
| 11 - Comentários do Blog | 43E2DE01-B924-4A2E-8B14-EE028D8AF336 |
| 12 - Notificações Enviadas | C67F0172-C388-44E2-82D5-6BBD52AC62B7 |
Gamificação e ranking
| Relatório | GUID |
|---|---|
| 13 - Conquistas por Usuário | 21DC3230-A8B5-4622-9E3B-E2F9FB94CF15 |
| 14 - Extrato de Moedas | 652F90DE-A96E-4C28-88B5-F5B526F863C2 |
| 15 - Produtos da Loja | C51BAF3F-6A5B-45E3-8E44-725A382F86CC |
| 16 - Ranking | 38C86E3A-7E33-406E-B95F-BA52616F31C9 |
Usuários e grupos
| Relatório | GUID |
|---|---|
| 17 - Grupos e Usuários | BF5FBA70-DFDD-47D5-9AD5-28BCA2F4B9DD |
| 18 - Relação de Usuários | 86B7FE41-C7CE-4CE0-ACD1-E49E5EEBBB75 |
| 26 - Relação de Público-Alvo | 347FD0D0-D243-4D75-9F1B-5B8AC0CD6179 |
Acesso, auditoria e conformidade
| Relatório | GUID |
|---|---|
| 19 - Status de Acesso à Plataforma por Usuário | 7F109F8C-562E-4597-9264-A360D3FD1FF0 |
| 20 - Log de Acessos à Plataforma | FE5902CD-7AA6-4C5C-B554-D14A312AF847 |
| 21 - Log de autorização TOTP | E27B6F40-D045-4D72-A108-99E5A528FE15 |
| 22 - Logs de Auditoria | 4E1A0017-F4A1-442E-8CA3-516D48C63A8F |
| 23 - Log de Downloads | DD7CA98A-63DB-44BA-A350-D202A9A61B4C |
| 24 - Termo de Aceite | 1C881F62-8443-4252-8ED6-D87C8DA3B966 |
| 27 - Assinatura de certificados | 56413EB3-FACB-485D-AD1D-53A6372D3077 |
Recursos opcionais — aparecem só quando o recurso está habilitado na instância:
| Relatório | GUID |
|---|---|
| Habilidades por Usuário | 6AF2E2ED-6AE0-4543-ACA2-5209FFC937FA |
| Respostas Atividade Feedback | 235FC866-057C-4C11-96A8-EAB45491E0B6 |
| Respostas Atividade Reconhecimento | 1CF82E1E-925F-4339-8A90-485532834FD8 |
Relatórios personalizados existem só na instância que os criou: pegue o guid_report deles na listagem.
Problemas comuns
| O que aparece | Causa provável | O que fazer |
|---|---|---|
| HTTP 401 | customer_id da rota diferente do token, ou usuário sem a permissão Gerenciar relatórios | Confira a instância e a permissão do usuário de serviço |
| Relatório esperado não aparece | O recurso que o habilita está desligado na instância | Habilite o recurso na área administrativa |
Itens com "permission": false | O perfil do usuário do token não tem o relatório liberado | Libere no perfil ou use um usuário com perfil Administrador |
| Lista vazia | O usuário do token não é administrador da instância | Revise o cadastro do usuário de serviço |
Próximo passo
Com o guid_report em mãos, execute o relatório — veja Consumir um relatório pela API.
Precisa de ajuda?
Escreva para meajuda@engage.bz informando o customer_id, o ambiente e o relatório que você quer consumir. Nunca envie senhas, tokens ou o client_secret por e-mail.
Este artigo foi útil?
Que bom!
Obrigado pelo seu feedback
Desculpe! Não conseguimos ajudar você
Obrigado pelo seu feedback
Feedback enviado
Agradecemos seu esforço e tentaremos corrigir o artigo