Dapatkan Proses

peringatan

Sebelum mengambil proses, tinjau konfigurasi webhook dan strategi fallback kami — klik di sini.

Endpoint

Lingkungan	URL
Production	`GET https://api.idcloud.unico.app/client/v1/process/{processId}`
Sandbox	`GET https://api.idcloud.uat.unico.app/client/v1/process/{processId}`

Permintaan

Headers

Header	Nilai
`Authorization`	`Bearer <access_token>`

Parameter path

Parameter	Tipe	Wajib	Deskripsi
`processId`	string (UUID)	ya	Identifier proses yang dikembalikan oleh Buat Proses.

Contoh

cURL
Node.js

curl -X GET https://api.idcloud.unico.app/client/v1/process/$PROCESS_ID \
  -H "Authorization: Bearer $TOKEN"

import fetch from 'node-fetch';

const res = await fetch(
  `https://api.idcloud.unico.app/client/v1/process/${processId}`,
  { headers: { Authorization: `Bearer ${accessToken}` } }
);
const { process: proc } = await res.json();

Respons

200 OK

{
  "process": {
    "id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
    "flow": "idchecktrust",
    "callbackUri": "https://example.com/callback",
    "userRedirectUrl": "https://example.com/redirect",
    "state": "PROCESS_STATE_FINISHED",
    "result": "PROCESS_RESULT_OK",
    "createdAt": "2024-01-01T10:00:00Z",
    "finishedAt": "2024-01-01T10:15:00Z",
    "expiresAt": "2024-01-08T10:00:00Z",
    "purpose": "VERIFICATION",
    "clientReference": "client-ref-abc",
    "useCase": "smart_revalidation",
    "capacities": ["liveness", "face_match"],
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909",
      "friendlyName": "Luke Skywalker",
      "notifications": [
        {
          "notificationChannel": "email"
        }
      ]
    },
    "authenticationInfo": {
      "authenticationId": "auth-123",
      "livenessResult": "LIVENESS_RESULT_LIVE",
      "authenticationResult": "AUTHENTICATION_RESULT_INCONCLUSIVE",
      "identityFraudstersResult": "TRUST_RESULT_INCONCLUSIVE",
      "bioTokenEngineResult": "BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED",
      "smartRevalidationResult": "SMART_REVALIDATION_RESULT_UNSPECIFIED",
      "idAgeResult": "ID_AGE_RESULT_UNSPECIFIED",
      "scoreEngineResult": {
        "scoreEnabled": "SCORE_ENABLED_TRUE",
        "score": 85.5
      }
    },
    "companyData": {
      "branchId": "branch-123",
      "countryCode": "BR"
    },
    "bioTokenData": {
      "referenceProcessId": "ref-proc-123",
      "authenticationId": "auth-ref-123"
    },
    "services": [
      {
        "envelopeId": "4d4f3d90-04a3-4259-b63b-930ab10d2e47",
        "documentIds": ["doc-abc-123"],
        "consent_granted": true,
        "documents": [
          {
            "doc_id": "doc-abc-123",
            "typified": true,
            "cpf_match": true,
            "face_match": true,
            "validate_doc": true,
            "reused_doc": false,
            "signed_url": "https://example.com/doc?token=xyz",
            "doc": {
              "version": 1,
              "code": "CNH",
              "data": {
                "numero": "044589731564",
                "cpfNumero": "12345678909",
                "nomeCivil": "Luke Skywalker",
                "dataNascimento": "1990-05-12T00:00:00Z",
                "dataExpiracao": "2027-12-07T00:00:00Z",
                "categoria": "B"
              }
            }
          }
        ]
      }
    ]
  }
}

Field tingkat atas

Field	Tipe	Deskripsi
`process.id`	string (UUID)	Identifier proses.
`process.flow`	string	Identifier flow yang dikirim saat pembuatan.
`process.callbackUri`	string	URL callback yang dikonfigurasi untuk event proses.
`process.userRedirectUrl`	string	URL untuk mengarahkan pengguna setelah journey selesai.
`process.state`	enum	Status proses saat ini. Lihat nilai di bawah.
`process.result`	enum	Hasil verifikasi. Muncul hanya ketika `state = PROCESS_STATE_FINISHED`.
`process.createdAt`	string (datetime)	Timestamp ISO 8601 ketika proses dibuat.
`process.finishedAt`	string (datetime)	Timestamp ISO 8601 ketika proses selesai. Muncul hanya ketika `state = PROCESS_STATE_FINISHED`.
`process.expiresAt`	string (datetime)	Timestamp ISO 8601 ketika proses kedaluwarsa.
`process.purpose`	string	Tujuan proses seperti yang dikonfigurasi dalam flow.
`process.clientReference`	string	Referensi sisi klien opsional untuk pengindeksan di portal.
`process.useCase`	string	Identifier use case yang terkait dengan flow.
`process.capacities`	array of strings	Daftar kapabilitas yang diaktifkan dalam proses ini.
`process.token`	string	JWT yang ditandatangani untuk integrasi SDK.
`process.person`	object	Identifikasi yang diberikan saat pembuatan.
`process.person.notifications`	array	Saluran notifikasi yang dikonfigurasi untuk journey (misalnya `email`).
`process.authenticationInfo`	object	Hasil per kapabilitas. Lihat di bawah.
`process.companyData`	object	Konteks perusahaan dan cabang.
`process.companyData.branchId`	string	Identifier cabang.
`process.companyData.countryCode`	string	Kode negara ISO 3166-1 alpha-2.
`process.bioTokenData`	object	Info proses referensi — muncul hanya dalam alur Validasi 1:1 dan Revalidasi Cerdas.
`process.services`	array	Envelope yang ditandatangani, dokumen yang ditangkap, dan output layanan lainnya. Lihat di bawah.

