Voltar para o blog
AutomaçãoAPIWebhooksDesenvolvimento

Automatize Tudo: Guia Completo de Webhooks e API do Infi Pulse

Aprenda a integrar o Infi Pulse ao seu sistema usando webhooks e API REST. Automação completa de pagamentos, notas fiscais e mais.

Equipe Infi Pulse

Autor

7 de janeiro de 2025
6 min read
Automatize Tudo: Guia Completo de Webhooks e API do Infi Pulse

Automatize completamente seus recebimentos internacionais com webhooks e API REST. Guia para desenvolvedores.

O que São Webhooks?

Webhooks são notificações automáticas enviadas quando eventos acontecem:

1. Cliente paga PIX
2. Infi Pulse detecta pagamento
3. Enviamos POST para sua URL
4. Seu sistema processa automaticamente

Por que Usar Webhooks?

Sem webhooks:

❌ Precisa ficar checando manualmente
❌ Atraso na confirmação
❌ Processos manuais

Com webhooks:

✅ Notificação instantânea
✅ Automação total
✅ Experiência profissional

Configurando Webhooks

1. Crie um Endpoint

Seu servidor precisa receber POSTs:

// Express.js exemplo
import express from 'express'
import crypto from 'crypto'

const app = express()
app.use(express.json())

app.post('/webhooks/pulse', async (req, res) => {
  const signature = req.headers['x-pulse-signature']
  const payload = req.body

  // Valida assinatura (importante!)
  if (!validateSignature(payload, signature)) {
    return res.status(401).send('Invalid signature')
  }

  // Processa o evento
  await handlePulseEvent(payload)

  // Retorna 200 para confirmar recebimento
  res.status(200).send('OK')
})

function validateSignature(payload, signature) {
  const secret = process.env.PULSE_WEBHOOK_SECRET
  const hash = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex')

  return hash === signature
}

app.listen(3000)

2. Configure no Dashboard

Settings > Webhooks > Add Webhook

URL: https://seusite.com/webhooks/pulse
Secret: [gerado automaticamente]
Events: [selecione quais eventos quer receber]

3. Teste a Integração

Use nossa ferramenta de teste:

curl -X POST https://api.pulse.infinitum.com.br/webhooks/test \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://seusite.com/webhooks/pulse"
  }'

Eventos Disponíveis

payment.received

Disparado quando PIX é confirmado:

{
  "event": "payment.received",
  "timestamp": "2025-01-07T14:30:00Z",
  "data": {
    "payment_id": "pmt_abc123",
    "link_id": "lnk_xyz789",
    "amount_brl": 550.00,
    "exchange_rate": 5.55,
    "amount_usdt": 99.09,
    "fee": 8.25,
    "net_amount_usdt": 97.61,
    "status": "confirmed",
    "pix_tx_id": "E12345678202501071430",
    "customer": {
      "name": "João Silva",
      "document": "***123.456-**",
      "bank": "Nubank"
    }
  }
}

payment.processing

Disparado quando iniciamos a conversão:

{
  "event": "payment.processing",
  "timestamp": "2025-01-07T14:30:15Z",
  "data": {
    "payment_id": "pmt_abc123",
    "status": "processing",
    "estimated_completion": "2025-01-07T14:35:00Z"
  }
}

payment.completed

Disparado quando USDT chega na carteira:

{
  "event": "payment.completed",
  "timestamp": "2025-01-07T14:33:12Z",
  "data": {
    "payment_id": "pmt_abc123",
    "status": "completed",
    "blockchain_tx": "0x742d35cc6634c0532925a3b844bc9e7595f0beb...",
    "network": "tron",
    "confirmations": 19
  }
}

payment.failed

Disparado se algo der errado:

{
  "event": "payment.failed",
  "timestamp": "2025-01-07T14:35:00Z",
  "data": {
    "payment_id": "pmt_abc123",
    "status": "failed",
    "reason": "insufficient_liquidity",
    "refund_status": "processing"
  }
}

