프로세스 생성

MarkdownChatGPTClaude

이 엔드포인트는 동일한 경로를 공유하지만 본문 파라미터, 기능 및 응답 필드가 다른 세 가지 제품을 처리합니다:

• 온보딩 - Unico의 신원 데이터베이스와 얼굴을 비교하여 사용자가 누구인지 검증합니다 (subject.duiType + subject.code 필수).
• 트랜잭션 - 이전 프로세스의 얼굴과 비교하여 동일 인물인지 확인합니다 (referenceProcessId 또는 셀피/프로세스 ID가 포함된 references 배열 필수).
• Cardholder Verification - 셀피 캡처 없이 카드가 신고된 소지자에게 속하는지 확인합니다 (subject.code + card 필수). 선택적으로 referenceProcessId를 통해 이전에 검증된 프로세스를 재사용하여 재사용 게이트를 트리거할 수 있습니다. 이 필드가 없으면 응답은 기본적으로 unsure 결과가 됩니다. Cardholder Verification 기능을 참조하세요.

활성 제품은 요청 헤더에 전송된 APIKEY에 의해 결정됩니다.

전체 통합 플로우는 API 개요를 참조하세요.

엔드포인트

환경	URL
프로덕션	POST https://api.id.unico.app/processes/v1
샌드박스	POST https://api.id.uat.unico.app/processes/v1

요청

헤더

헤더	값
Authorization	Bearer <access_token> (인증 참조)
APIKEY	프로비저닝된 API 키 - 활성 제품과 활성화된 기능을 정의합니다.
Content-Type	application/json

본문 파라미터

온보딩

필드	유형	필수	설명
subject.duiType	integer	예	문서 유형 식별자. 아래 duiType 값을 참조하세요.
subject.code	string	예	subject.duiType에 정의된 식별자 값. 점이나 대시 없이 입력하세요.
subject.name	string	아니요	전체 이름.
subject.gender	string	아니요	M 또는 F.
subject.birthDate	string (ISO 8601)	아니요	생년월일 (YYYY-MM-DD).
subject.email	string	아니요	이메일 주소.
subject.phone	string	아니요	E.164 전화번호.
subject.clientReference	string	조건부	귀하의 시스템에서 사용자의 고유 식별자. 다중 계정 기능에 필수입니다. 기반 내에서 고유해야 하며, 최대 256자, 공백 없음.
useCase	string	아니요	작업 컨텍스트, 예: Onboarding.
subsidiaryId	string	아니요	지점 ID — 여러 지점이 있는 경우에만 필요합니다.
imageBase64	string	예	프론트엔드에서 캡처한 셀피, base64 형식.

트랜잭션

필드	유형	필수	설명
references	array	조건부	1:1 검증 플로우를 위한 참조 입력. 각 항목에는 referenceType (REFERENCE_TYPE_IMAGE_BASE64 또는 REFERENCE_TYPE_PROCESS_ID)과 referenceContent (base64 인코딩 이미지 또는 프로세스 UUID)가 포함됩니다.
referenceProcessId	string	조건부	더 이상 사용되지 않음. 대신 references를 사용하세요. 비교할 참조 온보딩 프로세스의 ID. 참조가 by-Unico 프로세스인 경우 authenticationInfo.authenticationId를 사용하세요.
imageBase64	string	예	프론트엔드에서 캡처한 셀피, base64 형식.
subject	object	아니요	사용자 정보 컨테이너.
subject.duiType	string	아니요	식별자 유형. 가능한 값: 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	아니요	subject.duiType에 정의된 식별자 값. 점이나 대시 없이 입력하세요.
subject.name	string	아니요	사용자의 전체 이름.
subject.gender	string	아니요	M 또는 F.
subject.birthDate	string (ISO 8601)	아니요	생년월일 (YYYY-MM-DD).
subject.email	string	아니요	이메일 주소.
subject.phone	string	아니요	E.164 전화번호.
useCase	string	아니요	작업 컨텍스트, 예: Transactional.
subsidiaryId	string	아니요	지점 ID - 여러 지점이 있는 경우에만 필수.

