문서 프로세스 생성

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

새 캡처 — 처리를 위해 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
BR	5	브라질 여권
MX	2	멕시코 CURP
AR	6	아르헨티나 여권
AR	7	아르헨티나 DNI
US	4	미국 SSN
US	11	미국 여권
US	18	미국 운전면허증
ID	16	인도네시아 NIK
NG	8	나이지리아 NIN
CL	9	칠레 RUN
EC	10	에콰도르 NI
GT	12	과테말라 CUI
UY	13	우루과이 CI
ZZ	15	이메일 주소
ZZ	17	전화번호
MX	25	멕시코 RFC(개인)
CO	26	콜롬비아 NIT
PE	27	페루 RUC
CA	28	캐나다 SIN
DK	29	덴마크 CPR
GB	30	영국 국민보험번호(NINO)
PL	31	폴란드 PESEL
SE	32	스웨덴 개인번호(PNR)
AT	34	오스트리아 세금 번호(STNR)
FI	35	핀란드 개인 식별 코드(HETU)
—	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	식별된 문서 유형. 가능한 값: `unico.moja.dictionary.br.rg.v2.Rg`, `unico.moja.dictionary.br.cnh.v2.Cnh`, `unico.moja.dictionary.br.cin.v1.Cin`, `unico.moja.dictionary.br.passaporte.v1.Passaporte`.
`document.cpfMatch`	boolean	문서에서 추출된 식별자가 `subject.code`와 일치하면 `true`.
`document.faceMatch`	boolean	문서의 얼굴이 `document.authProcessId`의 생체인식 셀피와 일치하면 `true`.
`document.content`	object	OCR로 추출된 필드. 구조는 문서 유형에 따라 다릅니다.
`document.fileUrls`	array	문서 이미지 다운로드를 위한 임시 URL (10분 유효).

400 Bad Request

페이로드가 잘못된 형식이거나, 이미지가 유효하지 않거나, 필수 필드가 누락되었습니다. 아래 오류 코드를 참조하세요.

403 Forbidden

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

409 Conflict

이 테넌트에 이미 제공된 processId가 존재합니다. 아래 오류 코드를 참조하세요.

오류 코드

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가 아닙니다.

코드	메시지	설명
`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에 필요)은 프로세스 생성을 참조하세요.

엔드포인트​

요청​

예시​

응답​

오류 코드​

다음 단계​

엔드포인트

요청

예시

응답

오류 코드

다음 단계