Criação da Despesa

Crie uma despesa individual sob um contrato existente. A despesa contém os dados de pagamento, o período de competência e os documentos comprobatórios.

Pré-requisitos

O contrato referenciado deve existir e não pode estar no status rejected.
As datas (payment_date, start_deferral_date, end_deferral_date) devem ser dias úteis (sem fins de semana ou feriados nacionais).
start_deferral_date não pode ser posterior a end_deferral_date.
Quando o contrato possui contract_value, a soma dos valores de todas as despesas não pode ultrapassar esse limite.

Atalho para submissão

Se os documentos comprobatórios forem incluídos no campo documents durante a criação, a despesa é automaticamente encaminhada para revisão (status pending_adm_approval), sem necessidade de chamar o endpoint de submissão separadamente.

Request

ENDPOINT

/expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense

MÉTODO

POST

Path params

Parâmetro	Tipo	Descrição
`fund_class_key`	string	Chave única do fundo (UUID)
`contract_key`	string	Chave única do contrato

Request Body — Pagamento por transferência (TED/PIX)
{
    "payment_method": "transfer",
    "start_deferral_date": "2026-06-02",
    "end_deferral_date": "2026-06-30",
    "description": "Honorários de auditoria referente ao 1º semestre de 2026",
    "payment_value": 15000.00,
    "payment_date": "2026-07-01",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_account": {
            "account_number": "123456",
            "account_branch": "0001",
            "account_digit": "0",
            "financial_institution_code": "341"
        },
        "transfer_type": "wire_transfer",
        "source_account": {
            "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e"
        }
    },
    "documents": [
        {
            "name": "NF-e 001234",
            "document_type": "invoice",
            "document_b64": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoK..."
        }
    ]
}

Request Body — Pagamento por boleto
{
    "payment_method": "bank_slip",
    "start_deferral_date": "2026-06-02",
    "end_deferral_date": "2026-06-30",
    "description": "Taxa de custódia - junho/2026",
    "payment_value": 3500.00,
    "payment_date": "2026-07-01",
    "payment": {
        "target": {
            "name": "CUSTODIANTE EXEMPLO S.A.",
            "document_number": "98.765.432/0001-10"
        },
        "bank_slip": {
            "digitable_line": "34191.09008 63521.510047 91020.150008 1 10010000035000"
        },
        "source_account": {
            "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e"
        }
    }
}

Atributos do body

Campo	Tipo	Obrigatoriedade	Descrição
`payment_method`	string	obrigatório	Método de pagamento: `transfer`, `automatic_debit` ou `bank_slip`.
`start_deferral_date`	string	obrigatório	Data início da competência no formato `YYYY-MM-DD`. Deve ser dia útil.
`end_deferral_date`	string	obrigatório	Data fim da competência no formato `YYYY-MM-DD`. Deve ser dia útil e ≥ `start_deferral_date`.
`description`	string	obrigatório	Descrição da despesa. Máximo de 200 caracteres.
`payment_value`	number	obrigatório	Valor da despesa. Mínimo: `0`.
`payment_date`	string	obrigatório	Data de pagamento no formato `YYYY-MM-DD`. Deve ser dia útil.
`payment`	object	obrigatório	Dados do pagamento. Ver Atributos de `payment`.
`documents`	array	opcional	Lista de documentos comprobatórios. Quando informado, a despesa é automaticamente encaminhada para revisão. Ver Atributos de `documents`.

Atributos de `payment`

Campo	Tipo	Obrigatoriedade	Descrição
`target`	object	obrigatório	Dados do beneficiário.
`target.name`	string	obrigatório	Nome do beneficiário.
`target.document_number`	string	obrigatório	CPF (`###.###.###-##`) ou CNPJ (`##.###.###/####-##`) do beneficiário.
`target_account`	object	condicional	Dados da conta bancária de destino. Obrigatório para `payment_method = transfer`.
`target_account.account_number`	string	obrigatório	Número da conta (1-20 dígitos, não pode ser todos zeros).
`target_account.account_branch`	string	obrigatório	Agência (exatamente 4 dígitos, não pode ser todos zeros).
`target_account.account_digit`	string	obrigatório	Dígito verificador (1 dígito).
`target_account.financial_institution_code`	string	obrigatório	Código do banco (exatamente 3 dígitos, não pode ser todos zeros).
`target_account.financial_institution_ispb`	string	opcional	ISPB do banco (exatamente 8 dígitos).
`target_account.account_type`	string	opcional	Tipo da conta bancária.
`transfer_type`	string	condicional	Tipo de transferência: `pix` ou `wire_transfer`. Necessário para `payment_method = transfer`.
`target_pix_key`	string	condicional	Chave PIX do beneficiário (1-77 caracteres). Obrigatório quando `transfer_type = pix`.
`pix_qrcode`	string	opcional	QR Code PIX (1-255 caracteres).
`bank_slip`	object	condicional	Dados do boleto. Obrigatório para `payment_method = bank_slip`.
`bank_slip.digitable_line`	string	obrigatório	Linha digitável do boleto (47-48 caracteres).
`source_account`	object	opcional	Conta de débito de origem do pagamento.
`source_account.account_key`	string	obrigatório	Chave única da conta de origem (UUID).
`conciliation_metadata`	object	opcional	Metadados de conciliação.
`conciliation_metadata.fee_type`	string	opcional	Tipo de taxa para conciliação.
`conciliation_metadata.conciliation_value`	string	opcional	Valor de conciliação.
`conciliation_metadata.conciliation_field`	string	opcional	Campo de conciliação.

