Buat Proses

MarkdownChatGPTClaude

Endpoint ini menangani tiga produk yang berbagi path yang sama tetapi berbeda dalam parameter body, kapabilitas, dan field respons:

• Integrasi — memvalidasi siapa pengguna tersebut dengan membandingkan wajah mereka dengan basis identitas Unico (subject.duiType + subject.code diperlukan).
• Transaksional — memverifikasi bahwa ini adalah orang yang sama dari proses sebelumnya dengan membandingkan wajah-dengan-wajah (referenceProcessId ATAU array references dengan selfie / process id diperlukan).
• Cardholder Verification — memastikan bahwa sebuah kartu adalah milik pemegang yang dinyatakan, tanpa pengambilan selfie apa pun (subject.code + card diperlukan). Secara opsional menggunakan kembali proses yang telah divalidasi sebelumnya melalui referenceProcessId untuk memicu gate penggunaan kembali; tanpa itu, respons akan default ke unsure. Lihat kapabilitas Cardholder Verification.

Produk aktif ditentukan oleh APIKEY yang dikirim di header permintaan.

Untuk alur integrasi lengkap, lihat Ringkasan API.

Endpoint

Lingkungan	URL
Production	POST https://api.id.unico.app/processes/v1
Sandbox	POST https://api.id.uat.unico.app/processes/v1

Permintaan

Headers

Header	Nilai
Authorization	Bearer <access_token> (lihat Autentikasi)
APIKEY	API key yang telah disediakan — menentukan produk aktif dan kapabilitas yang diaktifkan.
Content-Type	application/json

Parameter body

Integrasi

Field	Tipe	Wajib	Deskripsi
subject.duiType	integer	ya	Pengidentifikasi tipe dokumen. Lihat nilai duiType di bawah.
subject.code	string	ya	Nilai pengenal sebagaimana didefinisikan oleh subject.duiType. Tanpa titik atau tanda hubung.
subject.name	string	tidak	Nama lengkap.
subject.gender	string	tidak	M atau F.
subject.birthDate	string (ISO 8601)	tidak	Tanggal lahir (YYYY-MM-DD).
subject.email	string	tidak	Alamat email.
subject.phone	string	tidak	Nomor telepon E.164.
subject.clientReference	string	kondisional	Pengidentifikasi unik pengguna dalam sistem Anda. Wajib untuk kemampuan Multi Akun. Unik dalam basis Anda, maksimal 256 karakter, tanpa spasi.
useCase	string	tidak	Konteks operasi, misalnya Onboarding.
subsidiaryId	string	tidak	ID cabang — diperlukan hanya jika terdapat beberapa cabang.
imageBase64	string	ya	Selfie yang ditangkap oleh front-end Anda, dalam base64.

Transaksional

Field	Tipe	Wajib	Deskripsi
references	array	kondisional	Input referensi untuk alur Validasi 1:1. Setiap item berisi referenceType (REFERENCE_TYPE_IMAGE_BASE64 atau REFERENCE_TYPE_PROCESS_ID) dan referenceContent (gambar yang di-encode base64 atau UUID proses).
referenceProcessId	string	kondisional	Tidak digunakan lagi. Gunakan references sebagai gantinya. ID proses Integrasi referensi untuk dibandingkan. Jika referensi adalah proses by-Unico, gunakan authenticationInfo.authenticationId.
imageBase64	string	ya	Selfie yang ditangkap oleh front-end Anda, dalam base64.
subject	object	tidak	Wadah informasi pengguna.
subject.duiType	string	tidak	Jenis pengenal. Nilai yang mungkin: DUI_TYPE_AR_DNI, DUI_TYPE_BR_CPF, DUI_TYPE_ID_NIK, DUI_TYPE_MX_CURP, DUI_TYPE_NG_NIN, DUI_TYPE_US_SSN.
subject.code	string	tidak	Nilai pengenal sebagaimana didefinisikan oleh subject.duiType. Tanpa titik atau tanda hubung.
subject.name	string	tidak	Nama lengkap pengguna.
subject.gender	string	tidak	M atau F.
subject.birthDate	string (ISO 8601)	tidak	Tanggal lahir (YYYY-MM-DD).
subject.email	string	tidak	Alamat email.
subject.phone	string	tidak	Nomor telepon E.164.
useCase	string	tidak	Konteks operasi, misalnya Transactional.
subsidiaryId	string	tidak	ID cabang — diperlukan hanya jika ada beberapa cabang.

