---
title: 5.9. Cancelar contrato
url: https://docs.vehub.com.br/API/VeFlow%20-%20Cart%C3%A3o%20de%20cr%C3%A9dito/5.%20Contrato%20de%20receb%C3%ADveis/v1.1/5.9.%20Cancelar%20contrato/
---
# 5.9. Cancelar contrato

## 🔗 Endpoint

| Método                                             | URL                                              |
| -------------------------------------------------- | ------------------------------------------------ |
| ![DELETE](https://img.shields.io/badge/DELETE-red) | `/public/api/v1.1/cartao/contratos/{idContrato}` |

---

## 🧾 Descrição

Solicita o **cancelamento de um contrato** de cartão previamente criado na plataforma **VeFlow**.

O processo é **assíncrono**: a plataforma valida as regras de elegibilidade, responde `202 Accepted` com o `identificadorProcessamento` e encaminha o cancelamento ao regime de interoperabilidade junto à registradora. O contrato passa para o status **8 — Em cancelamento** e só chega a **5 — Cancelado** quando a registradora confirma. O desfecho é informado por webhook.

---

## ⚠ Regras de cancelamento

* **Nenhuma UR vinculada ao contrato pode estar liquidada.**
* A **próxima UR performada** — isto é, a de data de liquidação mais próxima — deve estar a **no mínimo D+3 dias úteis** da data atual.
    * Exemplo: se hoje é 07/08, a próxima UR deve ser a partir de 12/08 (considerando 08, 09 e 12 como dias úteis).
* A requisição é aceita **somente dentro da janela operacional: 09:00 às 18:00 em dias úteis**.

Atendidas essas regras, o pedido de cancelamento é encaminhado à registradora.

---

## 📤 Requisição

### 🔑 Parâmetros de rota

| Parâmetro  | Tipo   | Obrigatório | Descrição                                                                        |
| ---------- | ------ | ----------- | -------------------------------------------------------------------------------- |
| idContrato | string | Sim         | GUID do contrato, devolvido em [5.1. Criar contratos](5.1.%20Criar%20contratos.md). |

### 📋 Payload (JSON)

```json
{
  "motivo": 0,
  "descricao": ""
}
```

### 🧾 Detalhamento dos Campos

| Campo     | Tipo    | Obrigatório | Descrição                                                                              |
| --------- | ------- | ----------- | -------------------------------------------------------------------------------------- |
| motivo    | integer | Sim         | Motivo do cancelamento (ver tabela **Motivos de cancelamento** abaixo).                 |
| descricao | string  | Não         | Texto livre com o detalhamento do cancelamento. Máximo de 500 caracteres.               |

### 🔢 Motivos de cancelamento

| Código | Descrição                     |
| ------ | ----------------------------- |
| 1      | Valor solicitado não atingido |
| 2      | Falha ao vincular URs         |
| 3      | Cancelamento manual           |
| 4      | Outros                        |
| 5      | Falha no envio ao fundo       |

**Regras e formatos**

* `motivo` aceita somente os códigos de `1` a `5`. Qualquer outro valor é recusado com `400 Bad Request`.
* Recomenda-se preencher `descricao` sempre que `motivo = 4` (Outros), para rastreabilidade da operação.

---

## 🧪 Exemplo de cURL

```bash
curl -X DELETE https://api.veflow.com/public/api/v1.1/cartao/contratos/5174568D-9FFE-4C10-9FC2-B0F4E7F8D1B6 \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}" \
  -H "Idempotency-Key: 1f8ad6c3-4b90-4e72-98a5-6c31de07b2f9" \
  -H "Content-Type: application/json" \
  -d '{
    "motivo": 3,
    "descricao": "Cancelamento solicitado pelo cedente antes do registro definitivo."
  }'
```

---

## 📥 Responses

### ✅ 202 Accepted

```json
{
  "identificador": "5174568D-9FFE-4C10-9FC2-B0F4E7F8D1B6",
  "identificadorProcessamento": "A1B2C3D4-1111-2222-3333-444455556666",
  "mensagem": "Contrato enviado para cancelamento!"
}
```

| Campo                      | Tipo   | Descrição                                                     |
| -------------------------- | ------ | ------------------------------------------------------------- |
| identificador              | string | GUID do contrato em cancelamento.                             |
| identificadorProcessamento | string | GUID do processamento assíncrono, para acompanhamento.        |
| mensagem                   | string | Mensagem de confirmação do recebimento.                       |

---

### ❌ 400 Bad Request

```json
{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "titulo": "Atenção",
  "status": 400,
  "erros": [
    "Campo 'motivo' é obrigatório.",
    "Motivo de cancelamento inválido. Valores aceitos: 1 a 5.",
    "Não é possível cancelar o contrato pois já existem URs liquidadas.",
    "A próxima UR performada está com liquidação inferior a 3 dias úteis.",
    "Contrato já cancelado anteriormente."
  ]
}
```

---

### ❌ 403 Forbidden — fora da janela de operação

```json
{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.4",
  "titulo": "Atenção",
  "status": 403,
  "erros": [
    "Operação permitida apenas entre 09:00 e 18:00 em dias úteis."
  ]
}
```

---

### ❌ 404 Not Found

```json
{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "titulo": "Atenção",
  "status": 404,
  "erros": [
    "Contrato não encontrado."
  ]
}
```

---

## 🔄 Mudanças em relação à v1

| Aspecto            | v1                                                     | v1.1                                                                        |
| ------------------ | ------------------------------------------------------ | --------------------------------------------------------------------------- |
| Rota               | `DELETE /public/api/v1/cartao/contrato/{identificador}` | `DELETE /public/api/v1.1/cartao/contratos/{idContrato}`                     |
| Corpo              | Sem corpo                                              | `motivo` (obrigatório) e `descricao`                                        |
| Retorno de sucesso | `200 OK` com `identificador` e `mensagem`              | `202 Accepted` com `identificador`, `identificadorProcessamento` e `mensagem` |
| Fora da janela     | Objeto simples com `mensagem`                          | `403 Forbidden` no formato **RFC 9110** (`tipo`, `titulo`, `status`, `erros`) |

---

## 🕒 Observações

* O `202 Accepted` indica apenas que a solicitação passou pelas validações iniciais. O **status final do cancelamento é informado por webhook** — ver [3.2. Atualizações do contrato](../../3.%20Notificações%20-%20WebHook/3.2.%20Atualizações%20do%20contrato.md).
* Enquanto o contrato estiver em **8 — Em cancelamento**, não é possível adicionar nem remover URs.
* Se a registradora recusar o cancelamento, o contrato passa para **9 — Falha no cancelamento** e permanece ativo; a solicitação precisa ser refeita.
* Cancelamentos fora das regras descritas são recusados com `400 Bad Request` — nenhuma solicitação é registrada nesses casos.
* URs que estavam vinculadas ao contrato cancelado permanecem consultáveis para fins de auditoria em [5.3. Detalhes do contrato](5.3.%20Detalhes%20do%20contrato.md) e em [5.10. URs removidas e rejeitadas](5.10.%20URs%20removidas%20e%20rejeitadas.md).
* Envie sempre o header `Idempotency-Key`: em caso de reenvio, a mesma chave devolve o `identificadorProcessamento` original em vez de abrir um novo cancelamento.
* Headers obrigatórios e convenções gerais: [1.1. Primeiros Passos](../../1.%20Início/1.1.%20Primeiros%20Passos.md).