Atributos de `documents`

Campo	Tipo	Obrigatoriedade	Descrição
`name`	string	obrigatório	Nome do documento. Máximo de 255 caracteres.
`document_type`	string	obrigatório	Tipo do documento: `invoice` (NF), `calculation_memory` (memória de cálculo), `contract` (contrato) ou `bank_slip` (boleto).
`document_b64`	string	obrigatório	Conteúdo do documento codificado em Base64.

Response

STATUS

201

Response Body
{
    "expense_key": "7f3e9a1b-2c4d-5e6f-8901-abcdef234567",
    "contract_key": "contrato-auditoria-2026",
    "status": "pending_adm_approval",
    "payment_method": "transfer",
    "start_deferral_date": "2026-06-02",
    "end_deferral_date": "2026-06-30",
    "description": "Honorários de auditoria referente ao 1º semestre de 2026",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_account": {
            "account_number": "123456",
            "account_branch": "0001",
            "account_digit": "0",
            "financial_institution_code": "341"
        },
        "transfer_type": "wire_transfer",
        "source_account": {
            "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e"
        }
    },
    "payment_value": 15000.00,
    "payment_date": "2026-07-01",
    "rebate_expense_key": null,
    "fund_class": {
        "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO",
        "manager": {
            "name": "EXEMPLO GESTORA LTDA",
            "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
            "document_number": "45.585.471/0001-47"
        },
        "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
        "document_number": "60.910.091/0001-24"
    }
}

Atributos da resposta

Campo	Tipo	Descrição
`expense_key`	string	Chave única da despesa (UUID). Guarde este valor para as próximas etapas.
`contract_key`	string	Chave do contrato ao qual a despesa pertence.
`status`	string	Status da despesa. Será `pending_adm_approval` se documentos foram incluídos na criação, ou `created` caso contrário.
`payment_method`	string	Método de pagamento da despesa.
`start_deferral_date`	string	Data início de competência no formato `YYYY-MM-DD`.
`end_deferral_date`	string	Data fim de competência no formato `YYYY-MM-DD`.
`description`	string	Descrição da despesa.
`payment`	object	Dados do pagamento conforme enviado na criação.
`payment_value`	number	Valor da despesa.
`payment_date`	string	Data de pagamento no formato `YYYY-MM-DD`.
`rebate_expense_key`	string	Chave da despesa original quando se tratar de um rebate, ou `null`.
`fund_class`	object	Dados do fundo associado.

Possíveis erros

STATUS

404

Contrato não encontrado

O par fund_class_key + contract_key não corresponde a nenhum contrato cadastrado.

{
  "title": "Contract Not Found",
  "description": "Contract with key {contract_key} and fund class {fund_class_key} was not found.",
  "translation": "O contrato com chave {contract_key} do fundo {fund_class_key} não foi encontrado.",
  "code": "ESB000011"
}

STATUS

400

Contrato rejeitado

Não é possível criar despesas em um contrato com status rejected.

{
  "title": "Cannot Create Expense On Rejected Contract",
  "description": "Cannot create expense on rejected contract {contract_key}.",
  "translation": "Não é possível criar despesa no contrato rejeitado {contract_key}.",
  "code": "ESB000035"
}

Contrato vencido

A data de validade do contrato já passou. Não é possível criar novas despesas.

{
  "title": "Contract Expired",
  "description": "Contract {contract_key} has expired.",
  "translation": "O contrato {contract_key} está vencido.",
  "code": "ESB000029"
}

Soma das despesas excede o valor do contrato

A soma dos valores de todas as despesas ultrapassaria o contract_value definido no contrato.

{
  "title": "Expense Value Sum Greater Than Contract",
  "description": "The sum of expense values exceeds the contract value for {contract_name}.",
  "translation": "A soma dos valores das despesas excede o valor do contrato {contract_name}.",
  "code": "ESB000030"
}

Data inválida (não é dia útil)

A data informada em payment_date, start_deferral_date ou end_deferral_date não é um dia útil.

{
  "title": "Date Invalid For Expense Creation",
  "description": "The date {date} is not a valid workday for expense creation.",
  "translation": "A data {date} não é um dia útil válido para criação de despesa.",
  "code": "ESB000032"
}

Data início posterior à data fim de competência

O campo start_deferral_date é posterior ao end_deferral_date.

{
  "title": "Start Deferral Date Greater Than End Deferral Date",
  "description": "The start deferral date {start_date} is greater than the end deferral date {end_date}.",
  "translation": "A data de início de competência {start_date} é maior que a data de fim de competência {end_date}.",
  "code": "ESB000033"
}

Próximos passos

Se os documentos foram incluídos na criação (status pending_adm_approval): aguarde a análise da QI Tech.
Se os documentos não foram incluídos (status created):
1. Upload de documentos — adicione ao menos um documento antes de submeter.
2. Submeter a despesa — encaminhe para análise da QI Tech.

Request​

Path params​

Atributos do body​

Atributos de payment​

Atributos de documents​

Response​

Atributos da resposta​

Possíveis erros​

Próximos passos​

Request

Path params

Atributos do body

Atributos de `payment`

Atributos de `documents`

Response

Atributos da resposta

Possíveis erros

Próximos passos