informasi

Untuk produk ini, tidak memungkinkan untuk melakukan orkestrasi dengan Skor Risiko. Hasil selalu dikembalikan secara sinkron dalam respons POST.

Cardholder Verification

Field	Tipe	Wajib	Deskripsi
subject.duiType	integer	ya	Pengidentifikasi tipe dokumen. Lihat nilai duiType di bawah. Saat ini hanya DUI_TYPE_BR_CPF.
subject.code	string	ya	CPF pemegang kartu yang diverifikasi. Tanpa titik atau tanda hubung.
card.bin	string	kondisional	6 atau 8 digit pertama kartu (BIN). Diperlukan bersama dengan card.last4.
card.last4	string	kondisional	4 digit terakhir kartu. Diperlukan bersama dengan card.bin.
card.name	string	tidak	Nama pemegang kartu sebagaimana tercetak pada kartu.
referenceProcessId	string (UUID)	tidak	ID proses yang telah divalidasi sebelumnya untuk digunakan kembali — proses dengan hasil Verifikasi Identitas atau Deteksi Kehidupan yang disetujui untuk CPF yang sama. Versi kemampuan ini saat ini berbasis penggunaan kembali: tanpa field ini, gate tidak akan pernah dipicu dan respons akan default ke hasil unsure standar — permintaan itu sendiri tidak akan pernah gagal.
useCase	string	tidak	Konteks operasi, misalnya CardholderVerification.
subsidiaryId	string	tidak	ID cabang — diperlukan hanya jika terdapat beberapa cabang.

informasi

Tidak ada imageBase64 yang dikirim untuk produk ini — Cardholder Verification berjalan sepenuhnya di back-end, tanpa langkah pengambilan selfie.

Nilai duiType

Negara	Kode	Deskripsi
AR	6	Paspor Argentina
AR	7	DNI Argentina
AR	49	SIM Argentina (Licencia Nacional de Conducir)
AT	34	Nomor Pajak Austria (STNR)
BE	36	Nomor Nasional Belgia (NN)
BR	1	CPF Brasil
BR	5	Paspor Brasil
BR	14	CNPJ Brasil
CA	28	SIN Kanada
CH	33	Nomor AHV/AVS Swiss
CL	9	RUN Chili
CL	52	Paspor Chili
CL	57	SIM Chili (Licencia de Conducir)
CO	26	NIT Kolombia
CO	53	Paspor Kolombia
CO	55	SIM Kolombia (Licencia de Conducción)
CO	56	Kartu Kewarganegaraan Kolombia (Cédula de Ciudadanía)
DE	41	Nomor Identifikasi Pajak Jerman (IdNr)
DK	29	CPR Denmark
EC	10	NI Ekuador
ES	50	Nomor Identitas Warga Asing Spanyol (NIE)
ES	51	Dokumen Identitas Nasional Spanyol (DNI)
FI	35	Kode Identitas Pribadi Finlandia (HETU)
FR	46	Nomor Referensi Pajak Prancis (SPI)
GB	30	Nomor Asuransi Nasional Inggris (NINO)
GT	12	CUI Guatemala
ID	16	NIK Indonesia
IE	47	Nomor Layanan Publik Pribadi Irlandia (PPSN)
IT	37	Codice Fiscale Italia (CF)
LU	48	Nomor Identifikasi Nasional Luksemburg (Matricule)
MX	2	CURP Meksiko
MX	25	RFC Meksiko (Perorangan)
MX	58	SIM Meksiko (Licencia de Conducir)
NG	8	NIN Nigeria
NG	20	Nomor Verifikasi Bank Nigeria (BVN)
NG	43	Token BVN Nigeria (hash)
NG	44	Token NIN Nigeria (hash)
NL	42	Nomor Layanan Warga Negara Belanda (BSN)
NO	39	Nomor Identitas Nasional Norwegia (Fødselsnummer)
PE	27	RUC Peru
PE	40	DNI Peru
PE	54	Paspor Peru
PL	31	PESEL Polandia
PT	45	Nomor Identifikasi Pajak Portugal (NIF)
SE	32	Nomor Pribadi Swedia (PNR)
SE	38	Nomor Koordinasi Swedia (Samordningsnummer)
TR	24	Nomor Identifikasi Turki (TCKN)
US	4	SSN Amerika Serikat
US	11	Paspor Amerika Serikat
US	18	SIM Amerika Serikat
US	21	Kartu Paspor Amerika Serikat
US	22	Paspor Polikarbonat Amerika Serikat
US	23	Kartu Identitas Amerika Serikat
UY	13	CI Uruguay
ZZ	15	Alamat email
ZZ	17	Nomor telepon
—	0	Tidak ditentukan
—	3	Pengidentifikasi internal Unico

