Pular para o conteúdo principal

Envio de Garantia na Operação

Este conjunto de endpoints permite a adição de garantias associadas a uma operação. O collateral será submetido para assinatura junto com os documentos da operação. Cada tipo de garantia contém as suas regras de documentos necessários e todos os tipos de garantias estão contemplados aqui nesta documentação.


Envio de Garantia (POST)​

Request​

ENDPOINT
/commercial_paper/operation/OPERATION-KEY/collateral
MÉTODO
POST

Path Params​

CampoTipoDescriçãoCaracteres Máx.
OPERATION-KEY *stringChave única da operação (UUID v4).36

O sistema de garantias possibilita a adição de diferentes tipos de instrumentos, cada um com sua própria configuração de documentos adicionais. Nesta sessão, tratamos todos os modelos de garantia disponíveis e seus respectivos payloads.

Tipos de Garantias​

1 - Alienação fiduciária de imóvel

2 - Alienação fiduciária de veículo

3 - Alienação fiduciária de aeronave

4 - Alienação fiduciária de equipamentos/produtos/Estoque

5 - Alienação fiduciária de obras de arte

6 - Alienação fiduciária de títulos e valores mobiliários

7 - Alienação fiduciária de Ações e Cotas

8 - Alienação fiduciária de diretos creditórios

9 - Hipoteca de imóveis

10 - Hipoteca de embarcações

11 - Aval

12 - Fiador

13 - Fiança Bancária

14 - Recebiveis de cartão

15 - Garantia de estoque

16 - Monitoramento de garantias

17 - Garantia de estoque de veículos (Floor Plan)

18 - Outras garantias

Alienação fiduciária de imóvel​

Request Body
{
"collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b",
"collateral_type": "fiduciary_alienation_property",
"additional_documents": [
{
"document_type": "property_appraisal_report",
"document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff"
},
{
"document_type": "property_registration_updated",
"document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
},
{
"document_type": "property_full_content_certificate",
"document_key": "210c38b5-6b61-4b74-b042-19ebef77e360"
},
{
"document_type": "property_insurance_policy",
"document_key": "4cc6d706-551f-4d5e-8539-1b59b2f96cff"
}
]
}

Tipos de Documentos​

EnumDescrição
property_appraisal_report**Laudo de Avaliação do Imóvel.
property_registration_updated**Matrícula atualizada.
property_full_content_certificate**Certidão de Inteiro Teor da Matrícula.
property_insurance_policyApólice de Seguros (se exigível no contrato).
othersOutros documentos.
aviso

(**) Obrigatório para alienação fiduciária de imóvel

Alienação fiduciária de veículo​

Request Body
{
"collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
"collateral_type": "fiduciary_alienation_vehicle",
"additional_documents": [
{
"document_type": "vehicle_appraisal_report",
"document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
},
{
"document_type": "vehicle_inspection_report",
"document_key": "210c38b5-6b61-4b74-b042-19ebef77e360"
},
{
"document_type": "vehicle_crv_certificate",
"document_key": "4cc6d706-551f-4d5e-8539-1b59b2f96cff"
}
]
}

Tipos de Documentos​

EnumDescrição
vehicle_appraisal_report**Laudo de Avaliação do Veículo (defasagem máxima de 30 dias) ou Tabela FIPE.
vehicle_inspection_report**Laudo vistoria.
vehicle_crv_certificate**Certificado de Registro de Veículo (CRLV) Atualizado.
othersOutros documentos.
aviso

(**) Obrigatório para alienação fiduciária de veículo

Alienação fiduciária de aeronave​

Request Body
{
"collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
"collateral_type": "fiduciary_alienation_aircraft",
"additional_documents": [
{
"document_type": "aircraft_certificate_anac",
"document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
},
{
"document_type": "aircraft_rab_consult",
"document_key": "210c38b5-6b61-4b74-b042-19ebef77e360"
},
{
"document_type": "aircraft_insurance_policy",
"document_key": "4cc6d706-551f-4d5e-8539-1b59b2f96cff"
},
{
"document_type": "aircraft_appraisal_report",
"document_key": "df608f78-5293-4f96-ab60-31185633b52c"
}
]
}

Tipos de Documentos​

EnumDescrição
aircraft_certificate_anac**Certificado de Matrícula - ANAC.
aircraft_rab_consult**Consulta de Aeronave no Registro Aeronáutico Brasileiro.
aircraft_insurance_policy**Apólice de Seguro - Beneficiário o Fundo.
aircraft_appraisal_report**Laudo de Avaliação de Aeronave.
othersOutros documentos.
aviso

