Documentação da API
Integre seus produtos e serviços com a plataforma LeadsAI através de nossa API de webhooks.
Integrações com Plataformas Externas
A LeadsAI permite que você integre facilmente seus produtos digitais existentes com nossa plataforma. Isso significa que você pode usar a LeadsAI para vender e gerenciar leads para seus produtos ou serviços externos, enquanto nós cuidamos de todo o processo de vendas, pagamentos e qualificação de leads.
Configure seu produto
Durante a criação do seu produto, marque a opção "Usar plataforma externa após pagamento" e insira a URL para onde os clientes serão redirecionados após a compra, bem como a URL do webhook para receber notificações.
Receba notificações de pagamentos
Quando um cliente compra seu produto, processamos o pagamento e enviamos uma notificação detalhada para seu webhook, contendo todas as informações necessárias sobre o pagamento e o cliente.
Ative o acesso do cliente
Com os dados recebidos no webhook, você pode ativar automaticamente o acesso do cliente ao seu produto ou serviço. O cliente também será redirecionado para a URL de redirecionamento configurada.
Documentação do Webhook
Nosso webhook envia uma requisição HTTP POST para a URL configurada sempre que um pagamento for concluído com sucesso. Abaixo está a documentação completa do formato dos dados e como implementar um receptor de webhook.
Eventos do Webhook
| Evento | Descrição |
|---|---|
| payment.completed | Enviado quando um pagamento é concluído com sucesso |
Formato da Carga Útil (Payload)
A carga útil enviada para seu webhook segue o formato JSON abaixo:
{
"event": "payment.completed",
"payment": {
"id": "pay_123456789",
"reference": "REF123456",
"amount": 1000,
"currency": "MZN",
"status": "COMPLETED",
"completedAt": "2025-04-04T15:30:00Z"
},
"product": {
"id": "prod_987654321",
"name": "Curso Premium",
"price": 1000,
"quantity": 1,
"category": "Educação",
"description": "Curso completo de..."
},
"productOwneruserId": "user_123456",
"customer": {
"id": "lead_123456789",
"email": "cliente@example.com",
"phone": "+258865504448",
"name": "Nome do Cliente"
},
"metadata": {
"platform": "LeadsAI",
"timestamp": "2025-04-04T15:30:00Z"
}
}Implementando o Receptor de Webhook
Seu receptor de webhook deve:
- Aceitar requisições HTTP POST na URL configurada
- Processar a carga útil JSON recebida
- Verificar o evento (sempre será "payment.completed")
- Ativar o acesso do cliente ao seu produto ou serviço
- Retornar um código de status HTTP 200 para confirmar o recebimento
Importante
Seu endpoint de webhook deve responder com um código de status HTTP 200 dentro de 10 segundos. Se o endpoint não responder, consideraremos a entrega como falha e tentaremos novamente até 3 vezes.
Exemplos de Implementação
Exemplo em Node.js (Express)
// Exemplo de receptor de webhook usando Express
const express = require('express');
const app = express();
app.use(express.json());
// Endpoint para receber notificações de pagamento
app.post('/webhook/leadsai-payment', async (req, res) => {
try {
const data = req.body;
// Verifica se é um evento de pagamento completo
if (data.event === 'payment.completed') {
const payment = data.payment;
const customer = data.customer;
const product = data.product;
console.log(`Pagamento concluído: ${payment.id} para o cliente ${customer.name}`);
// TODO: Implemente a lógica para ativar o acesso do cliente ao seu produto
// Por exemplo, criar uma conta de usuário, ativar uma licença, etc.
await activateCustomerAccess({
customerId: customer.id,
customerEmail: customer.email,
customerPhone: customer.phone,
customerName: customer.name,
productId: product.id,
paymentReference: payment.reference
});
// Responde com sucesso
res.status(200).json({ success: true, message: 'Webhook processado com sucesso' });
} else {
// Evento desconhecido
console.warn(`Evento desconhecido recebido: ${data.event}`);
res.status(400).json({ success: false, message: 'Evento desconhecido' });
}
} catch (error) {
console.error('Erro ao processar webhook:', error);
res.status(500).json({ success: false, message: 'Erro ao processar webhook' });
}
});
async function activateCustomerAccess(customerData) {
// Implemente sua lógica para ativar o acesso do cliente
// Por exemplo, atualizar um banco de dados, chamar outra API, etc.
}
app.listen(3000, () => {
console.log('Servidor de webhook rodando na porta 3000');
});Exemplo em PHP
<?php
// Exemplo de receptor de webhook em PHP
// Obtém a carga útil JSON
$payload = file_get_contents('php://input');
$data = json_decode($payload, true);
// Verifica se os dados são válidos
if (!$data || !isset($data['event'])) {
http_response_code(400);
echo json_encode(['success' => false, 'message' => 'Payload inválido']);
exit;
}
// Verifica se é um evento de pagamento completo
if ($data['event'] === 'payment.completed') {
$payment = $data['payment'];
$customer = $data['customer'];
$product = $data['product'];
// Registra o evento
error_log("Pagamento concluído: {$payment['id']} para o cliente {$customer['name']}");
// TODO: Implemente a lógica para ativar o acesso do cliente ao seu produto
// Por exemplo, criar uma conta de usuário, ativar uma licença, etc.
activateCustomerAccess([
'customerId' => $customer['id'],
'customerEmail' => $customer['email'],
'customerPhone' => $customer['phone'],
'customerName' => $customer['name'],
'productId' => $product['id'],
'paymentReference' => $payment['reference']
]);
// Responde com sucesso
http_response_code(200);
echo json_encode(['success' => true, 'message' => 'Webhook processado com sucesso']);
} else {
// Evento desconhecido
error_log("Evento desconhecido recebido: {$data['event']}");
http_response_code(400);
echo json_encode(['success' => false, 'message' => 'Evento desconhecido']);
}
function activateCustomerAccess($customerData) {
// Implemente sua lógica para ativar o acesso do cliente
// Por exemplo, atualizar um banco de dados, chamar outra API, etc.
}
?>Considerações de Segurança
Ao implementar integrações com webhooks, é importante considerar aspectos de segurança para garantir que apenas requisições legítimas sejam processadas pelo seu sistema.
Valide a origem das requisições
Recomendamos que você implemente uma validação adicional, como verificar se a requisição vem de nossos servidores ou adicionar um token de autenticação à URL do webhook.
Armazene dados de forma segura
Sempre armazene informações sensíveis de clientes de forma segura e em conformidade com as leis de proteção de dados aplicáveis.
Implemente idempotência
Garanta que sua implementação seja idempotente, ou seja, se o mesmo webhook for recebido múltiplas vezes, não cause efeitos colaterais indesejados.
Precisa de Ajuda com Integrações?
Nossa equipe está disponível para ajudar com qualquer dúvida sobre integrações e implementações técnicas. Entre em contato conosco para obter suporte personalizado.