Persyaratan gambar

• Resolusi minimum: 640 x 480 (standar HD)
• Ukuran file maksimum: 800 KB (kompresi JPEG92 disarankan)
• Format yang diterima: PNG, JPEG, WebP
• Token JWT dari SDK kedaluwarsa setelah 10 menit dan hanya dapat digunakan sekali

Permintaan yang dikompresi

API mendukung pengiriman body permintaan yang dikompresi, menggunakan header HTTP standar Content-Encoding. Ini bersifat opsional dan sepenuhnya backward-compatible: klien yang tidak mengirim header ini akan tetap berfungsi seperti sebelumnya.

Format yang didukung

Encoding	Header Content-Encoding	Status
Gzip	gzip	✅ Direkomendasikan
Deflate	deflate	✅ Didukung
Tanpa kompresi	(header tidak ada)	✅ Didukung (perilaku default)

Rekomendasi

Gunakan gzip. Ini memiliki dukungan paling universal di berbagai bahasa dan pustaka HTTP, sehingga menghindari ambiguitas implementasi yang ada pada format lain.

Kompresi direkomendasikan untuk permintaan dengan body yang besar (misalnya, payload JSON yang ekstensif, pengunggahan gambar yang di-encode base64, pengiriman data secara batch). Untuk permintaan kecil, overhead dari kompresi mungkin tidak memberikan manfaat yang berarti.

Cara mengirim permintaan yang dikompresi

1. Kompresi body permintaan (misalnya, JSON yang telah di-serialize) menggunakan algoritma yang dipilih.
2. Kirim body yang telah dikompresi sebagai byte biner dalam permintaan.
3. Sertakan header Content-Encoding dengan nilai yang sesuai (gzip atau deflate).
4. Pertahankan Content-Type yang menjelaskan format konten asli (misalnya, application/json), bukan encoding transport-nya.

cURL

echo '{"subject":{"code":"12345678909"},"useCase":"Onboarding","imageBase64":"/9j/4AAQSkZJR..."}' | gzip > body.json.gz

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Content-Encoding: gzip" \
  --data-binary @body.json.gz

Python (requests)

import gzip
import json
import requests

payload = {
    "subject": {"code": "12345678909"},
    "useCase": "Onboarding",
    "imageBase64": capturedImage,
}
compressed_body = gzip.compress(json.dumps(payload).encode("utf-8"))

response = requests.post(
    "https://api.id.unico.app/processes/v1",
    data=compressed_body,
    headers={
        "Authorization": f"Bearer {token}",
        "APIKEY": api_key,
        "Content-Type": "application/json",
        "Content-Encoding": "gzip",
    },
)

