--- title: 4.14. Atualizar 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.14.%20Atualizar%20item/ --- # 4.14. Atualizar item ## 🔗 Endpoint | Método | URL | | --------------------------------------------------- | -------------------------------------------------------------------- | | ![PATCH](https://img.shields.io/badge/PATCH-yellow) | `/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](4.16.%20Adicionar%20URs%20ao%20item.md) e [4.17. Remover URs do item](4.17.%20Remover%20URs%20do%20item.md). > ⚠️ **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](4.13.%20Detalhes%20do%20item.md): 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](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). | ### 📋 Payload (JSON) ```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 ```bash 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 ```bash 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](4.13.%20Detalhes%20do%20item.md), já com os valores atualizados. ```json { "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](4.13.%20Detalhes%20do%20item.md). `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 ```json { "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 ```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'." ] } ``` É 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 ```json { "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 ```json { "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](4.7.%20Refazer%20consulta.md). --- ## 🔢 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](4.13.%20Detalhes%20do%20item.md). --- ## 🕒 Observações * A atualização é **síncrona** e já reflete em [4.13. Detalhes do item](4.13.%20Detalhes%20do%20item.md) e [4.12. Listar itens do carrinho](4.12.%20Listar%20itens%20do%20carrinho.md). * **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](4.16.%20Adicionar%20URs%20ao%20item.md) e [4.17. Remover URs do item](4.17.%20Remover%20URs%20do%20item.md). * `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](4.1.%20Solicitar%20agenda.md), 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](4.12.%20Listar%20itens%20do%20carrinho.md). * Se a agenda passou da `dataValidade` (ver [4.3. Detalhes da agenda](4.3.%20Detalhes%20da%20agenda.md)), 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](4.15.%20Remover%20item.md). * Headers obrigatórios e convenções gerais: [1.1. Primeiros Passos](../../1.%20Início/1.1.%20Primeiros%20Passos.md).