Despesas recorrentes

Uma despesa recorrente gera automaticamente uma despesa por período. Pela API, as recorrências só são consultadas. Elas vêm de dois lugares:

• Contrato: nascem das recurrences do contrato de despesa quando ele entra em vigor.
• QI Tech: as demais são cadastradas pela QI Tech.

Status da recorrência

Status	Descrição
active	Gerando despesas.
pending_approval	Aguardando aprovação da QI Tech.
finished	Chegou ao fim (end_date).
canceled	Encerrada antes do fim.
reproved	Reprovada pela QI Tech.

Listar despesas recorrentes

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}/recurring_expenses

MÉTODO

GET

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
status	string	Não	Um status da recorrência.
expense_type	string	Não	Um tipo de despesa.
contract_key	string	Não	Recorrências de um contrato.
limit	integer	Não	Itens por página, de 0 a 100. Padrão: 10.
page	integer	Não	Página, a partir de 0. Padrão: 0.

A lista vem da recorrência mais recente para a mais antiga.

STATUS

200

Corpo da resposta

{
    "data": [
        {
            "recurring_expense_key": "a0b1c2d3-e4f5-4a6b-8c7d-9e0f1a2b3c4d",
            "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"
            },
            "expense_type": "audit_tax",
            "description": "Auditoria anual - parcela mensal",
            "recurring_configuration_data": {
                "expense_type": "audit_tax",
                "description": "Auditoria anual - parcela mensal",
                "amount": 2500.0,
                "accrual": {
                    "accrual_system": "monthly"
                },
                "consolidated_by_manager": true,
                "payment": {
                    "payment_reference": {
                        "reference_date": "end_date",
                        "workdays_only": true
                    },
                    "target": {
                        "document_number": "44.555.666/0001-81",
                        "name": "AUDITORES EXEMPLO S.A."
                    }
                },
                "start_date": "2027-01-01",
                "end_date": "2027-12-31",
                "contract_key": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
                "vendor_key": "5d2e7b9a-3c4f-4e8a-b1d6-9f0a2c3e4b57"
            },
            "amount": 2500.0,
            "consolidated_by_manager": true,
            "status": "active",
            "contract_key": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
            "vendor_key": "5d2e7b9a-3c4f-4e8a-b1d6-9f0a2c3e4b57",
            "start_date": "2027-01-01",
            "end_date": "2027-12-31"
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}

Campo	Descrição
recurring_expense_key	Chave da recorrência (UUID).
fund_class	Classe de fundo, como na consulta de despesas.
expense_type	Tipo das despesas geradas.
description	Descrição das despesas geradas.
recurring_configuration_data	Configuração da recorrência como foi cadastrada. Ver abaixo.
amount	Valor de cada despesa.
consolidated_by_manager	true quando a gestora envia a nota fiscal de cada despesa gerada.
status	Status da recorrência.
contract_key, vendor_key	Contrato e fornecedor, ou null.
start_date, end_date	Vigência, YYYY-MM-DD; end_date null sem fim.
disabled_at	Momento do encerramento. Presente só em recorrências encerradas.

Configuração da recorrência

Em recurring_configuration_data:

• accrual define o período: accrual_system (monthly, bimonthly ou yearly) e start_month.
• payment.payment_reference define a data de pagamento de cada despesa: reference_date (start_date ou end_date do período), workdays_only, days_after e months_after.
• payment traz o favorecido e, nas recorrências sem contrato, o meio e o destino do pagamento.

Nas recorrências de contrato, cada despesa é paga ao fornecedor, na conta principal dele, no último dia útil do mês.

Consultar despesa recorrente

Devolve uma recorrência e as despesas geradas por ela.

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}/recurring_expense/{recurring_expense_key}

MÉTODO

GET

A resposta tem a estrutura da lista, com mais um campo: expenses, as despesas geradas pela recorrência (expense_key, status).

Erros

Status	code	Quando acontece
400	EXP000069	A classe de fundo não é da gestora.
403	EXP000124	A consultoria não tem vínculo ativo com o fundo. Normalmente o consultant-api recusa antes, com 401 (CIT000018).
404	EXP000028	A recorrência não existe no fundo.
500	QIT000500	limit ou page fora do intervalo ou não inteiro. A validação desses parâmetros chega como erro interno: corrija o parâmetro e repita a chamada.

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