.NET (C#, HttpClient)

using System.IO.Compression;
using System.Text;
using System.Text.Json;

var json = JsonSerializer.Serialize(payload);
var jsonBytes = Encoding.UTF8.GetBytes(json);

using var outputStream = new MemoryStream();
using (var gzipStream = new GZipStream(outputStream, CompressionMode.Compress, leaveOpen: true))
{
    await gzipStream.WriteAsync(jsonBytes, 0, jsonBytes.Length);
}
outputStream.Position = 0;

var content = new ByteArrayContent(outputStream.ToArray());
content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
content.Headers.ContentEncoding.Add("gzip");

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {token}");
client.DefaultRequestHeaders.Add("APIKEY", apiKey);

var response = await client.PostAsync("https://api.id.unico.app/processes/v1", content);

tips

Untuk contoh Python, gunakan parameter data=, bukan json=. Parameter json= menserialisasi payload secara otomatis, tetapi tidak mengompresnya.

Menggunakan deflate sebagai gantinya: alur di atas identik — hanya panggilan kompresi dan nilai Content-Encoding yang berubah.

Bahasa	deflate
Bash / cURL	zlib-flate -compress < body.json > body.json.deflate (dari qpdf), lalu -H "Content-Encoding: deflate"
Python	zlib.compress(data) sebagai pengganti gzip.compress(data)
.NET (C#)	System.IO.Compression.DeflateStream sebagai pengganti GZipStream

deflate ambigu dalam praktiknya

Content encoding deflate pada HTTP ditentukan sebagai zlib stream (RFC 1950), tetapi beberapa klien dan server secara historis mengirim atau mengharapkan raw DEFLATE (RFC 1951) sebagai gantinya. API ini mengharapkan zlib-wrapped stream standar — output yang sama yang dihasilkan zlib.compress() (Python) atau DeflateStream (.NET) secara default. Jika ragu, gunakan gzip, yang tidak memiliki ambiguitas seperti ini.

Perilaku error

Jika Content-Encoding dikirim dengan nilai yang tidak didukung, atau body rusak atau tidak valid untuk encoding yang dideklarasikan, API akan mengembalikan 400 Bad Request dengan pesan yang menunjukkan bahwa body permintaan gagal didekompresi.

FAQ

Apakah saya perlu mengubah sesuatu jika saya tidak ingin menggunakan kompresi? Tidak. Dukungan Content-Encoding bersifat aditif — permintaan tanpa header ini akan tetap diproses secara normal.

Apakah ini memengaruhi respons API? Tidak. Fitur ini hanya berkaitan dengan body yang dikirim oleh klien (permintaan). Kompresi respons (apa yang dikembalikan oleh API) dikontrol secara terpisah melalui header Accept-Encoding.

Format mana yang harus saya pilih? Gunakan gzip, kecuali ada batasan khusus dalam lingkungan Anda yang mengharuskan penggunaan format lain.

Contoh

Integrasi — cURL

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "duiType": 1,
      "code": "12345678909",
      "name": "Luke Skywalker",
      "gender": "M",
      "birthDate": "2000-05-20",
      "email": "[email protected]",
      "phone": "5519725570707"
    },
    "useCase": "Onboarding",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

Integrasi — Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      duiType: 1,
      code: '12345678909',
      name: 'Luke Skywalker',
      gender: 'M',
      birthDate: '2000-05-20',
      email: '[email protected]',
      phone: '5519725570707'
    },
    useCase: 'Onboarding',
    imageBase64: capturedImage
  })
});

const result = await res.json();

Transaksional — cURL

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "references": [
      {
        "referenceType": "REFERENCE_TYPE_PROCESS_ID",
        "referenceContent": "4f00b35f-69d4-415a-a843-d975cefcb169"
      }
    ],
    "useCase": "Transactional",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

Transaksional — Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    references: [
      {
        referenceType: 'REFERENCE_TYPE_PROCESS_ID',
        referenceContent: '4f00b35f-69d4-415a-a843-d975cefcb169'
      }
    ],
    useCase: 'Transactional',
    imageBase64: capturedImage
  })
});

const result = await res.json();

Cardholder Verification — cURL

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "duiType": 1,
      "code": "12345678909"
    },
    "card": {
      "bin": "12345678",
      "last4": "4321",
      "name": "Luke Skywalker"
    },
    "referenceProcessId": "4f00b35f-69d4-415a-a843-d975cefcb169",
    "useCase": "CardholderVerification"
  }'

Cardholder Verification — Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      duiType: 1,
      code: '12345678909'
    },
    card: {
      bin: '12345678',
      last4: '4321',
      name: 'Luke Skywalker'
    },
    referenceProcessId: '4f00b35f-69d4-415a-a843-d975cefcb169',
    useCase: 'CardholderVerification'
  })
});

const result = await res.json();

Respons

Integrasi

200 OK

Kontrak ini bersifat unik — field idCloud.result membawa keputusan konsolidasi dari kapabilitas yang digunakan.

Unico mengonsolidasikan hasil dari kapabilitas yang dijalankan menjadi satu idCloud.result, siap untuk menentukan langkah berikutnya dalam alur Anda — tanpa perlu mengorkestrasi hasil individual.

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "idCloud": {
    "result": "approved"
  }
}

Field	Tipe	Deskripsi
id	string (UUID)	Identifier proses. Gunakan dengan Dapatkan Proses untuk kueri ulang.
status	integer	1 (memproses), 3 (selesai dengan sukses), 5 (error).

Possible result values