Casos de Uso Reais

1. Automação de Notas Fiscais

async function handlePulseEvent(payload) {
  if (payload.event === 'payment.received') {
    const { payment_id, amount_brl, customer } = payload.data

    // Emite nota fiscal automaticamente
    await emitirNotaFiscal({
      valor: amount_brl,
      cliente: customer.name,
      cpf: customer.document,
      descricao: 'Serviços de desenvolvimento'
    })

    // Envia email de confirmação
    await sendEmail({
      to: customer.email,
      subject: 'Pagamento Confirmado',
      template: 'payment-received',
      data: { payment_id, amount_brl }
    })

    // Atualiza CRM
    await updateCRM({
      customer_id: customer.id,
      status: 'paid',
      payment_date: new Date()
    })
  }
}

2. Integração com Sistema de Entregas

async function handlePulseEvent(payload) {
  if (payload.event === 'payment.completed') {
    const { payment_id } = payload.data

    // Busca pedido associado
    const order = await db.orders.findOne({ payment_id })

    // Libera entrega
    await deliverySystem.release(order.id)

    // Notifica cliente
    await sendSMS({
      to: order.customer.phone,
      message: `Seu pedido #${order.id} foi confirmado e está a caminho!`
    })
  }
}

3. Dashboard em Tempo Real

// Backend - Server-Sent Events
app.get('/events/payments', (req, res) => {
  res.setHeader('Content-Type', 'text/event-stream')
  res.setHeader('Cache-Control', 'no-cache')
  res.setHeader('Connection', 'keep-alive')

  // Quando webhook chega
  webhookEmitter.on('payment', (data) => {
    res.write(`data: ${JSON.stringify(data)}\n\n`)
  })
})

// Frontend - Real-time updates
const evtSource = new EventSource('/events/payments')
evtSource.onmessage = (event) => {
  const payment = JSON.parse(event.data)
  updateDashboard(payment)
}

API REST

Além de webhooks, use nossa API para consultas e ações:

Autenticação

# Todas requisições precisam do header:
Authorization: Bearer YOUR_API_KEY

Obtenha sua API key em: Dashboard > API Keys

Criar Link de Pagamento

POST /v1/payment-links

{
  "amount": 550.00,
  "description": "Design de Logo - Cliente ABC",
  "wallet_address": "TXYZf4h48e72k4Fd15Op9VKSt8PdP7xU4Z",
  "network": "tron",
  "expires_at": "2025-01-10T23:59:59Z",
  "webhook_url": "https://seusite.com/webhooks/pulse",
  "metadata": {
    "order_id": "ORD-12345",
    "customer_email": "cliente@exemplo.com"
  }
}

Response:

{
  "id": "lnk_xyz789",
  "url": "https://pay.pulse.infinitum.com.br/lnk_xyz789",
  "qr_code": "data:image/png;base64,iVBORw0KGgo...",
  "amount_brl": 550.00,
  "exchange_rate": 5.55,
  "estimated_usdt": 99.09,
  "expires_at": "2025-01-10T23:59:59Z",
  "status": "pending"
}

Consultar Pagamento

GET /v1/payments/{payment_id}

Response:

{
  "id": "pmt_abc123",
  "link_id": "lnk_xyz789",
  "status": "completed",
  "amount_brl": 550.00,
  "amount_usdt": 97.61,
  "fee": 8.25,
  "created_at": "2025-01-07T14:25:00Z",
  "paid_at": "2025-01-07T14:30:00Z",
  "completed_at": "2025-01-07T14:33:12Z",
  "blockchain_tx": "0x742d35cc...",
  "metadata": {
    "order_id": "ORD-12345"
  }
}

Listar Pagamentos

GET /v1/payments?limit=20&status=completed&start_date=2025-01-01

Response:

{
  "data": [
    { /* payment 1 */ },
    { /* payment 2 */ }
  ],
  "pagination": {
    "total": 150,
    "page": 1,
    "per_page": 20,
    "total_pages": 8
  }
}