정보

이 제품에서는 위험 점수와 오케스트레이션이 불가능합니다. 결과는 항상 POST 응답에서 동기적으로 반환됩니다.

Cardholder Verification

필드	유형	필수	설명
subject.duiType	integer	예	문서 유형 식별자. 아래 duiType 값을 참조하세요. 현재 DUI_TYPE_BR_CPF만 지원됩니다.
subject.code	string	예	검증 대상 카드 소지자의 CPF. 점이나 대시 없이 입력하세요.
card.bin	string	조건부	카드의 처음 6자리 또는 8자리 (BIN). card.last4와 함께 필수입니다.
card.last4	string	조건부	카드의 마지막 4자리. card.bin과 함께 필수입니다.
card.name	string	아니요	카드에 인쇄된 카드 소지자 이름.
referenceProcessId	string (UUID)	아니요	재사용할, 이전에 검증된 프로세스의 ID — 동일한 CPF에 대해 승인된 신원 확인 또는 라이브니스 결과가 있는 프로세스여야 합니다. 이 기능의 현재 버전은 재사용 기반으로 동작합니다. 이 필드가 없으면 게이트가 트리거되지 않고, 응답은 기본적으로 표준 unsure 결과가 됩니다 — 요청 자체가 실패하는 것은 아닙니다.
useCase	string	아니요	작업 컨텍스트, 예: CardholderVerification.
subsidiaryId	string	아니요	지점 ID — 여러 지점이 있는 경우에만 필요합니다.

정보

이 제품에는 imageBase64가 전송되지 않습니다 — Cardholder Verification은 셀피 캡처 단계 없이 전적으로 백엔드에서 실행됩니다.

duiType 값

국가	코드	설명
AR	6	아르헨티나 여권
AR	7	아르헨티나 DNI
AR	49	아르헨티나 운전면허증(Licencia Nacional de Conducir)
AT	34	오스트리아 세금 번호(STNR)
BE	36	벨기에 국민 번호(NN)
BR	1	브라질 CPF
BR	5	브라질 여권
BR	14	브라질 CNPJ
CA	28	캐나다 SIN
CH	33	스위스 AHV/AVS 번호
CL	9	칠레 RUN
CL	52	칠레 여권
CL	57	칠레 운전면허증(Licencia de Conducir)
CO	26	콜롬비아 NIT
CO	53	콜롬비아 여권
CO	55	콜롬비아 운전면허증(Licencia de Conducción)
CO	56	콜롬비아 시민증(Cédula de Ciudadanía)
DE	41	독일 세금 식별 번호(IdNr)
DK	29	덴마크 CPR
EC	10	에콰도르 NI
ES	50	스페인 외국인 신분 번호(NIE)
ES	51	스페인 국민 신분증(DNI)
FI	35	핀란드 개인 식별 코드(HETU)
FR	46	프랑스 세금 참조 번호(SPI)
GB	30	영국 국민보험번호(NINO)
GT	12	과테말라 CUI
ID	16	인도네시아 NIK
IE	47	아일랜드 개인 공공 서비스 번호(PPSN)
IT	37	이탈리아 세금 코드(Codice Fiscale, CF)
LU	48	룩셈부르크 국민 식별 번호(Matricule)
MX	2	멕시코 CURP
MX	25	멕시코 RFC(개인)
MX	58	멕시코 운전면허증(Licencia de Conducir)
NG	8	나이지리아 NIN
NG	20	나이지리아 은행 확인 번호(BVN)
NG	43	나이지리아 BVN 토큰(해시)
NG	44	나이지리아 NIN 토큰(해시)
NL	42	네덜란드 시민 서비스 번호(BSN)
NO	39	노르웨이 국민 식별 번호(Fødselsnummer)
PE	27	페루 RUC
PE	40	페루 DNI
PE	54	페루 여권
PL	31	폴란드 PESEL
PT	45	포르투갈 세금 식별 번호(NIF)
SE	32	스웨덴 개인번호(PNR)
SE	38	스웨덴 조정 번호(Samordningsnummer)
TR	24	튀르키예 신분증 번호(TCKN)
US	4	미국 SSN
US	11	미국 여권
US	18	미국 운전면허증
US	21	미국 여권 카드
US	22	미국 폴리카보네이트 여권
US	23	미국 신분증
UY	13	우루과이 CI
ZZ	15	이메일 주소
ZZ	17	전화번호
—	0	미지정
—	3	Unico 내부 식별자