Nilai process.state

Nilai	Arti
`PROCESS_STATE_CREATED`	Proses dibuat; pengguna belum menyelesaikan journey.
`AWAITING_FOR_DOCUMENT`	Proses dibuat tanpa dokumen identifikasi; menunggu untuk diatur melalui Set Process Document. Hanya muncul ketika Custom Flow mengizinkan dokumen opsional.
`PROCESS_STATE_FINISHED`	Journey selesai. Periksa `result` dan `authenticationInfo`.
`PROCESS_STATE_FAILED`	Error pemrosesan.

Inkonsistensi penamaan state

AWAITING_FOR_DOCUMENT tidak mengikuti konvensi prefiks PROCESS_STATE_* yang digunakan oleh state lainnya. Ini adalah inkonsistensi penamaan yang diketahui dalam API saat ini.

Nilai process.result

Nilai	Arti
`PROCESS_RESULT_OK`	Semua kapabilitas mengembalikan hasil positif.
`PROCESS_RESULT_INVALID_IDENTITY`	Setidaknya satu kapabilitas mengembalikan hasil negatif definitif (misalnya liveness gagal, identitas tidak cocok).
`PROCESS_RESULT_ERROR`	Error selama pemrosesan hasil.
`PROCESS_RESULT_EXPIRED`	Proses kedaluwarsa sebelum journey selesai.
`PROCESS_RESULT_UNSPECIFIED`	Proses belum selesai.

Hasil kapabilitas dalam authenticationInfo

Semua field selalu dikembalikan terlepas dari flow. Field untuk kapabilitas yang tidak digunakan dalam flow mengembalikan *_UNSPECIFIED.

Nilai enum yang disingkat

Nilai singkat (misalnya livenessResult = LIVE, authenticationResult = INCONCLUSIVE) dipetakan langsung ke nilai enum lengkap yang didokumentasikan di sini (LIVENESS_RESULT_LIVE, AUTHENTICATION_RESULT_INCONCLUSIVE, dll.) — prefiks dihilangkan untuk singkatnya.

Field	Kapabilitas	Nilai yang mungkin
`authenticationId`	—	Identifier unik untuk percobaan autentikasi ini.
`livenessResult`	Deteksi Kehidupan	`LIVENESS_RESULT_LIVE`, `LIVENESS_RESULT_NOT_LIVE`, `LIVENESS_RESULT_UNSPECIFIED`
`authenticationResult`	Verifikasi Identitas	`AUTHENTICATION_RESULT_POSITIVE`, `AUTHENTICATION_RESULT_NEGATIVE`, `AUTHENTICATION_RESULT_INCONCLUSIVE`, `AUTHENTICATION_RESULT_UNSPECIFIED`
`identityFraudstersResult`	Klasifikasi Risiko Penipuan	`TRUST_RESULT_YES`, `TRUST_RESULT_INCONCLUSIVE`, `TRUST_RESULT_UNSPECIFIED`
`bioTokenEngineResult`	Validasi 1:1	`BIO_TOKEN_ENGINE_RESULT_POSITIVE`, `BIO_TOKEN_ENGINE_RESULT_NEGATIVE`, `BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED`
`smartRevalidationResult`	Revalidasi Cerdas	`SMART_REVALIDATION_RESULT_POSITIVE`, `SMART_REVALIDATION_RESULT_NEGATIVE`, `SMART_REVALIDATION_RESULT_UNSPECIFIED`
`idAgeResult`	Verifikasi Usia	`ID_AGE_RESULT_POSITIVE`, `ID_AGE_RESULT_NEGATIVE`, `ID_AGE_RESULT_INCONCLUSIVE`, `ID_AGE_RESULT_UNSPECIFIED`
`scoreEngineResult.scoreEnabled`	Skor Risiko	`SCORE_ENABLED_TRUE`, `SCORE_ENABLED_FALSE`, `SCORE_ENABLED_UNSPECIFIED`
`scoreEngineResult.score`	Skor Risiko	Angka dari -100 sampai +100. Muncul ketika `authenticationResult = AUTHENTICATION_RESULT_INCONCLUSIVE` dan Skor Risiko diaktifkan.
`serproResult.score`	Hasil Kemiripan Serpro	`0`–`100` (kemiripan); `-1` (tidak ada wajah yang terdaftar untuk CPF ini); `-2` (error integrasi).

