4.16. Adicionar URs ao item¶

🔗 Endpoint¶

Método	URL
	`/public/api/v1.1/cartao/agendas/{idAgenda}/carrinho/itens/{idItem}/urs`

🧾 Descrição¶

Vincula URs da agenda a um item de carrinho já existente, informando quanto de cada UR deve ser alocado no item.

É o endpoint de ajuste manual da composição: use-o para completar um item criado com estrategia igual a 1 (URs selecionadas) ou para corrigir a composição de um item montado com estrategia igual a 4 (Alocação automática por parcela), quando a alocação automática não atendeu.

O processamento é síncrono: a resposta já traz o resultado consolidado da alocação, com o que foi aceito, o que foi ignorado e os totais do item. Este endpoint não devolve identificadorProcessamento.

Informar valorGarantido por UR é justamente o que habilita o rateio parcial: a mesma UR pode compor mais de um item do carrinho, desde que a soma alocada entre todos os itens não passe do seu valorDisponivel.

📋 Parâmetros de rota¶

Parâmetro	Tipo	Obrigatório	Descrição
idAgenda	string	Sim	GUID da agenda, devolvido como `identificador` em 4.1 e 4.2.
idItem	string	Sim	GUID do item de carrinho, devolvido na criação do item em 4.10.

📤 Requisição¶

📋 Payload (JSON)¶

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

🧾 Detalhamento dos Campos¶

Campo	Tipo	Obrigatório	Descrição
urs	object[]	Sim	URs a vincular ao item. Deve conter ao menos um elemento.
urs[].idUr	string	Sim	GUID da UR a vincular. A UR deve pertencer à agenda informada em `{idAgenda}`.
urs[].valorGarantido	number	Não	Quanto da UR alocar neste item. Quando omitido, aloca todo o `valorDisponivel` da UR.
urs[].tipoValor	integer	Não	Como interpretar `valorGarantido`. Ver tabela Tipo de valor. Padrão: `1` (Valor absoluto).

🔢 Tipo de valor¶

Código	Significado	Como o `valorGarantido` é interpretado
1	Valor absoluto	Valor em reais, com até 2 casas decimais.
2	Percentual	Percentual do `valorDisponivel` da UR, de `0` a `100`, com até 4 casas decimais.

Regras de validação

urs não pode ser vazio e cada elemento precisa ter idUr.
Cada UR informada deve pertencer à agenda do path.
Cada UR informada deve ter valorDisponivel maior que zero para ser alocada.
Quando valorGarantido é informado, precisa ser maior que zero e não pode passar do valorDisponivel da UR.
URs que não passam nas validações individuais não interrompem a chamada: elas voltam no array ignoradas com o motivo, e as demais são alocadas normalmente.
Se a soma alocada da mesma UR entre os itens do carrinho passar do valorDisponivel, a chamada inteira é recusada com 409 Conflict e nenhuma alocação é aplicada.

🧪 Exemplo de cURL¶

curl -X POST https://api.veflow.com/public/api/v1.1/cartao/agendas/534D8AAE-61E4-4264-9D15-715B9E1F1D51/carrinho/itens/AEB4EA8C-BEF4-4E4E-A009-0A94AF172EAB/urs \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}" \
  -H "Idempotency-Key: c48e21b0-7f35-49aa-8d02-1e6b5c93af77" \
  -H "Content-Type: application/json" \
  -d '{
    "urs": [
      {
        "idUr": "7D121577-3C5A-494D-B052-291D9E100D0D",
        "valorGarantido": 1500.00,
        "tipoValor": 1
      },
      {
        "idUr": "A1B2C3D4-5E6F-7890-1234-56789ABCDEF0",
        "valorGarantido": 50.0000,
        "tipoValor": 2
      }
    ]
  }'

📥 Responses¶

✅ 200 OK¶

{
  "adicionadas": 2,
  "ignoradas": [
    {
      "idUr": "B7E4C0D2-9A18-4F55-83C6-2D1F7A9E4B30",
      "motivo": "UR não pertence à agenda informada."
    }
  ],
  "totais": {
    "quantidadeUrs": 12,
    "valorGarantido": 48250.00,
    "valorGarantidoAdicionado": 3200.00
  }
}

🧾 Detalhamento dos Campos¶

Campo	Tipo	Descrição
adicionadas	integer	Quantidade de URs efetivamente vinculadas ao item nesta chamada.
ignoradas	object[]	URs informadas que não foram vinculadas, com o motivo de cada uma.
totais	object	Consolidado do item depois da operação.