idCloud.result	Arti	Tindakan yang direkomendasikan
approved	Orang nyata dan identitas tervalidasi.	Lanjutkan alur.
denied	Identitas tidak tervalidasi, pemeriksaan liveness gagal, atau risiko ekstrem teridentifikasi.	Akhiri alur atau alihkan ke alur alternatif.
critical-risk	Tingkat risiko kritis teridentifikasi.	Akhiri alur atau arahkan ke peninjauan manual.
high-risk	Tingkat risiko tinggi teridentifikasi.	Arahkan ke peninjauan manual atau alur alternatif.
retry	Capture atau skor tidak cukup untuk dievaluasi.	Minta pengguna melakukan capture baru.
inconclusive	Bukti tidak cukup untuk sebuah keputusan.	Arahkan ke peninjauan manual atau alur alternatif.

Nilai yang dikembalikan bergantung pada recipe yang dikonfigurasi dalam APIKey Anda. Lihat Alur untuk nilai hasil yang dapat dikembalikan oleh setiap recipe.

Klien di Brasil dapat menerima respons per kapabilitas

Struktur respons secara keseluruhan tetap sama — hasil tunggal adalah default-nya.

Integrasi di Brasil dapat menerima hasil per kapabilitas yang terbuka. Setiap kapabilitas yang diaktifkan di APIKey menambahkan blok tersendiri ke respons — field untuk kapabilitas yang dinonaktifkan tidak disertakan.

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": { "result": "yes" },
  "riskLevel": { "result": "inconclusive" },
  "idFace": {
    "personId": "a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890",
    "result": "FOUND"
  },
  "government": { "serpro": 87 },
  "liveness": 1
}

Field respons bergantung pada APIKey Anda

Contoh di atas menampilkan semua kemungkinan field kapabilitas. Respons aktual Anda hanya akan menyertakan field untuk kapabilitas yang diaktifkan dalam konfigurasi APIKey Anda — field untuk kapabilitas yang dinonaktifkan tidak disertakan sama sekali. Hubungi manajer proyek Unico Anda untuk mengaktifkan atau menyesuaikan kapabilitas.

Field	Tipe	Deskripsi
unicoId.result	string	yes, no, inconclusive — lihat Verifikasi Identitas.
riskLevel.result	string	approved, reproved, risk-critical, risk-high, inconclusive — lihat nilai yang mungkin di bawah atau Klasifikasi Risiko Penipuan.
idFace.result	string	FOUND — lihat Pengidentifikasi Wajah.
idFace.personId	string	Pengidentifikasi opak stabil untuk wajah, dikembalikan bersama idFace.result = FOUND. Ketika tidak ada wajah yang dapat diidentifikasi dalam gambar, permintaan gagal dengan error 20532 alih-alih mengembalikan blok idFace.
identityFraudsters.result	string	Tidak digunakan lagi. Gunakan riskLevel sebagai gantinya. Klien dengan integrasi yang sedang berjalan dapat terus menggunakannya sambil mengoordinasikan migrasi dengan tim proyek yang bertanggung jawab.
government.serpro	integer	Skor kemiripan Serpro (0–100, -1, -2). Tersedia di Brasil saja. Lihat Hasil Kemiripan Serpro.
liveness	integer	1 (lulus), 2 (gagal) — lihat Deteksi Kehidupan.

riskLevel.result — nilai yang mungkin

Nilai	Makna
approved	Ini adalah wajah pemegang ID, dan tidak ditemukan bukti terkait penipuan.
reproved	Penolakan direkomendasikan, karena beberapa indikator penipuan terdeteksi.
risk-critical	Penolakan direkomendasikan, namun keputusan akhir ada pada kebijaksanaan Anda. Risiko kritis menunjukkan bahwa kami menemukan setidaknya 2 bukti kuat adanya penipuan.
risk-high	Penolakan juga direkomendasikan, namun keputusan tetap ada pada Anda. Risiko tinggi menunjukkan bahwa kami menemukan setidaknya satu bukti kuat adanya penipuan.
inconclusive	Tidak ditemukan bukti kuat adanya penipuan. Oleh karena itu, tidak dapat disimpulkan apakah terdapat risiko yang relevan atau tidak.

informasi

Ketika unicoId.result = inconclusive dan orkestrasi Skor Risiko aktif, proses mungkin mengembalikan status: 1 (memproses). Poll Dapatkan Proses atau gunakan webhook untuk mengambil hasil akhir.

Klien di Meksiko dapat menerima blok RENAPO Verification

Respons mempertahankan struktur yang sama dan menambahkan blok idGov.

