4.6. Adicionar UR a Simulação¶

🔗 Endpoint¶

Método	URL
	/api/v1.1/cartao/agenda/{identificador}/simulacoes/{idSimulacao}/adiciona-ur

🧾 Descrição¶

Vincula manualmente (ou por lote) URs performadas a simulação já cadastradas para uma agenda específica. Esse endpoint permite ao usuário forçar a associação de uma ou mais URs a uma simulação/contrato identificado, quando a alocação automática não atende ou quando há necessidade de ajuste manual.

Validações importantes realizadas pelo servidor:

• As URs informadas em idTitulos devem estar presentes na agenda referenciada por {identificador}.
• Cada UR deve possuir valorLivre > 0 para ser efetivamente vinculada.

📤 Requisição¶

📋 Payload (JSON)¶

{
  "idTitulos": []
}

🧾 Detalhamento dos Campos¶

Regras de validação

• idTitulos deve conter pelo menos 1 GUID válido.

• Para cada idTitulo:

  • Verificar se pertence à agenda {identificador} — caso contrário, retornar erro (4xx).
  • Verificar valorLivre > 0 — caso contrário, retornar erro (4xx).

🧪 Exemplo de cURL¶

curl -X POST https://api.veflow.com/api/v1.1/cartao/agenda/534D8AAE-61E4-4264-9D15-715B9E1F1D51/vincula-ur-parcela-garantia \
  -H "Authorization: Bearer {seu_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "idTitulos": [
      "7D121577-3C5A-494D-B052-291D9E100D0D",
      "A1B2C3D4-5E6F-7890-1234-56789ABCDEF0"
    ],
    "idSimulacao": "264E71E2-827D-4EE2-A0E9-AD66EF851C5C"
  }'

📥 Responses¶

✅ 200 OK¶

{
  "mensagem": "Vínculos processados."
}

Indica que os vínculos foram processados com sucesso. O retorno não detalha individualmente cada vínculo — para isso consulte o recurso de detalhe da simulação/agenda.

❌ 400 Bad Request — UR não pertence à agenda (exemplo)¶

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "titulo": "Atenção",
  "status": 400,
  "erros": [
    "UR 'A1B2C3D4-5E6F-7890-1234-56789ABCDEF0' não pertence à agenda '534D8AAE-61E4-4264-9D15-715B9E1F1D51'."
  ]
}

❌ 400 Bad Request — UR sem valor livre (exemplo)¶

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "titulo": "Atenção",
  "status": 400,
  "erros": [
    "UR '7D121577-3C5A-494D-B052-291D9E100D0D' possui valorLivre = 0 e não pode ser vinculada."
  ]
}

❌ 409 Conflict — conflito de vínculo (exemplo)¶

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "titulo": "Conflito",
  "status": 409,
  "erros": [
    "UR '7D121577-3C5A-494D-B052-291D9E100D0D' já está vinculada a outra parcela no contrato 'CTR-2025-0001'."
  ]
}

🕒 Observações¶

• O processamento pode ser síncrono (resposta imediata) ou assíncrono (retorno de identificador para acompanhamento) dependendo do volume — o contrato de API deve definir o comportamento.
• Após vinculação, os balances (valorLivre, valorGarantido) da UR serão atualizados.
• Autenticação obrigatória via Authorization: Bearer {token}.
• Para desfazer vínculos, utilize o endpoint de remoção de vínculo.