4.8. Consultar carrinho¶

🔗 Endpoint¶

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

🧾 Descrição¶

Retorna o carrinho da agenda: os itens montados até agora, o total garantido por eles e a validade da agenda que os sustenta.

🛒 Como o carrinho funciona¶

Uma agenda tem um único carrinho, e esse carrinho tem N itens.
Cada item vira um contrato no momento da efetivação. Um carrinho com três itens gera três contratos.
Itens de tipos diferentes coexistem no mesmo carrinho: você pode ter um item de troca de titularidade (antecipação) e outro de garantia lado a lado.
A mesma UR pode ser rateada entre itens, desde que a soma alocada nela respeite o valorDisponivel daquela UR — o valor livre já descontado o percentual máximo por UR configurado na operação.

Consulte este endpoint antes de efetivar: ele é a fotografia do que será registrado.

📤 Requisição¶

🧭 Parâmetros de rota¶

Parâmetro	Tipo	Obrigatório	Descrição
idAgenda	string	Sim	GUID da agenda, devolvido em 4.1. Solicitar agenda.

🧪 Exemplo de cURL¶

curl -X GET https://api.veflow.com/public/api/v1.1/cartao/agendas/534D8AAE-61E4-4264-9D15-715B9E1F1D51/carrinho \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}" \
  -H "Content-Type: application/json"

📥 Responses¶

✅ 200 OK¶

{
  "quantidadeItens": 2,
  "totais": {
    "valorGarantido": 45000.00,
    "quantidadeUrs": 12
  },
  "itens": [
    {
      "idItem": "9E5B1C77-40A2-4D6E-8B31-52C7A0F9D184",
      "tipoContrato": 1,
      "valorGarantido": 25000.00,
      "quantidadeUrs": 7
    },
    {
      "idItem": "C1F70D3B-6A94-4E52-9C08-7B3E15A2D6F0",
      "tipoContrato": 2,
      "valorGarantido": 20000.00,
      "quantidadeUrs": 6
    }
  ],
  "dataValidadeAgenda": "2025-09-03T18:00:00"
}

🧾 Detalhamento dos Campos¶

🔹 Nível raiz¶

Campo	Tipo	Descrição
quantidadeItens	integer	Quantidade de itens no carrinho. Cada item vira um contrato na efetivação.
totais	object	Consolidado do carrinho (ver abaixo).
itens	array	Itens montados no carrinho. Array vazio (`[]`) significa carrinho vazio.
dataValidadeAgenda	string	Validade da agenda que sustenta o carrinho. Passada essa data e hora, os itens são invalidados.

🔹 totais¶

Campo	Tipo	Descrição
valorGarantido	number	Soma do `valorGarantido` de todos os itens — quanto das URs está sendo utilizado pelo carrinho.
quantidadeUrs	integer	Quantidade de URs distintas envolvidas. Uma UR rateada entre dois itens conta uma vez aqui, e uma vez em cada item.

🔹 itens¶

Campo	Tipo	Descrição
idItem	string	GUID do item de carrinho. Use-o para consultar, alterar ou remover o item.
tipoContrato	integer	Tipo do contrato que o item vai gerar: `1` = Troca de titularidade, `2` = Garantia.
valorGarantido	number	Quanto de UR o item já tem alocado.
quantidadeUrs	integer	Quantidade de URs alocadas no item.

🔢 tipoContrato¶

Código	Significado
1	Troca de titularidade — antecipação: a UR é cedida ao fundo. É a única fase em que existem `valorNominal`, `valorDesconto` e `valorAquisicao`.
2	Garantia — a UR fica travada em favor do credor, sem cessão. Não tem deságio: nunca traz nominal, desconto, aquisição nem taxa.

Fumaça não é tipo de contrato. É uma configuração da garantia (tipoContrato = 2): prazo estendido, somente URs performadas e regra de retenção. Aparece nos parâmetros do item, não neste código.

✅ 200 OK — carrinho vazio¶

{
  "quantidadeItens": 0,
  "totais": {
    "valorGarantido": 0.00,
    "quantidadeUrs": 0
  },
  "itens": [],
  "dataValidadeAgenda": "2025-09-03T18:00:00"
}

Uma agenda sem itens montados devolve 200 com o carrinho vazio — não 404.

❌ 404 Not Found¶

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "titulo": "Não encontrado",
  "status": 404,
  "erros": [
    "Agenda '534D8AAE-61E4-4264-9D15-715B9E1F1D51' não encontrada."
  ]
}

🕒 Observações¶

Cada item é montado por uma estratégia de alocação: 1 = URs selecionadas, 2 = Split por valor desejado, 3 = Troca por valor desejado, 4 = Alocação automática por parcela. Ver 4.10. Adicionar item.
O rateio da mesma UR entre itens é validado contra o valorDisponivel da UR, não contra o valorLivre. Ultrapassar o teto faz a alocação ser recusada — confira os valores em 4.4. Listar URs da agenda.
Na alocação automática por parcela, a plataforma busca as melhores URs para cada parcela por regras de prioridade (menor prazo, maior valor disponível, ordenação configurada) e considera URs com data prevista de liquidação a partir de 5 dias úteis antes da data de vencimento da parcela. Esse comportamento é parametrizável por cliente.
valorGarantido é o vocabulário da fase de carrinho e contrato. Enquanto o item não é efetivado, esse valor é alocação na plataforma — ainda não é ônus registrado nas registradoras. O ônus registrado aparece como valorComprometido em 4.5. Detalhes da UR.
Depois de dataValidadeAgenda, os itens do carrinho são invalidados e é necessário refazer a consulta e remontar o carrinho — ver 4.7. Refazer consulta.
Não existe CET no retorno de nenhuma rota da agenda ou do carrinho.
Headers obrigatórios e convenções gerais: 1.2. Convenções da API.