Cara Mengintegrasikan Verifikasi Sertifikat Blockchain ke Aplikasi Anda

Ringkasan

Panduan ini memandu Anda mengintegrasikan verifikasi sertifikat blockchain ke aplikasi Anda. Baik Anda membangun sistem HR, platform learning management, atau portal verifikasi kredensial, Anda akan belajar cara memverifikasi sertifikat secara programatis.

Prasyarat

Sebelum memulai, pastikan Anda memiliki:

• Pemahaman dasar tentang REST API
• Familiar dengan JavaScript/TypeScript (contoh disediakan)
• Akses ke kredensial API OnChainCert
• Endpoint RPC Polygon (opsional untuk query blockchain langsung)

Gambaran Arsitektur

OnChainCert menyediakan dua metode verifikasi:

Metode	Use Case	Waktu Respons	Biaya
Verifikasi API	Sebagian besar aplikasi	100-500ms	Tier gratis tersedia
Blockchain Langsung	Kebutuhan keamanan tinggi	1-3 detik	Biaya gas berlaku

Untuk sebagian besar integrasi, verifikasi API memberikan keseimbangan terbaik antara kecepatan dan keandalan.

Quick Start: Verifikasi API

Langkah 1: Dapatkan Kredensial API

Daftar di OnChainCert Developer Portal untuk menerima:

• API Key (publik, aman untuk frontend)
• API Secret (privat, hanya server-side)

Langkah 2: Request Verifikasi Dasar

const verifyCertificate = async (certificateHash) => {
  const response = await fetch(
    `https://api.onchaincert.org/v1/verify/${certificateHash}`,
    {
      headers: {
        'X-API-Key': process.env.ONCHAINCERT_API_KEY,
      },
    }
  );
  
  return response.json();
};

Langkah 3: Handle Response

Verifikasi yang berhasil mengembalikan:

{
  "valid": true,
  "certificate": {
    "hash": "0x7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069",
    "recipient": "John Doe",
    "title": "Advanced Web Development",
    "issuer": {
      "name": "Tech Academy",
      "verified": true,
      "walletAddress": "0x..."
    },
    "issuedAt": "2025-01-15T10:30:00Z",
    "blockchain": {
      "network": "polygon",
      "transactionHash": "0x...",
      "blockNumber": 12345678
    }
  }
}

Pola Integrasi

Pola 1: Integrasi LMS

Untuk Learning Management System, integrasikan verifikasi saat penyelesaian kursus:

class CertificateService {
  async issueCertificate(courseId, userId) {
    const course = await this.getCourse(courseId);
    const user = await this.getUser(userId);
    
    const certificateData = {
      recipient: user.fullName,
      email: user.email,
      title: course.certificateTitle,
      description: course.description,
      completedAt: new Date().toISOString(),
      metadata: {
        courseId,
        score: user.finalScore,
        hoursCompleted: course.duration,
      },
    };
    
    const response = await fetch('https://api.onchaincert.org/v1/issue', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': process.env.ONCHAINCERT_API_KEY,
        'X-API-Secret': process.env.ONCHAINCERT_API_SECRET,
      },
      body: JSON.stringify(certificateData),
    });
    
    return response.json();
  }
}

Pola 2: Verifikasi Sistem HR

Untuk verifikasi kredensial pelamar saat proses hiring:

const verifyApplicantCredentials = async (applicant) => {
  const verificationResults = await Promise.all(
    applicant.certificates.map(async (cert) => {
      const result = await verifyCertificate(cert.hash);
      return {
        claimed: cert.title,
        verified: result.valid,
        issuer: result.certificate?.issuer?.name,
        match: result.certificate?.recipient === applicant.name,
      };
    })
  );
  
  return {
    applicantId: applicant.id,
    totalCertificates: verificationResults.length,
    verified: verificationResults.filter(r => r.verified && r.match).length,
    flagged: verificationResults.filter(r => !r.verified || !r.match),
  };
};

Pola 3: Portal Verifikasi Publik

Untuk membangun halaman verifikasi publik:

// Contoh komponen React
function VerificationPortal() {
  const [hash, setHash] = useState('');
  const [result, setResult] = useState(null);
  const [loading, setLoading] = useState(false);
  
  const handleVerify = async () => {
    setLoading(true);
    try {
      const response = await fetch(`/api/verify?hash=${hash}`);
      const data = await response.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  };
  
  return (
    <div>
      <input 
        value={hash}
        onChange={(e) => setHash(e.target.value)}
        placeholder="Masukkan hash atau URL sertifikat"
      />
      <button onClick={handleVerify} disabled={loading}>
        {loading ? 'Memverifikasi...' : 'Verifikasi Sertifikat'}
      </button>
      {result && <VerificationResult data={result} />}
    </div>
  );
}

Verifikasi Blockchain Langsung

Untuk aplikasi yang membutuhkan keamanan maksimum dan trustlessness:

import { ethers } from 'ethers';

const ONCHAINCERT_CONTRACT = '0x...'; // Alamat kontrak di Polygon

const ABI = [
  'function verifyCertificate(bytes32 hash) view returns (bool valid, address issuer, uint256 timestamp)',
];

const verifyOnChain = async (certificateHash) => {
  const provider = new ethers.JsonRpcProvider(
    process.env.POLYGON_RPC_URL
  );
  
  const contract = new ethers.Contract(
    ONCHAINCERT_CONTRACT,
    ABI,
    provider
  );
  
  const [valid, issuer, timestamp] = await contract.verifyCertificate(
    certificateHash
  );
  
  return {
    valid,
    issuer,
    issuedAt: new Date(timestamp * 1000),
  };
};

Penanganan Error

Response error umum dan cara menanganinya:

Kode Error	Arti	Tindakan
404	Sertifikat tidak ditemukan	Periksa format hash, mungkin tidak valid
410	Sertifikat dicabut	Tampilkan pemberitahuan pencabutan
429	Batas rate terlampaui	Implementasikan exponential backoff
500	Error server	Coba lagi dengan backoff, hubungi support

Praktik Terbaik Keamanan

1. Jangan pernah ekspos API secret di kode frontend
2. Validasi hash sertifikat sebelum query
3. Implementasikan rate limiting di endpoint verifikasi Anda
4. Cache hasil verifikasi dengan tepat (5-15 menit direkomendasikan)
5. Log semua percobaan verifikasi untuk jejak audit

Testing

Gunakan environment sandbox untuk development:

const API_BASE = process.env.NODE_ENV === 'production'
  ? 'https://api.onchaincert.org'
  : 'https://sandbox.onchaincert.org';

Sandbox menyediakan sertifikat test dan response blockchain simulasi tanpa transaksi nyata.

Langkah Selanjutnya

• Review dokumentasi API lengkap
• Jelajahi library SDK untuk Python, Go, dan PHP
• Bergabung dengan komunitas developer untuk dukungan

---

Panduan ini dipelihara oleh tim engineering OnChainCert. Untuk dukungan teknis, hubungi [email protected]