🔹 ignoradas¶

Campo	Tipo	Descrição
idUr	string	GUID da UR que não foi vinculada.
motivo	string	Motivo da recusa. Ver tabela Motivos de UR ignorada.

🔹 totais¶

Campo	Tipo	Descrição
quantidadeUrs	integer	Quantidade de URs vinculadas ao item após a operação.
valorGarantido	number	Soma do `valorGarantido` alocado no item após a operação.
valorGarantidoAdicionado	number	Soma dos valores alocados nesta chamada.

📝 Motivos de UR ignorada¶

Motivo	Quando acontece
`UR não pertence à agenda informada.`	O `idUr` existe, mas está em outra agenda. Cada item só pode ser composto por URs da agenda em que foi criado.
`UR sem valor disponível para alocação.`	O `valorDisponivel` da UR é zero — ela já está integralmente alocada em outros itens ou comprometida.
`UR já vinculada a este item.`	A UR já compõe o item. Para alterar o valor alocado, remova-a em 4.17 e vincule novamente.
`UR não performada e o item exige somente URs performadas.`	O item é de garantia com configuração de fumaça, que aceita apenas URs performadas.

❌ 400 Bad Request¶

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "titulo": "Atenção",
  "status": 400,
  "erros": [
    "O array 'urs' deve conter ao menos um elemento.",
    "Campo 'idUr' é obrigatório em todos os elementos de 'urs'.",
    "Campo 'tipoValor' inválido. Valores aceitos: 1 ou 2."
  ]
}

❌ 404 Not Found¶

Retornado quando a agenda ou o item informados não existem no grupo econômico.

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

❌ 409 Conflict¶

Retornado quando a soma alocada da mesma UR entre os itens do carrinho passa do valorDisponivel da UR. Nenhuma alocação da chamada é aplicada.

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
  "titulo": "Atenção",
  "status": 409,
  "erros": [
    "UR '7D121577-3C5A-494D-B052-291D9E100D0D' já possui 1200.00 alocados em outros itens do carrinho. A soma solicitada (2000.00) excede o valorDisponivel de 1500.00."
  ]
}

🔄 Mudanças nesta versão¶

O que mudou	Detalhe
A rota `adiciona-ur` virou o sub-recurso `urs`	As URs de um item passaram a ser um sub-recurso REST: `.../carrinho/itens/{idItem}/urs`. A rota `vincula-ur-parcela-garantia`, que aparecia no cURL antigo, não existe.
`idTitulos` virou o array `urs` com valor por UR	Antes era uma lista simples de GUIDs, que só permitia alocar a UR inteira. Agora cada elemento leva `idUr`, `valorGarantido` e `tipoValor`, o que habilita o rateio parcial.
O campo `idSimulacao` saiu do corpo	O identificador do item já está no path, em `{idItem}`. Mandá-lo também no corpo era redundante e permitia divergência.
O comportamento é síncrono	A versão anterior dizia que a operação poderia ser síncrona ou assíncrona. A definição é: síncrona, com o resultado consolidado na própria resposta.
Entraram `ignoradas` e `totais`	Antes o retorno era só uma mensagem, sem detalhe por vínculo. Agora a resposta diz o que entrou, o que foi ignorado e como o item ficou.

🕒 Observações¶

Este endpoint trata apenas de alocação (valorGarantido). Deságio não é calculado aqui: contratos de garantia não têm deságio, e em itens de troca de titularidade os valores de antecipação (valorNominal, valorDesconto e valorAquisicao) são apurados nas consultas de contrato, na seção 5.
O tipoContrato do item define o que pode ser vinculado: 1 (Troca de titularidade) ou 2 (Garantia). Quando a garantia usa a configuração de fumaça — prazo estendido, somente URs performadas e regra de retenção —, apenas URs performadas são aceitas.
URs com promessa de cessão já têm o ônus de terceiro refletido em valorComprometido, o que reduz o valorLivre e, por consequência, o valorDisponivel. A promessa de cessão aparece apenas em leitura, nunca é criada pela API.
Use Idempotency-Key para poder repetir a chamada com segurança em caso de timeout, sem alocar a mesma UR duas vezes.
Para conferir como o item ficou, use 4.18. Listar URs do item. Para desfazer vínculos, use 4.17. Remover URs do item.
Confira a dataValidade da agenda antes de vincular URs: passada a validade, os itens montados sobre ela são invalidados — ver 4.3. Detalhes da agenda.
Headers obrigatórios e convenções gerais: 1.2. Convenções da API.