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.
A operação é de uma modalidade só (antecipação ou garantia), e por isso todos os itens do carrinho têm o mesmo tipoContrato — ver 2.1. Conceitos.
Nesta versão, cada UR fica em um item só nas estratégias 1 a 3. Compare a alocação com o valorDisponivel da UR — a fórmula está em 2.2. Dicionário de dados. A UR que não cabe fica Ignorada, com o motivo — ver 8.1. Enumerações.

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 no carrinho. Nesta versão, cada UR está em um item só.

🔹 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.
Cada UR fica em um item só nas estratégias 1 a 3. A alocação é comparada com o valorDisponivel da UR, não com o valorLivre — a fórmula está em 2.2. Dicionário de dados. A UR que não cabe fica Ignorada, com o motivo — ver 8.1. Enumerações; ela não é gravada no item e por isso não aparece nesta consulta, só na resposta da chamada que fez a alocação. 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.