Integrasi di Meksiko dengan RENAPO Verification aktif menerima blok idGov tambahan berisi data yang disimpan RENAPO untuk CURP pengguna. Ini adalah jawaban terpisah dari hasil identitas.

{
  "id": "11111111-2222-3333-4444-555555555555",
  "status": 3,
  "idCloud": { "result": "approved" },
  "idGov": {
    "government_valid": true,
    "curp": "PUEA880304MDFRJN04",
    "government_name": "ANA PRUEBA EJEMPLO",
    "date_of_birth": "1988-03-04",
    "age": 38,
    "gender": "F",
    "deceased": false,
    "is_mexican": true,
    "citizenship": "MEXICO",
    "state_of_birth": "Ciudad de México",
    "state_iso": "MX-CMX",
    "issuing_entity_code": "DF",
    "municipality_registration": ""
  }
}

Field	Tipe	Deskripsi
idGov	object	Data RENAPO untuk CURP. Tidak ada jika kapabilitas tidak diaktifkan. {} jika RENAPO tidak merespons. Hanya Meksiko. Lihat RENAPO Verification.

Transaksional

200 OK

Kontrak ini bersifat unik — field idCloud.result membawa keputusan konsolidasi dari kapabilitas yang digunakan.

Unico mengonsolidasikan hasil dari kapabilitas yang dijalankan menjadi satu idCloud.result, siap untuk menentukan langkah berikutnya dalam alur Anda — tanpa perlu mengorkestrasi hasil individual.

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "idCloud": {
    "result": "approved"
  }
}

Field	Tipe	Deskripsi
id	string (UUID)	Identifier proses.
status	integer	3 (selesai dengan sukses), 5 (error). Untuk semua nilai yang mungkin, lihat Dapatkan Proses.

Possible result values

idCloud.result	Arti	Tindakan yang direkomendasikan
approved	Orang nyata dan identitas tervalidasi.	Lanjutkan alur.
denied	Identitas tidak tervalidasi, pemeriksaan liveness gagal, atau risiko ekstrem teridentifikasi.	Akhiri alur atau alihkan ke alur alternatif.
critical-risk	Tingkat risiko kritis teridentifikasi.	Akhiri alur atau arahkan ke peninjauan manual.
high-risk	Tingkat risiko tinggi teridentifikasi.	Arahkan ke peninjauan manual atau alur alternatif.
retry	Capture atau skor tidak cukup untuk dievaluasi.	Minta pengguna melakukan capture baru.
inconclusive	Bukti tidak cukup untuk sebuah keputusan.	Arahkan ke peninjauan manual atau alur alternatif.

Nilai yang dikembalikan bergantung pada recipe yang dikonfigurasi dalam APIKey Anda. Lihat Alur untuk nilai hasil yang dapat dikembalikan oleh setiap recipe.

Klien di Brasil dapat menerima respons per kapabilitas

Struktur respons secara keseluruhan tetap sama — hasil tunggal adalah default-nya.

Integrasi di Brasil dapat menerima hasil per kapabilitas yang terbuka. Setiap kapabilitas yang diaktifkan di APIKey menambahkan blok tersendiri ke respons — field untuk kapabilitas yang dinonaktifkan tidak disertakan.

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "biometryToken": { "result": true },
  "liveness": 1
}

Field	Tipe	Deskripsi
biometryToken.result	boolean	true jika wajah yang dikirim cocok dengan proses referensi; false jika tidak.
liveness	integer	1 (lulus), 2 (gagal) — lihat Deteksi Kehidupan.

Cardholder Verification

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "cardholderVerification": {
    "result": "approved"
  }
}

Field	Tipe	Deskripsi
id	string (UUID)	Identifier proses.
status	integer	1 (memproses), 3 (selesai dengan sukses), 5 (error). Untuk semua nilai, lihat Dapatkan Proses.
cardholderVerification.result	string	approved — CPF dan kartu tersebut adalah milik orang yang sama. unsure — baik karena reuse gate tidak terpenuhi, atau karena verifikasi itu sendiri tidak meyakinkan. Tidak muncul selama status belum bernilai 3. Lihat Cardholder Verification.

Kode Error

400 Bad Request

