메인 콘텐츠로 건너뛰기
POST
cURL

인증

x-api-key
string
header
필수

Business Console의 Developers -> API keys에서 발급받은 귀하 애플리케이션의 API 키입니다. 기본 키는 전체 접근 권한을 갖습니다. 이름이 지정된 키는 리소스별 none, read, write 범위로 권한을 제한할 수 있으며 특정 워크플로나 승인된 세션, IP 주소 목록, 만료일 등으로 제한할 수도 있습니다. 401은 키가 잘못되었거나 폐기되었거나 만료되었음을 의미합니다. 403은 키가 전송되지 않았거나, 키에 해당 리소스나 작업에 대한 접근 권한이 없거나, 요청이 허용된 IP 목록 외부 주소에서 발생했음을 의미합니다. 세션 경로에서의 404는 해당 세션이 키의 허용 워크플로 또는 상태 범위를 벗어났음을 의미합니다. 미디어 접근 권한이 없는 키는 이미지, 비디오, PDF URL을 null로 수신하며, 세션 write 권한이 없는 키는 세션 링크와 token을 null로 수신합니다. https://docs.didit.me/console/api-keys 를 참고하십시오.

본문

multipart/form-data
document
file
필수

주소 증명 문서입니다. 허용되는 확장자: tiff, jpg, jpeg, png, pdf, webp. 최대 업로드 크기: 15 MB(더 큰 파일은 400으로 거부됨). 다중 페이지 PDF가 지원됩니다(대기 시간이 늘어날 수 있음). 암호화된 PDF는 document_password가 필요합니다. 이미지는 처리 전에 자동으로 압축됩니다.

document_password
string
write-only

document가 암호화된 PDF인 경우 복호화하기 위한 비밀번호입니다. 비밀번호 없이(또는 잘못된 비밀번호로) 암호화된 PDF를 전송하면 400이 반환됩니다.

expected_address
string

문서와 대조하여 확인할 주소입니다. 지오코딩되어 추출된 주소와 비교됩니다. 불일치하는 경우(또는 제공된 주소를 지오코딩/검증할 수 없는 경우) poa_address_mismatch_action에 따라 ADDRESS_MISMATCH_WITH_PROVIDED가 추가됩니다. 지오코딩된 형태는 expected_details_formatted_address / expected_details_parsed_address로 다시 반환됩니다.

예시:

"Av. Monseñor Tavella 1291, Salta, Argentina"

expected_country
string

문서와 대조하여 검증할 국가(ISO 3166-1 코드, 예: ARG 또는 AR). 문서의 국가와 일치하지 않으면 POA_COUNTRY_MISMATCH_WITH_PROVIDED가 추가되며, poa_address_mismatch_action의 적용을 받습니다.

예시:

"ARG"

expected_first_name
string

name_on_document와 대조하여 검증할 이름입니다(퍼지 일치, 음차 인식). 일치 임계값보다 낮은 점수는 NAME_MISMATCH_WITH_PROVIDED를 추가하며, 이는 poa_address_mismatch_action의 제어를 받습니다.

예시:

"Sophia"

expected_last_name
string

name_on_document와 대조하여 확인할 성으로, 일치 점수 산정을 위해 expected_first_name과 결합됩니다.

예시:

"Martinez"

poa_languages_allowed
string

ISO 639-1 코드로 지정된 수락 가능한 문서 언어의 쉼표로 구분된 목록(예: en,es,fr). 생략하거나 비워 두면 지원되는 51개 언어 모두가 수락됩니다. 목록 외의 언어로 작성된 문서는 UNSUPPORTED_DOCUMENT_LANGUAGE를 추가하며(poa_unsupported_language_action에 의해 관리됨), 목록에 알 수 없는 코드가 포함되어 있으면 지원되는 전체 코드 세트와 함께 400을 반환합니다.

예시:

"en,es"

poa_document_age_months
string

문서 유형별 최대 문서 사용 기간(개월)을 설정하는 쉼표로 구분된 key:value 쌍 — 키: utility_bill, bank_statement, government_issued_document, other_poa_document, 값: 1–120 또는 무제한(문서 연령 확인 안 함)을 나타내는 -1. 생략 시 기본값: utility_bill:3,bank_statement:3,government_issued_document:12,other_poa_document:12. 제한보다 오래된 문서는 POA_DOCUMENT_EXPIRED로 거부됩니다. 주의: 이 필드를 제공할 때는 수락할 모든 유형을 나열해야 합니다. 생략된 유형은 수락되지 않은 것으로 처리되며(정보성 POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION), 문서 연령 확인을 건너뜁니다.

예시:

"utility_bill:3,bank_statement:6"

