Consulta de despesas

Lista as despesas de um fundo ou de todos os fundos da gestora. A lista traz todas as despesas do fundo: as lançadas pela gestora ou consultoria, inclusive as que ainda estão em análise, e as calculadas pela QI Tech. Para a consultoria, ela traz só as lançadas por agentes (expense_contract, expense, reimbursement e rebate_fee).

Status e origens: Ciclo da despesa.
Uma despesa pela chave, com documentos e histórico: Consulta de despesa por chave.

Listar despesas do fundo

Disponível em

Perfil	Host	Permissão exigida
Gestora	`manager-api`	Leitura
Consultoria	`consultant-api`	Ler Despesas ou Ler Consolidações

URL base de cada host: Ambientes (Hosts).

ENDPOINT

/expense/fund_class/{fund_class_key}/expenses

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

Todos opcionais. Parâmetros marcados como lista aceitam vários valores separados por vírgula.

Parâmetro	Tipo	Descrição
`page`	integer	Página, a partir de `0`. Padrão: `0`.
`limit`	integer	Itens por página, de `0` a `100`. Padrão: `10`.
`status`	lista	Status da despesa. Valor desconhecido não dá erro; só não encontra nada.
`expense_status_to_ignore`	string	Exclui um status.
`expense_type`	lista	Tipos de despesa.
`expense_type_to_ignore`	lista	Exclui tipos de despesa.
`origin_type`	lista	Origens da despesa.
`exclude_origin_type`	lista	Exclui origens. Use `rebate_fee` para esconder os rebates.
`reference_date`	string	Data de referência exata, `YYYY-MM-DD`.
`from_end_deferral_date`	string	`end_deferral_date` a partir desta data, `YYYY-MM-DD`.
`to_end_deferral_date`	string	`end_deferral_date` até esta data, `YYYY-MM-DD`.
`payment_date_start`	string	Data de pagamento a partir desta data, `YYYY-MM-DD`.
`payment_date_end`	string	Data de pagamento até esta data, `YYYY-MM-DD`. Não pode ser anterior a `payment_date_start`.
`ignore_paid_on_future`	boolean	`true` exclui despesas com pagamento confirmado depois da data de referência.
`contract_key`	string	Despesas de um contrato.
`vendor_key`	string	Despesas do fornecedor do contrato.
`recipient_name`	string	Parte do nome do fornecedor do contrato ou do favorecido do pagamento.
`recipient_document`	string	Parte do CPF ou CNPJ do fornecedor ou do favorecido, com ou sem pontuação.
`rebated_expense_key`	string	Rebates de uma taxa de gestão.
`created_by_agent_type`	string	`manager` ou `consultant`: quem lançou a despesa.
`permission_type`	string	`owner` ou `viewer`: a permissão de quem consulta sobre a despesa. Só traz despesas lançadas pela gestora ou consultoria.
`description`	string	Parte da descrição.
`kpi`	string	Indicador: `in_analysis`, `in_provision` ou `pending_invoice`. Exclui despesas canceladas e rebates.
`days`	integer	Período do `kpi`, contando hoje: `1`, `7` ou `30`.

A lista vem da despesa mais recente para a mais antiga.

Exemplo de chamada
GET /expense/fund_class/{fund_class_key}/expenses?status=consolidated,paid&exclude_origin_type=rebate_fee&limit=50

Resposta

STATUS

200

