5.7. Adicionar URs ao contrato¶

🔗 Endpoint¶

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

🧾 Descrição¶

Adiciona uma ou mais URs (Unidades de Recebíveis) a um contrato já existente, reforçando a composição do contrato sem precisar cancelá-lo e recriá-lo.

O processamento é assíncrono: a plataforma VeFlow valida a requisição, responde 202 Accepted com o identificadorProcessamento e segue com o vínculo junto à registradora. O resultado de cada UR é informado por webhook — ver 3.2. Atualizações do contrato.

⚠ Regras de inclusão¶

A UR não pode estar liquidada.
O valorGarantido solicitado não pode exceder o valor livre da UR na registradora. URs já comprometidas em outros contratos entram somente pelo saldo remanescente.
O contrato precisa estar em status que aceite composição. Contratos cancelados (status = 5) e liquidados (status = 7) não recebem novas URs.
A requisição é aceita somente dentro da janela operacional: 09:00 às 18:00 em dias úteis.
Cada UR é processada individualmente: parte da lista pode ser vinculada com sucesso enquanto outra parte falha. O desfecho por UR chega por webhook.

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

{
  "urs": [
    {
      "idUr": "",
      "valorGarantido": 0.00
    }
  ]
}

🧾 Detalhamento dos Campos¶

Campo	Tipo	Obrigatório	Descrição
urs	object[]	Sim	Lista de URs a serem adicionadas ao contrato. Mínimo de 1 e máximo de 500 itens por requisição.
urs[].idUr	string	Sim	GUID da UR a ser vinculada ao contrato.
urs[].valorGarantido	number	Sim	Valor da UR a ser comprometido no contrato, com 2 casas decimais. Deve ser maior que zero.

Regras e formatos

idUr não pode se repetir dentro da mesma requisição.
valorGarantido é o vocabulário da fase de contrato: representa quanto daquela UR passa a estar comprometido neste contrato.
Em contratos de troca de titularidade (tipoContrato = 1), valorNominal, valorDesconto e valorAquisicao das URs adicionadas são calculados pela plataforma com a taxa do contrato. Em contratos de garantia (tipoContrato = 2) não há deságio e esses campos não existem.

🧪 Exemplo de cURL¶

curl -X POST https://api.veflow.com/public/api/v1.1/cartao/contratos/5174568D-9FFE-4C10-9FC2-B0F4E7F8D1B6/urs \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}" \
  -H "Idempotency-Key: 7e1b4c92-2f55-4d0b-9a83-1c6e5d40af73" \
  -H "Content-Type: application/json" \
  -d '{
    "urs": [
      { "idUr": "29E8F0CE-3391-4A65-8091-2331802CEABE", "valorGarantido": 1500.00 },
      { "idUr": "7D121577-3C5A-494D-B052-291D9E100D0D", "valorGarantido": 820.45 }
    ]
  }'

📥 Responses¶

✅ 202 Accepted¶

{
  "identificadorProcessamento": "A1B2C3D4-1111-2222-3333-444455556666",
  "mensagem": "Solicitação de inclusão de URs recebida com sucesso!"
}

Campo	Tipo	Descrição
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 'urs' é obrigatório e deve conter ao menos um item.",
    "Campo 'valorGarantido' deve ser maior que zero.",
    "A UR já está liquidada e não pode ser adicionada ao contrato.",
    "O valor garantido informado excede o valor livre da UR.",
    "O contrato está cancelado e não aceita novas URs."
  ]
}

❌ 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."
  ]
}

🕒 Observações¶

O 202 Accepted indica apenas que a solicitação passou pelas validações iniciais. A efetivação do vínculo é informada por webhook.
O status de cada UR no contrato (0 = vinculada com sucesso, 1 = falha no vínculo, 2 = em processamento, 3 = pendente extensão, 999 = UR cancelada) chega em 3.2. Atualizações do contrato.
URs que a registradora ou a plataforma rejeitarem ficam disponíveis para auditoria em 5.10. URs removidas e rejeitadas.
A composição atualizada do contrato pode ser conferida em 5.3. Detalhes do contrato.
Envie sempre o header Idempotency-Key: em caso de reenvio, a mesma chave devolve o identificadorProcessamento original em vez de duplicar a inclusão.
Headers obrigatórios e convenções gerais: 1.1. Primeiros Passos.