8.5. Atualizar Taxa por Operação

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.

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 ou por 8.6. Atualizar Taxa de um Cedente.

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
	`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 CNPJ a CNPJ.

Request Body — toda a operação

{
  "taxa": 2.1500,
  "somenteSemTaxa": false
}

Request Body — cedentes específicos

{
  "taxa": 2.1500,
  "somenteSemTaxa": false,
  "cnpjCedente": ["12345678000199", "98765432000188"]
}

Response Body — 202 Accepted

{
  "identificador": "A1B2C3D4-1111-2222-3333-444455556666",
  "mensagem": "Replicação de taxa recebida e enfileirada."
}

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.

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

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.
`escopo`	Número	`1` toda a operação, `2` cedentes informados. Ver 8.8.
`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.