문서 프로세스 생성

이 엔드포인트는 동일한 경로를 공유하지만 본문 파라미터가 다른 두 가지 문서 흐름을 처리합니다:

새 캡처 — 처리를 위해 base64로 문서 이미지를 제출합니다 (document.files 필수).
재사용 — 이전에 캡처된 문서를 참조하여 캡처를 건너뜁니다 (document.documentId 필수).

활성 흐름은 요청 본문에 document.documentId가 제공되었는지 여부에 따라 결정됩니다.

문서 프로세스를 생성하기 전에 재사용 가능한 문서 조회를 사용하여 사용자가 이미 재사용 가능한 문서를 보유하고 있는지 확인하세요.

전체 통합 흐름은 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 형식 전화번호.
`document.purpose`	string	예	비즈니스 목적. 값: `creditprocess`, `carpurchase`, `paybypaycheck`, `onboarding`, `fgts`.
`document.authProcessId`	string	예	이 문서 캡처와 연결된 생체인식 프로세스의 ID.
`document.files`	array	예	base64로 인코딩된 문서 이미지 (앞면 및/또는 뒷면).
`document.files[].data`	string	예	base64로 인코딩된 문서 이미지 (PNG, JPEG 또는 WebP, 최대 800 KB).
`subsidiaryId`	string	아니오	지점 ID — 여러 지점이 있는 경우에만 필요.

