--- title: 4.13. Detalhes do item 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.13.%20Detalhes%20do%20item/ --- # 4.13. Detalhes do item ## 🔗 Endpoint | Método | URL | | ---------------------------------------------------- | -------------------------------------------------------------------- | | ![GET](https://img.shields.io/badge/GET-brightgreen) | `/public/api/v1.1/cartao/agendas/{idAgenda}/carrinho/itens/{idItem}` | --- ## 🧾 Descrição Retorna os **detalhes de um item do carrinho** de uma agenda de recebíveis de cartão. O retorno traz os mesmos campos do registro de [4.12. Listar itens do carrinho](4.12.%20Listar%20itens%20do%20carrinho.md) e acrescenta o array `urs`, com um **resumo das URs alocadas** no item — o suficiente para conferir a composição sem uma segunda chamada. --- ## 📤 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). | | idItem | string | Sim | GUID do item do carrinho, devolvido em [4.12. Listar itens do carrinho](4.12.%20Listar%20itens%20do%20carrinho.md). | --- ## 🧪 Exemplo de cURL ```bash curl -X GET https://api.veflow.com/public/api/v1.1/cartao/agendas/534D8AAE-61E4-4264-9D15-715B9E1F1D51/carrinho/itens/7C2C4D03-80BB-43E9-885C-F6A1C2660A68 \ -H "Authorization: Bearer {seu_token}" \ -H "GrupoEconomico: {seu_grupo_economico}" ``` --- ## 📥 Responses ### ✅ 200 OK ```json { "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 } ], "urs": [ { "id": "7D121577-3C5A-494D-B052-291D9E100D0D", "credenciadora": { "cnpj": "10293847560102", "nome": "CREDENCIADORA EXEMPLO S.A." }, "arranjo": { "sigla": "MCC", "nome": "Mastercard Crédito" }, "dataPrevistaLiquidacao": "2025-09-25", "valorGarantido": 1200.00, "tipoValor": 1 } ] } ``` ### 🔹 Nível Raiz | Campo | Tipo | Descrição | | --------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | idItem | string | GUID do item do carrinho. | | 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. | | urs | array | Resumo das URs alocadas no item. | ### 🔹 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. | | quantidadeUrs | integer | Quantidade **total** 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`. | ### 🔹 urs[] | Campo | Tipo | Descrição | | ---------------------- | ------- | ------------------------------------------------------------------------------- | | id | string | GUID da UR (Unidade de Recebível) alocada no item. | | credenciadora.cnpj | string | CNPJ da credenciadora responsável pela UR. | | credenciadora.nome | string | Nome da credenciadora. | | arranjo.sigla | string | Sigla do arranjo de pagamento (ex.: `MCC`, `VCC`). | | arranjo.nome | string | Nome do arranjo (ex.: Mastercard Crédito). | | dataPrevistaLiquidacao | string | Data prevista de liquidação da UR (`YYYY-MM-DD`). | | valorGarantido | number | Valor da UR comprometido por este item. | | tipoValor | integer | Como o `valorGarantido` da UR é interpretado: `1` = Valor fixo, `2` = Percentual. | > O array `urs` é um **resumo**: traz as primeiras URs do item, ordenadas por `dataPrevistaLiquidacao`. O total está em `totais.quantidadeUrs`. Para a lista completa, paginada e com os filtros por credenciadora, arranjo e data, use a página **4.18** (listagem das URs do item). --- ### ❌ 404 Not Found ```json { "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.5", "titulo": "Atenção", "status": 404, "erros": [ "Item '7C2C4D03-80BB-43E9-885C-F6A1C2660A68' não encontrado no carrinho da agenda '534D8AAE-61E4-4264-9D15-715B9E1F1D51'." ] } ``` --- ## 🔢 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. | ### 🔹 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 * Enquanto o item existe no carrinho, o `valorGarantido` de cada UR 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. * Ônus de terceiros sobre a UR — por exemplo **promessa de cessão** — são informação de leitura e nunca podem ser criados pela API. Eles aparecem na listagem completa das URs da agenda, em [4.4. Listar URs da agenda](4.4.%20Listar%20URs%20da%20agenda.md). * `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`. * 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 — ver [4.7. Refazer consulta](4.7.%20Refazer%20consulta.md). * Para alterar taxa, contrato no ERP, conta corrente, tags ou parcela do item, use [4.14. Atualizar item](4.14.%20Atualizar%20item.md). * Headers obrigatórios e convenções gerais: [1.2. Convenções da API](../../1.%20Início/1.2.%20Convenções%20da%20API.md).