Cara Mengintegrasikan Pengesahan Sijil Blockchain ke Aplikasi Anda

Ringkasan

Panduan ini membimbing anda mengintegrasikan pengesahan sijil blockchain ke aplikasi anda. Sama ada anda membina sistem HR, platform pengurusan pembelajaran, atau portal pengesahan kelayakan, anda akan belajar cara mengesahkan sijil secara programatik.

Prasyarat

Sebelum bermula, pastikan anda mempunyai:

• Pemahaman asas tentang REST API
• Biasa dengan JavaScript/TypeScript (contoh disediakan)
• Akses kepada kredensial API OnChainCert
• Endpoint RPC Polygon (pilihan untuk pertanyaan blockchain langsung)

Gambaran Keseluruhan Seni Bina

OnChainCert menyediakan dua kaedah pengesahan:

Kaedah	Kes Penggunaan	Masa Respons	Kos
Pengesahan API	Kebanyakan aplikasi	100-500ms	Tier percuma tersedia
Blockchain Langsung	Keperluan keselamatan tinggi	1-3 saat	Yuran gas dikenakan

Untuk kebanyakan integrasi, pengesahan API memberikan keseimbangan terbaik antara kelajuan dan kebolehpercayaan.

Mula Pantas: Pengesahan API

Langkah 1: Dapatkan Kredensial API

Daftar di Portal Pembangun OnChainCert untuk menerima:

• API Key (awam, selamat untuk frontend)
• API Secret (peribadi, bahagian pelayan sahaja)

Langkah 2: Permintaan Pengesahan Asas

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: Kendalikan Respons

Pengesahan yang berjaya 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
    }
  }
}

Corak Integrasi

Corak 1: Integrasi LMS

Untuk Sistem Pengurusan Pembelajaran, integrasikan pengesahan semasa tamat 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();
  }
}

Corak 2: Pengesahan Sistem HR

Untuk pengesahan kelayakan pemohon semasa proses pengambilan:

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),
  };
};

Corak 3: Portal Pengesahan Awam

Untuk membina halaman pengesahan awam:

// 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 sijil"
      />
      <button onClick={handleVerify} disabled={loading}>
        {loading ? 'Mengesahkan...' : 'Sahkan Sijil'}
      </button>
      {result && <VerificationResult data={result} />}
    </div>
  );
}

Pengesahan Blockchain Langsung

Untuk aplikasi yang memerlukan keselamatan maksimum:

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),
  };
};

Pengendalian Ralat

Respons ralat biasa dan cara mengendalikannya:

Kod Ralat	Maksud	Tindakan
404	Sijil tidak dijumpai	Semak format hash, mungkin tidak sah
410	Sijil dibatalkan	Papar notis pembatalan
429	Had kadar terlampaui	Laksanakan exponential backoff
500	Ralat pelayan	Cuba semula dengan backoff, hubungi sokongan

Amalan Terbaik Keselamatan

1. Jangan sekali-kali dedahkan API secret dalam kod frontend
2. Sahkan hash sijil sebelum pertanyaan
3. Laksanakan had kadar pada endpoint pengesahan anda
4. Cache hasil pengesahan dengan sewajarnya (5-15 minit disyorkan)
5. Log semua percubaan pengesahan untuk jejak audit

Pengujian

Gunakan persekitaran sandbox untuk pembangunan:

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

Sandbox menyediakan sijil ujian dan respons blockchain simulasi tanpa transaksi sebenar.

Langkah Seterusnya

• Semak dokumentasi API lengkap
• Terokai pustaka SDK untuk Python, Go, dan PHP
• Sertai komuniti pembangun untuk sokongan

---

Panduan ini diselenggara oleh pasukan kejuruteraan OnChainCert. Untuk sokongan teknikal, hubungi [email protected]