8.9. Roteiro Antecipação Automática Ponta a Ponta
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.
Pré-requisitos
- Credenciais de acesso à API pública (
client_ideclient_secret) — ver 1.1. Primeiros Passos. - 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.
Visão geral¶
Sequência de chamadas¶
| # | Passo | Endpoint | Resultado / uso |
|---|---|---|---|
| 1 | Cadastrar o cedente e vinculá-lo | POST /cedentes/simplificado — 8.1 | Devolve idEmpresa, usado em todos os passos seguintes |
| 2 | Habilitar o ciclo | PUT /cedentes/{idEmpresa}/antecipacao-automatica — 8.2 | Define taxa, valores, arranjos e credenciadoras |
| 3 | Conferir o que ficou valendo | GET /cedentes/{idEmpresa}/antecipacao-automatica — 8.4 | 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 | 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 | Mostra o desfecho de cada dia, inclusive os sem contrato |
| 7 | Consultar o contrato gerado | GET /cartao/contratos — Listar contratos | 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¶
{
"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¶
{
"idOperacao": 1,
"taxa": 1.9900,
"valorMinimo": 500.00,
"valorMaximo": 250000.00
}
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. 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.
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), ou consulte o campo origemAgenda em Listar contratos. Em totais.taxa vem a taxa do vínculo aplicada ao contrato.
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¶
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.
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.
Posso mudar a taxa depois? Sim. Para um cedente, 8.6. Para muitos de uma vez — a carteira inteira ou uma lista de CNPJs — 8.5. A taxa nova vale a partir do próximo ciclo; contratos já gerados não são reprecificados.
Como desligo temporariamente? 8.3. A configuração é preservada, então religar é apenas chamar 8.2 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.