8.2. Habilitar Antecipação Automática

Habilita o ciclo de antecipação automática de recebíveis de cartão para um cedente, em uma operação específica.

Com o ciclo habilitado, VeHub passa a, todo dia útil: buscar a agenda de recebíveis do estabelecimento na registradora, selecionar as URs elegíveis dentro dos valores configurados e gerar o contrato de cessão sozinho — sem nenhuma chamada de API a cada ciclo.

Cada contrato gerado é avisado pelo webhook de contratos que já existe na API de recebíveis de cartão (tipoNotificacao = 2). O fluxo completo, com o momento em que a notificação chega, está em 8.9. Roteiro - Antecipação Automática Ponta a Ponta.

A configuração é por cedente × operação

O mesmo cedente pode participar de mais de uma operação, com taxa e valores diferentes em cada uma. Por isso idOperacao vai no corpo da requisição, e não na rota: cada chamada configura um par cedente × operação.

Requer habilitação prévia do grupo econômico

A antecipação automática só pode ser ativada em grupos econômicos homologados para o recurso. Sem essa habilitação, todas as chamadas desta seção retornam 403. Fale com o time de implantação antes de integrar.

O horário do ciclo não vem por API

O horário em que o ciclo roda é parâmetro da operação, definido pelo time de implantação — tipicamente no primeiro horário da manhã. Ele é devolvido em 8.4. Consultar Configuração Vigente para conferência, mas não é editável por esta API.

Habilitar Antecipação Automática¶

Método	URL
	`https://BASE_URL/public/api/v1/cedentes/{idEmpresa}/antecipacao-automatica`

Cria ou substitui a configuração do ciclo automático. É um upsert: reenviar a chamada sobrescreve a configuração anterior daquele par cedente × operação.

Path Params¶

Campo	Tipo	Descrição
`idEmpresa`	Número	Identificador da empresa cedente.

Request Body¶

Campo	Tipo	Obrigatório	Descrição
`idOperacao`	Número	Sim	Operação do vínculo a configurar.
`taxa`	Decimal	Sim	Deságio aplicado no contrato gerado pelo ciclo, com até 8 casas decimais. Ver Por que a taxa é obrigatória.
`valorMinimo`	Decimal	Não	Piso por ciclo. Se o total elegível do dia ficar abaixo deste valor, o ciclo não gera contrato. Omitido ou `null`, sem piso.
`valorMaximo`	Decimal	Não	Teto por ciclo. Limita quanto será antecipado no dia. Omitido ou `null`, sem teto.
`arranjos`	Lista	Não	Siglas dos arranjos de pagamento (ex.: `MCC`, `VCC`). Omitido ou vazio considera todos.
`credenciadoras`	Lista	Não	Identificadores das credenciadoras. Omitido ou vazio considera todas as habilitadas na operação.

Credenciadoras são informadas por identificador, não por CNPJ

Aqui o campo credenciadoras recebe o id da credenciadora. A consulta de configuração (8.4) devolve id, nome e cnpj juntos, então o de-para é resolvido uma única vez.

Por que a taxa é obrigatória¶

A taxa do contrato automático é sempre a do vínculo cedente × operação. Sem informá-la, o contrato sairia sem deságio. Um cedente recém-cadastrado não nasce com taxa — ela é definida aqui, ou depois por 8.5 e 8.6.

Operações com deságio por Fonte Externa

Se a operação calcula o deságio por fonte externa, enviar taxa resulta em 422. Nesses casos a taxa é determinada fora de VeHub, e a antecipação automática não pode ser habilitada por esta via.

Request Body — completo

{
  "idOperacao": 1,
  "taxa": 1.9900,
  "valorMinimo": 500.00,
  "valorMaximo": 250000.00,
  "arranjos": ["MCC", "VCC"],
  "credenciadoras": [12, 37]
}

Request Body — mínimo

{
  "idOperacao": 1,
  "taxa": 1.9900
}

A resposta devolve a configuração vigente, no mesmo formato de 8.4. Consultar Configuração Vigente.

Erros¶

Status	Quando acontece
`400`	Payload inválido — taxa ausente, valor negativo, arranjo ou credenciadora inexistente.
`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`	Cedente ou operação não encontrados, ou sem vínculo vivo entre eles.
`422`	Operação não é de cartões, está inativa, ou calcula deságio por Fonte Externa.