이미지 요구사항

• 최소 해상도: 640 x 480 (HD 표준)
• 최대 파일 크기: 800 KB (JPEG92 압축 권장)
• 허용 형식: PNG, JPEG, WebP
• SDK의 JWT 토큰은 10분 후 만료되며 한 번만 사용할 수 있습니다

압축된 요청

API는 표준 Content-Encoding HTTP 헤더를 사용하여 압축된 요청 본문을 전송하는 것을 지원합니다. 이는 선택 사항이며 완전히 하위 호환됩니다: 이 헤더를 전송하지 않는 클라이언트는 이전과 정확히 동일하게 계속 작동합니다.

지원되는 형식

인코딩	Content-Encoding 헤더	상태
Gzip	gzip	✅ 권장
Deflate	deflate	✅ 지원됨
압축 없음	(헤더 없음)	✅ 지원됨 (기본 동작)

권장 사항

gzip을 사용하세요. 언어와 HTTP 라이브러리 전반에서 가장 보편적으로 지원되며, 다른 형식에 존재하는 구현상의 모호함을 피할 수 있습니다.

압축은 본문이 큰 요청(예: 방대한 JSON 페이로드, base64로 인코딩된 이미지 업로드, 배치 제출)에 권장됩니다. 소규모 요청의 경우, 압축의 오버헤드가 의미 있는 이점을 가져오지 않을 수 있습니다.

압축된 요청을 보내는 방법

1. 선택한 알고리즘을 사용하여 요청 본문(예: 직렬화된 JSON)을 압축합니다.
2. 압축된 본문을 요청에서 바이너리 바이트로 전송합니다.
3. 일치하는 값(gzip 또는 deflate)으로 Content-Encoding 헤더를 포함합니다.
4. Content-Type은 전송 인코딩이 아니라 원본 콘텐츠 형식(예: application/json)을 나타내도록 유지합니다.

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

팁

Python 예제의 경우, json=이 아니라 data= 파라미터를 사용하세요. json= 파라미터는 페이로드를 자동으로 직렬화하지만 압축하지는 않습니다.

deflate를 대신 사용하는 경우: 위 흐름은 동일하며, 압축 호출과 Content-Encoding 값만 달라집니다.

Language	deflate
Bash / cURL	zlib-flate -compress < body.json > body.json.deflate(qpdf에서 제공), 그다음 -H "Content-Encoding: deflate"
Python	gzip.compress(data) 대신 zlib.compress(data)
.NET (C#)	GZipStream 대신 System.IO.Compression.DeflateStream

deflate는 실제로는 모호합니다

HTTP의 deflate 콘텐츠 인코딩은 zlib 스트림(RFC 1950)으로 규정되어 있지만, 일부 클라이언트와 서버는 역사적으로 원시 DEFLATE(RFC 1951)를 대신 생성하거나 기대해 왔습니다. 이 API는 표준 zlib로 감싼 스트림을 기대하며, 이는 zlib.compress()(Python) 또는 DeflateStream(.NET)이 기본적으로 생성하는 것과 동일한 출력입니다. 확실하지 않다면 이러한 모호함이 없는 gzip을 사용하는 것이 좋습니다.

오류 동작

Content-Encoding이 지원되지 않는 값으로 전송되거나, 본문이 선언된 인코딩에 대해 손상되었거나 유효하지 않은 경우, API는 요청 본문의 압축 해제에 실패했음을 나타내는 메시지와 함께 400 Bad Request를 반환합니다.

자주 묻는 질문

압축을 사용하지 않으려면 무언가를 변경해야 하나요? 아니요. Content-Encoding 지원은 추가적인 것입니다 — 이 헤더가 없는 요청은 이전과 마찬가지로 정상적으로 계속 처리됩니다.

이것이 API 응답에 영향을 미치나요? 아니요. 이 기능은 클라이언트가 전송하는 본문(요청)에만 관련됩니다. 응답 압축(API가 반환하는 것)은 Accept-Encoding 헤더로 별도로 제어됩니다.

어떤 형식을 선택해야 하나요? 환경에 특정한 제약이 다른 형식을 요구하지 않는 한, gzip을 사용하세요.

예제

온보딩 - 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": {
      "code": "12345678909",
      "name": "Luke Skywalker",
      "gender": "M",
      "birthDate": "2000-05-20",
      "email": "[email protected]",
      "phone": "5519725570707"
    },
    "useCase": "Onboarding",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

