Skip to main content
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.
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.

​
Endpoint

​
POST
endpoint
/api/v1/e-consignado/contratos/{ContractID}/cancelar

​
URL Base

​
HML
https://integracao.apidev.wincred.digital
​
PROD
https://api.wincred.com.br

​
Headers

HeaderTipoObrigatórioDescrição
Content-TypestringSimapplication/json
AuthorizationstringSimBearer {seu_token_de_acesso}

​
Parâmetros

​
Path Parameters

​
ContractID
UUID
required
Identificador único do contrato que será canceladoExemplo: 019a7d83-6b10-7ec8-ad35-fbcb2a61bb17

​
Request Body

​
motivo_cancelamento
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.

​
Regras de Negócio

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.
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.
O motivo do cancelamento é opcional, mas recomenda-se informá-lo para facilitar a rastreabilidade e análise de motivos de cancelamento no futuro.
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.

​
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)

{
    "erros": [
        {
            "codigo": "WIN_C00002",
            "msg": "Contrato não encontrado"
        }
    ]
}

​
Respostas de erro comuns no sistema

​
Resposta de Erro (4xx Bad Request)

{
    "erros": [
        {
            "codigo": "WIN_xxxx",
            "msg": "MENSGEM DE ERRO DESCRITIVA"
        }
    ]
}

​
Resposta de Erro (422 Unprocessable Entity)

{
  "erros": [
    {
      "codigo": "WIN_XXXX",
      "msg": "Proposta não encontrada"
    }
  ]
}

​
Resposta de Erro (401 Unauthorized)

{
  "code": 401,
  "message": ""
}
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.

​
Resposta de Erro (500 Unauthorized)

{
  "code": 500,
  "message": ""
}

​
Códigos de Status

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

​
Exemplos

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"
}'

​
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
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).

​
Relacionado

Atualizar Dados Bancários

Atualize dados bancários antes de cancelar por dados inválidos.

Eventos de Resultado de Proposta

Entenda os webhooks relacionados ao ciclo de vida do contrato.