--- title: 4.12. Listar itens do carrinho url: https://docs.vehub.com.br/API/VeFlow%20-%20Cart%C3%A3o%20de%20cr%C3%A9dito/4.%20Agenda%20de%20receb%C3%ADveis/v1.1/4.12.%20Listar%20itens%20do%20carrinho/ --- # 4.12. Listar itens do carrinho ## 🔗 Endpoint | Método | URL | | ---------------------------------------------------- | ---------------------------------------------------------------- | | ![GET](https://img.shields.io/badge/GET-brightgreen) | `/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](4.10.%20Adicionar%20item.md) — 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](4.1.%20Solicitar%20agenda.md). | ### 📋 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 ```bash 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 ```json { "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](4.13.%20Detalhes%20do%20item.md) e [4.14. Atualizar item](4.14.%20Atualizar%20item.md). | | 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: ```json { "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 ```json { "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](4.3.%20Detalhes%20da%20agenda.md)), os itens montados sobre ela são invalidados e é necessário refazer a consulta — ver [4.7. Refazer consulta](4.7.%20Refazer%20consulta.md). * 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](4.4.%20Listar%20URs%20da%20agenda.md). * 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](4.14.%20Atualizar%20item.md). 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](../../1.%20Início/1.2.%20Convenções%20da%20API.md).