Corpo da resposta
{
    "data": [
        {
            "expense_key": "b7f1c8e2-5a7d-4c7f-9a0e-2c3d4e5f6a7b",
            "fund_class": {
                "name": "FIDC EXEMPLO",
                "manager": {
                    "name": "EXEMPLO GESTORA LTDA",
                    "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
                    "document_number": "22.333.444/0001-81"
                },
                "fund_class_key": "c1d2e3f4-a5b6-4789-abcd-ef1234567890",
                "document_number": "33.444.555/0001-81",
                "accounting_date": "2026-11-06"
            },
            "status": "consolidated",
            "type": "audit_tax",
            "origin": {
                "origin_type": "expense_contract",
                "origin_key": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
            },
            "payment_value": 15000.0,
            "created_by": {
                "agent_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
                "agent_type": "manager",
                "name": "EXEMPLO GESTORA LTDA"
            },
            "reference_date": "2026-11-06",
            "start_deferral_date": null,
            "end_deferral_date": null,
            "consolidated_value": 15000.0,
            "provisioned_value": null,
            "recognized_value": 15000.0,
            "payment": {
                "target": {
                    "name": "AUDITORES EXEMPLO S.A.",
                    "document_number": "44.555.666/0001-81"
                },
                "target_account": {
                    "account_number": "123456",
                    "account_branch": "0001",
                    "account_digit": "7",
                    "financial_institution_code": "341",
                    "financial_institution_ispb": "60701190"
                }
            },
            "expense_datetime": "2026-11-03T14:03:21Z",
            "last_updated": "2026-11-06T10:15:40Z",
            "description": "Auditoria do exercício 2026",
            "payment_method": "transfer",
            "payment_date": "2026-11-20",
            "consolidation_analysis": {
                "consolidation_analysis_key": "e3f4a5b6-c7d8-4e9f-8a0b-1c2d3e4f5a6b",
                "analysis_number": 1,
                "status": "approved"
            },
            "contract": {
                "contract_key": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
                "name": "Auditoria 2026",
                "status": "active",
                "vendor": {
                    "vendor_key": "5d2e7b9a-3c4f-4e8a-b1d6-9f0a2c3e4b57",
                    "name": "AUDITORES EXEMPLO S.A."
                }
            },
            "rebate": false,
            "rebated_expense_key": null,
            "permission_type": "owner"
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}

Atributos de cada despesa

Campo	Tipo	Descrição
`expense_key`	string	Chave da despesa (UUID).
`fund_class`	object	Classe de fundo: `name`, `fund_class_key`, `document_number`, `accounting_date` (data contábil atual, `YYYY-MM-DD`) e `manager` (`name`, `manager_key`, `document_number`).
`status`	string	Status da despesa. Ver status.
`type`	string	Tipo da despesa. Ver tipos.
`origin`	object	`origin_type` e `origin_key`. Ver origem.
`payment_value`	number	Valor a pagar, ou `null`.
`created_by`	object	Quem lançou: `agent_key`, `agent_type` (`manager` ou `consultant`), `name`. `null` para despesas calculadas pela QI Tech.
`reference_date`	string	Data em que a despesa entrou na carteira, `YYYY-MM-DD`, ou `null` enquanto está na etapa de submissão.
`start_deferral_date`	string	Início da provisão, `YYYY-MM-DD`, ou `null`.
`end_deferral_date`	string	Fim da provisão, `YYYY-MM-DD`, ou `null`.
`consolidated_value`	number	Valor consolidado, ou `null`.
`provisioned_value`	number	Valor provisionado, ou `null`.
`recognized_value`	number	Valor já reconhecido na carteira.
`payment`	object	Dados de pagamento: `target` (`name`, `document_number`) e, conforme o meio de pagamento, `target_account`, `target_pix_key`, `pix_qrcode`, `bank_slip`, `source_account`, `vendor_bank_account_key`, `conciliation_metadata`. Pode vir vazio (`{}`).
`expense_datetime`	string	Criação, ISO 8601 em UTC (`2026-11-03T14:03:21Z`).
`last_updated`	string	Última alteração da despesa ou da análise, ISO 8601 em UTC.
`description`	string	Descrição.
`payment_method`	string	`transfer`, `pix`, `bank_slip` ou `automatic_debit`, ou `null`.
`payment_date`	string	Data de pagamento, `YYYY-MM-DD`. Presente só quando definida.
`payment_confirmation`	object	`confirmation_date` (`YYYY-MM-DD`). Presente só depois do pagamento.
`consolidation_analysis`	object	Análise de consolidação vigente: `consolidation_analysis_key`, `analysis_number`, `status`. Ver análise de consolidação.
`contract`	object	Contrato da despesa: `contract_key`, `name`, `status`, `vendor` (`vendor_key`, `name`). `null` sem contrato.
`rebate`	boolean	`true` quando a despesa é um rebate de taxa de gestão.
`rebated_expense_key`	string	Taxa de gestão do rebate, ou `null`.
`permission_type`	string	`owner` quando quem consulta lançou a despesa; `viewer` quando outro agente lançou (para a gestora, a consultoria). `null` para despesas calculadas pela QI Tech.
`gross_provisioned_value`	number	Só em `management_tax`: o valor provisionado da taxa, que os rebates não reduzem (`0` sem provisionado).
`approved_rebate_value`	number	Só em `management_tax`: soma dos rebates com análise aprovada.

Listar despesas de todos os fundos

Lista as despesas de todos os fundos da gestora, com a mesma resposta da lista do fundo.

Disponível em

Perfil	Host	Permissão exigida
Gestora	`manager-api`	Leitura

URL base de cada host: Ambientes (Hosts).

ENDPOINT

/expense/expenses

MÉTODO

GET

Aceita os mesmos filtros da lista do fundo, exceto reference_date, from_end_deferral_date, to_end_deferral_date e ignore_paid_on_future, que são ignorados. Tem dois parâmetros a mais:

Parâmetro	Tipo	Descrição
`fund_class_key`	string	Restringe a esses fundos. Repetível: `fund_class_key=...&fund_class_key=...`.
`payment_date`	string	Data de pagamento exata, `YYYY-MM-DD`.

Exemplo de chamada
GET /expense/expenses?fund_class_key={fund_class_key_1}&fund_class_key={fund_class_key_2}&payment_date=2026-11-20

Erros

Status	`code`	Quando acontece
400	`EXP000069`	A classe de fundo não é da gestora.
400	`EXP000186`	`created_by_agent_type`, `permission_type` ou `kpi` com valor fora da lista, ou `payment_date_end` anterior a `payment_date_start`.
400	`EXP000185`	`days` diferente de `1`, `7` e `30` (filtro `kpi`).
404	`EXP000018`	Lista de todos os fundos: a gestora não tem fundos no serviço de despesas.
500	`QIT000500`	`limit` ou `page` fora do intervalo, data fora do formato `YYYY-MM-DD` ou booleano inválido (`ignore_paid_on_future`). A validação desses parâmetros chega como erro interno: corrija o parâmetro e repita a chamada.

Exemplo
{
  "title": "Manager Not Associated with Fund Class",
  "description": "Manager with key a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c is not associated with Fund Class with key c1d2e3f4-a5b6-4789-abcd-ef1234567890.",
  "translation": "Gestor com chave a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c nao esta associado com Fundo com chave c1d2e3f4-a5b6-4789-abcd-ef1234567890.",
  "code": "EXP000069"
}

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

Listar despesas do fundo​

Parâmetros de caminho​

Parâmetros de consulta​

Resposta​

Atributos de cada despesa​

Listar despesas de todos os fundos​

Erros​