온보딩 - 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: {
      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();

트랜잭션 - 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 '{
    "referenceProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
    "useCase": "Transactional",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

트랜잭션 - 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({
    referenceProcessId: referenceProcessId,
    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();

응답

온보딩

200 OK

이 계약은 단일합니다 — idCloud.result 필드가 사용된 기능들의 통합 판정을 전달합니다.

Unico는 실행된 기능들의 결과를 단일 idCloud.result로 통합하여, 개별 결과를 조정할 필요 없이 플로우의 다음 단계를 바로 결정할 수 있게 합니다.

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

필드	유형	설명
id	string (UUID)	프로세스 식별자. 재조회 시 프로세스 조회와 함께 사용합니다.
status	integer	1 (처리 중), 3 (성공적으로 완료), 5 (오류).

가능한 결과 값

idCloud.result	의미	권장 조치
approved	실제 사람이며 신원이 검증되었습니다.	플로우를 진행하세요.
denied	신원이 검증되지 않았거나, 라이브니스 검사에 실패했거나, 극단적인 위험이 감지되었습니다.	플로우를 종료하거나 대체 플로우로 리디렉션하세요.
critical-risk	심각한 위험 수준이 감지되었습니다.	플로우를 종료하거나 수동 검토로 라우팅하세요.
high-risk	높은 위험 수준이 감지되었습니다.	수동 검토 또는 대체 플로우로 라우팅하세요.
retry	평가하기에 캡처 또는 점수가 불충분합니다.	사용자에게 새로운 캡처를 요청하세요.
inconclusive	판정을 내리기에 증거가 충분하지 않습니다.	수동 검토 또는 대체 플로우로 라우팅하세요.

반환되는 값은 APIKey에 구성된 레시피에 따라 다릅니다. 각 레시피가 반환할 수 있는 결과 값은 플로우를 참조하세요.

브라질의 클라이언트는 기능별 응답을 받을 수 있습니다

전체 응답 구조는 동일하게 유지됩니다 — 단일 결과가 기본값입니다.

브라질의 통합은 개방형의 기능별 결과를 받을 수 있습니다. APIKey에서 활성화된 각 기능은 응답에 자체 블록을 추가하며, 비활성화된 기능의 필드는 생략됩니다.

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

응답 필드는 APIKey에 따라 다릅니다

위의 예시는 모든 가능한 기능 필드를 보여줍니다. 실제 응답에는 APIKey 설정에서 활성화된 기능의 필드만 포함되며, 비활성화된 기능의 필드는 완전히 생략됩니다. 기능을 활성화하거나 조정하려면 Unico 프로젝트 매니저에게 문의하세요.

필드	유형	설명
unicoId.result	string	yes, no, inconclusive - 신원 확인 참조.
riskLevel.result	string	approved, reproved, risk-critical, risk-high, inconclusive — 아래 가능한 값 참조 또는 사기 위험 분류.
idFace.result	string	FOUND — 얼굴 식별자 참조.
idFace.personId	string	얼굴에 대한 안정적인 불투명 식별자로, idFace.result = FOUND와 함께 반환됩니다. 이미지에서 얼굴을 식별할 수 없는 경우, 요청은 오류 20532로 실패하며 idFace 블록을 반환하지 않습니다.
identityFraudsters.result	string	더 이상 사용되지 않습니다. 대신 riskLevel을 사용하세요. 통합이 진행 중인 클라이언트는 프로젝트 팀과 마이그레이션을 조율하면서 계속 사용할 수 있습니다.
government.serpro	integer	Serpro 유사도 점수 (0-100, -1, -2). 브라질에서만 사용 가능합니다. Serpro 유사도 반환 참조.
liveness	integer	1 (통과), 2 (실패) - 라이브니스 참조.

riskLevel.result — 가능한 값

값	의미
approved	신분증 소지자의 얼굴이 맞으며, 사기와 관련된 증거가 발견되지 않았습니다.
reproved	여러 사기 지표가 감지되었으므로 거부를 권장합니다.
risk-critical	거부를 권장하나 최종 결정은 귀하의 판단에 달려 있습니다. 심각 위험은 최소 2개의 강력한 사기 증거가 발견되었음을 나타냅니다.
risk-high	거부도 권장하나 결정은 귀하에게 있습니다. 높은 위험은 최소 1개의 강력한 사기 증거가 발견되었음을 나타냅니다.
inconclusive	강력한 사기 증거가 발견되지 않았습니다. 따라서 관련 위험이 있는지 여부를 결론짓기 어렵습니다.

정보

unicoId.result = inconclusive이고 위험 점수 오케스트레이션이 활성화된 경우, 프로세스가 status: 1 (처리 중)을 반환할 수 있습니다. 프로세스 조회를 폴링하거나 웹훅을 사용하여 최종 결과를 가져오세요.

멕시코의 클라이언트는 RENAPO Verification 블록을 받을 수 있습니다

응답 구조는 동일하게 유지되며 idGov 블록이 추가됩니다.

RENAPO Verification이 활성화된 멕시코의 통합은 사용자의 CURP에 대해 RENAPO가 보유한 기록이 담긴 추가 idGov 블록을 받습니다. 이는 신원 결과와는 별개의 응답입니다.

{
  "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": ""
  }
}

필드	유형	설명
idGov	object	CURP에 대한 RENAPO 기록. 기능이 활성화되지 않은 경우 없음. RENAPO가 응답하지 않은 경우 {}. 멕시코 전용. RENAPO Verification 참조.

트랜잭션

200 OK

이 계약은 단일합니다 — idCloud.result 필드가 사용된 기능들의 통합 판정을 전달합니다.

Unico는 실행된 기능들의 결과를 단일 idCloud.result로 통합하여, 개별 결과를 조정할 필요 없이 플로우의 다음 단계를 바로 결정할 수 있게 합니다.

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

필드	유형	설명
id	string (UUID)	프로세스 식별자.
status	integer	3 (성공적으로 완료), 5 (오류). 모든 가능한 값은 프로세스 조회를 참조하세요.

가능한 결과 값

idCloud.result	의미	권장 조치
approved	실제 사람이며 신원이 검증되었습니다.	플로우를 진행하세요.
denied	신원이 검증되지 않았거나, 라이브니스 검사에 실패했거나, 극단적인 위험이 감지되었습니다.	플로우를 종료하거나 대체 플로우로 리디렉션하세요.
critical-risk	심각한 위험 수준이 감지되었습니다.	플로우를 종료하거나 수동 검토로 라우팅하세요.
high-risk	높은 위험 수준이 감지되었습니다.	수동 검토 또는 대체 플로우로 라우팅하세요.
retry	평가하기에 캡처 또는 점수가 불충분합니다.	사용자에게 새로운 캡처를 요청하세요.
inconclusive	판정을 내리기에 증거가 충분하지 않습니다.	수동 검토 또는 대체 플로우로 라우팅하세요.

반환되는 값은 APIKey에 구성된 레시피에 따라 다릅니다. 각 레시피가 반환할 수 있는 결과 값은 플로우를 참조하세요.

브라질의 클라이언트는 기능별 응답을 받을 수 있습니다

전체 응답 구조는 동일하게 유지됩니다 — 단일 결과가 기본값입니다.

브라질의 통합은 개방형의 기능별 결과를 받을 수 있습니다. APIKey에서 활성화된 각 기능은 응답에 자체 블록을 추가하며, 비활성화된 기능의 필드는 생략됩니다.

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

필드	유형	설명
biometryToken.result	boolean	제출된 얼굴이 참조 프로세스와 일치하면 true; 그렇지 않으면 false.
liveness	integer	1 (통과), 2 (실패) - 라이브니스 참조.

Cardholder Verification

200 OK

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

필드	유형	설명
id	string (UUID)	프로세스 식별자.
status	integer	1 (처리 중), 3 (성공적으로 완료), 5 (오류). 모든 가능한 값은 프로세스 조회를 참조하세요.
cardholderVerification.result	string	approved — CPF와 카드가 동일 인물에게 속합니다. unsure — 재사용 게이트가 충족되지 않았거나 검증 자체가 결론에 이르지 못했습니다. status가 아직 3이 아닌 동안에는 존재하지 않습니다. Cardholder Verification 참조.

오류 코드

400 Bad Request

코드	메시지	설명
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.	재사용 플로우(referenceProcessId/bioTokenId, 이미지 없음)가 거부되었습니다. 이 API 키에 대해 프로세스 재사용이 활성화되어 있지 않기 때문입니다.
20900	O base64 informado não é válido.	base64 파라미터가 유효하지 않습니다. 가능한 원인: 이미지가 아니거나 인젝션 시도입니다.
20807	A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.	업로드된 이미지의 해상도가 너무 낮습니다.
20532	No face detected in image.	제출된 이미지에서 얼굴을 감지할 수 없습니다.
20513	The referenced process was not found.	referenceProcessId가 존재하지 않거나 더 이상 접근할 수 없는 프로세스를 가리킵니다.
20512	The referenced process is not available for reuse.	참조된 프로세스가 존재하지만 재사용할 수 없습니다.
20509	The subject.name field is invalid.	subject.name에 유효하지 않은 문자가 포함되어 있습니다.
20508	The subject.gender field is invalid.	subject.gender는 M 또는 F여야 합니다.
20507	O parâmetro subject.code é inválido.	비표준이거나 존재하지 않는 CPF입니다.
20506	O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.	이미지 크기가 800 KB를 초과합니다; JPEG92로 압축하세요.
20505	O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.	base64 형식이 유효하지 않거나 지원되지 않습니다.
20065	The referenceProcessId field is invalid.	referenceProcessId가 유효한 UUID가 아닙니다.
20062	The useCase field is invalid.	useCase 필드에 인식할 수 없는 값입니다.
20024	The referenceProcessId field is missing.	referenceProcessId 파라미터가 제공되지 않았고 대안으로 references도 전송되지 않았습니다. Cardholder Verification에는 적용되지 않습니다 — 이 기능의 referenceProcessId는 필수로 검증되지 않으며, 재사용 게이트가 충족되지 않으면 대신 unsure로 응답합니다.
20533	The card field is missing.	Cardholder Verification: card 객체가 제공되지 않았습니다.
20534	The card.bin field is missing.	Cardholder Verification: card.bin이 제공되지 않았습니다.
20535	The card.last4 field is missing.	Cardholder Verification: card.last4가 제공되지 않았습니다.
20536	The card data is invalid.	Cardholder Verification: 카드 데이터가 유효하지 않은 것으로 거부되었습니다.
20021	The subject.phone field is invalid.	subject.phone 형식이 유효하지 않습니다 (IDD + 지역 코드 + 번호, 13자).
20019	The subject.birthDate field is invalid.	subject.birthDate가 ISO 8601 형식 (YYYY-MM-DD) 범위를 벗어났습니다.
20009	O parâmetro imagebase64 não foi informado.	셀피 이미지 파라미터가 누락되었습니다.
20008	The subject.email field is invalid.	subject.email의 이메일 형식이 유효하지 않습니다.
20006	O parâmetro subject.name não foi informado.	subject.name 파라미터가 누락되었습니다.
20005	O parâmetro subject.code não foi informado.	subject.code 파라미터가 누락되었습니다.
20004	O parâmetro subject não foi informado.	subject 파라미터가 누락되었습니다.
20003	The request body is missing or invalid.	null이거나 유효하지 않은 페이로드입니다.
20002	O parâmetro APIKey não foi informado.	요청 헤더에 APIKEY 파라미터가 누락되었습니다.
20001	O parâmetro authtoken não foi informado.	요청 헤더에 통합 토큰 파라미터가 누락되었습니다.
10508	The JWT with the captured face has already been used.	JWT는 한 번만 사용할 수 있습니다.
10507	The JWT with the captured face is expired.	JWT가 만료되었습니다; 10분 이내에 전송해야 합니다.
10506	The imageBase64 field is not a valid JWT from SDK.	imageBase64가 SDK에서 생성된 유효한 JWT가 아닙니다.

403 Forbidden

Bearer 토큰 또는 APIKEY가 누락되었거나, 만료되었거나, 유효하지 않습니다. 인증을 참조하세요.

코드	메시지	설명
30017	User does not have permission to perform this action.	잘못된 형식의 JWT이거나 이 작업을 수행할 권한이 없는 사용자입니다.
10502	O token informado está expirado.	액세스 토큰이 만료되었습니다.
10501	O token informado é inválido.	인증 토큰이 유효하지 않습니다.
10201	O AppKey informado é inválido.	APIKEY가 유효하지 않거나 존재하지 않습니다.

409 Conflict

코드	메시지	설명
20073	The processID already exists.	제공된 processId가 이 테넌트에 이미 존재합니다.

429 Too Many Requests

속도 제한에 도달했습니다. 시스템이 HTTP 429 오류를 수신하면 연쇄 장애를 방지하고 제한을 악화시키지 않기 위한 메커니즘을 구현해야 합니다.

모범 사례:

• 쿨다운 기간 (백오프): 시스템에서 후속 요청을 즉시 중지하거나 조절하세요. 실패한 요청을 타이트한 루프에서 지속적으로 재시도하지 마세요.
• 큐잉 및 조절: 발신 요청을 버퍼링하거나 큐에 넣어 다시 보내기 전에 트래픽 흐름을 제어하세요.
• 지터를 포함한 지수 백오프: 재시도할 때 시도 간 대기 시간을 지수적으로 늘리고 (예: 1초, 2초, 4초, 8초) 작은 랜덤 지연("지터")을 추가하여 큐에 있는 모든 요청이 정확히 같은 밀리초에 재시도하는 허드 효과를 방지하세요.

경고

백오프 없이 속도 제한된 엔드포인트에 지속적으로 요청하면 제한 기간이 연장되고 시스템의 운영 처리량에 심각한 영향을 줄 수 있습니다. 요청을 적절히 조절하면 더 부드럽고 탄력적인 통합을 보장할 수 있습니다.

기본 제한, 요청 증가 및 추가 세부사항은 속도 제한을 참조하세요.

500 Internal Server Error

코드	메시지	설명
99999	Internal failure! Try again later	내부 오류가 발생했습니다.

다음 단계

• 온보딩 프로세스 결과를 조회하려면 프로세스 조회를 참조하세요.
• 모든 레시피 조합과 가능한 결과 값을 확인하려면 플로우를 참조하세요.
• 문서 및 연령 인증 작업에 대해서는 이 섹션의 해당 페이지를 참조하세요.