Gateway da Kobana
Integração nativa · Somente leitura (pull) · Sincroniza automaticamente a cada 60 min (configurável) + sob demanda · Baixa em tempo real por webhook
O Gateway da Kobana é a plataforma de emissão de boletos e Pix da Kobana. Ao conectá-lo, o Dunning traz as cobranças e os clientes emitidos no Gateway e passa a cobrar por eles — com a linha digitável e o QR Pix já prontos para o devedor pagar direto no portal.
Pré-requisitos
- Uma conta no Gateway da Kobana com boletos e/ou Pix emitidos.
- Um token de acesso (access token) da API do Gateway, gerado no painel da Kobana.
- A URL pública do Dunning configurada (necessária para o Gateway entregar os webhooks).
Como conectar
O Gateway usa chave estática — você cola um token, sem fluxo de redirecionamento.
- No painel da Kobana, gere ou copie o token de acesso da API do Gateway.
- No Dunning, abra Configurações → Integrações e escolha o Gateway da Kobana.
- Cole o token de acesso e selecione o ambiente (
produçãoousandbox). - Clique em Conectar. O Dunning valida o token na hora com uma chamada de teste; um token inválido é recusado antes de salvar.
- Ao salvar, o Dunning cria automaticamente os webhooks no Gateway (clientes e cobranças) e faz a primeira sincronização.
De → Para: como os campos são mapeados
A cada sincronização, o Dunning traduz os títulos do Gateway para o modelo de cobranças e a carteira:
| Campo no Gateway | Campo no Dunning |
|---|---|
| Boleto / cobrança Pix | Cobrança |
amount (valor) | Valor original |
expire_at (vencimento) | Vencimento |
created_at | Data de emissão |
Linha digitável (line / barcode) | Linha digitável / código de barras |
QR Pix (pix_qrcode / qrcode.emv) | Copia-e-cola Pix |
URL de pagamento (shorten_url / url) | URL de pagamento |
document_number / txid | Número do documento |
Status opened / registered / blocked | pending (ou overdue se vencido) |
Status overdue / chargeback | overdue |
Status paid | paid (baixa + saída da régua) |
Status canceled / expired | cancelled |
Cliente (customer_id / payer) | Pessoa na carteira |
| CPF/CNPJ do cliente | Documento da pessoa |
| Nome do cliente | Nome da pessoa |
Boletos ainda em geração (ou com falha de geração) não têm status cobrável e são pulados até ficarem prontos.
Um chargeback/estorno de um boleto ou Pix já pago reabre a cobrança (overdue) e a faz recomeçar a régua do início, reenviando os avisos — o mesmo comportamento de estorno descrito em Ciclo de vida.
Baixa por webhook
O grande diferencial do Gateway é a baixa em tempo real. Quando um boleto ou um Pix é pago, o Gateway dispara um webhook (bank_billet.paid, pix.paid) e o Dunning dá baixa na hora: a cobrança é marcada como paga e sai da régua imediatamente — o devedor que acabou de pagar não recebe a próxima mensagem de cobrança. Cancelamento, vencimento e registro do boleto também chegam por webhook.
Como complemento à baixa em tempo real, o Dunning ainda faz um pull ativo dos boletos e Pix na sincronização — automática (a cada 60 min por padrão) ou manual — para cobrir qualquer evento que não tenha chegado por webhook. Assim, mesmo que um webhook se perca, a cobrança fica consistente na próxima sincronização.
O que não faz / limitações
- Não emite boletos nem Pix. A emissão continua no Gateway; o Dunning só cobra o que já foi emitido.
- Não escreve de volta no Gateway. É somente leitura (pull) — dar baixa ou cancelar no Dunning não altera o título no Gateway.
- Sem webhook, há atraso. Se o webhook falhar, a mudança aparece apenas no próximo ciclo de sincronização (até 60 min por padrão).
Como desconectar ou reconfigurar
Refaça o setup a qualquer momento para trocar o token ou o ambiente — a reconfiguração recria os webhooks quando necessário. Para rotacionar a chave, gere um novo token no painel da Kobana e cole-o no Dunning; o token antigo deixa de ser usado.
Solução de problemas
- A sincronização está desatualizada. Confira o intervalo configurado (padrão 60 min) e clique em Sincronizar agora para forçar um pull imediato.
- Um pagamento não deu baixa. Verifique no log de integração se o webhook
bank_billet.paid/pix.paidchegou; se não, o pull da próxima sincronização regulariza. Confirme também que a URL pública do Dunning está acessível ao Gateway. - Um cliente não apareceu. O sync de clientes roda junto com o de cobranças; um cliente sem título ainda não vira cobrança, mas a pessoa é criada quando o primeiro boleto/Pix dele é sincronizado.
- Uma cobrança aparece duplicada. Não deveria: o Dunning deduplica por
externalId(kobana:bank_billet:{id}/kobana:pix:{id}). Cobranças com origens diferentes (ex.: importadas à mão) podem coexistir — verifique a origem de cada uma. - A conexão caiu / token inválido. Gere um novo token no painel da Kobana e reconecte.
Segurança
O token de acesso é cifrado em repouso e nunca é devolvido pela API. Os webhooks criados no Gateway recebem um secret próprio, usado para validar a assinatura de cada entrega — o Dunning só processa eventos que comprovadamente vieram do Gateway.