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 permite alocar parte do valor da UR no item. Nesta versão, cada UR fica em um item só nas estratégias 1 a 3.

📋 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	Identificador 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	Identificador 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 permite alocar parte do valor da UR.
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.