재사용 가능한 문서 조회

Markdown ChatGPT Claude

이 엔드포인트를 사용하여 새로운 Document 캡처 플로우를 시작하기 전에 사용자가 이미 재사용 가능한 문서를 가지고 있는지 확인하세요. 문서가 발견되면 해당 documentId를 POST /processes/v1(Document 유형)에 직접 전달하여 캡처 단계를 건너뛸 수 있습니다.

Endpoint

환경	URL
프로덕션	`GET https://api.idcloud.unico.app/documents/v1`
샌드박스	`GET https://api.idcloud.uat.unico.app/documents/v1`

요청

헤더

헤더	값
`Authorization`	`Bearer <access_token>` (인증 참조)
`APIKEY`	Document Capture and Reuse가 활성화된 프로비저닝된 API 키.

쿼리 매개변수

매개변수	유형	필수	설명
`code`	string	예	사용자 식별자(CPF 또는 CURP, 형식 없이).
`type`	string	예	조회할 문서 유형입니다. 허용되는 값: `BR_RG`, `BR_CNH`, `BR_CIN`, `BR_PASSPORT`.

참고

위의 type 값은 이 엔드포인트에만 해당됩니다. 다음과 혼동하지 마세요:

POST 요청의 subject.duiType — DUI_TYPE_* 접두사를 사용하며 문서 유형이 아니라 사람을 식별합니다(예: DUI_TYPE_BR_CPF).
응답의 documentType — 전체 레지스트리 경로를 사용합니다(예: unico.moja.dictionary.br.cnh.v2.Cnh).

예제

cURL
Node.js

curl -X GET "https://api.idcloud.unico.app/documents/v1?code=12345678909&type=BR_CNH" \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY"

import fetch from 'node-fetch';

const params = new URLSearchParams({ code: '12345678909', type: 'BR_CNH' });
const res = await fetch(
  `https://api.idcloud.unico.app/documents/v1?${params}`,
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      APIKEY: apiKey
    }
  }
);
const data = await res.json();
// data.items[0].documentId → 재사용을 위해 POST /processes/v1에 전달

응답

200 OK

{
  "items": [
    {
      "documentType": "unico.moja.dictionary.br.cnh.v2.Cnh",
      "documentId": "doc-abc-123"
    }
  ]
}

필드	유형	설명
`items`	array	사용자에 대해 발견된 재사용 가능한 문서 목록입니다. 지정된 `code`와 `type`에 대해 재사용 가능한 문서가 없으면 빈 배열입니다.
`items[].documentType`	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`.
`items[].documentId`	string	문서 식별자입니다. 문서를 재사용하려면 `POST /processes/v1`의 `document.documentId`에 이 값을 전달하세요.

documentId를 재사용에 사용하기

documentId를 확보하면, 캡처를 건너뛰기 위해 이를 Document 프로세스 요청에 전달하세요:

{
  "subject": {
    "code": "12345678909",
    "name": "Luke Skywalker"
  },
  "document": {
    "purpose": "onboarding",
    "authProcessId": "<biometric-process-id>",
    "documentId": "doc-abc-123"
  }
}

필드	설명
`document.purpose`	이 문서 프로세스의 비즈니스 목적입니다. 허용되는 값: `creditprocess`, `carpurchase`, `paybypaycheck`, `onboarding`, `fgts`. 이 값들은 Document API에 특화된 것으로, 생체 인식 SDK의 `purpose` 열거형과 다릅니다.
`document.authProcessId`	이 사용자에 대해 이전에 생성된 생체 인식 프로세스의 ID입니다(`POST /processes/v1`에서 발급됨).
`document.documentId`	이 엔드포인트의 응답에서 얻은 문서 ID입니다. 이 값이 제공되면 `document.files`는 생략할 수 있습니다 — 플랫폼이 이전에 캡처된 문서를 자동으로 조회합니다.

오류 코드

400 Bad Request
403 Forbidden
404 Not Found
429 Too Many Requests
500 Internal Server Error

코드	메시지	설명
`20507`	O parâmetro subject.code é inválido.	식별자 값(CPF 또는 CURP)의 형식이 잘못되었거나 존재하지 않습니다.
`20002`	O parâmetro APIKey não foi informado.	APIKEY 헤더가 누락되었습니다.
`20001`	O parâmetro authtoken não foi informado.	인증 토큰 헤더가 누락되었습니다.

Bearer 토큰 또는 APIKEY가 누락, 만료, 또는 유효하지 않습니다.

코드	메시지	설명
`30020`	The provided authorization token does not have permission to perform this action.	토큰에 문서 셀피에 접근할 권한이 없습니다.
`30017`	User does not have permission to perform this action.	JWT 형식이 잘못되었거나 사용자에게 이 작업을 수행할 권한이 없습니다.
`10502`	O token informado está expirado.	Access token이 만료되었습니다.
`10501`	O token informado é inválido.	인증 토큰이 유효하지 않습니다.
`10201`	O AppKey informado é inválido.	APIKEY가 누락되었거나 존재하지 않습니다.

코드	메시지	설명
`99987`	Attachment not found.	문서에 연결된 첨부 파일을 찾을 수 없습니다.
`50001`	The process is not found.	지정된 매개변수에 대한 문서를 찾을 수 없습니다.

코드	메시지	설명
`99999`	Internal failure! Try again later.	서버 측 처리 오류입니다.

Endpoint​

요청​

예제​

응답​

documentId를 재사용에 사용하기​

오류 코드​

Endpoint

요청

예제

응답

documentId를 재사용에 사용하기

오류 코드