Execução de garantia

---

Introdução

Este recurso tem como objetivo executar uma garantia constituída sobre as cotas de um investidor, convertendo o bloqueio em pagamento ao credor.

Diferente dos demais eventos de bloqueio, a execução de garantia gera um pedido de resgate na classe do fundo e o valor apurado é pago nominalmente ao credor cadastrado na garantia — não ao investidor. A posição do investidor é reduzida na proporção das cotas resgatadas.

Pré-requisitos

Antes de solicitar a execução, confirme que:

Requisito	Detalhe
Bloqueio aprovado	O bloqueio de cotas deve estar no status approved.
Bloqueio do tipo garantia	Apenas bloqueios com o objeto collateral são executáveis. Bloqueios de penhora judicial não são.
Credor identificado	collateral.recipient deve conter name e document_number.
Conta bancária do credor	collateral.recipient.bank_account deve conter account_number, account_branch, account_digit e financial_institution_ispb.

O cadastro do credor e da conta bancária é feito no momento da solicitação de bloqueio de cotas. Uma execução solicitada sobre uma garantia com cadastro incompleto não é registrada.

Atenção

A conta bancária informada em collateral.recipient.bank_account é a conta do credor e é o destino do pagamento da execução. Não confundir com collateral.bank_account_key, que identifica uma conta do investidor e não participa da execução.

Request

ENDPOINT

/quota_lock/investor/INVESTOR_KEY/quota_lock/QUOTA_LOCK_KEY/investor_position_lock/INVESTOR_POSITION_LOCK_KEY/event

MÉTODO

POST

STATUS

201

Execução de garantia

{
    "type": "collateral_execution",
    "net_value": 1000.00
}

Collateral Execution Event

Campo	Tipo	Descrição	Caracteres	Obrigatório
type	string	Enumerador do tipo de evento. Para execução de garantia: collateral_execution	até 255	Sim
net_value	float	Valor líquido a ser executado e pago ao credor	-	Sim

O valor informado em net_value não pode exceder o valor financeiro bloqueado no momento da solicitação.

Response

Execução registrada

{
    "investor_position_lock_event_key": "UUID"
}

Campo	Tipo	Descrição	Caracteres
investor_position_lock_event_key	string	Identificador do evento de execução criado	36

O que acontece após a solicitação

1. O evento de execução é registrado com o status pending_processing. Os valores bloqueados permanecem integralmente bloqueados neste momento.
2. Um pedido de resgate do tipo net_value_redemption é aberto automaticamente na classe do fundo, no valor informado.
3. O pedido de resgate é cotizado no ciclo normal da classe. O pagamento é emitido para a conta do credor, líquido de IR e IOF.
4. Com a cotização concluída, a quantidade de cotas efetivamente resgatada é abatida do bloqueio e o evento passa para done.

Caso o pedido de resgate seja cancelado antes da cotização, o evento de execução passa para canceled e os valores bloqueados são preservados integralmente — não há baixa parcial.

Event Status

Enumerador	Descrição
pending_processing	Execução registrada, aguardando a cotização do pedido de resgate
done	Execução concluída, cotas abatidas do bloqueio
canceled	Execução cancelada, valores bloqueados preservados

Acompanhamento

O status da execução é consultado pelo endpoint de consulta de bloqueio de cotas, no objeto investor_position_locks[].events[].

Evento na consulta de bloqueio

{
    "investor_position_locks": [
        {
            "investor_position_lock_key": "UUID",
            "current_locked_quotas": 100.00000000000000,
            "events": [
                {
                    "quota_lock_event_key": "UUID",
                    "type": "collateral_execution",
                    "status": "pending_processing"
                }
            ]
        }
    ]
}

observação

Na resposta da consulta, o identificador do evento é retornado no campo quota_lock_event_key. Ele corresponde ao investor_position_lock_event_key devolvido na criação.

Concluída a execução, o mesmo evento passa a apresentar status: "done" e o campo new_locked_quotas com a quantidade de cotas remanescente no bloqueio.

Não há webhook dedicado a eventos de execução de garantia. Os webhooks disponíveis para bloqueio de cotas estão descritos em Webhooks de bloqueio de cota.

Erros

Status	Código	Descrição
400	QLK000044	O net_value informado é nulo, zero ou negativo
400	QLK000042	O net_value informado excede o valor bloqueado
400	QLK000036	O agente selecionado não é o solicitante do bloqueio
404	QLK000022	Bloqueio de cotas não encontrado
404	QLK000037	Posição bloqueada não encontrada