4.13. Detalhes do item¶

🔗 Endpoint¶

Método	URL
	`/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 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.
idItem	string	Sim	GUID do item do carrinho, devolvido em 4.12. Listar itens do carrinho.

🧪 Exemplo de cURL¶

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¶

{
  "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¶

{
  "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.
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.
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), os itens montados sobre ela são invalidados — ver 4.7. Refazer consulta.
Para alterar taxa, contrato no ERP, conta corrente, tags ou parcela do item, use 4.14. Atualizar item.
Headers obrigatórios e convenções gerais: 1.2. Convenções da API.