Configuração do Webhook ASAAS (por empresa)

Cada empresa que usa o Fast Delivery precisa configurar um webhook no painel ASAAS apontando para a URL exclusiva da sua conta. Isso permite que o sistema processe automaticamente pagamentos de entrega e saques dos motoristas.

---

URL do Webhook

POST https://api-fastdelivery.obotzap.com/api/v1/webhooks/asaas/{company_id}

Substitua {company_id} pelo UUID da sua empresa. Você pode consultar esse valor em Configurações → Integração no painel Fast Delivery.

URL por empresa

Cada empresa tem sua própria URL com company_id distinto. Isso garante que os eventos sejam roteados corretamente e que a assinatura HMAC seja verificada com o segredo exclusivo da sua conta.

---

Eventos a habilitar

No painel ASAAS, ao criar o webhook, selecione os seguintes eventos:

Pagamentos (cobranças PIX de entrega)

Evento	O que acontece no Fast Delivery
PAYMENT_RECEIVED	PIX recebido → entrega sai de aguardando pagamento para pendente (visível para os motoristas)
PAYMENT_CONFIRMED	Confirmação definitiva do pagamento (D+1) → status financeiro atualizado para confirmado
PAYMENT_REFUNDED	Estorno realizado → entrega é cancelada automaticamente
PAYMENT_OVERDUE	Cobrança vencida → entrega em aguardando pagamento é cancelada

Transferências (saques dos motoristas)

Evento	O que acontece no Fast Delivery
TRANSFER_DONE	Saque concluído → saldo da carteira do motorista é decrementado
TRANSFER_APPROVED	Equivalente ao TRANSFER_DONE; ambos são tratados da mesma forma
TRANSFER_FAILED	Saque falhou → status volta para falhou, sem alterar o saldo
TRANSFER_CANCELLED	Saque cancelado → mesmo comportamento do TRANSFER_FAILED

Selecione todos os 8 eventos

Habilitar apenas um subconjunto pode fazer com que o sistema fique desatualizado. Por exemplo, sem TRANSFER_FAILED um saque recusado pelo banco continuaria aparecendo como "em processamento".

---

Configurando o segredo HMAC

O ASAAS assina cada requisição com um cabeçalho asaas-signature. O Fast Delivery valida essa assinatura usando o segredo configurado para a sua empresa.

1. Gere o segredo no ASAAS

Ao cadastrar o webhook no painel ASAAS, o sistema fornece um Webhook Token. Copie esse valor.

2. Salve no Fast Delivery

Faça uma requisição autenticada como company_owner:

POST /api/v1/companies/me/asaas-config
Authorization: Bearer {seu_jwt}
Content-Type: application/json

{
  "api_key": "sua_chave_asaas",
  "webhook_secret": "token_gerado_pelo_asaas"
}

A partir desse momento, toda requisição recebida no webhook terá a assinatura validada com esse segredo.

Sem segredo configurado

Se o webhook_secret não estiver configurado para a empresa, o sistema usa o segredo global da plataforma como fallback. Isso funciona, mas é menos seguro — qualquer evento enviado para outra empresa poderia, em teoria, ser aceito. Configure sempre o segredo próprio.

---

Fluxo completo: do PIX à entrega

Cliente paga o PIX
        ↓
ASAAS dispara PAYMENT_RECEIVED → Fast Delivery
        ↓
Entrega: awaiting_payment → pending
        ↓
Motorista aceita e realiza a entrega
        ↓
(D+1) ASAAS dispara PAYMENT_CONFIRMED → Fast Delivery
        ↓
payment_status: confirmed

---

Fluxo de saque do motorista

Motorista solicita saque
        ↓
Backend cria transferência no ASAAS (status: processing)
        ↓
ASAAS dispara TRANSFER_DONE ou TRANSFER_FAILED
        ↓
TRANSFER_DONE → saldo decrementado, status: completed
TRANSFER_FAILED → status: failed, saldo mantido

---

Testando a integração

Use o Sandbox ASAAS para simular eventos sem movimentar dinheiro real.

1. Configure a chave de sandbox em Configurações → Integração no Fast Delivery (campo environment: sandbox)
2. A URL do webhook é a mesma — o sistema detecta automaticamente o ambiente pela chave
3. Simule um pagamento no painel Sandbox ASAAS e verifique se a entrega muda de status em tempo real

Logs de auditoria

Todos os eventos processados ficam registrados em Logs de Auditoria no painel Fast Delivery, com timestamp, tipo de evento e resultado da operação.