> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wincred.digital/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancelar Contrato

> Cancele contratos que apresentaram erro antes da conclusão do KYC

Esta API permite o cancelamento de contratos que tiveram algum erro durante o processo de contratação, até a fase de KYC. É utilizada para encerrar propostas que não podem prosseguir devido a problemas identificados nas etapas iniciais.

<Warning>
  Esta API só pode ser utilizada para contratos que ainda não passaram pela fase de Averbação. Contratos que já foram averbados não podem ser cancelados através deste endpoint e devem seguir o processo de cancelamento padrão da instituição financeira.
</Warning>

## Endpoint

<ParamField path="POST" type="endpoint">
  `/api/v1/e-consignado/contratos/{ContractID}/cancelar`
</ParamField>

### URL Base

<ParamField path="HML">
  `https://integracao.apidev.wincred.digital`
</ParamField>

<ParamField path="PROD">
  `https://api.wincred.com.br`
</ParamField>

### Headers

| Header          | Tipo   | Obrigatório | Descrição                      |
| --------------- | ------ | ----------- | ------------------------------ |
| `Content-Type`  | string | Sim         | `application/json`             |
| `Authorization` | string | Sim         | `Bearer {seu_token_de_acesso}` |

## Parâmetros

### Path Parameters

<ParamField path="ContractID" type="UUID" required>
  Identificador único do contrato que será cancelado

  **Exemplo:** `019a7d83-6b10-7ec8-ad35-fbcb2a61bb17`
</ParamField>

### Request Body

<ParamField body="motivo_cancelamento" type="string">
  Descrição do motivo do cancelamento do contrato (campo opcional)

  **Exemplo:** `"Cliente desistiu da proposta"`

  **Observação:** Este campo é opcional e pode ser utilizado para registrar o motivo do cancelamento no histórico do contrato.
</ParamField>

## Regras de Negócio

<AccordionGroup>
  <Accordion title="Fase do Contrato" icon="circle-check">
    O cancelamento só é permitido para contratos que ainda não passaram pela fase de Averbação. Contratos em qualquer status antes da conclusão do KYC podem ser cancelados através deste endpoint.
  </Accordion>

  <Accordion title="Contratos Averbados" icon="ban">
    Contratos que já foram averbados não podem ser cancelados através deste endpoint. Para estes casos, deve-se seguir o processo de cancelamento padrão estabelecido pela instituição financeira.
  </Accordion>

  <Accordion title="Registro de Motivo" icon="file-lines">
    O motivo do cancelamento é opcional, mas recomenda-se informá-lo para facilitar a rastreabilidade e análise de motivos de cancelamento no futuro.
  </Accordion>

  <Accordion title="Efeitos do Cancelamento" icon="triangle-exclamation">
    Após o cancelamento, o contrato não poderá ser reativado. Caso o cliente deseje prosseguir, será necessário criar uma nova proposta do zero.
  </Accordion>
</AccordionGroup>

## Respostas

### 204 - No Content

A requisição foi bem-sucedida e o contrato foi cancelado. Não há conteúdo no corpo da resposta.

```
Status: 204 No Content
```

### Resposta de Erro (404 Not Found)

```json theme={null}
{
    "erros": [
        {
            "codigo": "WIN_C00002",
            "msg": "Contrato não encontrado"
        }
    ]
}
```

## Respostas de erro comuns no sistema

### Resposta de Erro (4xx Bad Request)

```json theme={null}
{
    "erros": [
        {
            "codigo": "WIN_xxxx",
            "msg": "MENSGEM DE ERRO DESCRITIVA"
        }
    ]
}
```

### Resposta de Erro (422 Unprocessable Entity)

```json theme={null}
{
  "erros": [
    {
      "codigo": "WIN_XXXX",
      "msg": "Proposta não encontrada"
    }
  ]
}
```

### Resposta de Erro (401 Unauthorized)

```json theme={null}
{
  "code": 401,
  "message": ""
}
```

<Warning>
  **Esse payload é um retorno da API de autenticação e não da API do sistema.**

  Esta resposta pode indicar que o token de autenticação fornecido é inválido ou expirou. Verifique se o token está correto e se ainda é válido.
</Warning>

### Resposta de Erro (500 Unauthorized)

```json theme={null}
{
  "code": 500,
  "message": ""
}
```

## Códigos de Status

