Eventos de compra e venda de Criptomoedas

Este documento detalha o funcionamento dos webhooks disparados pelo sistema durante o ciclo de vida das operações de Compra (PURCHASE) e Venda (SELL). Você receberá um webhook com o evento pix.exchange.updated para cada alteração de status, contendo todas as informações da transação de forma detalhada e organizada.

🏗️ Estrutura do Payload

🔑 Campos Principais

Campo	Tipo	Descrição
`data.event`	string	Tipo do evento (`pix.exchange.updated`)
`data.data`	object	Dados específicos da transação de exchange
`id`	string	ID único do evento webhook
`apiKeyId`	string	ID da chave API que gerou o evento
`eventType`	string	Tipo do evento (igual a `data.event`)
`timestamp`	number	Timestamp Unix do evento

💰 Dados da Transação de Exchange

Campo	Tipo	Descrição
`id`	string	🆔 ID único da transação
`userId`	string	👤 ID do usuário
`pixId`	string	🎫 ID da transação PIX relacionada
`walletAddress`	string	� Endereço da carteira de criptomoedas
`baseAmount`	string	💎 Valor bruto (centavos na compra, unidade na venda)
`feeAmount`	string	💸 Valor da taxa aplicada
`netAmount`	string	💰 Valor líquido após taxas
`estimatedFinalAmount`	string	� Valor final estimado
`finalAmount`	string	� Valor final real
`token`	string	🪙 Símbolo da criptomoeda (BTC, ETH, USDT, USDC)
`tradePrice`	string	� Preço de cotação aplicado
`transactionHash`	string	🔗 Hash da transação na blockchain (quando concluída)
`network`	string	🌐 Rede blockchain utilizada
`orderType`	string	📈 Tipo da ordem (`PURCHASE` ou `SELL`)
`status`	string	📊 Status atual da transação
`error`	string	❌ Mensagem de erro (se houver)
`createdAt`	string	📅 Data/hora de criação
`updatedAt`	string	🔄 Data/hora de atualização
`logs`	array	📝 Histórico de logs da transação

📊 Ciclo de Vida e Status

O campo status varia conforme o tipo da operação (orderType).

📥 Fluxo de Compra (`PURCHASE`)

Na compra, o usuário paga BRL e recebe Criptomoedas.

Status	Descrição
`PENDING`	⏳ Ordem criada, aguardando início do processamento.
`PENDING_MANUAL_REVIEW`	📋 Aguardando aprovação administrativa (se necessário).
`ADMIN_PROCESSING`	⚙️ Ordem em processamento pela administração.
`TRADE_EXECUTED`	✅ Compra do ativo realizada com sucesso na exchange.
`CRYPTO_SENT`	📤 Finalizado. Ativo enviado para a carteira do usuário.
`FAILED`	❌ Operação falhou.

📤 Fluxo de Venda (`SELL`)

Na venda, o usuário entrega Criptomoedas e recebe saldo em conta (BRL).

Status	Descrição
`PENDING`	⏳ Ordem criada, aguardando liquidação.
`TRADE_EXECUTED`	✅ Venda do ativo realizada com sucesso na exchange.
`DEPOSIT_PARTNER_PROCESSING`	🔄 Valor em BRL em transferência para a plataforma.
`ADMIN_COMPLETED`	✅ Finalizado. Saldo BRL conciliado e creditado.
`FAILED`	❌ Operação falhou (ex: erro de rede ou saldo insuficiente).
`CANCELED`	🚫 Ordem cancelada.

📝 Exemplo de Payload Completo

{
  "data": {
    "event": "pix.exchange.updated",
    "data": {
      "id": "e1x2c3h4-a5n6-7g8e-9u0p-1d2a3t4e5s6",
      "userId": "u1s2e3r4-i5d6-7f8g-9h0i-j1k2l3m4n5o6",
      "token": "USDT",
      "network": "Polygon",
      "orderType": "PURCHASE",
      "status": "CRYPTO_SENT",
      "baseAmount": "100.00",
      "feeAmount": "1.50",
      "netAmount": "98.50",
      "tradePrice": "5.12",
      "estimatedFinalAmount": "19.23",
      "walletAddress": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
      "transactionHash": "0xa1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456",
      "logs": [],
      "createdAt": "2024-01-14T10:00:00.000Z",
      "updatedAt": "2024-01-14T10:05:00.000Z"
    }
  },
  "id": "ev1nt2id3-4ev5-6nt7-8id9-0ev1nt2id3ev4",
  "apiKeyId": "ap1k2ey3-4ap5-6ke7-8y9-0ap1k2ey3ap4",
  "eventType": "pix.exchange.updated",
  "timestamp": 1736868300000
}

🎯 Campos Principais (Resumo)

Campo	Descrição
`data.event`	🎪 Tipo do evento (`pix.exchange.updated`)
`data.data.id`	🆔 ID único da transação
`data.data.token`	🪙 Símbolo da criptomoeda
`data.data.orderType`	📈 Tipo da ordem (`SELL` ou `PURCHASE`)
`data.data.status`	📊 Status atual da transação
`data.data.baseAmount`	💎 Quantidade bruta
`data.data.finalAmount`	💵 Valor final real
`id`	🆔 ID único do evento webhook
`timestamp`	🕐 Timestamp do evento