Cancelar Link de Pagamento

DELETE /v1/payment-links/{link_id}

Rate Limits

Limite de requisições para proteger a API:

100 requisições/minuto por API key
1000 requisições/hora por IP

Headers de resposta:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704650400

Retry Logic para Webhooks

Se seu endpoint falhar, tentamos novamente:

Tentativa 1: Imediato
Tentativa 2: 5 segundos depois
Tentativa 3: 30 segundos depois
Tentativa 4: 5 minutos depois
Tentativa 5: 1 hora depois

Após 5 tentativas, marcamos como falho e enviamos email de alerta.

Segurança Best Practices

1. Sempre Valide a Assinatura

function validateSignature(payload, signature) {
  const secret = process.env.PULSE_WEBHOOK_SECRET
  const hash = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex')

  return crypto.timingSafeEqual(
    Buffer.from(hash),
    Buffer.from(signature)
  )
}

2. Use HTTPS

❌ http://seusite.com/webhooks
✅ https://seusite.com/webhooks

Webhooks HTTP serão rejeitados.

3. Idempotência

Você pode receber o mesmo webhook múltiplas vezes:

async function handlePulseEvent(payload) {
  const { payment_id } = payload.data

  // Verifica se já processou
  const exists = await db.payments.findOne({ payment_id })
  if (exists) {
    console.log(`Payment ${payment_id} already processed`)
    return
  }

  // Processa e salva
  await processPayment(payload)
}

4. Timeout de Resposta

Retorne 200 OK rapidamente (< 3s):

app.post('/webhooks/pulse', async (req, res) => {
  // Retorna imediatamente
  res.status(200).send('OK')

  // Processa em background
  processWebhookAsync(req.body)
})

async function processWebhookAsync(payload) {
  // Processamento pesado aqui
  await emitirNota(payload)
  await updateCRM(payload)
  // etc...
}

Debugging e Logs

Visualize Webhooks no Dashboard

Dashboard > Webhooks > Logs

2025-01-07 14:30:00 | payment.received | 200 | 145ms
2025-01-07 14:30:15 | payment.processing | 200 | 89ms
2025-01-07 14:33:12 | payment.completed | 200 | 102ms

Teste com ngrok

Para desenvolvimento local:

# Terminal 1
ngrok http 3000

# Terminal 2
node server.js

# Configure webhook para:
https://abc123.ngrok.io/webhooks/pulse

SDKs Oficiais

Node.js

npm install @infinitum/pulse-sdk

import { Pulse } from '@infinitum/pulse-sdk'

const pulse = new Pulse({
  apiKey: process.env.PULSE_API_KEY,
  webhookSecret: process.env.PULSE_WEBHOOK_SECRET
})

// Criar link
const link = await pulse.paymentLinks.create({
  amount: 550,
  description: 'Design de Logo'
})

// Validar webhook
app.post('/webhooks', (req, res) => {
  const event = pulse.webhooks.validate(req.body, req.headers)

  if (event.type === 'payment.completed') {
    // Processar
  }

  res.sendStatus(200)
})

Python

pip install pulse-python

from pulse import Pulse

pulse = Pulse(api_key=os.environ['PULSE_API_KEY'])

# Criar link
link = pulse.payment_links.create(
    amount=550.00,
    description='Design de Logo'
)

# Validar webhook
@app.route('/webhooks', methods=['POST'])
def webhook():
    event = pulse.webhooks.validate(
        request.data,
        request.headers.get('X-Pulse-Signature')
    )

    if event.type == 'payment.completed':
        # Processar

    return '', 200

Próximos Passos

  1. Crie uma API key no dashboard
  2. Configure um webhook de teste
  3. Use ngrok para testar localmente
  4. Implemente idempotência no seu código
  5. Monitore logs no dashboard

Precisa de ajuda? Nossa documentação técnica completa está em docs.pulse.infinitum.com.br ou entre em contato com o suporte técnico.