---
title: 8.5. Atualizar Taxa por Operação
url: https://docs.vehub.com.br/API/Cadastro%20de%20Cedente/8.%20Antecipa%C3%A7%C3%A3o%20autom%C3%A1tica%20de%20cart%C3%A3o/8.5.%20Atualizar%20Taxa%20por%20Opera%C3%A7%C3%A3o/
---
Replica uma taxa de deságio para os vínculos cedente × operação de uma operação — todos eles, ou apenas os cedentes que você informar.

!!! warning "Isto replica, não cria um padrão"
    A taxa vive exclusivamente no **vínculo cedente × operação**. Esta chamada grava o valor nos vínculos **que já existem** no momento do processamento. Um cedente vinculado **depois** dela fica sem taxa até recebê-la por [8.2. Habilitar Antecipação Automática](8.2.%20Habilitar%20Antecipa%C3%A7%C3%A3o%20Autom%C3%A1tica.md) ou por [8.6. Atualizar Taxa de um Cedente](8.6.%20Atualizar%20Taxa%20de%20um%20Cedente.md).

!!! info "Processamento assíncrono"
    Uma operação pode ter centenas de milhares de vínculos. A atualização é enfileirada e processada em blocos, com confirmações independentes. A resposta `202` confirma o **recebimento**, não a conclusão — acompanhe pelo endpoint de consulta do processamento, mais abaixo.

---

## Atualizar Taxa por Operação

