5.9. Cancelar contrato¶

🔗 Endpoint¶

Método	URL
	`/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.

📋 Payload (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¶

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¶

{
  "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¶

{
  "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¶

{
  "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¶

{
  "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.
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 e em 5.10. URs removidas e rejeitadas.
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.