5.6. Atualizar contrato¶

🔗 Endpoint¶

Método	URL
	`/public/api/v1.1/cartao/contratos/{idContrato}`

🧾 Descrição¶

Atualiza os dados cadastrais de um contrato já criado na plataforma VeFlow.

A operação é um merge parcial: apenas os campos enviados no corpo da requisição são alterados; os campos omitidos permanecem exatamente como estão. A resposta é síncrona (200 OK) e devolve o estado do contrato depois da atualização.

Esta rota altera somente informações de controle (dataVencimento, contratoNumero, tags). Ela não movimenta URs nem recalcula valores — para alterar a composição do contrato use 5.7. Adicionar URs ao contrato e 5.8. Remover URs do contrato.

📤 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)¶

{
  "dataVencimento": "0000-00-00",
  "contratoNumero": "",
  "tags": [""]
}

🧾 Detalhamento dos Campos¶

Campo	Tipo	Obrigatório	Descrição
dataVencimento	string	Não	Nova data de vencimento do contrato, no formato `YYYY-MM-DD`.
contratoNumero	string	Não	Número do contrato no sistema do cliente. Usado para conciliação externa. Máximo de 60 caracteres.
tags	string[]	Não	Lista de tags de rastreabilidade do contrato (p.ex. `["PA_01"]`). O envio substitui integralmente a lista atual.

Regras e formatos

Ao menos um dos três campos deve ser enviado. Corpo vazio ({}) é recusado com 400 Bad Request.
Campos ausentes do corpo não são alterados. Para limpar contratoNumero, envie null; para limpar as tags, envie "tags": [].
dataVencimento não pode ser anterior à dataPrevistaLiquidacao da última UR vinculada ao contrato.
Contratos cancelados (status = 5) ou liquidados (status = 7) não aceitam atualização.
A atualização não altera tipoContrato, estrategia, valores nem a lista de URs do contrato.

🧪 Exemplo de cURL¶

curl -X PATCH 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: 3ac7d0f1-8b64-4e2a-a1c9-5f0e77bd2a41" \
  -H "Content-Type: application/json" \
  -d '{
    "dataVencimento": "2025-12-20",
    "contratoNumero": "CTR-2025-000123",
    "tags": ["PA_01","GARANTIA"]
  }'

📥 Responses¶

✅ 200 OK¶

{
  "identificador": "5174568D-9FFE-4C10-9FC2-B0F4E7F8D1B6",
  "dataVencimento": "2025-12-20",
  "contratoNumero": "CTR-2025-000123",
  "tags": ["PA_01", "GARANTIA"],
  "mensagem": "Contrato atualizado com sucesso!"
}

Campo	Tipo	Descrição
identificador	string	GUID do contrato atualizado.
dataVencimento	string	Data de vencimento vigente após a atualização.
contratoNumero	string	Número do contrato vigente após a atualização.
tags	string[]	Tags vigentes após a atualização.
mensagem	string	Mensagem de confirmação.

❌ 400 Bad Request¶

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "titulo": "Atenção",
  "status": 400,
  "erros": [
    "Informe ao menos um campo para atualização.",
    "Campo 'dataVencimento' inválido. Formato esperado: YYYY-MM-DD.",
    "A data de vencimento não pode ser anterior à liquidação da última UR vinculada."
  ]
}

❌ 404 Not Found¶

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

🕒 Observações¶

A atualização é síncrona e refletida imediatamente em 5.3. Detalhes do contrato.
Envie sempre o header Idempotency-Key para evitar duplicidade em caso de reenvio por timeout.
Alterações cadastrais não geram notificação de webhook de contrato — o webhook é disparado apenas em mudanças de status e de composição, ver 3.2. Atualizações do contrato.
Headers obrigatórios e convenções gerais: 1.1. Primeiros Passos.