4.12. Listar itens do carrinho¶

🔗 Endpoint¶

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

🧾 Descrição¶

Retorna a lista paginada dos itens do carrinho de uma agenda de recebíveis de cartão.

Cada item representa uma composição já persistida no carrinho — criada em 4.10. Adicionar item — com a estratégia usada para montá-la, os parâmetros de contrato (taxa, contrato no ERP, parcela) e os totais consolidados das URs alocadas. Itens que já foram efetivados trazem, no array contratos, os contratos gerados a partir deles.

Este endpoint devolve somente itens persistidos no carrinho. Cálculos de conferência que não geram item não aparecem aqui.

🔄 Mudanças em relação à versão anterior¶

O envelope deixou de ser um objeto com o array itens e passou a seguir o padrão paginado da casa: registros, paginacao e mensagem.
O campo tipoVinculo foi removido. Ele descrevia o mesmo eixo de estrategia, com valores invertidos, e era fonte recorrente de leitura errada. Use estrategia (como o item foi montado) e origem (de onde o item entrou no carrinho).
Entrou o array contratos, com os contratos já gerados a partir do item.

📤 Requisição¶

🧭 Parâmetros de Rota¶

Parâmetro	Tipo	Obrigatório	Descrição
idAgenda	string	Sim	GUID da agenda, devolvido no campo `identificador` de 4.1. Solicitar agenda.

📋 Query Parameters¶

Parâmetro	Tipo	Obrigatório	Descrição
tipoContrato	integer	Não	Filtra os itens pelo tipo de contrato (`1` = Troca de titularidade, `2` = Garantia).
contratoErp	string	Não	Filtra os itens pelo código do contrato no ERP do cliente (comparação exata).
indicePagina	integer	Não	Página desejada. Padrão: `1`.
tamanhoDaPagina	integer	Não	Quantidade de registros por página. Padrão: `20`.
ordem	string	Não	Campo usado para ordenar a listagem (ex.: `dataInicial`, `valor`, `contratoErp`).
direcaoOrdem	string	Não	Direção da ordenação: `ASC` ou `DESC`.

⚠️ Não confunda o query param ordem — que ordena a listagem — com o campo ordem de cada registro, que guarda a ordenação usada na seleção das URs quando o item foi montado.

🧪 Exemplo de cURL¶

curl -X GET "https://api.veflow.com/public/api/v1.1/cartao/agendas/534D8AAE-61E4-4264-9D15-715B9E1F1D51/carrinho/itens?tipoContrato=2&indicePagina=1&tamanhoDaPagina=20&ordem=dataInicial&direcaoOrdem=ASC" \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}"

📥 Responses¶

✅ 200 OK¶

{
  "registros": [
    {
      "idItem": "7C2C4D03-80BB-43E9-885C-F6A1C2660A68",
      "tipoContrato": 2,
      "estrategia": 4,
      "taxa": null,
      "valor": 5000.00,
      "ordem": "ASC",
      "parcela": {
        "numero": 1,
        "total": 2,
        "valor": 5000.00,
        "data": "2025-09-30"
      },
      "contratoErp": "CTR-2025-0001",
      "contratoValor": 10000.00,
      "tipoValor": 1,
      "fumaca": {
        "habilitada": true,
        "prazoEstendidoDias": 30,
        "somenteUrPerformada": true,
        "retencao": {
          "tipoValor": 2,
          "valor": 10.00
        }
      },
      "performance": {
        "personalizada": true,
        "tipoValor": 1,
        "valor": 250.00
      },
      "alertaResilicao": false,
      "tipoAlertaPerformance": null,
      "origem": 4,
      "dataInicial": "2025-09-01",
      "dataFinal": "2025-10-05",
      "totais": {
        "valorAtingido": 5000.00,
        "valorNaoAtingido": 0.00,
        "quantidadeUrs": 7
      },
      "contratos": [
        {
          "idContrato": "B1F0A9C7-3E52-4B8D-9F41-6C7A2D0E5B33",
          "tipoContrato": 2,
          "dataGeracao": "2025-09-05",
          "valorGarantido": 5000.00,
          "quantidadeUrs": 7
        }
      ]
    }
  ],
  "paginacao": {
    "paginaAtual": 1,
    "paginaTotal": 1,
    "paginaQuantidadeRegistro": 20,
    "quantidadeRegistros": 1,
    "temPaginaAnterior": false,
    "temProximaPagina": false
  },
  "mensagem": null
}

🔹 registros[]¶

