Lançamento de despesa

Lança uma despesa do fundo. Sem submit, ela fica em pending_submission até você enviá-la pela submissão; com submit: true, ela já é enviada para análise na mesma chamada.

Antes de lançar, veja em Tipos de despesa quais tipos exigem contrato e quais contratos aceitam o tipo. O fluxo completo está em Ciclo da despesa. O rebate de taxa de gestão usa esta mesma chamada, com regras próprias em Rebate de taxa de gestão.

Lançar despesa

Disponível em

Perfil	Host	Permissão exigida
Gestora	manager-api	Escrita
Consultoria	consultant-api	Lançar e Editar Despesas ou Enviar Consolidações

URL base de cada host: Ambientes (Hosts).

ENDPOINT

/expense/fund_class/{fund_class_key}/expense

MÉTODO

POST

Parâmetros de caminho

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

Corpo da requisição — despesa com contrato, paga na conta do fornecedor

{
    "expense_key": "b7f1c8e2-5a7d-4c7f-9a0e-2c3d4e5f6a7b",
    "expense_type": "audit_tax",
    "contract_key": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "description": "Auditoria do exercício 2026",
    "payment_value": 15000.00,
    "payment_date": "2026-11-24",
    "payment_method": "transfer",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "44.555.666/0001-81"
        },
        "vendor_bank_account_key": "0f9e8d7c-6b5a-4f3e-2d1c-0b9a8f7e6d5c"
    },
    "documents": [
        {
            "name": "memoria_de_calculo.pdf",
            "document_type": "calculation_memory",
            "document_b64": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoK..."
        }
    ],
    "consolidation_analysis_documents": [
        {
            "name": "nfe_001234.pdf",
            "document_type": "invoice",
            "document_b64": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoK..."
        }
    ],
    "submit": true
}

Corpo da requisição — despesa sem contrato, por Pix, com provisão

{
    "expense_type": "notary",
    "description": "Registro de ata em cartório",
    "payment_value": 850.00,
    "payment_date": "2026-11-30",
    "start_deferral_date": "2026-11-03",
    "end_deferral_date": "2026-11-30",
    "payment_method": "pix",
    "payment": {
        "target": {
            "name": "CARTORIO EXEMPLO",
            "document_number": "11.222.333/0001-81"
        },
        "target_pix_key": "11222333000181"
    }
}

Atributos do corpo

Campo	Tipo	Obrigatório	Descrição
expense_key	string	Não	Chave da despesa (UUID) escolhida por você. Use-a para reenviar com segurança: uma chave já usada no fundo devolve 409 (EXP000080). Sem ela, a QI Tech gera uma.
expense_type	string	Condicional	Tipo de despesa. Ver tipos. Obrigatório, exceto no rebate, que é sempre distribution_fee. Não aceita pass_through_agent_fee. Os tipos calculados pela QI Tech (cetip_tax, selic_tax, custody_tax, administration_tax, management_tax e performance_fee) são recusados com EXP000218.
contract_key	string	Condicional	Contrato do fornecedor (UUID). Obrigatório nos tipos com contrato. Proibido em notary, court_fee, cvm_tax, anbima_tax e no rebate. Os contratos que aceitam o tipo estão em Tipos de despesa.
description	string	Sim	Descrição, de 1 a 200 caracteres.
payment_value	number	Sim	Valor, maior que zero.
payment_date	string	Condicional	Data de pagamento, YYYY-MM-DD, em dia útil, de hoje em diante. Obrigatório, exceto no rebate, em que é proibido.
start_deferral_date	string	Não	Início da provisão, YYYY-MM-DD, em dia útil. Envie junto com end_deferral_date, ou nenhum dos dois. Proibido no rebate.
end_deferral_date	string	Não	Fim da provisão, YYYY-MM-DD, em dia útil, igual ou posterior ao início.
payment_method	string	Sim	transfer (TED), pix, bank_slip (boleto) ou automatic_debit (débito automático).
payment	object	Sim	Favorecido e destino do pagamento. Ver Dados de pagamento.
is_reimbursement	boolean	Não	true quando a despesa reembolsa a gestora ou a consultoria por um pagamento que ela já fez. Proibido no rebate. Padrão: false.
reimbursement_recipient	string	Condicional	manager ou consultant. Obrigatório com is_reimbursement: true.
rebated_expense_key	string	Não	Chave da taxa de gestão (management_tax) do fundo que o rebate abate. Torna a despesa um rebate. Ver Rebate de taxa de gestão.
documents	array	Não	De 1 a 20 documentos da despesa. Ver documentos no lançamento.
consolidation_analysis_documents	array	Não	De 1 a 20 documentos da análise de consolidação (nota fiscal e comprovantes).
submit	boolean	Não	true envia a despesa para análise na mesma chamada. O rebate é sempre enviado. Padrão: false.

Nenhum outro campo é aceito.

Documentos no lançamento

