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.

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. O sistema não permitirá a criação de dois lotes com o mesmo identificador.

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 da liquidação no formato YYYY-MM-DD.
end_to_end_id	string	opcional	Identificador end-to-end do PIX da contraparte financeira da liquidação. Máximo de 32 caracteres.
source_document_number	string	opcional	CPF ou CNPJ da contraparte financeira da liquidação, com pontuação (ex: 12.345.678/0001-90 ou 123.456.789-00).

Atenção

Os campos account e account_key não devem ser passados simultaneamente. Caso nenhum dos dois seja informado, a liquidação será gerada na conta principal do fundo. As informações da conta devem ser referentes a uma conta pertencente ao fundo.

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.

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": "45.585.471/0001-47"
        },
        "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
        "document_number": "60.910.091/0001-24"
    },
    "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 da liquidação no formato YYYY-MM-DD.
account_key	string	Chave da conta associada ao lote (UUID).

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.

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.

Possíveis erros

STATUS

404

Fundo não encontrado

A fund_class_key informada na URL não corresponde a nenhum fundo cadastrado. Verifique se a chave está correta.

{
  "title": "Fund Class not Found",
  "description": "Fund Class with key {fund_class_key} was not found.",
  "translation": "A Classe de Fundo com chave {fund_class_key} nao foi encontrado.",
  "code": "SET000005"
}

STATUS

409

External ID duplicado

Já existe um lote cadastrado com o external_id informado. Cada lote deve ter um identificador único. Gere um novo external_id e tente novamente.

{
  "title": "Payment batch external id already exists",
  "description": "The Payment Batch with external id {payment_batch_external_id} already exists",
  "translation": "O Lote de Pagamento com identificador externo {payment_batch_external_id} ja existe",
  "code": "SET000009"
}

STATUS

400

Data contábil divergente

O lote está sendo criado em uma data diferente da data contábil vigente do fundo. Verifique a data contábil do fundo e tente novamente.

{
  "title": "Bad Request",
  "description": "Payment batch is being created in {accounting_date}, while fund is in {fund_class_accounting_date}",
  "translation": "Payment batch esta sendo criado em {accounting_date}, fundo esta em {fund_class_accounting_date}",
  "code": "SET000044"
}

STATUS

404

Conta não encontrada

A account_key informada não corresponde a nenhuma conta cadastrada. Verifique se a chave está correta e se a conta pertence ao fundo.

{
  "title": "Account not found",
  "description": "The account with key ({account_key}) was not found.",
  "translation": "A conta com chave({account_key}) não foi encontrada.",
  "code": "SET000009"
}

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.