4.14. Atualizar item¶

🔗 Endpoint¶

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

🧾 Descrição¶

Atualiza os parâmetros comerciais de um item do carrinho de uma agenda de recebíveis de cartão, antes de o item virar contrato.

A operação é um merge parcial: apenas os campos enviados no corpo são alterados; os campos omitidos permanecem exatamente como estão. A resposta é síncrona (200 OK) e devolve o item completo depois da atualização.

Esta rota altera somente dados de controle do item (taxa, contratoErp, contratoValor, idContaCorrente, tags e parcela). Ela não altera as URs alocadas e não recompõe o item — para mexer na composição use 4.16. Adicionar URs ao item e 4.17. Remover URs do item.

⚠️ Item já efetivado não é mais alterável. Depois de o item gerar contrato, a alteração é recusada com 409 Conflict. Verifique o array contratos em 4.13. Detalhes do item: item com contratos preenchido já saiu do carrinho.

📤 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.

📋 Payload (JSON)¶

{
  "taxa": 0.0000,
  "contratoErp": "",
  "contratoValor": 0.00,
  "idContaCorrente": "",
  "tags": [""],
  "parcela": {
    "numero": 1,
    "total": 1,
    "valor": 0.00,
    "data": "0000-00-00"
  }
}

🧾 Detalhamento dos Campos¶

Campo	Tipo	Obrigatório	Descrição
taxa	number	Não	Novo deságio do item, com até 4 casas decimais. Só se aplica a `tipoContrato` = `1` (troca de titularidade). Item de garantia não tem deságio: o envio é recusado com `400`.
contratoErp	string	Não	Identificador do contrato no ERP do cliente. Em garantia parcelada, é o campo que agrupa os itens de um mesmo contrato.
contratoValor	number	Não	Valor total do contrato no ERP. Em garantia, é o valor que o contrato pretende garantir.
idContaCorrente	string	Não	Identificador da conta corrente que receberá a liquidação do contrato gerado a partir do item.
tags	string[]	Não	Lista de tags de rastreabilidade do item (p.ex. `["PA_01"]`). O envio substitui integralmente a lista atual.
parcela	object	Não	Parcela da garantia à qual o item está vinculado. Quando enviado, o objeto substitui integralmente a parcela atual e os quatro campos abaixo são obrigatórios.
→ numero	integer	Condicional	Número da parcela (inteiro ≥ 1). Deve ser único dentro do mesmo `contratoErp`.
→ total	integer	Condicional	Quantidade total de parcelas do contrato (inteiro ≥ 1).
→ valor	number	Condicional	Valor da parcela a ser garantido pelo item (numérico > 0).
→ data	string	Condicional	Data de vencimento da parcela, no formato `YYYY-MM-DD`.

Regras e formatos

Ao menos um campo deve ser enviado. Corpo vazio ({}) é recusado com 400 Bad Request.
Campos ausentes do corpo não são alterados. Para limpar contratoErp ou idContaCorrente, envie null; para limpar as tags, envie "tags": [].
Datas no formato YYYY-MM-DD.
taxa aceita até 4 casas decimais e não se aplica a tipoContrato = 2: contrato de garantia não tem deságio e por isso o item de garantia nunca devolve valor nominal, desconto nem aquisição.
parcela é um objeto de substituição, não de merge: enviar apenas parcela.valor resulta em 400.
A alteração não movimenta URs: totais, urs e valorGarantido do item permanecem como estavam.
Item que já gerou contrato não aceita alteração — retorna 409 Conflict.
Item de agenda vencida (dataValidade) está invalidado e não aceita alteração — retorna 409 Conflict.
Qualquer violação das regras acima resulta em HTTP 400 com a lista de erros.

🧪 Exemplo de cURL¶

▶ Item de garantia parcelada: ajustar contrato do ERP, parcela e tags¶

curl -X PATCH 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}" \
  -H "Idempotency-Key: 5b1e0c74-3a92-4d18-9f6b-2c8d7e0a4f31" \
  -H "Content-Type: application/json" \
  -d '{
    "contratoErp": "CTR-2025-0009",
    "contratoValor": 12000.00,
    "tags": ["PA_01","GARANTIA"],
    "parcela": {
      "numero": 1,
      "total": 3,
      "valor": 4000.00,
      "data": "2025-10-15"
    }
  }'

▶ Item de troca de titularidade: ajustar deságio e conta corrente¶

