Guia de Integração - Due Diligence Engine

Este guia prático mostra como integrar a Due Diligence Engine em sua plataforma.

---

🚀 Quick Start

1. Obter API Key

1. Acesse o dashboard do CounterX
2. Vá em Settings > API Keys
3. Clique em Create API Key
4. Configure nome, scopes e rate limit
5. Copie e armazene a chave (mostrada apenas uma vez)

2. Primeira Requisição

curl -X POST https://api.counterx.com/v1/due-diligence/start \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assetId": "your-asset-id"
  }'

3. Verificar Trust Score

curl https://api.counterx.com/v1/due-diligence/trust-score/your-asset-id \
  -H "Authorization: Bearer YOUR_API_KEY"

---

📦 Casos de Uso Comuns

Caso 1: Marketplace de Ativos Digitais

Objetivo: Mostrar Trust Score em cada listing

// Ao exibir um asset no marketplace
async function displayAsset(assetId) {
  const asset = await getAsset(assetId);
  const trustScore = await getTrustScore(assetId);
  
  return {
    ...asset,
    trustScore: trustScore.trustScore,
    confidenceLevel: trustScore.confidenceLevel,
    riskFlags: trustScore.riskFlags
  };
}

// Componente React
function AssetCard({ asset }) {
  return (
    <div>
      <h2>{asset.title}</h2>
      <TrustBadge score={asset.trustScore} level={asset.confidenceLevel} />
      {asset.riskFlags.length > 0 && (
        <RiskFlags flags={asset.riskFlags} />
      )}
    </div>
  );
}

Caso 2: Verificação Automática ao Criar Asset

Objetivo: Iniciar Due Diligence automaticamente quando um asset é criado

async function createAsset(assetData) {
  // Criar asset
  const asset = await db.assets.create(assetData);
  
  // Iniciar Due Diligence automaticamente
  const dd = await startDueDiligence(asset.id);
  
  // Configurar webhook para notificação quando completar
  await setupWebhook({
    url: `${process.env.APP_URL}/webhooks/due-diligence`,
    events: ['due_diligence.completed']
  });
  
  return asset;
}

Caso 3: Integração com Stripe para Verificação Financeira

Objetivo: Conectar Stripe automaticamente para verificar receita

async function connectStripe(dueDiligenceId, stripeAccountId) {
  // Obter dados do Stripe
  const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);
  const account = await stripe.accounts.retrieve(stripeAccountId);
  const balance = await stripe.balance.retrieve({
    stripeAccount: stripeAccountId
  });
  
  // Upload como evidência
  await uploadEvidence(dueDiligenceId, {
    pillarType: 'FINANCIAL',
    evidenceType: 'API_CONNECTION',
    title: 'Stripe Account Verification',
    data: {
      accountId: stripeAccountId,
      balance: balance.available[0].amount,
      currency: balance.available[0].currency,
      verified: account.charges_enabled && account.payouts_enabled
    },
    source: 'Stripe API'
  });
}

Caso 4: Badge de Confiança no Site

Objetivo: Exibir badge de confiança verificada

<!-- Badge HTML -->
<div class="trust-badge" data-asset-id="your-asset-id">
  <div class="trust-score">--</div>
  <div class="trust-label">Trust Score</div>
</div>

