Webhooks
O que são webhooks
A tradução literal para webhook é um “gancho na web”. Em resumo, webhooks criam um tipo de conexão entre dois sistemas, para que um sistema possa receber informações do outro assim que uma determinada ação ocorrer.
Com um webhook configurado, você recebe notificações diretamente no seu sistema sobre o seu fluxo de charges, cobranças pontuais (orders) e assinaturas customizadas (subscriptions), sem precisar verificar as atualizações manualmente.
Como integrar os webhooks da barte ao seu negócio
Inicialmente, faça o login na plataforma da Barte e, no menu lateral, acesse Configurações → Integração.
Em Webhooks, para cadastrar um novo webhook, clique no botão Novo Webhook.
Feito isto, um popup será aberto com as informações que precisam ser preenchidas para o cadastro. Preencha as seguintes informações e clique em salvar para completar o cadastro:
- Nome: o nome do seu webhook
- Sua URL: o endpoint/servidor que receberá as informações do seu webhook
- Domínios: quais tipos de informações você quer receber em seu endpoint/servidor.
- Assinaturas: Informações sobre o status da assinatura
- Cobrança Pontual: informações sobre o status de uma cobrança pontual
Após salvar as informações, o seu webhook será criado com sucesso! Você pode editar posteriormente as informações do webhook criado caso seja necessário.
O que o webhook nos informa
Formato padrão da mensagem do webhook
O formato padrão de uma mensagem enviada pelo webhook ao endpoint/servidor contém os seguintes campos:
- uuid: o identificador da cobrança realizada
Exemplo: 7cec3e43-3eed-4801-92f7-114a760c3610
- dateTime: A data e a hora em que a cobrança foi criada no formato YYYY-MM-DDTHH:MM:SS (Exemplo: 2022-05-02T09:32:15.261978725)
- status: O status da cobrança (Exemplo: SENT)
- domain: tipo de cobrança realizada (Cobrança Pontual: ORDER / Assinatura Customizada: SUBSCRIPTION)
- uuidBuyer: O identificador do cliente. Também pode ser utilizado para acessar mais detalhes sobre seu cliente com a API de Buyers.
- documentBuyer: O CPF ou CNPJ do Buyer associado à cobrança
Como exemplo, abaixo temos uma mensagem enviada para o endpoint/servidor pelo webhook, no formato JSON:
{ "uuid":"633c43b9-1d14-497c-b5ce-e9d68dcb83ec", "dateTime":"2022-07-11T07:01:04.092780920", "status":"DEFAULTER", "domain":"SUBSCRIPTION", "uuidBuyer":"6fe2013e-6f49-4689-85d8-d31142e567f7", "documentBuyer":"73410889078", "address":{ "country":"BR", "state":"Minas Gerais", "city":"Uberlândia", "district":"Jardim Europa", "street":"Rua.Salim Suaid", "number":139, "zipCode":38408110, "complement":"" }}
Cobrança Pontual
Em uma cobrança pontual, o webhook nos retorna uma mensagem com ⇒ \"domain\":\"ORDER\.
Para uma cobrança pontual podemos ter diferentes status:
- SENT: Uma cobrança pontual foi enviada/gerada para o comprador
- ABANDONED: O comprador não iniciou o pagamento ou não pagou a primeira parcela de uma cobrança pontual (Boleto/Pix)
- LATE: O comprador está com uma cobrança em atraso
- PARTIALLY_PAID: O comprador pagou a parcela de uma cobrança pontual parcelada
- PAID: O comprador pagou a cobrança pontual ou pagou todas as parcelas de uma cobrança pontual parcelada
- CANCELED: A cobrança pontual foi cancelada
- REFUND: O valor da cobrança pontual foi estornada ao cliente
- CHARGEBACK: A cobrança foi contestada pelo cliente, e o valor da cobrança foi estornado
Outros pontos sobre o webhook de cobrança pontual:
- uma cobrança pontual parcelada, todas as charges (cobranças) são geradas previamente.
- O id da cobrança se mantém o mesmo, ainda que outro boleto ou pix seja gerado
Assinatura Customizada
Em uma assinatura customizada, o webhook nos retorna uma mensagem com ⇒ \"domain\":\"SUBSCRIPTION\.
Para uma assinatura podemos ter diferentes status:
- PENDING: O comprador ainda não pagou a parcela do mês da assinatura, porém ainda está dentro dos prazos de vencimento.
- DEFAULTER (Inadimplente): O comprador não pagou a parcela da assinatura dentro dos prazos de vencimento.
- ACTIVE: O comprador está com a parcela da assinatura para o mês paga
- INACTIVE: O comprador está com a assinatura inativa
Outros pontos sobre o webhook de cobrança pontual:
- As charges da assinatura são geradas mês a mês durante a vigência do plano
- O id da cobrança se mantém o mesmo, ainda que outro boleto ou pix seja gerado