Cada item de documents e de consolidation_analysis_documents tem:

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome do arquivo, de 1 a 255 caracteres.
document_type	string	Sim	Tipo. Em documents: invoice, calculation_memory, contract, bank_slip, payment_receipt, evidence, extra_document, settlement_term ou variance_justification. Em consolidation_analysis_documents, os mesmos menos contract e evidence.
document_b64	string	Sim	Conteúdo em Base64, até 20 MB por arquivo.

O corpo inteiro aceita até 100 MB.

Documentos exigidos no envio, aqui ou na submissão:

• Memória de cálculo (calculation_memory), em qualquer das duas listas: sempre, inclusive no rebate.
• Comprovante de pagamento (payment_receipt), em consolidation_analysis_documents: no reembolso com a nota fiscal (ou o boleto, nos tipos sem contrato) e no reembolso de cvm_tax ou anbima_tax.

A nota fiscal (invoice) é opcional no lançamento. Enviada em consolidation_analysis_documents, ela dispensa o envio posterior da nota: a análise de consolidação é enviada junto com a despesa. Nos tipos sem contrato e no rebate, o boleto (bank_slip) também serve, em qualquer das duas listas. cvm_tax e anbima_tax não exigem nota.

Resposta

STATUS

201

A despesa, na estrutura da consulta por chave, com permission_type: owner, sem status_events e consolidation_status_events. O status é pending_submission, ou o resultado do envio quando submit é true:

Situação no envio	Status da despesa
Sem provisão, contrato active ou sem contrato	pre_approved
Com provisão (start_deferral_date e end_deferral_date)	in_manual_analysis
Sem provisão, contrato ainda em análise	pending_contract_analysis

Quando a despesa fica pre_approved ou in_manual_analysis, a análise de consolidação (consolidation_analysis.status) também vai para in_manual_analysis se:

• a nota fiscal (ou o boleto, nos tipos sem contrato) já foi enviada; ou
• o tipo é cvm_tax ou anbima_tax.

O rebate fica pre_approved, e a análise dele só anda com a da taxa de gestão. Ver Rebate de taxa de gestão.

Erros

Status	code	Quando acontece
400	QIT000001	Corpo inválido: campo obrigatório ausente, data fora do formato, campo proibido para o caso (rebate com data, por exemplo) ou campo não previsto.
400	EXP000069	A classe de fundo não é da gestora.
400	EXP000136	Um documento não é Base64 válido.
400	EXP000137	Um documento passa de 20 MB.
400	EXP000218	O tipo é calculado pela QI Tech: cetip_tax, selic_tax, custody_tax, administration_tax, management_tax ou performance_fee.
400	EXP000120	O tipo exige contrato e contract_key não foi enviado.
400	EXP000125	contract_key enviado num tipo sem contrato.
400	EXP000134	is_reimbursement: true sem reimbursement_recipient.
400	EXP000121	payment_date é anterior a hoje.
400	EXP000122	payment_date não é dia útil.
400	EXP000161	Só uma das datas de provisão foi enviada.
400	EXP000009	end_deferral_date é anterior a start_deferral_date.
400	EXP000027	Uma data de provisão não é dia útil.
400	EXP000126	O contrato não existe no fundo.
400	EXP000128	O contrato não cobre o tipo de despesa.
400	EXP000130	O contrato está reprovado ou cancelado.
400	EXP000129	O contrato está expired, amended ou em outro status que não aceita despesas.
400	EXP000131	Nesse contrato, o tipo é calculado automaticamente.
400	EXP000159	O contrato vence antes do fim da provisão (sem provisão, antes da data de pagamento).
400	EXP000178 a EXP000183, EXP000208 a EXP000211 e demais erros de payment	Ver Dados de pagamento.
400, 404	EXP000087, EXP000089, EXP000090, EXP000133, EXP000166, EXP000206, EXP000010 e demais erros de rebate	Ver Rebate de taxa de gestão.
400	EXP000138	Envio sem memória de cálculo.
400	EXP000135	Envio de reembolso sem comprovante de pagamento, com a nota fiscal (ou o boleto, nos tipos sem contrato) já enviada ou com tipo cvm_tax ou anbima_tax.
400	EXP000153	Envio: o contrato deixou de aceitar a despesa.
403	EXP000124	A consultoria não tem vínculo ativo com o fundo. Normalmente o consultant-api recusa antes, com 401 (CIT000018).
404	EXP000001	A classe de fundo não existe.
409	EXP000080	A expense_key já foi usada no fundo. Consulte a despesa existente.
413	EXP000177	O corpo passa de 100 MB.
503	EXP000132	A API não conseguiu ler o contrato. Tente de novo.

Exemplo

{
  "title": "Payment Target Must Be Contract Vendor",
  "description": "The payment target must be the vendor of the contract 0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d (document 44.555.666/0001-81).",
  "translation": "O favorecido do pagamento deve ser o fornecedor do contrato 0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d (documento 44.555.666/0001-81).",
  "code": "EXP000208"
}

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

Próximo passo

• Despesa em pending_submission: Submissão.
• Despesa pre_approved sem nota: Análise de consolidação, para enviar a nota fiscal.