Desembolso para terceiro na operação

Este endpoint define ou substitui a instrução de desembolso para terceiro de uma operação, indicando que o valor liberado será pago a um beneficiário terceiro (por exemplo, um fornecedor) e não à conta de liquidação do emissor.

Recurso sob habilitação

O desembolso para terceiro não vem habilitado por padrão. Solicite a habilitação à QI Tech antes de integrar — sem ela, a requisição é recusada com COM000062.

Substituição integral e janela de alteração

A requisição substitui a instrução inteira — não há atualização parcial de campos. A instrução só pode ser definida ou alterada enquanto a operação está no status in_filling; fora desse status a requisição é recusada com COM000010.

---

Desembolso para terceiro na operação (PUT)

Request

ENDPOINT

/commercial_paper/operation/OPERATION-KEY/third_party_disbursement

MÉTODO

PUT

Path Params

Campo	Tipo	Descrição	Caracteres Máx.
OPERATION-KEY *	string	Chave única da operação (UUID v4).	36

Request Body — TED

{
    "payment_method": "ted",
    "target_account": {
        "account_branch": "0001",
        "account_number": "4464541",
        "account_digit": "3",
        "financial_institution_ispb": "32402502",
        "financial_institution_code_number": "329",
        "account_type": "checking",
        "owner_document_number": "11.222.333/0001-81",
        "owner_name": "Fornecedor Exemplo LTDA"
    }
}

Request Body — Boleto

{
    "payment_method": "bank_slip",
    "digitable_line": "34191790010104351004791020150008291070100000000"
}

Request Body Params

O corpo não aceita campos além dos listados (additionalProperties: false). As duas trilhas são mutuamente exclusivas e a exclusividade é garantida pelo schema: enviar target_account com bank_slip, digitable_line com ted, omitir o campo obrigatório da trilha escolhida ou enviar um campo desconhecido retorna QIT000001.

Campo	Tipo	Descrição	Caracteres Máx.
payment_method *	string	Trilha de pagamento utilizada no desembolso.	Enumeradores payment_method
target_account	object	Conta bancária do beneficiário. Obrigatório quando payment_method é ted; proibido quando bank_slip.	Objeto target_account
digitable_line	string	Linha digitável do boleto do beneficiário, somente dígitos (padrão ^[0-9]{47}$). Obrigatório quando payment_method é bank_slip; proibido quando ted.	47

Enumeradores payment_method

Valor	Descrição
ted	Pagamento por TED para a conta informada em target_account.
bank_slip	Pagamento do boleto informado em digitable_line.

Objeto target_account

Campo	Tipo	Descrição	Caracteres Máx.
account_branch *	string	Agência da conta bancária do beneficiário, somente dígitos (exatamente 4).	4
account_number *	string	Número da conta bancária do beneficiário, somente dígitos (1 a 20).	20
account_digit *	string	Dígito da conta bancária do beneficiário, somente dígitos (exatamente 1).	1
financial_institution_ispb *	string	Código ISPB da instituição financeira do beneficiário, somente dígitos (exatamente 8). Define o roteamento da TED.	8
financial_institution_code_number	string ou null	Código da instituição financeira do beneficiário, somente dígitos (3). Opcional e não utilizado no roteamento.	3
account_type *	string	Tipo da conta do beneficiário.	Enumeradores account_type
owner_document_number *	string	CPF ou CNPJ do titular da conta, formatado (000.000.000-00 ou 00.000.000/0000-00). Os dígitos verificadores são conferidos.	18
owner_name *	string	Nome do titular da conta (1 a 50 caracteres).	50

Enumeradores account_type

Valor	Descrição
checking	Conta corrente.
savings	Conta poupança.
salary	Conta salário.
payment	Conta de pagamento.

TED — confira o ISPB

A instituição de destino da TED é determinada pelo financial_institution_ispb. Um ISPB incorreto envia o dinheiro para a instituição errada mesmo que o financial_institution_code_number esteja correto.

Boleto — o valor precisa bater com o valor liberado

O valor do boleto é lido dos 10 últimos dígitos da linha digitável, em centavos, e precisa ser igual ao financial.released_amount da operação. Qualquer diferença é recusada com COM000061.

Como o released_amount calculado difere do valor solicitado por causa das taxas, o caminho prático é: criar a operação, ler o released_amount da resposta e só então anexar um boleto daquele valor exato. Não reescreva o valor de uma linha digitável real — isso invalida seus dígitos verificadores e o boleto deixa de ser pagável.

Uma nota comercial paga exatamente um beneficiário, pelo valor integral: split de pagamento não é suportado.

Response

STATUS

200

A resposta traz o objeto completo da operação, na mesma forma retornada pela consulta de operação por chave.

Response Body

{
    "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814",
    "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127",
    "operation_type": "commercial_paper",
    "operation_status": "in_filling",
    "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e",
    "issuer_name": "Dynamic Enterprises",
    "issuer_document_number": "28.980.395/0001-55",
    "issuer_bank_account": {
        "account_type": "checking",
        "account_digit": "3",
        "account_branch": "0001",
        "account_number": "4464541",
        "financial_institution_ispb": "32402502",
        "financial_institution_code_number": "329"
    },
    "financial": {
        ...
    }
}

Response Body Params

Campo	Tipo	Descrição
tenant_key *	string	Chave única do tenant.
operation_key *	string	Chave única da operação.
operation_status *	string	Status da operação.
issuer_key *	string	Chave única do emissor.
issuer_name *	string	Nome do emissor.
issuer_document_number *	string	Documento do emissor.
financial *	object	Dados financeiros da operação.

informação

A instrução aparece no objeto da operação como third_party_disbursement, na mesma forma em que foi enviada. Quando a operação não tem desembolso para terceiro, a chave é omitida da resposta — não retorna como null.

---

Erros

Os códigos abaixo estão descritos também no catálogo de erros.

Código	HTTP	Descrição
QIT000001	400	Falha de schema — por exemplo, payment_method ausente ou fora do enum, combinação inválida entre target_account e digitable_line, digitable_line fora do padrão de 47 dígitos, ou campo desconhecido no corpo.
COM000010	400	Operação não pode ser atualizada fora do status in_filling.
COM000061	400	Valor do boleto diferente do released_amount da operação.
COM000062	400	Tenant não habilitado para desembolso a terceiro.
COM000063	400	Documento do beneficiário inválido.
COM000007	404	Operação não encontrada.
COM000008	403	Operação não pertence ao tenant solicitante.