(**) Obrigatório para alienação fiduciária de aeronave

Alienação fiduciária de equipamentos produtos e estoque​

Request Body
{
"collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
"collateral_type": "fiduciary_alienation_equipment",
"additional_documents": [
{
"document_type": "equipment_purchase_invoice",
"document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
},
{
"document_type": "fiduciary_depositary_declaration",
"document_key": "210c38b5-6b61-4b74-b042-19ebef77e360"
},
{
"document_type": "equipment_appraisal_report",
"document_key": "4cc6d706-551f-4d5e-8539-1b59b2f96cff"
},
{
"document_type": "equipment_insurance_policy",
"document_key": "df608f78-5293-4f96-ab60-31185633b52c"
}
]
}

Tipos de Documentos​

EnumDescrição
equipment_purchase_invoice**Nota Fiscal - Registro de Compra.
equipment_appraisal_report**Laudo de Avaliação de Equipamentos (defasagem máxima de 30 dias).
equipment_insurance_policyApólice de Seguro de Equipamentos (se exigível no contrato).
fiduciary_depositary_declarationDeclaração de Fiel Depositário.
othersOutros documentos.
aviso

(**) Obrigatório para alienação fiduciária de equipamentos/produto/estoque

Alienação fiduciária de obras de arte​

Request Body
{
"collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
"collateral_type": "fiduciary_alienation_artwork",
"additional_documents": [
{
"document_type": "artwork_appraisal_report",
"document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
},
{
"document_type": "artwork_storage_certificate",
"document_key": "210c38b5-6b61-4b74-b042-19ebef77e360"
}
]
}

Tipos de Documentos​

EnumDescrição
artwork_appraisal_report**Laudo de avaliação de Obras de Arte.
artwork_storage_certificate**Local de Armazenamento com Certificado de Adequação.
artwork_insurance_policyApólice de Seguro (se exigível no contrato).
othersOutros documentos.
aviso

(**) Obrigatório para alienação fiduciária de obras de arte

Alienação fiduciária de títulos e valores mobiliários​

Request Body
{
"collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
"collateral_type": "fiduciary_alienation_securities",
"additional_documents": [
{
"document_type": "securities_negotiation_block",
"document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
}
]
}

Tipos de Documentos​

EnumDescrição
securities_negotiation_block**Bloqueio para Negociação junto ao Custodiante.
securities_registration_gravameLocal de Armazenamento com Certificado de Adequação.
othersOutros documentos.
aviso

(**) Obrigatório para alienação fiduciária de títulos valores mobiliários.

Alienação fiduciária de Ações e Cotas​

Request Body
{
"collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
"collateral_type": "fiduciary_assignment_shares",
"additional_documents": [
{
"document_type": "share_registration_book",
"document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
}
]
}

Tipos de Documentos​

EnumDescrição
share_registration_book**Livro de Registro de Ações Nominativas com Anotação do Gravame.
othersOutros documentos.
aviso

(**) Obrigatório para alienação fiduciária/Penhor de Ações/Cotas

Alienação fiduciária de diretos creditórios​

Request Body
{
"collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
"collateral_type": "fiduciary_assignment_shares",
}

Tipos de Documentos​

EnumDescrição
othersOutros documentos.

Hipoteca de imóveis​

Request Body
{
"collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
"collateral_type": "mortgage_property",
"additional_documents": [
{
"document_type": "property_appraisal_report",
"document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
},
{
"document_type": "property_registration",
"document_key": "210c38b5-6b61-4b74-b042-19ebef77e360"
},
{
"document_type": "property_insurance_policy",
"document_key": "4cc6d706-551f-4d5e-8539-1b59b2f96cff"
},
{
"document_type": "property_full_content_certificate",
"document_key": "df608f78-5293-4f96-ab60-31185633b52c"
}
]
}

Tipos de Documentos​

EnumDescrição
property_appraisal_report**Laudo de Avaliação de Imóvel.
property_registration**Registro de Propriedade Atualizado.
property_full_content_certificate**Certidão de Inteiro Teor da Matrícula.
property_insurance_policyApólice de Seguros (se exigível no contrato).
othersOutros documentos.
aviso

(**) Obrigatório para Hipoteca de imóveis.

Hipoteca de Embarcações​