<script>
async function loadTrustBadge(assetId) {
  const response = await fetch(
    `https://api.counterx.com/v1/due-diligence/trust-score/${assetId}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );
  
  const data = await response.json();
  
  if (data.success && data.data.status === 'VALID') {
    const badge = document.querySelector(`[data-asset-id="${assetId}"]`);
    badge.querySelector('.trust-score').textContent = data.data.trustScore;
    badge.classList.add(`trust-${data.data.confidenceLevel.toLowerCase()}`);
  }
}

// Carregar badge ao carregar página
document.addEventListener('DOMContentLoaded', () => {
  const assetId = document.querySelector('.trust-badge').dataset.assetId;
  loadTrustBadge(assetId);
});
</script>

---

🔔 Webhooks

Configurar Webhook

async function setupWebhook() {
  const response = await fetch('https://api.counterx.com/v1/webhooks', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      url: 'https://your-domain.com/webhooks/due-diligence',
      events: [
        'due_diligence.completed',
        'risk_flag.added',
        'trust_score.updated'
      ]
    })
  });
  
  return response.json();
}

Handler de Webhook (Express.js)

const express = require('express');
const crypto = require('crypto');
const app = express();

app.post('/webhooks/due-diligence', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const secret = process.env.WEBHOOK_SECRET;
  
  // Verificar assinatura
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(JSON.stringify(req.body)).digest('hex');
  
  if (signature !== digest) {
    return res.status(401).send('Invalid signature');
  }
  
  const event = req.body;
  
  switch (event.event) {
    case 'due_diligence.completed':
      handleDueDiligenceCompleted(event.data);
      break;
    case 'risk_flag.added':
      handleRiskFlagAdded(event.data);
      break;
    case 'trust_score.updated':
      handleTrustScoreUpdated(event.data);
      break;
  }
  
  res.status(200).send('OK');
});

function handleDueDiligenceCompleted(data) {
  console.log(`Due Diligence ${data.dueDiligenceId} completed`);
  console.log(`Trust Score: ${data.trustScore}`);
  
  // Atualizar asset no banco de dados
  // Enviar notificação por email
  // Atualizar cache
}

function handleRiskFlagAdded(data) {
  console.log(`Risk flag added: ${data.code} (${data.severity})`);
  
  // Notificar administradores
  // Atualizar UI se necessário
}

function handleTrustScoreUpdated(data) {
  console.log(`Trust score updated: ${data.trustScore}`);
  
  // Invalidar cache
  // Atualizar listings públicos
}

---

🎨 Componentes UI

Trust Badge Component (React)

import React from 'react';

function TrustBadge({ score, level, size = 'medium' }) {
  const getColor = () => {
    if (score >= 90) return '#10b981'; // green
    if (score >= 75) return '#3b82f6'; // blue
    if (score >= 60) return '#f59e0b'; // yellow
    if (score >= 40) return '#ef4444'; // red
    return '#6b7280'; // gray
  };
  
  const getLabel = () => {
    if (score >= 90) return 'Excelente';
    if (score >= 75) return 'Bom';
    if (score >= 60) return 'Moderado';
    if (score >= 40) return 'Baixo';
    return 'Muito Baixo';
  };
  
  return (
    <div 
      className={`trust-badge trust-badge-${size}`}
      style={{ borderColor: getColor() }}
    >
      <div className="trust-score" style={{ color: getColor() }}>
        {score !== null ? Math.round(score) : '--'}
      </div>
      <div className="trust-label">{getLabel()}</div>
      {level && (
        <div className="trust-confidence">
          Confiança: {level.replace('_', ' ')}
        </div>
      )}
    </div>
  );
}

export default TrustBadge;

Risk Flags Component (React)

import React from 'react';

function RiskFlags({ flags }) {
  if (!flags || flags.length === 0) {
    return null;
  }
  
  const getSeverityColor = (severity) => {
    switch (severity) {
      case 'CRITICAL': return '#dc2626';
      case 'HIGH': return '#ea580c';
      case 'MEDIUM': return '#f59e0b';
      case 'LOW': return '#3b82f6';
      default: return '#6b7280';
    }
  };
  
  return (
    <div className="risk-flags">
      <h3>Avisos de Risco</h3>
      {flags.map(flag => (
        <div 
          key={flag.code}
          className="risk-flag"
          style={{ borderLeftColor: getSeverityColor(flag.severity) }}
        >
          <div className="risk-flag-header">
            <span className="risk-flag-severity">{flag.severity}</span>
            <span className="risk-flag-title">{flag.title}</span>
          </div>
          <p className="risk-flag-description">{flag.description}</p>
        </div>
      ))}
    </div>
  );
}

export default RiskFlags;

---

🔒 Segurança

1. Armazenar API Key com Segurança

// ❌ NUNCA faça isso
const API_KEY = 'dd_live_abc123...'; // Exposto no código

// ✅ Use variáveis de ambiente
const API_KEY = process.env.COUNTERX_API_KEY;

// ✅ Ou use um serviço de secrets (AWS Secrets Manager, etc)

2. Validar Webhooks

Sempre valide a assinatura HMAC dos webhooks:

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(JSON.stringify(payload)).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

3. Rate Limiting no Cliente

Implemente rate limiting no seu lado para evitar exceder limites:

class RateLimiter {
  constructor(maxRequests, windowMs) {
    this.maxRequests = maxRequests;
    this.windowMs = windowMs;
    this.requests = [];
  }
  
  async check() {
    const now = Date.now();
    this.requests = this.requests.filter(time => now - time < this.windowMs);
    
    if (this.requests.length >= this.maxRequests) {
      const waitTime = this.windowMs - (now - this.requests[0]);
      await new Promise(resolve => setTimeout(resolve, waitTime));
      return this.check();
    }
    
    this.requests.push(now);
  }
}

const limiter = new RateLimiter(100, 60000); // 100 req/min

async function makeRequest() {
  await limiter.check();
  // Fazer requisição...
}

---

📊 Monitoramento

Logs e Métricas

async function trackDueDiligenceMetrics() {
  // Contar Due Diligences por status
  const stats = await Promise.all([
    countDueDiligences('PENDING'),
    countDueDiligences('IN_PROGRESS'),
    countDueDiligences('COMPLETED')
  ]);
  
  // Enviar para serviço de métricas (DataDog, etc)
  metrics.gauge('due_diligence.pending', stats[0]);
  metrics.gauge('due_diligence.in_progress', stats[1]);
  metrics.gauge('due_diligence.completed', stats[2]);
}

// Alertas
function setupAlerts() {
  // Alertar se Trust Score médio cair abaixo de 60
  if (averageTrustScore < 60) {
    sendAlert('Trust Score médio abaixo do esperado');
  }
  
  // Alertar se muitos flags críticos
  if (criticalFlagsCount > threshold) {
    sendAlert('Muitos flags críticos detectados');
  }
}

---

🐛 Troubleshooting

Erro: "UNAUTHORIZED"

• Verifique se a API Key está correta
• Verifique se está usando o header Authorization: Bearer
• Verifique se a API Key não expirou

Erro: "RATE_LIMIT_EXCEEDED"

• Implemente rate limiting no cliente
• Considere aumentar o rate limit no plano
• Use cache para reduzir requisições

Trust Score não atualiza

• Verifique se a Due Diligence está com status COMPLETED
• Verifique se não expirou (expiresAt)
• Verifique se há evidências verificadas para todos os pilares

Webhook não recebe eventos

• Verifique se a URL está acessível publicamente
• Verifique se está retornando 200 OK
• Verifique logs de falhas no dashboard
• Verifique assinatura HMAC

---

📚 Recursos

• Documentação Completa: /docs/DUE-DILIGENCE-API.md
• Taxonomia de Risk Flags: /docs/RISK-FLAGS-TAXONOMY.md
• Suporte: support@counterx.com
• Status da API: https://status.counterx.com

---

Última atualização: Janeiro 2025