Consulta de contratos

Chamadas de leitura dos contratos de despesa:

Consultar contrato por chave: um contrato, com histórico de status e links de download.
Listar contratos do fundo e de todos os fundos: listas paginadas, com filtros.
Resumo de contratos: quantidade de contratos por status.
Histórico de aditivos: o contrato original e seus aditivos.

Consultar contrato por chave

Devolve o contrato com o histórico de status e os links para baixar o documento e os anexos.

Disponível em

Perfil	Host	Permissão exigida
Gestora	`manager-api`	Leitura
Consultoria	`consultant-api`	Ler Contratos de Despesa

URL base de cada host: Ambientes (Hosts).

ENDPOINT

/expense_contract/fund_class/{fund_class_key}/contract/{contract_key}

MÉTODO

GET

Parâmetros de caminho

Parâmetro	Tipo	Descrição
`fund_class_key`	string	Chave da classe de fundo (UUID).
`contract_key`	string	Chave do contrato (UUID).

Resposta

STATUS

200

O contrato, na estrutura descrita em atributos do contrato, com os campos adicionais abaixo.

Trecho da resposta
{
    "contract_key": "3f2b8c1e-7d4a-4e9b-9a61-0c5d2e8f4b17",
    "status": "in_manual_analysis",
    "ai_analysis": {
        "ai_analysis_key": "7c8d9e0f-1a2b-4c3d-9e4f-5a6b7c8d9e0f",
        "status": "valid",
        "analysis_result": {
            "document_numbers": {
                "fund_class": "33.444.555/0001-81",
                "vendor": "44.555.666/0001-81"
            },
            "expense_types": ["audit_tax"],
            "expiration_date": "2027-12-31",
            "recurrences": [
                {
                    "expense_type": "audit_tax",
                    "amount": 2500.0,
                    "start_date": "2027-01-01",
                    "end_date": "2027-12-31",
                    "periodicity": "monthly"
                }
            ],
            "prohibited_clauses": []
        }
    },
    "attachments": [
        {
            "attachment_key": "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f7a",
            "status": "active",
            "created_at": "2026-11-09T14:20:11.004512",
            "download_url": "https://<link-temporario-de-download>"
        }
    ],
    "status_events": [
        {
            "status": "created",
            "event_datetime": "2026-11-09T14:03:22.498765",
            "author_type": "qitech",
            "author_name": null
        },
        {
            "status": "pending_submission",
            "event_datetime": "2026-11-09T14:03:22.498901",
            "author_type": "qitech",
            "author_name": null
        },
        {
            "status": "sent_to_analysis",
            "event_datetime": "2026-11-09T14:10:05.120034",
            "author_type": "qitech",
            "author_name": null
        },
        {
            "status": "in_manual_analysis",
            "event_datetime": "2026-11-09T14:11:40.774210",
            "author_type": "qitech",
            "author_name": null
        }
    ],
    "download_url": "https://<link-temporario-de-download>",
    "signed_download_url": null
}

Campo	Tipo	Descrição
`status_events`	array	Mudanças de status. Cada item traz `status`, `event_datetime`, `author_type` e `author_name`. Ver autoria abaixo.
`download_url`	string	URL para baixar o documento do contrato, válida por 24 horas. Antes do envio para análise, aponta para o último arquivo enviado; depois, para o documento congelado. Vem preenchida mesmo que nenhum arquivo tenha sido enviado.
`signed_download_url`	string	URL para baixar o documento assinado, válida por 24 horas, ou `null` enquanto ele não existe.
`attachments[].download_url`	string	URL para baixar cada anexo, válida por 24 horas.
`ai_analysis.analysis_result`	object	Dados lidos do documento: `document_numbers` (`fund_class`, `vendor`), `expense_types`, `expiration_date`, `recurrences` e `prohibited_clauses`. `null` enquanto a leitura não termina ou quando ela falha.

Autoria em status_events:

author_type manager ou consultant, com o nome em author_name: ação de um usuário do portal.
author_type qitech, com author_name: null: todos os demais casos, inclusive chamadas pela API com chave de integração.

ai_analysis.status: inconclusive indica divergência entre o documento e os dados do contrato. Quem decide é a análise da QI Tech.

Listar contratos do fundo

Lista os contratos de um fundo, com filtros e paginação.

Disponível em

Perfil	Host	Permissão exigida
Gestora	`manager-api`	Leitura
Consultoria	`consultant-api`	Ler Contratos de Despesa

URL base de cada host: Ambientes (Hosts).

ENDPOINT

/expense_contract/fund_class/{fund_class_key}/contracts

MÉTODO

GET

Parâmetros de caminho