Request Body
{
"collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
"collateral_type": "mortgage_ship",
"additional_documents": [
{
"document_type": "ship_registration",
"document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
},
{
"document_type": "ship_appraisal_report",
"document_key": "210c38b5-6b61-4b74-b042-19ebef77e360"
},
{
"document_type": "ship_insurance_policy",
"document_key": "4cc6d706-551f-4d5e-8539-1b59b2f96cff"
}
]
}

Tipos de Documentos​

EnumDescrição
ship_registration**Registro de Propriedade de Embarcação Atualizado.
ship_appraisal_report**Laudo de Avaliação de Embarcação (defasagem máxima de 3 meses).
ship_insurance_policyApólice de Seguros de embarcação (se exigível no contrato).
othersOutros documentos.
aviso

(**) Obrigatório para Hipoteca de embarcações.

Aval​

Request Body
{
"collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
"collateral_type": "guarantor",
"additional_documents": [
{
"document_type": "guarantor_civil_status_declaration",
"document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
},
{
"document_type": "guarantor_personal_document",
"document_key": "210c38b5-6b61-4b74-b042-19ebef77e360"
}
]
}

Tipos de Documentos​

EnumDescrição
guarantor_civil_status_declaration**Declaração de Estado Civil do Avalista.
guarantor_personal_document**Documento pessoal do Avalista.
guarantor_income_tax_declarationDeclaração de Imposto de Renda do Avalista.
othersOutros documentos.
aviso

(**) Obrigatório para Aval.

Fiador​

Request Body
{
"collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
"collateral_type": "surety",
"additional_documents": [
{
"document_type": "surety_civil_status_declaration",
"document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
},
{
"document_type": "surety_personal_document",
"document_key": "210c38b5-6b61-4b74-b042-19ebef77e360"
},
{
"document_type": "surety_income_tax_declaration",
"document_key": "4cc6d706-551f-4d5e-8539-1b59b2f96cff"
}
]
}

Tipos de Documentos​

EnumDescrição
surety_civil_status_declaration**Declaração de Estado Civil do Fiador.
surety_personal_document**Documento pessoal do Fiador.
surety_income_tax_declarationDeclaração de Imposto de Renda do Fiador.
othersOutros documentos.
aviso

(**) Obrigatório para Fiador.

Fiança Bancária​

Request Body
{
"collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
"collateral_type": "bank_surety",
"additional_documents": [
{
"document_type": "others",
"document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
}
]
}

Tipos de Documentos​

EnumDescrição
othersOutros documentos.

Recebiveis de cartão​

Request Body
{
"collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
"collateral_type": "card_receivables",
"additional_documents": [
{
"document_type": "others",
"document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
}
]
}

Tipos de Documentos​

EnumDescrição
othersOutros documentos.

Garantia de estoque​

Request Body
{
"collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
"collateral_type": "stock_guarantee",
"additional_documents": [
{
"document_type": "others",
"document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
}
]
}

Tipos de Documentos​

EnumDescrição
othersOutros documentos.

Monitoramento de garantias​

Request Body
{
"collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
"collateral_type": "monitoring_guarantee",
"additional_documents": [
{
"document_type": "guarantee_contract",
"document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
},
{
"document_type": "guarantee_agent_contract",
"document_key": "210c38b5-6b61-4b74-b042-19ebef77e360"
}
]
}

Tipos de Documentos​

EnumDescrição
guarantee_contract**Contrato de Garantia.
guarantee_agent_contract**Contrato de agente de Garantia.
othersOutros documentos.
aviso