Campo	Tipo	Descrição
idItem	string	GUID do item do carrinho. Use-o em 4.13. Detalhes do item e 4.14. Atualizar item.
tipoContrato	integer	Tipo de contrato que o item vai gerar: `1` = Troca de titularidade, `2` = Garantia.
estrategia	integer	Estratégia usada para compor o item (`1` a `4`). Ver a seção Enumerações.
taxa	number/null	Deságio do item, com até 4 casas decimais. Preenchido somente quando `tipoContrato` = `1`. Contrato de garantia não tem deságio, portanto vem `null`.
valor	number	Valor de referência do item: o valor desejado, quando a estratégia parte de um valor (`2`, `3` e `4`); ou a soma do `valorGarantido` das URs, quando `estrategia` = `1`.
ordem	string/null	Ordenação usada na seleção das URs que compõem o item: `ASC` (liquidação mais próxima primeiro) ou `DESC` (mais distante primeiro). `null` quando a estratégia não usa ordenação.
parcela	object/null	Parcela da garantia à qual o item está vinculado. `null` em itens que não nascem de parcela.
contratoErp	string/null	Código do contrato no ERP do cliente.
contratoValor	number/null	Valor total do contrato no ERP (soma das parcelas).
tipoValor	integer	Como o `valor` do item deve ser interpretado: `1` = Valor fixo, `2` = Percentual.
fumaca	object/null	Configuração de fumaça da garantia. `null` quando o item não usa fumaça.
performance	object/null	Configuração de performance aplicada na composição do item. `null` quando não houve personalização.
alertaResilicao	boolean	`true` indica inconsistência na composição do item que pode exigir comunicação de resilição às registradoras. Esse é o único significado do campo.
tipoAlertaPerformance	integer/null	Alerta de performance do item. `null` quando não há alerta. Ver a seção Enumerações.
origem	integer	Como o item entrou no carrinho (`1` a `4`). Ver a seção Enumerações.
dataInicial	string/null	Início da janela de liquidação considerada na composição (`YYYY-MM-DD`).
dataFinal	string/null	Fim da janela de liquidação considerada na composição (`YYYY-MM-DD`).
totais	object	Totais consolidados do item.
contratos	array	Contratos já gerados a partir do item. Vem vazio (`[]`) enquanto o item não foi efetivado.

🔹 parcela¶

Campo	Tipo	Descrição
numero	integer	Número da parcela dentro do contrato.
total	integer	Quantidade total de parcelas do contrato.
valor	number	Valor da parcela a ser garantido pelo item.
data	string	Data de vencimento da parcela (`YYYY-MM-DD`).

🔹 fumaca¶

Campo	Tipo	Descrição
habilitada	boolean	Indica se o item usa fumaça. Fumaça não é um tipo de contrato — é uma configuração da garantia.
prazoEstendidoDias	integer	Dias de prazo estendido aplicados na busca de URs além da data da parcela.
somenteUrPerformada	boolean	Quando `true`, a composição considera apenas URs já performadas.
retencao	object	Regra de retenção aplicada sobre cada UR alocada.
→ tipoValor	integer	Como o valor de retenção é interpretado: `1` = Valor fixo, `2` = Percentual.
→ valor	number	Valor retido por UR, conforme `retencao.tipoValor`.

🔹 performance¶

Campo	Tipo	Descrição
personalizada	boolean	Indica se a performance por UR foi personalizada na criação do item.
tipoValor	integer	Como o valor de performance é interpretado: `1` = Valor fixo, `2` = Percentual.
valor	number	Valor de performance considerado por UR, conforme `performance.tipoValor`.

🔹 totais¶

Campo	Tipo	Descrição
valorAtingido	number	Soma do `valorGarantido` das URs efetivamente alocadas no item.
valorNaoAtingido	number	Parte do `valor` do item que não foi coberta pelas URs disponíveis na agenda.
quantidadeUrs	integer	Quantidade de URs alocadas no item.

🔹 contratos[]¶

Campo	Tipo	Descrição
idContrato	string	GUID do contrato gerado a partir do item.
tipoContrato	integer	`1` = Troca de titularidade, `2` = Garantia.
dataGeracao	string	Data de geração do contrato (`YYYY-MM-DD`).
quantidadeUrs	integer	Quantidade de URs que compõem o contrato.
valorGarantido	number/null	Valor garantido pelo contrato. Presente somente quando `tipoContrato` = `2`.
valorNominal	number/null	Valor nominal das URs cedidas. Presente somente quando `tipoContrato` = `1`.
valorDesconto	number/null	Valor do deságio aplicado na cessão. Presente somente quando `tipoContrato` = `1`.
valorAquisicao	number/null	Valor de aquisição pago pelo fundo. Presente somente quando `tipoContrato` = `1`.
taxa	number/null	Deságio efetivado no contrato, com até 4 casas decimais. Presente somente quando `tipoContrato` = `1`.

🔹 paginacao¶

Campo	Tipo	Descrição
paginaAtual	integer	Página atual do retorno.
paginaTotal	integer	Total de páginas disponíveis.
paginaQuantidadeRegistro	integer	Quantidade máxima de registros por página.
quantidadeRegistros	integer	Total de registros encontrados.
temPaginaAnterior	boolean	Indica se há página anterior.
temProximaPagina	boolean	Indica se há próxima página.