| Código | Descrição                            |
| ------ | ------------------------------------ |
| `202`  | Requisição aceita e em processamento |
| `401`  | Não autorizado - token inválido      |
| `422`  | Erro de validação dos dados          |
| `429`  | Muitas requisições, limite atingido  |
| `500`  | Erro interno do servidor             |

***

## Exemplos

<CodeGroup>
  ```bash cURL theme={null}
  curl --location --request POST 'https://api.wincred.com.br/api/v1/e-consignado/contratos/019a7d83-6b10-7ec8-ad35-fbcb2a61bb17/cancelar' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer seu-token-aqui' \
  --data '{
      "motivo_cancelamento": "Cliente desistiu da proposta"
  }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.wincred.com.br/api/v1/e-consignado/contratos/019a7d83-6b10-7ec8-ad35-fbcb2a61bb17/cancelar',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer seu-token-aqui'
      },
      body: JSON.stringify({
        motivo_cancelamento: 'Cliente desistiu da proposta'
      })
    }
  );

  if (response.status === 204) {
    console.log('Contrato cancelado com sucesso');
  }
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.wincred.com.br/api/v1/e-consignado/contratos/019a7d83-6b10-7ec8-ad35-fbcb2a61bb17/cancelar"

  payload = {
      "motivo_cancelamento": "Cliente desistiu da proposta"
  }

  headers = {
      "Content-Type": "application/json",
      "Authorization": "Bearer seu-token-aqui"
  }

  response = requests.post(url, json=payload, headers=headers)

  if response.status_code == 204:
      print("Contrato cancelado com sucesso")
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "net/http"
  )

  func main() {
      url := "https://api.wincred.com.br/api/v1/e-consignado/contratos/019a7d83-6b10-7ec8-ad35-fbcb2a61bb17/cancelar"

      payload := map[string]string{
          "motivo_cancelamento": "Cliente desistiu da proposta",
      }

      jsonData, _ := json.Marshal(payload)

      req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
      req.Header.Set("Content-Type", "application/json")
      req.Header.Set("Authorization", "Bearer seu-token-aqui")

      client := &http.Client{}
      resp, err := client.Do(req)

      if err != nil {
          panic(err)
      }
      defer resp.Body.Close()

      if resp.StatusCode == 204 {
          fmt.Println("Contrato cancelado com sucesso")
      }
  }
  ```
</CodeGroup>

## Cenários de Uso

### Cenário 1: Cliente Desiste da Proposta

1. Cliente informa que não deseja mais prosseguir com o contrato
2. Sistema valida que o contrato ainda não foi averbado
3. Sistema chama API de cancelamento com motivo: "Cliente desistiu da proposta"
4. API retorna 204 (sucesso)
5. Contrato é cancelado e não pode mais ser processado

### Cenário 2: Dados Bancários Inválidos - Limite Excedido

1. Contrato atinge o limite máximo de tentativas de correção de dados bancários
2. Sistema identifica que o contrato não pode prosseguir
3. Sistema chama API de cancelamento com motivo: "Limite de tentativas de validação excedido"
4. API retorna 204 (sucesso)
5. Contrato é cancelado automaticamente

### Cenário 3: Falha no Processo de KYC

1. KYC retorna com resultado negativo
2. Sistema identifica que o contrato não pode ser aprovado
3. Sistema chama API de cancelamento com motivo: "Falha na validação de KYC"
4. API retorna 204 (sucesso)
5. Contrato é cancelado

<Check>
  **Dica:** Sempre verifique o status do contrato antes de tentar o cancelamento. Contratos em status de averbação ou posteriores devem seguir o fluxo de cancelamento específico da instituição financeira (Nesse caso é necessário entrar em contato com o suporte da Wincred para orientação).
</Check>

## Relacionado

<CardGroup cols={2}>
  <Card title="Atualizar Dados Bancários" icon="building-columns" href="e-consignado/casos-de-uso/contratação-ativa/apis/04-atualizar-dados-bancarios">
    Atualize dados bancários antes de cancelar por dados inválidos.
  </Card>

  <Card title="Eventos de Resultado de Proposta" icon="webhook" href="/e-consignado/casos-de-uso/contratação-ativa/webhooks-e-eventos/03-evento-de-resultado-de-proposta">
    Entenda os webhooks relacionados ao ciclo de vida do contrato.
  </Card>
</CardGroup>