---
title: Membuat proses
description: POST /v1/processes — field umum, batas validasi, field flow, dan respons 201 dengan Human Token dan intelligence.
canonical: https://developer.unico.io/id/human-plugin/api-reference/create-process
locale: id
generated_by: markdown-export
---

# Membuat proses

Mulai proses dan dapatkan Human Token serta intelligence orang tersebut.

`POST /v1/processes`

Memulai proses dengan salah satu [flow](#flows) dan menjawab dengan `id`, `state`, dan hasil di `data`: Human Token dan [intelligence](/id/human-plugin/get-started/intelligence) orang tersebut, `data.ndocs`.

## Sebelum memanggil

- Human Plugin sedang berjalan dan `GET /health/ready` menjawab `200`.
- Access key Anda diaktifkan untuk [flow](#flows) yang Anda gunakan.
- Jika Anda mengirim dokumen, `type`-nya ada di [katalog atribut](/id/human-plugin/additional-resources/attribute-catalog).

<a id="flows"></a>

## Flow

Field `flow` menentukan apa yang dilakukan proses. Human Plugin menjalankan flow berikut, dalam dua model integrasi:

- **API Only**: back-end Anda mengirim selfie di `imageBase64`, dan pembuatan langsung menjawab dengan hasilnya.
- **Human Token Journey**: orang tersebut mengambil selfie di journey pengambilan dan kembali ke `callbackUri` Anda. Pembuatan menjawab dengan `token` dan `link`, dan Anda membaca hasilnya dengan [Mengambil proses](/id/human-plugin/api-reference/get-process).

| Flow | Description | Possible result | Integration components required |
| --- | --- | --- | --- |
| `api+humantoken` | Menerima selfie melalui back-end Anda dan menghasilkan Human Token, pengenal wajah yang unik. Jawabannya final: tanpa pengambilan, tanpa panggilan kedua. | `PROCESS_STATE_FINISHED`, `PROCESS_STATE_FAILED` | API |
| `humantoken` | Mengambil selfie di journey pengambilan, dengan pemeriksaan deteksi kehidupan, dan menghasilkan Human Token. Pembuatan mengembalikan `token` dan `link`; baca hasilnya saat pengambilan selesai. | `PROCESS_STATE_CREATED`, `PROCESS_STATE_FINISHED`, `PROCESS_STATE_FAILED` | API, Web |
| `humantoken+revalidation` | Mengambil selfie dan membandingkan wajah dengan Human Token yang Anda harapkan. Mengembalikan apakah orangnya sama atau tidak, misalnya sebelum tindakan sensitif. | `PROCESS_STATE_CREATED`, `PROCESS_STATE_FINISHED`, `PROCESS_STATE_FAILED` | API, Web |

`clientId`, `correlationId`, dan `credential` sama di setiap flow.

## Permintaan

```json
{
  "flow": "api+humantoken",
  "clientId": "client-a",
  "correlationId": "onboarding-001",
  "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document-number>" },
  "imageBase64": "<selfie base64>"
}
```

### Field umum

| Field | Wajib | Batas (byte) | Catatan |
| --- | --- | --- | --- |
| `flow` | Ya | 64 | Salah satu dari [flow](#flows) |
| `clientId` | Ya | 128 | Id klien milik Anda. Intelligence menghitung nilai yang berbeda |
| `correlationId` | Ya | 128 | Referensi Anda untuk proses ini. **Unik**: nilai yang sudah dimiliki proses lain, apa pun statusnya, ditolak dengan `409` |
| `credential` | Ya, tetapi boleh kosong | | Key harus ada. Lihat di bawah |
| `credential.type` | Dengan dokumen | | Kode dari katalog atribut, persis dan peka huruf besar/kecil |
| `credential.value` | Dengan dokumen | 64 | Nomor dokumen |

`flow`, `clientId`, dan `correlationId` harus berupa string, tanpa karakter kontrol dan tanpa spasi di awal atau akhir. Nilai yang tidak valid ditolak, tidak pernah ditulis ulang.

### Field `credential`

- **Dengan dokumen:** objek dengan tepat `type` dan `value`, keduanya string, dikirim bersamaan.
- **Tanpa dokumen:** `null` atau `{}`. Proses tetap dihitung sebagai transaksi dan sebagai klien dalam intelligence.
- **Dihilangkan, atau objek dengan string kosong:** ditolak dengan `400 MISSING_CREDENTIAL_TYPE`. Ini menangkap key yang salah eja sebelum apa pun diproses.
- Key lain apa pun di dalam `credential` ditolak.

### Field flow

Apa yang ditambahkan setiap flow ke field umum:

| Field | Flow | Wajib | Nilai |
| --- | --- | --- | --- |
| `imageBase64` | `api+humantoken` | Ya | Selfie dalam base64. PNG, JPEG, atau WebP, hingga 800 KB |
| `callbackUri` | `humantoken`, `humantoken+revalidation` | Ya | Tempat orang tersebut kembali saat pengambilan selesai: halaman milik Anda, atau URL scheme aplikasi Anda |
| `references` | `humantoken+revalidation` | Ya | Satu item berisi Human Token yang Anda harapkan, seperti pada contoh di atas |

Human Plugin tidak menyimpan field ini, dan field opsional yang salah eja dapat diabaikan tanpa error.

Gunakan selfie frontal dengan pencahayaan baik berisi satu wajah untuk `api+humantoken`. Nilai yang bukan gambar ditolak, dan proses disimpan sebagai gagal: lihat [Penolakan flow](#flow-refusals).

Dengan `humantoken+revalidation`, hasilnya memiliki `humanTokenMatch` sebagai ganti `humanToken`:

- `"true"`: orangnya sama. Proses dihitung untuk orang tersebut, dan `ndocs` menggambarkannya.
- Nilai lain apa pun, atau pengambilan yang tidak live: tidak terkonfirmasi. Proses tidak dihitung untuk siapa pun, dan tidak ada `ndocs`.

`PROCESS_STATE_FINISHED` dijawab pada kedua kasus: baca `humanTokenMatch`. Lihat [Mengambil proses](/id/human-plugin/api-reference/get-process#finished-and-failed-processes).

Beberapa nama dicadangkan oleh Human Plugin dan ditolak dengan `400 INVALID_REQUEST`, seperti `clientReference`. Begitu pula ejaan lain dari field milik Human Plugin sendiri, seperti `client_id`, `correlation_id`, atau `Flow`: hanya `flow`, `clientId`, `correlationId`, dan `credential` yang dibaca, dengan ejaan persis seperti itu.

### Aturan body

- Satu objek JSON, maksimal **2 MiB** (kira-kira cukup untuk selfie dalam base64). Body yang lebih besar ditolak dengan `400 REQUEST_TOO_LARGE`.
- Tidak boleh ada apa pun setelah objek JSON.

## Respons

`201 Created`, dengan `Location: /v1/processes/<id>`.

```json
{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "ndocs": {
      "distinctClientsCount": 2,
      "transactionsCount": 3,
      "firstSeen": "2026-09-08",
      "lastSeen": "2026-11-03",
      "credentials": [
        { "type": "DUI_TYPE_NG_BVN", "countryCode": "NGA", "distinctCredentialCount": 1 }
      ]
    }
  }
}
```

- `id` adalah UUID dari Human Plugin. Setiap permintaan yang diterima membuat yang baru.
- `state` adalah status lokal. Lihat [siklus hidup](/id/human-plugin/api-reference/process-lifecycle).
- `humantoken` dan `humantoken+revalidation` menjawab `PROCESS_STATE_CREATED` dengan `token` dan `link`. Keduanya dikembalikan **sekali saja** dan tidak pernah disimpan: simpanlah. Lihat [Human Token Journey](/id/human-plugin/integrations/human-token-journey) dan panduan pengambilan untuk platform Anda.
- `data.ndocs` adalah intelligence orang tersebut. Bisa saja tidak ada: lihat [Intelligence](/id/human-plugin/get-started/intelligence).

<a id="result"></a>

### Hasil di `data`

Proses yang selesai memiliki field berikut di `data`. Flow Journey mengembalikannya saat Anda [membaca proses](/id/human-plugin/api-reference/get-process) setelah pengambilan.

| Field | Kapan | Nilai |
| --- | --- | --- |
| `humanToken` | `api+humantoken`, `humantoken` | Siapa orang tersebut: `value` adalah Human Token, dan `status` bernilai `validated` bila berhasil dihasilkan |
| `humanTokenMatch` | `humantoken+revalidation` | `"true"` bila orangnya sama dengan Human Token di `references` |
| `liveness` | Flow yang memeriksa deteksi kehidupan, seperti flow Journey | `value` bernilai `live` bila pengambilan berasal dari orang yang hidup, atau `not_live` bila tidak; `status` bernilai `validated` bila pemeriksaan berjalan |
| `ndocs` | Bila ada intelligence untuk orang tersebut | [Intelligence](/id/human-plugin/get-started/intelligence) orang tersebut |

Hasil Journey tampak seperti ini:

```json
{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "liveness": { "value": "live", "status": "validated" },
    "ndocs": { "distinctClientsCount": 1, "transactionsCount": 1, "firstSeen": "2026-11-05", "lastSeen": "2026-11-05", "credentials": [] }
  }
}
```

Periksa `liveness` sebelum memercayai hasilnya: dengan `not_live`, anggap pengambilan gagal dan minta orang tersebut mencoba lagi. Proses dengan `not_live` tidak dihitung dalam intelligence siapa pun.

## Error

| Status | `message` | Arti |
| --- | --- | --- |
| 400 | `INVALID_REQUEST`, `REQUEST_TOO_LARGE` | Bukan satu objek JSON, field yang dicadangkan, tipe salah, atau body lebih dari 2 MiB |
| 400 | `MISSING_<FIELD>`, `INVALID_<FIELD>` | Field wajib tidak ada atau formatnya salah, seperti `MISSING_CLIENT_ID` |
| 401 | Kosong (`""`) | Unico menolak access key Anda: tidak ada, salah, atau sudah tidak berlaku. Proses disimpan sebagai gagal. Periksa `HUMAN_API_ACCESS_KEY` |
| 409 | `CORRELATION_ID_ALREADY_USED` | Proses lain sudah memiliki `correlationId` tersebut. Tidak ada yang disimpan atau dikirim |
| 422 | `ATTRIBUTE_TYPE_NOT_SUPPORTED` | `credential.type` tidak ada di katalog. Tidak ada yang disimpan atau dikirim |
| 4xx | `message` dari flow | Flow menolak permintaan, misalnya gambar tidak valid. Lihat [Penolakan flow](#flow-refusals) |
| 502 | `UPSTREAM_UNAVAILABLE` | Proses tidak dapat dikonfirmasi tepat waktu |
| 503 | `DATABASE_UNAVAILABLE` | Database gagal. Tidak ada yang diproses |
| 500 | `INTERNAL` | Error tak terduga |

<a id="flow-refusals"></a>

### Penolakan flow

Ketika flow menolak permintaan, pembuatan menjawab `4xx` dengan alasan di `message`, dalam [envelope](/id/human-plugin/api-reference/errors-and-retries) yang biasa. Yang paling umum:

| `message` | Penyebab |
| --- | --- |
| `invalid flow` | `flow` bukan flow yang diaktifkan untuk akun Anda |
| `INVALID_IMAGE` (`400`) | `api+humantoken` tanpa `imageBase64` |
| `INVALID_REQUEST` (`400`) | `imageBase64` bukan gambar dalam base64 |
| `IMAGE_TOO_LARGE` | Gambar lebih dari 800 KB |
| `UNSUPPORTED_IMAGE_FORMAT` | Gambar bukan PNG, JPEG, atau WebP |
| `PERMISSION_DENIED` (`403`) | Access key Anda tidak diaktifkan untuk flow ini |

Proses yang ditolak disimpan sebagai gagal. Perbaiki permintaan dan buat proses baru dengan `correlationId` baru.

Baca [Error dan percobaan ulang](/id/human-plugin/api-reference/errors-and-retries) sebelum menambahkan logika percobaan ulang: percobaan baru memerlukan `correlationId` baru.

## Berikutnya

[Mengambil proses](/id/human-plugin/api-reference/get-process)