Field process.services

Konvensi penamaan campuran dalam services

Array services menggunakan camelCase untuk field tingkat envelope (envelopeId, documentIds) dan snake_case untuk field tingkat dokumen (doc_id, consent_granted, face_match, dll.). Ini mencerminkan respons API yang sebenarnya — kedua konvensi disengaja dan bukan merupakan kesalahan dokumentasi.

Field	Tipe	Deskripsi
`envelopeId`	string (UUID)	Identifier envelope yang ditandatangani.
`documentIds`	array of strings	ID dokumen yang ditangkap dalam layanan ini.
`consent_granted`	boolean	Apakah pengguna memberikan persetujuan berbagi data.
`documents`	array	Dokumen yang ditangkap dengan data OCR dan hasil validasi.
`documents[].doc_id`	string	Identifier dokumen.
`documents[].typified`	boolean	Apakah tipe dokumen berhasil diidentifikasi.
`documents[].cpf_match`	boolean	Apakah CPF pada dokumen cocok dengan CPF yang diberikan.
`documents[].face_match`	boolean	Apakah selfie cocok dengan foto di dokumen.
`documents[].validate_doc`	boolean	Apakah dokumen lolos validasi keaslian.
`documents[].reused_doc`	boolean	Apakah dokumen ini digunakan kembali dari proses sebelumnya.
`documents[].signed_url`	string	URL yang telah ditandatangani untuk mengunduh PDF dokumen (berlaku selama 5 menit — ambil ulang untuk memperbarui).
`documents[].doc.version`	integer	Versi skema OCR.
`documents[].doc.code`	string	Kode tipe dokumen (misalnya `CNH`, `RG`).
`documents[].doc.data`	object	Field OCR yang diekstrak. Konten bervariasi berdasarkan tipe dokumen dan data yang tersedia. Nama field dalam `doc.data` (misalnya `nomeCivil`, `dataNascimento`) dikembalikan dalam bahasa Portugis — ini adalah nilai aktual yang dihasilkan oleh mesin OCR.

400 Bad Request

Parameter path processId tidak ada atau salah format.

401 Unauthorized

Bearer token tidak ada, kedaluwarsa, atau tidak valid.

404 Not Found

processId tidak ada atau tidak termasuk dalam tenant yang terautentikasi.

429 Too Many Requests

Batas rate tercapai. Ketika sistem Anda menerima error HTTP 429, Anda harus menerapkan mekanisme untuk mencegah kegagalan berantai dan menghindari memperburuk pembatasan.

Praktik terbaik:

Periode pendinginan (backoff): Segera hentikan atau batasi permintaan berikutnya dari sistem Anda. Jangan terus-menerus mencoba ulang permintaan yang gagal dalam loop ketat.
Antrian & pembatasan: Buffer atau antrikan permintaan keluar di sisi Anda untuk mengontrol aliran lalu lintas sebelum mengirimnya kembali.
Exponential backoff dengan jitter: Saat mencoba ulang, tingkatkan waktu tunggu secara eksponensial antar percobaan (misalnya, 1 detik, 2 detik, 4 detik, 8 detik) dan tambahkan penundaan acak kecil ("jitter") untuk mencegah efek kawanan di mana semua permintaan yang diantrikan mencoba ulang pada milidetik yang sama persis.

peringatan

Terus-menerus menghubungi endpoint yang dibatasi rate tanpa melakukan backoff dapat memperpanjang periode pembatasan dan sangat memengaruhi throughput operasional sistem Anda. Pembatasan permintaan yang tepat di sisi Anda memastikan integrasi yang lebih lancar dan lebih tangguh.

Untuk batas default, peningkatan permintaan, dan detail tambahan, lihat Rate Limits.

Kode Error

400 Bad Request
401 Unauthorized
404 Not Found
429 Too Many Requests
500 Internal Server Error

Code	Message	Deskripsi
`3`	process id is invalid	Ketika process ID tidak valid.

Code	Message	Deskripsi
—	Jwt header is an invalid JSON	Ketika access token yang digunakan mengandung karakter yang salah.
—	Jwt is expired	Ketika access token yang digunakan telah kedaluwarsa.

Code	Message	Deskripsi
`5`	error getting process: rpc error: code = NotFound desc = process not found	Ketika process ID tidak ditemukan.

Code	Message	Deskripsi
`99999`	Internal failure! Try again later	Ketika terjadi error internal.

Polling vs webhook

Anda dapat melakukan polling pada endpoint ini untuk memeriksa progres, tetapi pola yang disarankan adalah berlangganan webhook dan hanya memanggil endpoint ini sebagai fallback. Lihat Webhook dan Event.

Selanjutnya

Untuk selfie yang ditangkap, lihat Get Selfie.
Untuk bundel audit bukti, lihat Get Evidence Set.

Endpoint​

Permintaan​

Contoh​

Respons​

Kode Error​

Polling vs webhook​

Selanjutnya​