Motimate: Como gerar relatórios usando a API pública

Além de compartilhar dados de conclusão de curso via Motimate xAPItambém oferecemos suporte à extração de arquivos Excel da API pública do Motimate. Esses relatórios do Excel se baseiam em modelos de relatório que foram criados anteriormente na seção Gerar relatórios em Insights no Motimate.

Aqui estão algumas informações úteis antes de começarmos:

As três funções relevantes da API pública do Motimate são:

• OBTER /insights/learnings/report_templates
   
• POST /insights/learnings/report_requests
   
• OBTER /insights/learnings/report_requests/{id}

Antes de gerar um relatório com a API pública, certifique-se de que um modelo de relatório já tenha sido gerado em Gerar relatórios(consulte o guia aqui) e que você saiba a partir de qual(is) modelo(s) gerará o(s) relatório(s). Desde que isso esteja pronto, o processo de geração de um relatório exigirá três etapas:

Etapa 1: Obtenha uma lista de modelos de relatório:

Comando: GET /insights/learnings/report_templates

Exemplo de resposta:

{
  "data": [
    {
      **"id": "abc86b82-029a-4b74-9690-4ab607f3eafe "**,
      "name": "Report Test" (Teste de relatório),
      "description" (descrição): "Testes para fins de API pública",
      "last_status": "uploading",
      "last_generated_at": null,
      "created_at": "2022-03-01T15:36:42.99789+01:00",
      "updated_at": "2022-03-01T15:41:26.98349+01:00",
      "user": {
        "name": "John Doe"
      }
    }
  ]
}

Anote o ID do modelo que você precisará usar na próxima etapa, neste caso: abc86b82-029a-4b74-9690-4ab607f3eafe

Etapa 2: Gerar um novo relatório com base no modelo selecionado

Comando: POST /insights/learnings/report_requests

Neste exemplo, certifique-se de enviar abc86b82-029a-4b74-9690-4ab607f3eafe como template_id nessa solicitação.

Exemplo de resposta:

{
  "data": {
    **"id": "abc23922-940d-4d6d-a6f0-ecaed00810c4"**,
    "status": "started",
    "created_at": "2022-03-03T08:48:46.051Z",
    "updated_at": "2022-03-03T08:48:46.051Z",
    "url": null,
    "template": {
      "id": "abc86b82-029a-4b74-9690-4ab607f3eafe",
      "name": "Report Test" (Teste de relatório),
      "description" (descrição): "Teste para fins de API pública",
      "created_at": "2022-03-01T15:36:42.99789+01:00",
      "updated_at": "2022-03-03T09:48:46.06885+01:00"
    }
  }
}

Observe que um valor para url ainda não está disponível. Dependendo da quantidade de dados incluídos no relatório, você pode levar vários minutos para gerar um relatório. Você solicitará a url do seu relatório na próxima etapa.

Etapa 3: Obtenha o URL do arquivo de relatório do Excel

Comando: GET /insights/learnings/report_requests/{id}

Certifique-se de usar o id para os dados na resposta da etapa 2, e não o id para o modelo!

Exemplo de resposta:

{
  "data": {
    "id": "abc23922-940d-4d6d-a6f0-ecaed00810c4",
    "status": "done",
    "created_at": "2022-03-03T08:48:46.051Z",
    "updated_at": "2022-03-03T08:48:46.839Z",
    **"url": "<https://motimate-reports-production.s3.eu-west-1.amazonaws.com/abc883af5017bcb49a6b99e71b01a0660b8f5204/report-test_1646297326.xlsx?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ABCAYLEQ6WVKO52OZP5X%2F20220303%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220303T085426Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=abc3806250e855b83fc121ea181764cc6df64481c63371004a27229acbaf98de>"**,
    "template": {
      "id": "abc86b82-029a-4b74-9690-4ab607f3eafe",
      "name": "Report Test" (Teste de relatório),
      "description" (descrição): "Teste para fins de API pública",
      "created_at": "2022-03-01T15:36:42.99789+01:00",
      "updated_at": "2022-03-03T09:48:46.70689+01:00"
    }
  }
}

Talvez você precise executar essa solicitação de forma recorrente a cada 30 segundos até obter uma resposta que inclua um valor para url. O tempo que isso leva depende de quantos dados são necessários para gerar o relatório.

Neste exemplo, o URL é https://motimate-reports-production.s3.eu-west-1.amazonaws.com/abc883af5017bcb49a6b99e71b01a0660b8f5204/report-test_1646297326.xlsx?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ABCAYLEQ6WVKO52OZP5X%2F20220303%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220303T085426Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=abc3806250e855b83fc121ea181764cc6df64481c63371004a27229acbaf98de

Ao acessar esse URL, você fará o download dos relatórios em um arquivo Excel .xlxs. No momento, não é possível extrair os dados em nenhum outro formato de arquivo, como, por exemplo, .csv.

Observação: o arquivo expirará após 10 minutos e você deverá fazer o download antes disso.

ℹ️ Se um modelo de relatório tiver sido criado por um administrador de grupo, que só tem acesso limitado aos dados de grupos e usuários selecionados, essa restrição ainda estará em vigor quando você usar a API pública do Motimate.