--- title: 8.9. Roteiro Antecipação Automática Ponta a Ponta url: https://docs.vehub.com.br/API/Cadastro%20de%20Cedente/8.%20Antecipa%C3%A7%C3%A3o%20autom%C3%A1tica%20de%20cart%C3%A3o/8.9.%20Roteiro%20-%20Antecipa%C3%A7%C3%A3o%20Autom%C3%A1tica%20Ponta%20a%20Ponta/ --- Roteiro completo para colocar um estabelecimento comercial em antecipação automática de recebíveis de cartão, do cadastro ao primeiro contrato gerado. Os passos estão na ordem em que devem ser executados. !!! info "Pré-requisitos" - Credenciais de acesso à API pública (`client_id` e `client_secret`) — ver [1.1. Primeiros Passos](../1.%20In%C3%ADcio/1.1.%20Primeiros%20Passos.md). - Grupo econômico **habilitado para antecipação automática** pelo time de implantação. Sem isso, os endpoints desta seção retornam `403`. - Uma **operação de cartões** ativa, com o horário do ciclo configurado. - Autorização (OPT-IN) do estabelecimento obtida pelo integrador. - **Recomendado:** URL de callback do webhook configurada, para ser avisado de cada contrato gerado — ver [3.0. Visão Geral](../../VeFlow%20-%20Cart%C3%A3o%20de%20cr%C3%A9dito/3.%20Notifica%C3%A7%C3%B5es%20-%20WebHook/3.0.%20Vis%C3%A3o%20Geral.md). --- ## Visão geral ```mermaid graph TD A[1. Cadastrar cedente simplificado] --> B[2. Habilitar antecipacao automatica] B --> C[3. Conferir a configuracao vigente] C --> D[4. Aguardar o ciclo diario] D --> H[5. Receber o webhook do contrato] D --> E[6. Consultar as execucoes] H --> F[7. Consultar o contrato gerado] E --> F E --> G[Sem contrato: ler o motivo] ``` --- ## Sequência de chamadas | # | Passo | Endpoint | Resultado / uso | | - | ---------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | 1 | Cadastrar o cedente e vinculá-lo | `POST /cedentes/simplificado` — [8.1](8.1.%20Cadastrar%20Cedente%20Simplificado.md) | Devolve `idEmpresa`, usado em todos os passos seguintes | | 2 | Habilitar o ciclo | `PUT /cedentes/{idEmpresa}/antecipacao-automatica` — [8.2](8.2.%20Habilitar%20Antecipa%C3%A7%C3%A3o%20Autom%C3%A1tica.md) | Define taxa, valores, arranjos e credenciadoras | | 3 | Conferir o que ficou valendo | `GET /cedentes/{idEmpresa}/antecipacao-automatica` — [8.4](8.4.%20Consultar%20Configura%C3%A7%C3%A3o%20Vigente.md) | Confirma a configuração e mostra o horário do ciclo | | 4 | Aguardar o ciclo | — | Roda automaticamente, todo dia útil | | 5 | Receber a notificação do contrato | Webhook `tipoNotificacao = 2` — [3.2. Atualizações do contrato](../../VeFlow%20-%20Cart%C3%A3o%20de%20cr%C3%A9dito/3.%20Notifica%C3%A7%C3%B5es%20-%20WebHook/3.2.%20Atualiza%C3%A7%C3%B5es%20do%20contrato.md) | Avisa que o contrato gerado foi registrado, ou que o registro falhou | | 6 | Consultar as execuções | `GET /cedentes/{idEmpresa}/antecipacao-automatica/execucoes` — [8.7](8.7.%20Consultar%20Execu%C3%A7%C3%B5es%20do%20Ciclo.md) | Mostra o desfecho de cada dia, inclusive os sem contrato | | 7 | Consultar o contrato gerado | `GET /cartao/contratos` — [Listar contratos](../../VeFlow%20-%20Cart%C3%A3o%20de%20cr%C3%A9dito/5.%20Contrato%20de%20receb%C3%ADveis/v1.1/5.2.%20Listar%20contratos.md) | Detalhes do contrato e das URs cedidas | Os passos 1 a 3 são feitos **uma vez**. Do passo 4 em diante, o ciclo é diário e não exige nenhuma chamada. --- ## Detalhamento dos passos ### Passo 1 — Cadastrar o cedente ```json title="POST /public/api/v1/cedentes/simplificado" { "documento": "12345678000199", "razaoSocial": "LOJA EXEMPLO COMERCIO LTDA", "idOperacao": 1 } ``` Guarde o `idEmpresa` devolvido. Se o cedente já existia, `jaExistia` volta `true` e o vínculo com a operação é garantido mesmo assim. ### Passo 2 — Habilitar a antecipação automática ```json title="PUT /public/api/v1/cedentes/4821/antecipacao-automatica" { "idOperacao": 1, "taxa": 1.9900, "valorMinimo": 500.00, "valorMaximo": 250000.00 } ``` !!! warning "A taxa é obrigatória" Um vínculo sem taxa não entra no ciclo, e as execuções passam a registrar o motivo **Sem taxa configurada**. ### Passo 5 — Receber a notificação do contrato Cada contrato gerado pelo ciclo é notificado pelo **mesmo webhook de contratos** que já atende os contratos criados por API — `tipoNotificacao = 2`, descrito em [3.2. Atualizações do contrato](../../VeFlow%20-%20Cart%C3%A3o%20de%20cr%C3%A9dito/3.%20Notifica%C3%A7%C3%B5es%20-%20WebHook/3.2.%20Atualiza%C3%A7%C3%B5es%20do%20contrato.md). Não existe tipo de notificação novo nem payload diferente: para o endpoint de callback, um contrato automático é um contrato como qualquer outro. !!! info "Quando a primeira notificação chega" A notificação não sai no instante em que o contrato é criado, e sim quando a registradora responde: `status` `4` (**Aguardando liquidação**) quando o registro é aceito, ou `3` (**Falha no registro**) quando é recusado. Daí em diante, o contrato é notificado nas mesmas situações que qualquer outro contrato. Para saber que o contrato veio do ciclo automático, cruze o `contrato.identificador` da notificação com o `identificadorContrato` das execuções ([8.7](8.7.%20Consultar%20Execu%C3%A7%C3%B5es%20do%20Ciclo.md)), ou consulte o campo `origemAgenda` em [Listar contratos](../../VeFlow%20-%20Cart%C3%A3o%20de%20cr%C3%A9dito/5.%20Contrato%20de%20receb%C3%ADveis/v1.1/5.2.%20Listar%20contratos.md). Em `totais.taxa` vem a taxa do vínculo aplicada ao contrato. !!! tip "Dias sem contrato não geram notificação" O webhook fala de contratos. Um dia em que o ciclo rodou e **não** contratou — agenda vazia, total abaixo do piso, vínculo sem taxa — não dispara nada: esse desfecho só aparece nas execuções do passo 6. ### Passo 6 — Ler o resultado do dia ```json title="GET /public/api/v1/cedentes/4821/antecipacao-automatica/execucoes?dataInicial=2026-09-22" ``` Quando `status` for **Não contratado**, o campo `motivoNaoContratacao` explica o porquê. Todos os códigos estão em [8.8. Status e Enumerações](8.8.%20Status%20e%20Enumera%C3%A7%C3%B5es.md). --- ## Perguntas frequentes **O ciclo rodou e não gerou contrato. É erro?** Não necessariamente. Agenda vazia, total abaixo do piso ou nenhuma UR elegível são desfechos normais, com `status` **Não contratado** e o motivo em `motivoNaoContratacao`. **Como fico sabendo que um contrato foi gerado?** Pelo webhook de contratos (`tipoNotificacao = 2`), o mesmo dos contratos criados por API — ver o passo 5. Sem URL de callback configurada, consulte as execuções em [8.7](8.7.%20Consultar%20Execu%C3%A7%C3%B5es%20do%20Ciclo.md). **Posso mudar a taxa depois?** Sim. Para um cedente, [8.6](8.6.%20Atualizar%20Taxa%20de%20um%20Cedente.md). Para muitos de uma vez — a carteira inteira ou uma lista de CNPJs — [8.5](8.5.%20Atualizar%20Taxa%20por%20Opera%C3%A7%C3%A3o.md). A taxa nova vale a partir do próximo ciclo; contratos já gerados não são reprecificados. **Como desligo temporariamente?** [8.3](8.3.%20Desabilitar%20Antecipa%C3%A7%C3%A3o%20Autom%C3%A1tica.md). A configuração é preservada, então religar é apenas chamar [8.2](8.2.%20Habilitar%20Antecipa%C3%A7%C3%A3o%20Autom%C3%A1tica.md) de novo. **O mesmo cedente pode ter taxas diferentes em operações diferentes?** Sim. A configuração é por par cedente × operação — é por isso que `idOperacao` vai no corpo das chamadas de habilitação.