Exportando relatórios de contratos

Este documento descreve como extrair o relatório geral de contratos da sua organização através da API.

Relatório geral

O relatório geral de contratos é um arquivo XLSX que contém todos os contratos da organização, incluindo dados básicos (datas de vigência, status, valor, participantes) e os campos personalizados (informações) de cada contrato.

Para extraí-lo, utilize a query Report_extractContractsReport. A query não recebe parâmetros e exige permissão de administrador da organização — portanto, o token utilizado precisa ter sido gerado por um usuário administrador (veja Token de autenticação).

Retorno

A query retorna um objeto que pode ser de dois tipos:

Sucesso (Report_ExtractContractsReport_Output_Success)

Propriedade	Tipo	Descrição
urlToDownloadFile	String	URL assinada para download do arquivo XLSX. Expira em 1 hora após a geração.

Falha (Report_ExtractContractsReport_Output_Failures)

Propriedade	Tipo	Descrição
failures	Array	Array contendo informações sobre a falha

Query

query {
  result: Report_extractContractsReport {
    ... on Report_ExtractContractsReport_Output_Success {
      urlToDownloadFile
    }
    ... on Report_ExtractContractsReport_Output_Failures {
      failures {
        ... on Error {
          message
        }
      }
    }
  }
}

JavaScript

async function extractContractsReport() {
  const response = await fetch('https://core-api.linte.com/graphql', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'key': '<seu-token>'
    },
    body: JSON.stringify({
      query: `
        query {
          result: Report_extractContractsReport {
            ... on Report_ExtractContractsReport_Output_Success {
              urlToDownloadFile
            }
            ... on Report_ExtractContractsReport_Output_Failures {
              failures {
                ... on Error {
                  message
                }
              }
            }
          }
        }
      `
    })
  });

  const result = await response.json();
  console.log(result);
}

extractContractsReport();

Python

import requests

def extract_contracts_report():
    response = requests.post(
        'https://core-api.linte.com/graphql',
        headers={
            'Content-Type': 'application/json',
            'key': '<seu-token>'
        },
        json={
            'query': '''
                query {
                  result: Report_extractContractsReport {
                    ... on Report_ExtractContractsReport_Output_Success {
                      urlToDownloadFile
                    }
                    ... on Report_ExtractContractsReport_Output_Failures {
                      failures {
                        ... on Error {
                          message
                        }
                      }
                    }
                  }
                }
            '''
        }
    )

    print(response.json())

if __name__ == '__main__':
    extract_contracts_report()

Estrutura do arquivo gerado

O arquivo é um XLSX com uma única aba chamada report. As colunas seguem a ordem abaixo:

Coluna	Descrição	Tipo
ID	ID/código do contrato	String (ex.: VIV-000123)
Categoria	Indica se é um contrato Principal ou um Aditivo*	String
Tipo	Tipo do contrato	String
Criado em	Data de criação do contrato	Data (DD/MM/YYYY)
Criado por	Nome do usuário que criou o contrato	String
Início da vigência	Data de início da vigência	Data (DD/MM/YYYY) ou Indeterminado
Fim da vigência	Data de fim da vigência	Data (DD/MM/YYYY) ou Indeterminado
ID do contrato principal	Quando for aditivo, ID do contrato principal*	String
Área solicitante	Área solicitante	String
Valor	Valor do contrato	Número
Criado a partir da demanda	ID da demanda que originou o contrato (se aplicável)	String
Status	Status atual do contrato	String
Categoria do status	Categoria do status	String
Participantes	Lista de participantes do contrato	String
Grupos participantes	Lista de grupos participantes	String

*As colunas Categoria e ID do contrato principal aparecem apenas quando a feature flag de aditivos contratuais está habilitada para a organização.

INFO

Após as colunas padrão, o relatório inclui automaticamente uma coluna por campo personalizado (informação) existente nos contratos. Campos com sub-campos (filhos) aparecem agrupados logo após o campo pai.

WARNING

A urlToDownloadFile retornada é temporária e expira em 1 hora. Por isso, em integrações automatizadas (ex.: ferramentas de BI), sempre chame a query novamente a cada atualização para obter uma URL fresca antes de baixar o arquivo.