Code	Message	Deskripsi
40221	This flow does not support reusing a prior process (referenceProcessId or bioTokenId) without an image; send an image (imageBase64, or references[0] with type IMAGE_BASE64) instead.	Alur penggunaan ulang (referenceProcessId/bioTokenId, tanpa gambar) ditolak karena penggunaan ulang proses tidak diaktifkan untuk API key ini.
20900	O base64 informado não é válido.	Parameter base64 tidak valid. Kemungkinan penyebab: bukan gambar atau percobaan injeksi.
20807	A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.	Resolusi gambar yang diunggah terlalu rendah.
20532	No face detected in image.	Tidak ada wajah yang dapat terdeteksi dalam gambar yang dikirim.
20513	The referenced process was not found.	referenceProcessId menunjuk ke proses yang tidak ada atau tidak lagi dapat diakses.
20512	The referenced process is not available for reuse.	Proses referensi ada tetapi tidak tersedia untuk digunakan kembali.
20509	The subject.name field is invalid.	subject.name mengandung karakter tidak valid.
20508	The subject.gender field is invalid.	subject.gender harus M atau F.
20507	O parâmetro subject.code é inválido.	CPF tidak standar atau tidak ada.
20506	O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.	Ukuran gambar melebihi 800 KB; kompres ke JPEG92.
20505	O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.	Format base64 tidak valid atau tidak didukung.
20065	The referenceProcessId field is invalid.	referenceProcessId bukan UUID yang valid.
20062	The useCase field is invalid.	Nilai yang tidak dikenali di field useCase.
20024	The referenceProcessId field is missing.	Parameter referenceProcessId tidak diberikan dan references tidak dikirim sebagai alternatif. Tidak berlaku untuk Cardholder Verification — referenceProcessId-nya tidak pernah divalidasi sebagai wajib; reuse gate yang tidak terpenuhi menjawab unsure sebagai gantinya.
20533	The card field is missing.	Cardholder Verification: objek card tidak diberikan.
20534	The card.bin field is missing.	Cardholder Verification: card.bin tidak diberikan.
20535	The card.last4 field is missing.	Cardholder Verification: card.last4 tidak diberikan.
20536	The card data is invalid.	Cardholder Verification: data kartu ditolak karena tidak valid.
20021	The subject.phone field is invalid.	Format subject.phone tidak valid (IDD + kode area + nomor, 13 karakter).
20019	The subject.birthDate field is invalid.	subject.birthDate di luar format ISO 8601 (YYYY-MM-DD).
20009	O parâmetro imagebase64 não foi informado.	Parameter gambar selfie tidak ada.
20008	The subject.email field is invalid.	Format email tidak valid di subject.email.
20006	O parâmetro subject.name não foi informado.	Parameter subject.name tidak ada.
20005	O parâmetro subject.code não foi informado.	Parameter subject.code tidak ada.
20004	O parâmetro subject não foi informado.	Parameter subject tidak ada.
20003	The request body is missing or invalid.	Payload null atau tidak valid.
20002	O parâmetro APIKey não foi informado.	Parameter APIKEY tidak ada di header permintaan.
20001	O parâmetro authtoken não foi informado.	Parameter token integrasi tidak ada di header permintaan.
10508	The JWT with the captured face has already been used.	JWT hanya dapat digunakan sekali.
10507	The JWT with the captured face is expired.	JWT kedaluwarsa; harus dikirim dalam 10 menit.
10506	The imageBase64 field is not a valid JWT from SDK.	imageBase64 bukan JWT valid yang dihasilkan oleh SDK.

403 Forbidden

Bearer token atau APIKEY tidak ada, kedaluwarsa, atau tidak valid. Lihat Autentikasi.

Code	Message	Deskripsi
30017	User does not have permission to perform this action.	JWT yang salah format atau pengguna tanpa izin untuk melakukan operasi ini.
10502	O token informado está expirado.	Access-token telah kedaluwarsa.
10501	O token informado é inválido.	Token autentikasi tidak valid.
10201	O AppKey informado é inválido.	APIKEY tidak valid atau tidak ada.

409 Conflict

Code	Message	Deskripsi
20073	The processID already exists.	processId yang diberikan sudah ada untuk tenant ini.

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.

500 Internal Server Error

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

Selanjutnya

• Untuk melihat kueri hasil proses Integrasi, lihat Dapatkan Proses.
• Untuk melihat semua kombinasi recipe dan nilai hasil yang mungkin, lihat Alur.
• Untuk operasi Dokumen dan Verifikasi Usia, lihat halaman masing-masing di bagian ini.