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 — Pix

{
    "payment_method": "pix",
    "pix_key": "52998224725",
    "pix_key_type": "cpf",
    "beneficiary": {
        "person_type": "natural",
        "name": "João da Silva",
        "document_number": "529.982.247-25",
        "street": "Rua das Flores",
        "number": "100",
        "postal_code": "01234-567",
        "city": "São Paulo",
        "state": "SP",
        "is_pep": false
    }
}

Request Body Params

O corpo não aceita campos além dos listados (additionalProperties: false). As três trilhas são mutuamente exclusivas e a exclusividade é garantida pelo schema: enviar o campo de uma trilha junto de outra, 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 nas demais trilhas.	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 nas demais trilhas.	47
pix_key	string	Chave Pix do beneficiário, sem formatação para CPF e CNPJ. Obrigatório quando payment_method é pix; proibido nas demais trilhas.	77
pix_key_type	string	Tipo declarado da chave Pix. Obrigatório quando payment_method é pix; proibido nas demais trilhas.	Enumeradores pix_key_type
beneficiary	object	Qualificação do terceiro beneficiário. Obrigatório quando payment_method é pix; opcional em ted e bank_slip.	Objeto beneficiary

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.
pix	Pagamento por Pix para a chave informada em pix_key.

Enumeradores pix_key_type

Valor	Descrição
cpf	CPF, 11 dígitos, sem pontuação.
cnpj	CNPJ, 14 dígitos, sem pontuação.
phone	Telefone no formato +55 seguido de 10 ou 11 dígitos.
email	Endereço de e-mail, até 77 caracteres.
evp	Chave aleatória (UUID minúsculo).

O formato da chave é validado pelo schema conforme o pix_key_type declarado — fora do formato, QIT000001. Para cpf e cnpj, os dígitos verificadores são conferidos depois: formato certo com dígito verificador errado retorna COM000071.

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.

Objeto beneficiary

Identifica o terceiro que recebe o valor. Obrigatório na trilha pix — uma chave Pix não diz quem é o recebedor — e opcional em ted e bank_slip. Viaja junto da instrução, é assinado com a operação e é usado na ata que formaliza o pagamento ao terceiro.

Apenas name e document_number são obrigatórios. Todos os demais campos são opcionais e servem para enriquecer a qualificação do beneficiário na ata.

Campo	Tipo	Descrição	Obrigatório
person_type	string	natural (pessoa física) ou legal (pessoa jurídica).	Opcional
name *	string	Nome do beneficiário.	Sempre
document_number *	string	CPF ou CNPJ formatado (000.000.000-00 ou 00.000.000/0000-00).	Sempre
street	string	Logradouro.	Opcional
number	string	Número do endereço.	Opcional
postal_code	string	CEP no formato 00000-000.	Opcional
city	string	Cidade.	Opcional
state	string	UF, duas letras maiúsculas.	Opcional
is_pep	boolean	Indica se é Pessoa Politicamente Exposta.	Opcional
trading_name	string	Nome fantasia.	Opcional
cnae_code	string	CNAE no formato 00.00-0-00.	Opcional
company_type	string	Tipo de empresa.	Opcional
foundation_date	string	Data de fundação (AAAA-MM-DD).	Opcional
neighborhood	string	Bairro.	Opcional
complement	string	Complemento do endereço.	Opcional
document_identification_number	string	RG.	Opcional
marital_status	string	Estado civil.	Opcional
property_system	string	Regime de bens.	Opcional
birthdate	string	Data de nascimento (AAAA-MM-DD).	Opcional
nationality	string	Nacionalidade.	Opcional
mother_name	string	Nome da mãe.	Opcional
father_name	string	Nome do pai.	Opcional
occupation	string	Ocupação.	Opcional

Quanto mais você enviar, mais completa fica a ata

Com person_type, a ata ganha a qualificação do beneficiário. Com street, number, postal_code, city e state — os cinco juntos —, ganha o endereço formatado. Enviando só nome e documento, a ata nomeia o beneficiário sem qualificar nem endereçar: nada falha, o documento apenas fica mais enxuto.

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, pix_key fora do formato do seu pix_key_type, 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.
COM000071	400	pix_key de cpf/cnpj com dígito verificador inválido.
COM000007	404	Operação não encontrada.
COM000008	403	Operação não pertence ao tenant solicitante.