Parâmetro	Tipo	Descrição
`fund_class_key`	string	Chave da classe de fundo (UUID).

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
`status`	string	Não	Status do contrato. Aceita vários valores separados por vírgula. Um valor desconhecido não dá erro e não encontra nenhum contrato.
`expense_type`	string	Não	Contratos que declaram este tipo de despesa.
`vendor_key`	string	Não	Contratos deste fornecedor.
`termination_status`	string	Não	Contratos com pedido de distrato neste status: `pending_analysis`, `approved` ou `reproved`.
`limit`	integer	Não	Itens por página, de `1` a `100`. Padrão: `10`.
`page`	integer	Não	Página, a partir de `0`. Padrão: `0`.

Resposta

STATUS

200

Corpo da resposta
{
    "data": [],
    "limit": 10,
    "page": 0,
    "is_last_page": true,
    "total": 0
}

Cada item de data é um contrato na estrutura de atributos do contrato, sem status_events nem links de download. total é o número de contratos que atendem aos filtros.

A lista vem do contrato mais recente para o mais antigo e traz cada versão da cadeia como um item separado: o contrato substituído (amended), os aditivos reprovados ou cancelados e o aditivo vigente. Num aditivo, amended_contract_key indica o contrato que ele substitui.

Listar contratos de todos os fundos

Lista os contratos de todos os fundos da gestora. Na consultoria, só dos fundos em que ela tem a permissão Ler Contratos de Despesa.

Aceita os mesmos filtros e devolve a mesma resposta da lista do fundo. O parâmetro adicional fund_class_key restringe a um fundo; um fundo fora desse escopo devolve lista vazia.

ENDPOINT

/expense_contract/contracts

MÉTODO

GET

Permissão: Gestora (manager-api): Leitura. Consultoria (consultant-api): integração ativa; o resultado traz só os fundos em que ela tem Ler Contratos de Despesa.

Resumo de contratos

Conta os contratos criados no período, agrupados pelo status atual.

ENDPOINT

/expense_contract/contracts/summary

MÉTODO

GET

Permissão: Gestora (manager-api): Leitura. Consultoria (consultant-api): integração ativa; o resultado traz só os fundos em que ela tem Ler Contratos de Despesa.

Parâmetro	Tipo	Obrigatório	Descrição
`fund_class_key`	string	Não	Restringe a um fundo.
`date_range_start`	string	Não	Início do período de criação, `YYYY-MM-DD`.
`date_range_end`	string	Não	Fim do período de criação, `YYYY-MM-DD`.

Sem as duas datas, o período vai do primeiro dia do mês corrente até hoje. Uma data enviada sozinha é ignorada.
O escopo de fundos é o mesmo da lista de todos os fundos. Um fund_class_key fora dele devolve as contagens zeradas.

Corpo da resposta
{
    "period": {
        "start": "2026-11-01",
        "end": "2026-11-09"
    },
    "contracts": {
        "total": 7,
        "pending_submission": 2,
        "pending_vendor_approval": 0,
        "sent_to_analysis": 1,
        "in_compliance_analysis": 0,
        "in_manual_analysis": 1,
        "pending_manager_approval": 0,
        "pending_signature": 1,
        "active": 2,
        "expired": 0,
        "amended": 0,
        "reproved": 0,
        "canceled": 0
    }
}

Histórico de aditivos

Devolve o contrato original e todos os aditivos da cadeia, do mais antigo para o mais recente. Funciona a partir de qualquer contrato da cadeia.

ENDPOINT

/expense_contract/fund_class/{fund_class_key}/contract/{contract_key}/history

MÉTODO

GET

Permissão: Gestora (manager-api): Leitura. Consultoria (consultant-api): Ler Contratos de Despesa.

A resposta é {"data": [...]}, sem paginação, com os contratos na estrutura de atributos do contrato.

Erros

Status	`code`	Quando acontece
400	`QIT000010`	`limit`, `page` ou data fora do formato.
400	`ECT000067`	Resumo: `date_range_start` posterior a `date_range_end`.
404	`ECT000005`	A classe de fundo não existe ou você não tem acesso a ela.
404	`ECT000009`	O contrato não existe nessa classe de fundo.
404	`ECT000001`	Lista de todos os fundos ou resumo: a gestora ou a consultoria ainda não está cadastrada no serviço de contratos.

Erros de autenticação, permissão e host: veja Erros da API.

Consultar contrato por chave​

Parâmetros de caminho​

Resposta​

Listar contratos do fundo​

Parâmetros de caminho​

Parâmetros de consulta​

Resposta​

Listar contratos de todos os fundos​

Resumo de contratos​

Histórico de aditivos​

Erros​

Consultar contrato por chave

Parâmetros de caminho

Resposta

Listar contratos do fundo

Parâmetros de caminho

Parâmetros de consulta

Resposta

Listar contratos de todos os fundos

Resumo de contratos

Histórico de aditivos

Erros