Status, webhooks e vínculo com agendamento

Cada cobrança tem status e eventos que disparam efeitos colaterais na Kontato. Entender isso ajuda a debugar quando algo "não rolou".

Os 4 status de cobrança

Status	Significa	Quando muda
Pendente	Criada, esperando pagamento	Estado inicial após criação
Pago	Cliente pagou, recebido	Webhook PAYMENT_RECEIVED ou polling Pix detecta pago
Vencido	Vencimento passou sem pagamento	Cron + webhook PAYMENT_OVERDUE
Cancelado	Você ou Asaas cancelou	Botão "Cancelar" ou auto-cancel após X dias

Eventos webhook processados

Quando algo muda no Asaas, ele POSTa na Kontato em tempo real. Os 3 eventos hoje processados:

PAYMENT_RECEIVED

Cliente pagou (via Pix ou cartão). Kontato:

• Muda status pra pago
• Atualiza agendamentos.pago = true (se vinculado)
• Soma selo no cartão fidelidade (se ativo)
• Credita 20% pra indicador (se cliente foi indicado — programa F92)
• Envia confirmação WhatsApp pro cliente
• Notifica você via push

PAYMENT_CONFIRMED

Confirmação adicional do Asaas após PAYMENT_RECEIVED (no caso de cartão, depois da liquidação efetiva). Kontato registra mas não dispara nada novo.

PAYMENT_OVERDUE

Cobrança venceu sem pagamento. Kontato:

• Muda status pra vencido
• Notifica você via push ("Maria está com cobrança de R$ 80 vencida")
• Não envia mensagem automática pro cliente (você decide se cobra de novo)

Eventos NÃO processados ainda

Roadmap futuro — hoje ignorados:

• PAYMENT_REFUNDED — estorno aprovado
• PAYMENT_CHARGEDBACKED — chargeback (cliente contestou no banco)
• PAYMENT_DELETED — cobrança apagada no Asaas

Se algum desses acontece, você precisa atualizar manualmente o status na Kontato.

Vínculo com agendamento

Cobranças criadas a partir de um agendamento ficam linkadas via cobrancas.agendamento_id:

• Quando paga → agendamentos.pago = true
• Card do agendamento mostra ícone "$" verde (pago)
• Relatório de Receita conta esse agendamento como "receita realizada"
• Histórico do cliente mostra qual cobrança correspondeu a qual atendimento

Indicação 20% — F92

Se o cliente que pagou foi indicado por outro cliente do mesmo negócio:

• Webhook PAYMENT_RECEIVED detecta o vínculo de indicação
• 20% do valor vai pra crédito do indicador (não do indicado)
• Crédito aparece no perfil do indicador como "Saldo de indicações"
• Indicador pode usar como desconto na própria mensalidade Kontato (não em cobrança ao cliente)

Detalhes em Programa de Indicação.

Webhook é automático

Você não precisa configurar webhook manualmente. Quando você conecta sua API key Asaas (em Conectar Asaas), a Kontato cadastra o webhook por trás na sua conta Asaas usando a própria API key.

O webhook escuta os eventos PAYMENT_RECEIVED, PAYMENT_CONFIRMED e PAYMENT_OVERDUE — cobrindo todo o ciclo de vida da cobrança que importa pro Kontato (cobrança caiu, confirmação adicional, ou venceu).

Foi cadastrado certo? Se você consegue criar uma cobrança Pix e ela atualiza pra "Pago" automaticamente quando o cliente paga (sem você marcar manualmente), o webhook está funcionando. Em desenvolvimento, isso costuma demorar ~5s do pagamento à atualização na Kontato.

Validação de segurança

Cada webhook traz token único por negócio na URL — a Kontato valida que veio do Asaas legítimo E que pertence ao negócio correto. Sem token correto, requisição é rejeitada com 401.

Token por negócio (v0.28.5+): cada negócio Kontato tem um token único salvo em negocios.asaas_webhook_token. Vazamento isolado: atacante que descobre token de um negócio não consegue forjar webhook de outros.

Debug — webhook não chega

Se cobrança "ficou pendente" mas cliente jura que pagou:

Histórico de webhooks (debug)

A Kontato registra cada webhook recebido em log interno pra rastreabilidade — usado pela equipe de suporte quando precisa investigar pagamento que não confirmou. UI dedicada de "Logs de webhook" pro dono ainda não está disponível.

Próximo passo

Você terminou Cobranças! Próxima categoria — Fidelidade já tem visão geral em Clientes, mas detalha mais:

Visão geral de Fidelidade →