| Método                                              | URL                                                                     |
| --------------------------------------------------- | ----------------------------------------------------------------------- |
| ![PATCH](https://img.shields.io/badge/PATCH-yellow) | `https://BASE_URL/public/api/v1/cedentes/operacoes/{idOperacao}/taxa`    |

### Path Params

| Campo        | Tipo   | Descrição                  |
| ------------ | ------ | -------------------------- |
| `idOperacao` | Número | Identificador da operação. |

### Request Body

| Campo            | Tipo     | Obrigatório | Descrição                                                                                                                                                  |
| ---------------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `taxa`           | Decimal  | Sim         | Taxa a replicar, com até 8 casas decimais.                                                                                                                  |
| `somenteSemTaxa` | Booleano | Não         | `true` aplica apenas aos vínculos que ainda **não** têm taxa, preservando as já definidas. Padrão `false` — **sobrescreve todas**.                           |
| `cnpjCedente`    | Lista    | Não         | CNPJ ou CPF dos cedentes, somente números. **Omitido ou vazio aplica a todos os cedentes da operação.** Preenchido aplica apenas a esses. Máximo de 10.000. |

### Os dois modos

| Modo                     | Como acionar                | Quando usar                                                                                     |
| ------------------------ | --------------------------- | ----------------------------------------------------------------------------------------------- |
| **Toda a operação**      | `cnpjCedente` omitido ou vazio | Mudança de política comercial que vale para a carteira inteira.                                |
| **Cedentes específicos** | `cnpjCedente` preenchido    | Reajuste de um recorte conhecido. Evita chamar [8.6](8.6.%20Atualizar%20Taxa%20de%20um%20Cedente.md) CNPJ a CNPJ. |

```json title="Request Body — toda a operação"
{
  "taxa": 2.1500,
  "somenteSemTaxa": false
}
```

```json title="Request Body — cedentes específicos"
{
  "taxa": 2.1500,
  "somenteSemTaxa": false,
  "cnpjCedente": ["12345678000199", "98765432000188"]
}
```

```json title="Response Body — 202 Accepted"
{
  "identificador": "A1B2C3D4-1111-2222-3333-444455556666",
  "mensagem": "Replicação de taxa recebida e enfileirada."
}
```

!!! warning "somenteSemTaxa: false sobrescreve taxas negociadas"
    Com o padrão `false`, a chamada substitui **todas** as taxas dos vínculos alcançados — inclusive as que foram negociadas individualmente com um cedente. Se a intenção é apenas preencher quem está sem taxa, envie `somenteSemTaxa: true`.

!!! tip "CNPJ sem vínculo não derruba a requisição"
    Documento informado que não tenha vínculo vivo na operação é simplesmente ignorado e devolvido em `cnpjCedenteNaoEncontrados` na consulta do processamento. Um lote de 10.000 CNPJs com 3 inexistentes aplica a taxa nos 9.997 e reporta os 3.

### Erros

| Status | Quando acontece                                                          |
| ------ | ------------------------------------------------------------------------ |
| `400`  | `taxa` ausente ou inválida, ou mais de 10.000 documentos em `cnpjCedente`. |
| `401`  | Token ausente, expirado ou sem permissão de acesso à API pública.        |
| `403`  | Grupo econômico não habilitado para antecipação automática.              |
| `404`  | Operação não encontrada no grupo econômico.                              |
| `422`  | Operação calcula deságio por Fonte Externa.                              |

---

## Consultar o Processamento

| Método                                        | URL                                                                                          |
| --------------------------------------------- | -------------------------------------------------------------------------------------------- |
| ![GET](https://img.shields.io/badge/GET-blue) | `https://BASE_URL/public/api/v1/cedentes/operacoes/{idOperacao}/taxa/processamentos/{identificador}` |

Acompanha uma replicação de taxa enfileirada.

### Path Params

| Campo           | Tipo   | Descrição                                          |
| --------------- | ------ | -------------------------------------------------- |
| `idOperacao`    | Número | Identificador da operação.                         |
| `identificador` | Texto  | GUID devolvido na resposta `202` da atualização.   |

```json title="Response Body — 200 OK"
{
  "identificador": "A1B2C3D4-1111-2222-3333-444455556666",
  "idOperacao": 1,
  "status": 4,
  "escopo": 2,
  "taxaNova": 2.1500,
  "quantidadeSolicitada": 10000,
  "quantidadeAtualizada": 9997,
  "cnpjCedenteNaoEncontrados": ["11111111000111", "22222222000122", "33333333000133"],
  "percentualConcluido": 100,
  "iniciadoEm": "2026-09-22T12:10:00Z",
  "concluidoEm": "2026-09-22T12:12:47Z",
  "mensagemErro": null
}
```

### Detalhamento dos Campos

| Campo                       | Tipo    | Descrição                                                                                            |
| --------------------------- | ------- | ------------------------------------------------------------------------------------------------------ |
| `status`                    | Número  | Situação do processamento. Ver [8.8. Status e Enumerações](8.8.%20Status%20e%20Enumera%C3%A7%C3%B5es.md). |
| `escopo`                    | Número  | `1` toda a operação, `2` cedentes informados. Ver [8.8](8.8.%20Status%20e%20Enumera%C3%A7%C3%B5es.md).   |
| `taxaNova`                  | Decimal | Taxa aplicada.                                                                                        |
| `quantidadeSolicitada`      | Número  | Vínculos alvo. No escopo `1`, o total de vínculos da operação.                                        |
| `quantidadeAtualizada`      | Número  | Vínculos efetivamente alterados.                                                                      |
| `cnpjCedenteNaoEncontrados` | Lista   | Documentos sem vínculo vivo na operação. Vazio quando todos casaram. Só se aplica ao escopo `2`.      |
| `percentualConcluido`       | Número  | 0 a 100. Acompanha o processamento em blocos.                                                         |
| `iniciadoEm`                | Texto   | Data e hora UTC do início, em ISO 8601.                                                               |
| `concluidoEm`               | Texto   | Data e hora UTC da conclusão. `null` enquanto o processamento não terminou.                           |
| `mensagemErro`              | Texto   | Preenchido apenas quando `status` é `Falha`.                                                          |

### Erros

| Status | Quando acontece                                                   |
| ------ | ----------------------------------------------------------------- |
| `401`  | Token ausente, expirado ou sem permissão de acesso à API pública. |
| `403`  | Grupo econômico não habilitado para antecipação automática.       |
| `404`  | Identificador não encontrado para a operação informada.           |