---
title: 5.6. Garantias
url: https://docs.vehub.com.br/API/Nota%20Comercial/5.%20Nota%20Comercial/5.6.%20Garantias/
---
# 5.6. Garantias

Gerencia as garantias vinculadas a uma Nota Comercial. Garantias podem ser aditadas, consultadas e excluídas enquanto a NC estiver em status **Em Digitação**.

---

## Listar Garantias da NC

### 🔗 Endpoint

| Método | URL |
|--------|-----|
| ![GET](https://img.shields.io/badge/GET-green) | `/public/v1/nota-comercial/{id}/garantias` |

### 🔹 Path Parameter

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| id | integer | Identificador único da NC |

### 🧪 Exemplo de cURL

```bash
curl -X GET https://api.vehub.com.br/public/v1/nota-comercial/100/garantias \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}"
```

### 📥 Response — `200 OK`

```json
[
  {
    "id": 5,
    "idTipoGarantia": 1,
    "tipoGarantia": "Cessão Fiduciária",
    "descricao": "Cessão fiduciária de recebíveis de cartão de crédito",
    "documentos": [
      {
        "id": 20,
        "nomeArquivo": "cessao-fiduciaria.pdf"
      }
    ]
  }
]
```

#### Detalhamento dos Campos — `[]`

| Campo | Tipo | Descrição |
|-------|------|-----------|
| id | integer | Identificador único da garantia |
| idTipoGarantia | integer | Código do tipo de garantia (ver Enumerações) |
| tipoGarantia | string | Descrição do tipo de garantia |
| descricao | string | Descrição livre da garantia |
| documentos | array | Arquivos vinculados à garantia |

---

## Adicionar Garantia

### 🔗 Endpoint

| Método | URL |
|--------|-----|
| ![POST](https://img.shields.io/badge/POST-blue) | `/public/v1/nota-comercial/{id}/garantias` |

### 🧾 Descrição

Adiciona uma garantia à NC. O envio é realizado como `multipart/form-data` para permitir o upload do documento comprobatório.

Os campos adicionais (`empresa` ou `pessoas`) variam conforme o tipo de garantia:
- **Garantias com Pessoa Física** (ex: Fiador PF): preencher `pessoas[]`
- **Garantias com Pessoa Jurídica** (ex: Fiador PJ): preencher `empresa`
- **Garantias sem vinculação de pessoa** (ex: Cessão Fiduciária, Hipoteca): omitir ambos

### 📋 Payload (multipart/form-data)

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| idTipoGarantia | integer | Sim | Tipo de garantia (ver Enumerações) |
| descricao | string | Sim | Descrição da garantia |
| arquivo | file | Não | Documento comprobatório (PDF, JPG ou PNG, máx. 20 MB) |

#### Campos adicionais para Fiador — Pessoa Jurídica

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| empresa.nome | string | Sim | Razão social |
| empresa.documento | string | Sim | CNPJ (somente números) |
| empresa.email | string | Sim | E-mail |
| empresa.telefone | string | Sim | Telefone (somente números) |
| empresa.dataFundacao | string | Sim | Data de fundação (YYYY-MM-DD) |
| empresa.cnae | string | Sim | CNAE principal |
| empresa.endereco | string | Sim | Logradouro |
| empresa.enderecoCep | string | Sim | CEP (somente números) |
| empresa.enderecoNumero | string | Sim | Número |
| empresa.enderecoComplemento | string | Não | Complemento |
| empresa.enderecoBairro | string | Sim | Bairro |
| empresa.enderecoCidade | string | Sim | Cidade |
| empresa.enderecoUF | string | Sim | UF |

#### Campos adicionais para Fiador — Pessoa Física

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| pessoas[0].nome | string | Sim | Nome completo |
| pessoas[0].documento | string | Sim | CPF (somente números) |
| pessoas[0].email | string | Sim | E-mail |
| pessoas[0].telefone | string | Sim | Telefone |
| pessoas[0].dataNascimento | string | Sim | Data de nascimento (YYYY-MM-DD) |
| pessoas[0].nacionalidade | string | Sim | Nacionalidade |
| pessoas[0].idOcupacao | integer | Não | ID da ocupação (ver Enumerações) |
| pessoas[0].idEstadoCivil | integer | Não | ID do estado civil (ver Enumerações) |
| pessoas[0].endereco | string | Sim | Logradouro |
| pessoas[0].enderecoCep | string | Sim | CEP |
| pessoas[0].enderecoNumero | string | Sim | Número |
| pessoas[0].enderecoComplemento | string | Não | Complemento |
| pessoas[0].enderecoBairro | string | Sim | Bairro |
| pessoas[0].enderecoCidade | string | Sim | Cidade |
| pessoas[0].enderecoUF | string | Sim | UF |

### 🧪 Exemplo de cURL — Cessão Fiduciária

```bash
curl -X POST https://api.vehub.com.br/public/v1/nota-comercial/100/garantias \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}" \
  -F "idTipoGarantia=1" \
  -F "descricao=Cessão fiduciária de recebíveis de cartão" \
  -F "arquivo=@/caminho/para/cessao.pdf"
```

### 📥 Response — `201 Created`

```json
{
  "mensagem": "Garantia adicionada com sucesso.",
  "id": 5
}
```

---

## Excluir Garantia

### 🔗 Endpoint

| Método | URL |
|--------|-----|
| ![DELETE](https://img.shields.io/badge/DELETE-red) | `/public/v1/nota-comercial/{id}/garantias/{idGarantia}` |

### 🔹 Path Parameters

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| id | integer | Identificador único da NC |
| idGarantia | integer | Identificador único da garantia |

### 📥 Response — `200 OK`

```json
{
  "mensagem": "Garantia removida com sucesso."
}
```

---

## ❌ Erros Comuns

### 400 Bad Request

```json
{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "titulo": "Atenção",
  "status": 400,
  "erros": [
    "Campo 'idTipoGarantia' é obrigatório.",
    "A Nota Comercial não está em status que permita alteração de garantias."
  ]
}
```