Consumir um relatório pela API

Todo relatório da área administrativa pode ser extraído pela API, em JSON, sem abrir a tela. Este artigo mostra como fazer a chamada, quanto tempo ela pode levar e como ler o resultado.

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.
• O identificador do relatório (guid_report), que vem da listagem descrita em Relatórios disponíveis e seus filtros.
• Teste em homologação: https://sandbox.engage.bz/api/v1.

Executar o relatório

1Faça a chamada

GET https://sandbox.engage.bz/api/v1/{customer_id}/reports/legacy/{guid_report}/{admin_id}/json
Authorization: Bearer {access_token}

No Postman: pasta 05 - Relatórios, request Consumir relatório (JSON).

Request Consumir relatório (JSON) no Postman com resposta 200 e os registros do relatório; nomes de usuário ocultados

Os filtros, quando houver, vão na query string — veja Parâmetros de filtro dos relatórios.

2Aguarde a resposta

A chamada é bloqueante. A API coloca o relatório numa fila, aguarda o processamento e só então devolve os dados. Não existe HTTP 202, número de processamento nem rota para consultar o andamento: a conexão fica aberta até o fim.

• Configure o timeout do seu cliente HTTP para 60 minutos. É o tempo máximo que a API aguarda o processamento. Passou disso, a chamada falha.
• Execute um relatório por vez com o mesmo usuário. Veja o motivo em "Cuidados", abaixo.

3Leia o resultado

A resposta é um array JSON simples. Cada objeto é uma linha do relatório, e as chaves são os nomes das colunas. Exemplo do relatório "27 - Assinatura de certificados" (valores ilustrativos):

[
  {
    "UsuarioID": 415322,
    "NomeUsuario": "João da Silva",
    "LoginUsuario": "joao.silva",
    "StatusUsuario": "Ativo",
    "NomeTrilha": "Trilha de Integração",
    "DataAssinaturaCertificado": ""
  }
]

Não há envelope nem paginação, e as colunas mudam de um relatório para outro.

Relatórios grandes

Em instâncias grandes, um relatório passa facilmente de 200 mil linhas e estoura o tempo de processamento. A saída é sempre filtrar:

• Por período: startDate e endDate, ou o par de datas próprio do relatório (por exemplo, roundCompletionDateStartDate e roundCompletionDateEndDate).
• Por ambiente: competitionId.
• Em janelas menores: extraia mês a mês e junte os resultados do seu lado.

Cuidados

• Duas chamadas iguais ao mesmo tempo dividem o resultado. Se o mesmo usuário pedir o mesmo relatório enquanto o primeiro ainda processa, a segunda chamada não gera um processamento novo: recebe o resultado da primeira, mesmo que os filtros sejam diferentes. Execute as chamadas em sequência.
• Parâmetro com nome errado é descartado em silêncio. O filtro não é aplicado e o relatório volta maior do que o esperado. Confira a grafia.
• Use sempre a rota terminada em /json. A variante sem /json devolve planilha e não é suportada para integração.
• Não envie environmentId. Ele não filtra nada: só marca a origem da chamada no log de auditoria, e o padrão já é o correto para integração.

Problemas comuns