🔹 mensagem¶

Campo	Tipo	Descrição
mensagem	string/null	Mensagem informativa opcional. Normalmente `null` nas consultas com sucesso.

✅ 200 OK — registro de troca de titularidade¶

Em itens de troca de titularidade (tipoContrato = 1) a taxa é obrigatória e o contrato gerado traz os valores da cessão:

{
  "idItem": "154EAC0D-5A76-4997-B7FB-A5FBA916C895",
  "tipoContrato": 1,
  "estrategia": 2,
  "taxa": 1.9900,
  "valor": 25000.00,
  "ordem": null,
  "parcela": null,
  "contratoErp": null,
  "contratoValor": null,
  "tipoValor": 1,
  "fumaca": null,
  "performance": {
    "personalizada": true,
    "tipoValor": 2,
    "valor": 5.50
  },
  "alertaResilicao": false,
  "tipoAlertaPerformance": 2,
  "origem": 2,
  "dataInicial": "2025-09-01",
  "dataFinal": "2025-09-30",
  "totais": {
    "valorAtingido": 24800.00,
    "valorNaoAtingido": 200.00,
    "quantidadeUrs": 12
  },
  "contratos": [
    {
      "idContrato": "D7438CFA-9C4B-4117-A13F-C1EDD2B987D7",
      "tipoContrato": 1,
      "dataGeracao": "2025-09-05",
      "quantidadeUrs": 12,
      "valorNominal": 24800.00,
      "valorDesconto": 493.52,
      "valorAquisicao": 24306.48,
      "taxa": 1.9900
    }
  ]
}

❌ 404 Not Found¶

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

🔢 Enumerações¶

🔹 tipoContrato¶

Código	Significado	Observação
1	Troca de titularidade	Há cessão das URs ao fundo, portanto há deságio (`taxa`) e valores de nominal, desconto e aquisição.
2	Garantia	Não há cessão nem deságio: o item trabalha apenas com `valorGarantido`.

Só existem esses dois valores. Fumaça não é tipo de contrato — é configuração da garantia (prazo estendido, somente URs performadas e regra de retenção), exposta no objeto fumaca. Penhor é legado e não é gerado nesta versão.

🔹 estrategia¶

Código	Significado	Descrição
1	URs selecionadas	O item foi montado a partir de uma lista explícita de URs (`idsUrs`).
2	Split por valor desejado	A plataforma distribuiu o valor desejado entre as URs da janela informada.
3	Troca por valor desejado	A plataforma substituiu URs até atingir o valor desejado, respeitando `ordem`.
4	Alocação automática por parcela	A plataforma alocou URs para cada parcela da garantia, conforme as regras de prioridade.

🔹 tipoValor¶

Código	Significado
1	Valor fixo
2	Percentual

🔹 origem¶

Código	Significado	Descrição
1	URs selecionadas	Item criado com seleção manual de URs.
2	Split por valor desejado	Item criado pelo split de um valor desejado.
3	Troca por valor desejado	Item criado pela troca por valor desejado.
4	Parcela de garantia	Item criado a partir de uma parcela de garantia cadastrada na agenda.

estrategia diz como o item foi composto; origem diz de onde ele entrou no carrinho. Os valores 1 a 3 coincidem; o 4 difere: estrategia = 4 é a alocação automática, origem = 4 é a parcela de garantia que disparou essa alocação.

🔹 tipoAlertaPerformance¶

Código	Significado	Descrição
1	Contrato não performado	Nenhuma UR do item atende à performance esperada.
2	Contrato performado parcialmente	Parte das URs do item atende à performance esperada; o restante ficou descoberto.

🕒 Observações¶

O item vive dentro do carrinho de uma agenda. Quando a agenda vence (dataValidade, em 4.3. Detalhes da agenda), os itens montados sobre ela são invalidados e é necessário refazer a consulta — ver 4.7. Refazer consulta.
Enquanto o item existe no carrinho, o valor das URs alocadas fica comprometido (valorComprometido) e deixa de compor o valorLivre / valorDisponivel na agenda — ver 4.4. Listar URs da agenda.
Em itens com estrategia = 4 (alocação automática por parcela), a busca considera URs com dataPrevistaLiquidacao a partir de 5 dias úteis antes da data da parcela, priorizando menor prazo e maior valor livre. Ajustes nessa regra são parametrizados por cliente.
valorNominal, valorDesconto e valorAquisicao só existem em antecipação (troca de titularidade), porque só ali houve cessão ao fundo. Contrato de garantia nunca traz esses campos nem taxa.
Um item com contratos preenchido já foi efetivado e não aceita mais alteração — ver 4.14. Atualizar item. Os contratos gerados também podem ser consultados na seção Contratos.
Headers obrigatórios e convenções gerais: 1.2. Convenções da API.