curl -X PATCH https://api.veflow.com/public/api/v1.1/cartao/agendas/534D8AAE-61E4-4264-9D15-715B9E1F1D51/carrinho/itens/A6B1E4C7-2F0D-4B88-9E51-3C7A2D9F6B04 \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}" \
  -H "Idempotency-Key: c0f4a821-7d55-4b30-8e19-6a2f9b1c7d04" \
  -H "Content-Type: application/json" \
  -d '{
    "taxa": 2.1500,
    "idContaCorrente": "B21F0B0E-6F5B-4C6A-9D34-2A1D0E4E77C1"
  }'

📥 Responses¶

✅ 200 OK¶

O corpo devolvido é o mesmo registro de 4.13. Detalhes do item, já com os valores atualizados.

{
  "idItem": "7C2C4D03-80BB-43E9-885C-F6A1C2660A68",
  "tipoContrato": 2,
  "estrategia": 4,
  "taxa": null,
  "valor": 4000.00,
  "ordem": "ASC",
  "parcela": {
    "numero": 1,
    "total": 3,
    "valor": 4000.00,
    "data": "2025-10-15"
  },
  "contratoErp": "CTR-2025-0009",
  "contratoValor": 12000.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": [],
  "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. Não é alterável por esta rota.
estrategia	integer	Estratégia usada para compor o item (`1` a `4`). Não é alterável por esta rota. 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.
origem	integer	Como o item entrou no carrinho (`1` a `4`).
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. Não são recalculados por esta rota.
contratos	array	Contratos já gerados a partir do item. Aqui vem sempre vazio (`[]`): item com contrato não aceita alteração.
urs	array	Resumo das URs alocadas no item. Não é alterado por esta rota.

🔹 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`).

O detalhamento dos objetos fumaca, performance, totais, contratos e urs é o mesmo de 4.13. Detalhes do item.

idContaCorrente e tags são dados de controle do item, aplicados ao contrato no momento em que ele é gerado, e não compõem o registro de leitura do item.

❌ 400 Bad Request¶

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "titulo": "Atenção",
  "status": 400,
  "erros": [
    "Informe ao menos um campo para atualização.",
    "Campo 'taxa' não se aplica a tipoContrato = 2.",
    "Campo 'parcela.data' é obrigatório quando o objeto 'parcela' é enviado.",
    "Campo 'parcela.data' inválido. Formato esperado: YYYY-MM-DD."
  ]
}

❌ 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'."
  ]
}

É o mesmo retorno quando a agenda informada não existe ou não pertence ao grupo econômico do header GrupoEconomico.

❌ 409 Conflict — item já virou contrato¶

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
  "titulo": "Conflito",
  "status": 409,
  "erros": [
    "O item '7C2C4D03-80BB-43E9-885C-F6A1C2660A68' já gerou o contrato 'B1F0A9C7-3E52-4B8D-9F41-6C7A2D0E5B33' e não pode mais ser alterado."
  ]
}

Depois de efetivado, o item deixa de ser editável: o que existe é um contrato, e as alterações cabíveis passam a ser as da seção 5. Contrato de recebíveis.

❌ 409 Conflict — agenda vencida¶

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
  "titulo": "Conflito",
  "status": 409,
  "erros": [
    "A agenda '534D8AAE-61E4-4264-9D15-715B9E1F1D51' passou da dataValidade: o item está invalidado e não aceita alteração."
  ]
}

Quando a agenda vence, os itens montados sobre ela são invalidados junto com as URs que a alimentavam. É necessário refazer a consulta e remontar o carrinho — ver 4.7. Refazer consulta.

🔢 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

As enumerações de origem e tipoAlertaPerformance estão em 4.13. Detalhes do item.

🕒 Observações¶

A atualização é síncrona e já reflete em 4.13. Detalhes do item e 4.12. Listar itens do carrinho.
Alterar o item não altera as URs alocadas. Nem totais nem urs são recalculados aqui. Para mexer na composição, use 4.16. Adicionar URs ao item e 4.17. Remover URs do item.
taxa não se aplica a item de tipoContrato = 2: garantia não tem deságio. valorNominal, valorDesconto e valorAquisicao só existem em antecipação (troca de titularidade), porque só ali houve cessão ao fundo.
A taxa do item é a que vale para o contrato — não a informada na solicitação da agenda em 4.1. Solicitar agenda, que é apenas projeção de vitrine.
Item com o array contratos preenchido já foi efetivado e não aceita mais alteração (409). Confira antes em 4.12. Listar itens do carrinho.
Se a agenda passou da dataValidade (ver 4.3. Detalhes da agenda), o item está invalidado e a alteração é recusada (409).
O header Idempotency-Key é obrigatório: em caso de reenvio da mesma chave, a plataforma devolve o resultado da primeira aplicação em vez de aplicar a alteração duas vezes.
Para descartar o item em vez de alterá-lo, use 4.15. Remover item.
Headers obrigatórios e convenções gerais: 1.1. Primeiros Passos.