(**) Obrigatório para Monitoramento de Garantias.`

Garantia de estoque de veículos (Floor Plan)​

Modelo de garantia utilizado em operações de Floor Plan, no qual o emissor disponibiliza um estoque de veículos como garantia da operação. Diferente dos demais tipos, este modelo não utiliza collateral_document_key — cada garantia representa um único veículo, enviado no campo vehicle.

Para cadastrar N veículos, envie N requisições POST, uma por veículo. Cada requisição cria uma garantia própria, com o seu collateral_key e o seu collateral_status.

Request Body
{
"collateral_type": "vehicle_stock",
"additional_documents": [
{
"document_type": "vehicle_crlv_certificate",
"document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
}
],
"vehicle": {
"chassis": "9BWZZZ377VT004251",
"plate": "ABC1D23",
"plate_state": "SP",
"renavam": "12345678901",
"value": 85000.00,
"year": 2023,
"mileage": 32000
}
}

vehicle object​

CampoTipoDescriçãoObrigatório
chassis *stringChassi do veículo. 17 caracteres alfanuméricos maiúsculos.Sim
platestringPlaca do veículo, no padrão Mercosul ou antigo.Não**
plate_statestringUF de emplacamento do veículo (sigla).Não**
renavamstringRENAVAM do veículo. 9 a 11 dígitos numéricos.Não**
valuenumberValor do veículo. Maior ou igual a 0.Não
yearintegerAno do veículo. Maior ou igual a 1900 e no máximo o ano seguinte ao atual.Não
mileageintegerQuilometragem do veículo. Maior ou igual a 0. Exige plate, plate_state e renavam.Não
aviso

(**) plate, plate_state e renavam formam um grupo tudo ou nada: o veículo deve enviar os três campos juntos (veículo emplacado/usado) ou nenhum dos três (veículo 0km, ainda sem emplacamento). O envio de apenas parte do grupo é rejeitado com erro de validação (400). Um veículo 0km também não pode enviar mileage.

Tipos de Documentos​

EnumDescrição
vehicle_crlv_certificateCertificado de Registro e Licenciamento de Veículo (CRLV).

O CRLV é enviado em additional_documents, na raiz do request body (ver additional_documents list). O envio é opcional e só é aceito o tipo vehicle_crlv_certificate. O documento é gravado na garantia e retorna no campo additional_documents da resposta, e não dentro de collateral_data.

Validação do veículo​

No cadastro, o veículo é consultado (não gravado) na base de estoque de veículos da B3:

  • Veículo livre (sem reserva ativa ou não encontrado na B3): a garantia é criada como validated e a requisição responde 201 com a garantia.
  • Veículo com reserva ativa na B3 ou erro na consulta: a garantia é gravada como canceled e a requisição responde 422 com o código COM000087. A garantia cancelada retorna no campo collateral do corpo do erro. Uma garantia canceled não entra na minuta nem na emissão, e não aparece na listagem de garantias da operação.
  • Chassi já presente em outra garantia validated da mesma operação: a requisição é rejeitada com 409 (COM000085) e nada é gravado. Um chassi cuja garantia anterior foi cancelada pode ser enviado novamente.

Response​

Response Body (201)
{
"collateral_key": "8a0c6e0e-3f5b-4c2a-9d7e-1b2f3c4d5e6f",
"collateral_type": "vehicle_stock",
"collateral_status": "validated",
"collateral_data": {
"vehicle": {
"chassis": "9BWZZZ377VT004251",
"plate": "ABC1D23",
"plate_state": "SP",
"renavam": "12345678901",
"value": 85000.00,
"year": 2023,
"mileage": 32000
}
},
"collateral_document_key": null,
"collateral_instrument_document_key": null,
"additional_documents": [
{
"collateral_document_key": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
"collateral_document_type": "vehicle_crlv_certificate",
"document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
}
],
"collateral_event_list": [
{
"collateral_status": "validated",
"event_type": "collateral_status_change",
"event_data": {
"from": "created",
"to": "validated",
"reason": "vehicle_consult_free",
"b3_response": {
"reservations": []
},
"b3_code": null,
"b3_description": null,
"b3_http_status": 200
},
"event_datetime": "2026-09-28T14:32:10.123456+00:00"
}
]
}
Response Body (422 — COM000087)
{
"title": "Unprocessable Entity",
"description": "Vehicle with chassis '9BWZZZ377VT004251' could not be validated on B3 (code: None, description: Vehicle has an active reservation with status 'Ativo'); the vehicle_stock collateral was registered as canceled.",
"translation": "O veiculo com chassi '9BWZZZ377VT004251' nao pode ser validado na B3 (codigo: None, descricao: Vehicle has an active reservation with status 'Ativo'); a garantia de estoque de veiculos foi registrada como cancelada.",
"code": "COM000087",
"collateral": {
"collateral_key": "8a0c6e0e-3f5b-4c2a-9d7e-1b2f3c4d5e6f",
"collateral_type": "vehicle_stock",
"collateral_status": "canceled",
"collateral_data": {
"vehicle": {
"chassis": "9BWZZZ377VT004251",
"plate": "ABC1D23",
"plate_state": "SP",
"renavam": "12345678901"
}
},
"collateral_document_key": null,
"collateral_instrument_document_key": null,
"additional_documents": [],
"collateral_event_list": [
{
"collateral_status": "canceled",
"event_type": "collateral_status_change",
"event_data": {
"from": "created",
"to": "canceled",
"reason": "vehicle_consult_marked",
"b3_response": {
"reservations": [
{
"reservation_status": "Ativo"
}
]
},
"b3_code": null,
"b3_description": "Vehicle has an active reservation with status 'Ativo'",
"b3_http_status": 200
},
"event_datetime": "2026-09-28T14:32:10.123456+00:00"
}
]
}
}

Status da garantia (collateral_status)​

Toda garantia, de qualquer tipo, retorna o campo collateral_status. Para os tipos que não dependem de validação externa, a garantia nasce validated e passa a finished na assinatura. Para vehicle_stock, o ciclo completo é:

StatusDescrição
validatedGarantia aceita no cadastro. Para vehicle_stock, o veículo foi consultado e está livre na B3.
canceledGarantia cancelada: veículo com reserva ativa ou erro na consulta no cadastro, garantia removida ou operação cancelada. Não entra na minuta nem na emissão.
pendingOperação assinada; o veículo aguarda a gravação na B3.
finishedVeículo gravado na B3 (ou, para os demais tipos, operação assinada).
failedA gravação do veículo na B3 falhou após a assinatura.

Histórico de eventos (collateral_event_list)​

Toda garantia retorna o campo collateral_event_list, com o histórico de mudanças de status em ordem cronológica.

CampoTipoDescrição
collateral_statusstringStatus da garantia após o evento.
event_typestringTipo do evento. collateral_status_change para mudanças de status.
event_dataobjectDados do evento: from (status anterior), to (novo status), reason (motivo) e, para vehicle_stock, a resposta da B3 (b3_response, b3_code, b3_description, b3_http_status).
event_datetimestringData e hora do evento (ISO 8601, UTC).

Fluxo após a assinatura​

  • Quando todos os envolvidos assinam, a operação passa para pending_collateral e cada veículo com garantia validated é consultado de novo e gravado na B3.
  • Se todos os veículos forem gravados, as garantias passam a finished e a operação segue para issued.
  • Se a consulta ou a gravação de algum veículo falhar, as garantias afetadas passam a failed e a operação passa a failed. A operação sai de failed por reprocessamento feito pela QI Tech ou por cancelamento.

Erros​

HTTP StatusCódigoDescrição
400—Erro de validação de schema (por exemplo, grupo plate/plate_state/renavam incompleto).
400COM000083Tenant não possui acesso a esse tipo de garantia.
400COM000084Ano do veículo maior que o ano seguinte ao atual.
409COM000085O chassi já está em uma garantia validated da mesma operação.
422COM000087Veículo com reserva ativa na B3 ou erro na consulta. A garantia fica gravada como canceled e retorna no campo collateral do corpo do erro.

Consulte também o catálogo de erros.

Outras garantias​

Request Body
{
"collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
"collateral_type": "others",
"additional_documents": [
{
"document_type": "others",
"document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
}
]
}

Tipos de Documentos​

EnumDescrição
othersOutros documentos.

Request Body Params​

CampoTipoDescriçãoObrigatório
collateral_document_key *stringChave do instrumento de Garantia.Sim
collateral_type *stringTipo do collateral.Enumeradores collateral_type
collateral_dataobjectEstrutura de metadados relacionados ao collateral.Sim
additional_documentslistDocumentos relacionados ao collateral.-

additional_documents list​

CampoTipoDescriçãoObrigatório
document_key *stringChave do instrumento de Garantia.Sim
document_type *stringTipo do documento da Garantia.Sim

Enumeradores collateral_type​

EnumDescrição
fiduciary_alienation_propertyAlienação fiduciária de imóvel.
fiduciary_alienation_vehicleAlienação fiduciária de veículo.
fiduciary_alienation_aircraftAlienação fiduciária de aeronave.
fiduciary_alienation_equipmentAlienação fiduciária de equipamentos/produtos/Estoque.
fiduciary_alienation_artworkAlienação fiduciária de obras de arte.
fiduciary_alienation_securitiesAlienação fiduciária de títulos e valores mobiliários.
fiduciary_assignment_sharesAlienação fiduciária/Penhor de Ações/Cotas.
fiduciary_assignment_credit_rightsAlienação fiduciária de diretos creditórios.
mortgage_propertyHipoteca de imóveis.
mortgage_shipHipoteca de embarcações.
guarantorAval.
suretyFiador.
bank_suretyFiança Bancária.
card_receivablesRecebiveis de cartão.
stock_guaranteeGarantia de estoque.
monitoring_guaranteeMonitoramento de garantias.
vehicle_stockGarantia de estoque de veículos (Floor Plan). Não utiliza collateral_document_key — veja Garantia de estoque de veículos (Floor Plan).
othersOutras garantias.