Criação do Lote de Pagamento

Este é o primeiro passo do fluxo de liquidação de ativos. A criação do lote de pagamento reserva um agrupamento onde as liquidações que serão processadas serão inseridas nas etapas seguintes.

Disponível em

Perfil	Host	Permissão exigida
Gestora	manager-api	Escrita
Consultoria	consultant-api	Criar Lotes
Cedente	assignor-api	Escrita

URL base de cada host: Ambientes (Hosts).

Pré-requisitos

Antes de criar um lote, você precisa ter em mãos a fund_class_key — chave única do fundo no qual os ativos serão liquidados. Essa chave compõe o endpoint utilizado em toda esta API:

/settlement/fund_class/{fund_class_key}

Para mais detalhes sobre o fluxo completo, consulte a página de introdução.

Atenção

Cada lote deve possuir um external_id único por fundo.

Em caso de erro, reenvie a requisição. Duplicidade (SET000009) significa que o lote já existe: consulte-o pela consulta de lote em vez de recriar. Veja Reenvio e duplicidade.

Request

ENDPOINT

/settlement/fund_class/{fund_class_key}/payment_batch

MÉTODO

POST

Request Body

{
    "external_id": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "description": "PAGAMENTOS - ABC - 2025-01-01",
    "account": {
        "account_number": "123456",
        "account_digit": "0",
        "account_branch": "0001",
        "financial_institution_code": "329"
    }
}

Atributos do body

Campo	Tipo	Obrigatoriedade	Descrição
external_id	string	obrigatório	Chave única de identificação deste lote no sistema do parceiro integrador. Máximo de 50 caracteres.
description	string	opcional	Descrição do lote de liquidação. Máximo de 255 caracteres.
account	object	opcional	Dados da conta onde a liquidação será creditada. Quando não informado, a liquidação será gerada na conta principal do fundo. Veja Atributos de account.
account_key	string	opcional	Chave da conta onde a liquidação será creditada (UUID, 36 caracteres). Alternativa ao campo account.
reference_date	string	opcional	Data de referência do lote no formato YYYY-MM-DD. Quando omitida, vale a data corrente (horário de Brasília). Não pode ser anterior à data contábil atual do fundo.
end_to_end_id	string	opcional	Identificador end-to-end do Pix da contraparte financeira da liquidação (32 caracteres, começando com E).
source_document_number	string	opcional	CPF ou CNPJ da contraparte financeira da liquidação, com pontuação (ex: 11.222.333/0001-81 ou 969.698.790-03). Quando omitido, pode ser preenchido pelo documento padrão da configuração de liquidação do fundo.
settlement_expenses	array	opcional	Despesas de liquidação descontadas no lote, no máximo uma por tipo. Veja Atributos de settlement_expenses.

Atenção

Os campos account e account_key não devem ser passados simultaneamente (SET000034). Caso nenhum dos dois seja informado, a liquidação será gerada na conta principal do fundo. A conta deve pertencer ao fundo ou tê-lo como agente autorizado (SET000032).

Atributos de account

Campo	Tipo	Obrigatoriedade	Descrição
account_number	string	obrigatório	Número da conta. Máximo de 20 caracteres.
account_digit	string	obrigatório	Dígito da conta. 1 caractere.
account_branch	string	obrigatório	Agência da conta. Máximo de 4 caracteres.
financial_institution_code	string	obrigatório	Código da instituição financeira. Máximo de 20 caracteres.

Atributos de settlement_expenses

Campo	Tipo	Obrigatoriedade	Descrição
amount	number	obrigatório	Valor da despesa.
expense_type	string	obrigatório	bank_account (despesa bancária) ou collection_agent_fee (taxa de agente de cobrança).
description	string	opcional	Descrição da despesa. Máximo de 255 caracteres.

Response

STATUS

201

Response Body

{
    "external_id": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "description": "PAGAMENTOS - ABC - 2025-01-01",
    "fund_class": {
        "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS",
        "manager": {
            "name": "EXEMPLO CAPITAL",
            "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
            "document_number": "22.333.444/0001-81"
        },
        "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
        "document_number": "11.222.333/0001-81",
        "accounting_date": "2025-01-01",
        "payment_batch_automatic_discard": false
    },
    "payment_batch_key": "63f0dbec-e9c4-4943-929e-1d47b9edbb0b",
    "status": "pending_settlements_insertion",
    "reference_date": "2025-01-01",
    "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e"
}

Atributos da resposta

Campo	Tipo	Descrição
external_id	string	A mesma chave externa fornecida na requisição.
description	string	Descrição do lote.
fund_class	object	Dados do fundo associado ao lote. Veja Atributos de fund_class.
payment_batch_key	string	Identificador único do lote gerado pela QI Tech (UUID).
status	string	Status inicial do lote. Sempre retorna pending_settlements_insertion, indicando que o lote está pronto para receber liquidações.
reference_date	string	Data de referência do lote no formato YYYY-MM-DD.
account_key	string	Chave da conta associada ao lote (UUID).
settlement_expenses	array	Despesas de liquidação criadas, com settlement_expense_key, amount, status, description e type. Presente apenas quando informadas.

A resposta também ecoa os demais campos enviados no corpo (por exemplo account, source_document_number, end_to_end_id).

Atributos de fund_class

Campo	Tipo	Descrição
name	string	Nome do fundo.
manager	object	Dados do gestor do fundo. Veja Atributos de manager.
fund_class_key	string	Chave única do fundo (UUID).
document_number	string	CNPJ do fundo.
accounting_date	string	Data contábil atual do fundo, no formato YYYY-MM-DD.
payment_batch_automatic_discard	boolean	Indica se o fundo descarta automaticamente lotes deixados em aberto.

Atributos de manager

Campo	Tipo	Descrição
name	string	Nome do gestor.
manager_key	string	Chave única do gestor (UUID).
document_number	string	CNPJ do gestor.

Próximos passos

Após criar o lote, o fluxo continua com:

1. Inserção das liquidações — adicione as liquidações (pagamentos de parcelas, amortizações, etc.) ao lote.
2. Encerramento do lote — sinalize que todas as liquidações foram inseridas para que o processamento seja iniciado.

Erros

Status	Código	Quando acontece
409	SET000009	Já existe lote com este external_id no fundo. Consulte-o em vez de recriar.
404	SET000005	A fund_class_key não existe.
403	SET000028	O fundo não pertence ao seu perfil (gestora do fundo, consultoria vinculada ou cedente associado).
400	SET000044	reference_date anterior à data contábil atual do fundo.
404	SET000031	A conta informada (account_key ou account) não foi encontrada.
400	SET000032	A conta informada não pertence ao fundo.
400	SET000034	account e account_key enviados juntos.
403	SET000085	Conta escrow não autorizada a operar para este fundo.
400	SET000001	source_document_number não é um CPF/CNPJ válido.
400	SET000050 / SET000051	expense_type inválido, ou mais de uma despesa do mesmo tipo.
400	QIT000001	Corpo inválido (campo obrigatório ausente, formato inválido ou campo não aceito).

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