--- title: 문서 프로세스 생성 description: 새 문서를 캡처하거나 생체인식 프로세스와 연결된 이전에 캡처된 문서를 재사용합니다. canonical: https://developer.unico.io/ko/dual-api/developers/api-reference/api/post-processes-document locale: ko generated_by: markdown-export --- - [/ko/](/ko/) - [API 레퍼런스](/ko/dual-api/developers/api-reference/) - [API](/ko/dual-api/developers/api-reference/api/) - 문서 프로세스 생성 **이 페이지에서# 문서 프로세스 생성 이 엔드포인트는 동일한 경로를 공유하지만 본문 파라미터가 다른 두 가지 문서 흐름을 처리합니다: **새 캡처** — 처리를 위해 base64로 문서 이미지를 제출합니다 (`document.files` 필수). **재사용** — 이전에 캡처된 문서를 참조하여 캡처를 건너뜁니다 (`document.documentId` 필수). 활성 흐름은 요청 본문에 `document.documentId`가 제공되었는지 여부에 따라 결정됩니다. 문서 프로세스를 생성하기 전에 [재사용 가능한 문서 조회](/ko/dual-api/developers/api-reference/api/get-document)를 사용하여 사용자가 이미 재사용 가능한 문서를 보유하고 있는지 확인하세요. 전체 통합 흐름은 [API 개요](/ko/dual-api/developers/api-reference/api/)를 참조하세요. ### 엔드포인트​ 환경URL**프로덕션**`POST https://api.id.unico.app/processes/v1`**샌드박스**`POST https://api.id.uat.unico.app/processes/v1` ### 요청​ 헤더 헤더값`Authorization``Bearer ` ([인증](/ko/dual-api/developers/api-reference/authentication) 참조)`APIKEY`문서 캡처 및 재사용이 활성화된 프로비저닝된 API 키.`Content-Type``application/json` 본문 파라미터 새 캡처재사용필드유형필수설명`subject.duiType`integer예문서 유형 식별자. 아래 [`duiType` 값](#duitype-values)을 참조하세요.`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` 값](#duitype-values)을 참조하세요.`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 ([재사용 가능한 문서 조회](/ko/dual-api/developers/api-reference/api/get-document)에서 획득). 제공 시 `document.files`를 생략할 수 있습니다.`subsidiaryId`string아니오지점 ID — 여러 지점이 있는 경우에만 필요. **`duiType` 값**국가코드설명AR6아르헨티나 여권AR7아르헨티나 DNIAR49아르헨티나 운전면허증(Licencia Nacional de Conducir)AT34오스트리아 세금 번호(STNR)BE36벨기에 국민 번호(NN)BR1브라질 CPFBR5브라질 여권BR14브라질 CNPJCA28캐나다 SINCH33스위스 AHV/AVS 번호CL9칠레 RUNCL52칠레 여권CL57칠레 운전면허증(Licencia de Conducir)CO26콜롬비아 NITCO53콜롬비아 여권CO55콜롬비아 운전면허증(Licencia de Conducción)CO56콜롬비아 시민증(Cédula de Ciudadanía)DE41독일 세금 식별 번호(IdNr)DK29덴마크 CPREC10에콰도르 NIES50스페인 외국인 신분 번호(NIE)ES51스페인 국민 신분증(DNI)FI35핀란드 개인 식별 코드(HETU)FR46프랑스 세금 참조 번호(SPI)GB30영국 국민보험번호(NINO)GT12과테말라 CUIID16인도네시아 NIKIE47아일랜드 개인 공공 서비스 번호(PPSN)IT37이탈리아 세금 코드(Codice Fiscale, CF)LU48룩셈부르크 국민 식별 번호(Matricule)MX2멕시코 CURPMX25멕시코 RFC(개인)MX58멕시코 운전면허증(Licencia de Conducir)NG8나이지리아 NINNG20나이지리아 은행 확인 번호(BVN)NG43나이지리아 BVN 토큰(해시)NG44나이지리아 NIN 토큰(해시)NL42네덜란드 시민 서비스 번호(BSN)NO39노르웨이 국민 식별 번호(Fødselsnummer)PE27페루 RUCPE40페루 DNIPE54페루 여권PL31폴란드 PESELPT45포르투갈 세금 식별 번호(NIF)SE32스웨덴 개인번호(PNR)SE38스웨덴 조정 번호(Samordningsnummer)TR24튀르키예 신분증 번호(TCKN)US4미국 SSNUS11미국 여권US18미국 운전면허증US21미국 여권 카드US22미국 폴리카보네이트 여권US23미국 신분증UY13우루과이 CIZZ15이메일 주소ZZ17전화번호—0미지정—3Unico 내부 식별자 ### 예시​ 새 캡처 — 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-type-values)을 참조하세요.`document.cpfMatch`boolean문서에서 추출된 식별자가 `subject.code`와 일치하면 `true`.`document.faceMatch`boolean문서의 얼굴이 `document.authProcessId`의 생체인식 셀피와 일치하면 `true`.`document.content`objectOCR로 추출된 필드. 구조는 문서 유형에 따라 다릅니다 — [필드 상세 정보는 여기를 클릭하세요](/ko/assets/files/document-content-fields-0e4663f2ade946e901bbc7523c21f032.json).`document.fileUrls`array문서 이미지 다운로드를 위한 임시 URL (10분 유효). 성공적으로 추출된 필드만 `document.content`에 포함됩니다. OCR이 읽을 수 없었던 항목은 빈 값으로 반환되지 않고 생략됩니다. **`document.type` 값**통합 스키마통합 스키마를 사용하는 모든 문서 유형([필드 참조](/ko/assets/files/document-content-fields-0e4663f2ade946e901bbc7523c21f032.json)의 `unified_schema`)은 `document.type`에 `unico.moja.dictionary..generic.v1.` 형식으로 반환됩니다. 여기서 ``는 소문자 ISO 3166-1 alpha-2 코드이고 ``는 식별된 유형입니다. 예를 들어: `unico.moja.dictionary.ar.generic.v1.IdCard`: 아르헨티나 신분증 `unico.moja.dictionary.us.generic.v1.PolycarbonatePassport`: 미국 폴리카보네이트 여권 개별 스키마고유한 필드 스키마를 사용하는 문서 유형([필드 참조](/ko/assets/files/document-content-fields-0e4663f2ade946e901bbc7523c21f032.json)의 `specific_document_schemas`에 나열됨)은 아래 표에 정리되어 있습니다:국가값문서BR`unico.moja.dictionary.br.rg.v2.Rg`RGBR`unico.moja.dictionary.br.cnh.v2.Cnh`CNH (운전면허증)BR`unico.moja.dictionary.br.cin.v1.Cin`CINBR`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 Request403 Forbidden409 Conflict500 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`가 누락되었거나 만료되었거나 유효하지 않습니다. [인증](/ko/dual-api/developers/api-reference/authentication)을 참조하세요.코드메시지설명`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내부 오류가 발생한 경우. ### 다음 단계​ 이 호출 전에 문서가 이미 사용 가능한지 확인하려면 [재사용 가능한 문서 조회](/ko/dual-api/developers/api-reference/api/get-document)를 참조하세요. 생체인식 프로세스 생성 (`document.authProcessId`에 필요)은 [프로세스 생성](/ko/dual-api/developers/api-reference/api/post-processes)을 참조하세요. 마지막 업데이트 2026년 10월 8일**에