Integrasikan backend Anda

Daftar periksa untuk memanggil Human Plugin dari layanan sisi server.

Markdown

Human Plugin dirancang untuk dipanggil hanya oleh back-end Anda. Jangan mengeksposnya ke browser atau aplikasi seluler: Human Plugin tidak memiliki autentikasi masuk.

1. Buat

curl

curl -X POST "$HUMAN_PLUGIN_URL/v1/processes" \
  -H 'Content-Type: application/json' \
  -d '{
    "flow": "api+humantoken",
    "clientId": "client-a",
    "correlationId": "onboarding-001",
    "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document number>" },
    "imageBase64": "<base64 selfie>"
  }'

Node.js

const response = await fetch(`${process.env.HUMAN_PLUGIN_URL}/v1/processes`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    flow: 'api+humantoken',
    clientId: 'client-a',
    correlationId: 'onboarding-001',
    credential: { type: 'DUI_TYPE_NG_BVN', value: documentNumber },
    imageBase64,
  }),
  signal: AbortSignal.timeout(60_000),
});

const body = await response.json();
if (response.status !== 201) {
  // body is { message, details }
  throw new Error(`Human Plugin ${response.status} ${body.message}`);
}
const { id, state, data } = body;

Atur timeout klien Anda minimal 60 detik: proses pembuatan dapat memakan waktu hingga 30 detik, ditambah langkah-langkah database. id hanya datang pada jawaban pembuatan, sehingga klien yang menyerah terlalu cepat bisa kehilangan proses yang sebenarnya selesai.

2. Simpan yang akan Anda butuhkan nanti

Simpan	Karena
id	Pegangan untuk GET
token dan link Journey, jika ada	Hanya dikembalikan pada respons pembuatan, tidak pernah disimpan oleh Human Plugin
correlationId Anda	Harus unik. Buat yang baru untuk setiap percobaan, termasuk percobaan ulang, kecuali setelah 503

3. Baca hasilnya

1. Jika state adalah PROCESS_STATE_FINISHED, baca hasilnya dari data: humanToken (atau humanTokenMatch pada revalidasi), liveness, dan ndocs. Selesai tidak sama dengan disetujui.
2. Jika state adalah PROCESS_STATE_CREATED, lakukan polling GET /v1/processes/{id} dengan backoff sampai berubah. Tidak ada hal lain yang memajukan proses.
3. Jika state adalah PROCESS_STATE_FAILED, proses berakhir tanpa hasil. Mulai proses baru jika alur Anda mengizinkannya.

4. Manfaatkan intelligence

data.ndocs memberi tahu apa yang telah dilakukan orang tersebut bersama Anda: dengan berapa banyak klien dan dokumen Anda mereka terlihat, dan kapan. Gunakan data ini dalam keputusan Anda bersama Human Token, dan ingat bahwa data ini bisa tidak ada. Lihat Intelligence.

5. Penanganan kegagalan

• Jangan mencoba ulang 500 atau 502 pada pembuatan secara otomatis. Lihat Error dan percobaan ulang.
• Coba ulang 503 pada pembuatan dengan correlationId yang sama, dan kegagalan apa pun pada GET, dengan backoff.
• 409 berarti correlationId sudah dipakai. Jangan pernah menggunakannya kembali.
• Buat peringatan untuk 503 yang berulang: artinya Human Plugin tidak dapat menjangkau databasenya.

Ekspektasi operasional

• Panggil Human Plugin dari jaringan yang sama dengan container. Terminasi TLS di depannya jika jalurnya melewati jaringan yang tidak tepercaya.
• Satu instalasi Human Plugin adalah satu batas isolasi. Klien, merek, atau lingkungan berbeda yang tidak boleh berbagi intelligence memerlukan instalasi dan database terpisah, masing-masing dengan intelligence-nya sendiri.