필드	유형	필수	설명
`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 형식 전화번호.
`document.purpose`	string	예	비즈니스 목적. 값: `creditprocess`, `carpurchase`, `paybypaycheck`, `onboarding`, `fgts`.
`document.authProcessId`	string	예	이 문서와 연결된 생체인식 프로세스의 ID.
`document.documentId`	string	예	이전에 캡처된 문서의 ID (재사용 가능한 문서 조회에서 획득). 제공 시 `document.files`를 생략할 수 있습니다.
`subsidiaryId`	string	아니오	지점 ID — 여러 지점이 있는 경우에만 필요.

duiType 값

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

예시

새 캡처 — cURL
새 캡처 — Node.js
재사용 — cURL
재사용 — Node.js

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"
    },
    "document": {
      "purpose": "onboarding",
      "authProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
      "files": [
        { "data": "/9j/4AAQSkZJR..." }
      ]
    }
  }'

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'
    },
    document: {
      purpose: 'onboarding',
      authProcessId: '80371b2a-3ac7-432e-866d-57fe37896ac6',
      files: [{ data: documentImageBase64 }]
    }
  })
});

const result = await res.json();

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"
    },
    "document": {
      "purpose": "onboarding",
      "authProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
      "documentId": "doc-abc-123"
    }
  }'

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'
    },
    document: {
      purpose: 'onboarding',
      authProcessId: '80371b2a-3ac7-432e-866d-57fe37896ac6',
      documentId: 'doc-abc-123'
    }
  })
});

const result = await res.json();

응답

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "document": {
    "id": "doc-abc-123",
    "type": "unico.moja.dictionary.br.cnh.v2.Cnh",
    "cpfMatch": true,
    "faceMatch": true,
    "content": {
      "numero": "12345678",
      "nomeCivil": "Luke Skywalker",
      "dataNascimento": "2000-05-20T00:00:00Z",
      "categoria": "B",
      "dataExpiracao": "2030-05-20T00:00:00Z"
    },
    "fileUrls": [
      "https://storage.unico.app/documents/doc-abc-123/front.jpg"
    ]
  }
}

필드	유형	설명
`id`	string (UUID)	프로세스 식별자.
`status`	integer	`3` (성공적으로 완료), `5` (실패로 완료).
`document.id`	string	캡처된 문서 식별자. 재사용을 위해 향후 `document.documentId` 요청에서 이 값을 사용하세요.
`document.type`	string	식별된 문서 유형으로, 정규화된 전체 dictionary 이름 형식입니다. 아래의 `document.type` 값을 참조하세요.
`document.cpfMatch`	boolean	문서에서 추출된 식별자가 `subject.code`와 일치하면 `true`.
`document.faceMatch`	boolean	문서의 얼굴이 `document.authProcessId`의 생체인식 셀피와 일치하면 `true`.
`document.content`	object	OCR로 추출된 필드. 구조는 문서 유형에 따라 다릅니다 — 필드 상세 정보는 여기를 클릭하세요.
`document.fileUrls`	array	문서 이미지 다운로드를 위한 임시 URL (10분 유효).

성공적으로 추출된 필드만 document.content에 포함됩니다. OCR이 읽을 수 없었던 항목은 빈 값으로 반환되지 않고 생략됩니다.

document.type 값

통합 스키마

통합 스키마를 사용하는 모든 문서 유형(필드 참조의 unified_schema)은 document.type에 unico.moja.dictionary.<country>.generic.v1.<DocumentType> 형식으로 반환됩니다. 여기서 <country>는 소문자 ISO 3166-1 alpha-2 코드이고 <DocumentType>는 식별된 유형입니다. 예를 들어:

unico.moja.dictionary.ar.generic.v1.IdCard: 아르헨티나 신분증
unico.moja.dictionary.us.generic.v1.PolycarbonatePassport: 미국 폴리카보네이트 여권

개별 스키마

고유한 필드 스키마를 사용하는 문서 유형(필드 참조의 specific_document_schemas에 나열됨)은 아래 표에 정리되어 있습니다:

국가	값	문서
BR	`unico.moja.dictionary.br.rg.v2.Rg`	RG
BR	`unico.moja.dictionary.br.cnh.v2.Cnh`	CNH (운전면허증)
BR	`unico.moja.dictionary.br.cin.v1.Cin`	CIN
BR	`unico.moja.dictionary.br.passaporte.v1.Passaporte`	여권
MX	`unico.moja.dictionary.mx.ine.v1.Ine`	INE 유권자 증명서
MX	`unico.moja.dictionary.mx.lpc.v1.Lpc`	Licencia para conducir (운전면허증)
MX	`unico.moja.dictionary.mx.pasaporte.v1.Pasaporte`	여권
—	`unico.moja.dictionary.other.unknown.v1.Unknown`	유형을 식별할 수 없음 — `document.content`가 비어 있습니다

document.type이 unico.moja.dictionary.other.unknown.v1.Unknown인 경우 OCR 추출이 수행되지 않고 어떤 필드도 반환되지 않습니다.

오류 코드

400 Bad Request
403 Forbidden
409 Conflict
500 Internal Server Error

코드	메시지	설명
`99989`	The document is invalid.	`document` 객체의 구조가 유효하지 않습니다.
`99988`	The document is empty.	요청 본문에 `document` 객체가 누락되었습니다.
`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.	업로드된 이미지의 해상도가 너무 낮습니다.
`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.	비표준이거나 존재하지 않는 식별자 값.
`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 형식이 유효하지 않거나 지원되지 않습니다.
`20068`	The document.documentId or document.files parameter must be present.	`document.documentId`와 `document.files` 모두 제공되지 않았습니다.
`20067`	The document.purpose parameter is invalid.	`document.purpose`의 값을 인식할 수 없습니다.
`20066`	The document.authProcessId parameter is invalid.	`document.authProcessId`의 값이 유효하지 않습니다.
`20062`	The useCase field is invalid.	`useCase` 필드의 값을 인식할 수 없습니다.
`20021`	The subject.phone field is invalid.	`subject.phone` 형식이 유효하지 않습니다 (국가 코드 + 지역 코드 + 번호, 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`의 이메일 형식이 유효하지 않습니다.
`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가 아닙니다.

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가 유효하지 않거나 존재하지 않습니다.

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

코드	메시지	설명
`99999`	Internal failure! Try again later	내부 오류가 발생한 경우.

다음 단계

이 호출 전에 문서가 이미 사용 가능한지 확인하려면 재사용 가능한 문서 조회를 참조하세요.
생체인식 프로세스 생성 (document.authProcessId에 필요)은 프로세스 생성을 참조하세요.

엔드포인트​

요청​

예시​

응답​

오류 코드​

다음 단계​

엔드포인트

요청

예시

응답

오류 코드

다음 단계