poa_name_mismatch_action
enum<string>
기본값:DECLINE

허용되지만 현재 적용되지 않음 — 이름 불일치 경고(NAME_MISMATCH_WITH_PROVIDED)는 대신 poa_address_mismatch_action을 따릅니다. 이름과 주소 불일치 동작을 모두 제어하려면 poa_address_mismatch_action을 설정하십시오.

사용 가능한 옵션:
DECLINE,
NO_ACTION
poa_document_issues_action
enum<string>
기본값:DECLINE

파일 무결성 문제 발생 시 수행할 작업입니다. 실제로는 이 endpoint에서 DOCUMENT_METADATA_MISMATCH만 생성됩니다.

사용 가능한 옵션:
DECLINE,
NO_ACTION
poa_document_authenticity_action
enum<string>
기본값:DECLINE

문서 위변조가 의심될 때(SUSPECTED_DOCUMENT_MANIPULATION) 수행할 작업입니다(예: 전자 서명 후 PDF 수정, 알려진 PDF 편집기로 처리됨, 오버레이 텍스트 조작 확인, 일치하지 않는 EXIF 날짜 등). POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT(파일상에서 변경 여부를 입증할 수 없는 다시 입력된 텍스트 필드)에도 적용되며, DECLINE은 이 또한 거부하고 NO_ACTION은 경고로 유지합니다.

사용 가능한 옵션:
DECLINE,
NO_ACTION
poa_unsupported_language_action
enum<string>
기본값:DECLINE

문서 언어가 poa_languages_allowed에 속하지 않을 때 수행할 작업입니다 (UNSUPPORTED_DOCUMENT_LANGUAGE).

사용 가능한 옵션:
DECLINE,
NO_ACTION
poa_address_mismatch_action
enum<string>
기본값:DECLINE

추출된 세부 정보가 expected_* 필드와 일치하지 않을 때 수행할 작업입니다. ADDRESS_MISMATCH_WITH_PROVIDED, NAME_MISMATCH_WITH_PROVIDED, POA_COUNTRY_MISMATCH_WITH_PROVIDED 모두 이 작업을 따릅니다.

사용 가능한 옵션:
DECLINE,
NO_ACTION
poa_issuer_not_identified_action
enum<string>
기본값:DECLINE

문서에서 발급 회사/조직을 식별할 수 없을 때(ISSUER_NOT_IDENTIFIED) 수행할 작업입니다.

사용 가능한 옵션:
DECLINE,
NO_ACTION
save_api_request
boolean
기본값:true

true(기본값)인 경우 호출을 API 유형 세션으로 저장합니다. Business Console에서 확인할 수 있고 반환된 request_id를 사용하여 GET /v3/session/{sessionId}/decision/을 통해 조회할 수 있으며 status.updated webhook을 통해 알림이 전송되고 업로드된 문서가 저장됩니다. false인 경우 아무것도 저장되지 않으며 request_id는 응답 상관관계 식별 전용의 일시적인 UUID입니다.

예시:

true

vendor_data
string

저장된 세션에 저장되고 응답에 다시 반환되는 선택적 불투명 문자열(내부 사용자 ID, 이메일, UUID 등)입니다. API 호출을 자체 기록과 연관 짓고 나중에 세션을 필터링하는 데 사용합니다.

예시:

"user-123"

metadata
object

세션과 함께 저장되고(save_api_request=true인 경우) 응답에 그대로 반환되는 선택적 JSON 객체입니다. multipart 요청에서는 JSON 인코딩된 문자열 필드(예: metadata={"flow":"onboarding"})로 전송하십시오. 객체로 파싱됩니다.

예시:

응답

문서가 처리되었습니다. poa.status는 Approved 또는 Declined입니다. 감지된 모든 문제는 poa.warnings에 항목별로 나열됩니다. 만료되었거나 불일치하거나 의심스러운 문서라도 status: "Declined"와 함께 200을 반환하므로 HTTP 코드뿐만 아니라 본문도 확인해야 합니다. save_api_request=true인 경우 request_id는 저장된 세션 ID입니다.

request_id
string<uuid>

save_api_request=true일 때 유지된 세션 ID(GET /v3/session/{sessionId}/decision/와 함께 사용 가능), 그렇지 않으면 임시 상관관계 UUID입니다.

poa
object
vendor_data
string | null

전송한 vendor_data의 에코 값 또는 null입니다.

metadata
object | null

전송한 metadata 객체의 에코 값 또는 null입니다.

created_at
string<date-time>

응답이 생성된 시점의 ISO 8601 타임스탬프(UTC)입니다.

마지막 수정일 2026년 11월 7일