> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # 주소 증명 API: POA 인증 및 OCR > POST /v3/poa/로 공과금 고지서, 은행 거래내역서, 임대차 계약서를 인증하세요. OCR 주소 추출, 진위 확인, 사용량 기반 요금, 계약 불필요. Didit 제공. ## OpenAPI ````yaml ko/openapi-25.json POST /v3/poa/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: 신분증 인증 API입니다. x-api-key 헤더로 인증합니다. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/poa/: post: tags: - Standalone APIs summary: 주소 증명(문서 OCR + 주소 확인) description: >- 단 한 번의 호출로 공과금 고지서, 은행 거래 내역서, 정부 발급 문서 등 주소 증명 문서를 추출하고 검증합니다. 발급 기관, 발급일/만료일, 소유자 성명, 원본 및 파싱/지오코딩된 주소, `Approved`/`Declined` `status`, 발견된 모든 문제를 설명하는 `warnings` 목록을 반환합니다. **지연 시간.** 추출은 LLM을 기반으로 작동합니다. 일반적인 호출은 **5–15초**, 여러 페이지로 구성된 PDF는 최대 **약 30초**가 소요됩니다. 클라이언트 타임아웃을 **최소 45초**로 구성하고 호출이 완료되기 전에 재시도하지 마세요. **작동 방식.** 문서(이미지 또는 PDF, 최대 15 MB, 암호화된 PDF는 `document_password` 필요)는 문서 유형 및 하위 유형(예: `UTILITY_BILL` / `WATER_BILL`)으로 분류되며, LLM 기반 추출을 통해 발급 기관, 날짜, 소유자 성명, 주소가 추출됩니다. 주소는 파싱 및 지오코딩되어 `poa_parsed_address`에 반영됩니다. PDF/EXIF 포렌식을 통해 디지털 서명 후 수정, 알려진 PDF 편집기 사용, 오버레이 텍스트 조작, 의심스러운 재내보내기 등의 변조 여부를 스크리닝하여 `SUSPECTED_DOCUMENT_MANIPULATION` 또는 `DOCUMENT_METADATA_MISMATCH`를 표시합니다. 텍스트 필드가 공백 처리된 후 다른 글꼴로 다시 입력되었으나 파일 자체에는 내용 변경 여부에 대한 증거가 없는 경우 `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`가 표시됩니다. 문서 발행 기간은 `poa_document_age_months`를 기준으로 검증되며, 언어는 `poa_languages_allowed`를 기준으로 검증됩니다. `expected_address`, `expected_country` 또는 `expected_first_name`/`expected_last_name`을 전달하면 추출된 값과 교차 확인하여 불일치를 표시합니다. **결정 로직.** 최소 하나의 경고라도 거부로 처리되지 않는 한 `status`는 `Approved`가 됩니다. 치명적 오류(Hard failure)는 항상 거부됩니다: `MISSING_ADDRESS_INFORMATION`, `POA_DOCUMENT_EXPIRED`, `INVALID_DOCUMENT_TYPE`, `UNABLE_TO_VALIDATE_DOCUMENT_AGE`, 그리고 `UNABLE_TO_EXTRACT_ISSUE_DATE` 및 `POA_NAME_NOT_DETECTED`(이 endpoint에서는 구성할 수 없음). 5가지 위험 그룹은 `poa_*_action` 옵션(`DECLINE` 또는 `NO_ACTION`, 모두 기본값은 `DECLINE`)을 통해 요청별로 구성할 수 있습니다. `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` 및 `UNPARSABLE_OR_INVALID_ADDRESS`는 이 endpoint에서 정보 제공용이며 절대 거부되지 않습니다. 전혀 처리할 수 없는 문서는 `400`을 반환하고, 읽을 수는 있지만 문제가 있는 문서는 `200`과 함께 `status: "Declined"`를 반환합니다. 따라서 HTTP 코드뿐만 아니라 항상 `poa.status`와 `poa.warnings`를 확인하세요. **결제.** `200` 응답마다 주소 증명 API 크레딧이 1개씩 차감됩니다(요금제 크레딧 또는 충전 잔액에서 차감). 조직의 잔액이 호출 비용을 충당할 수 없는 경우, endpoint는 문서 처리를 시작하기 전에 크레딧 부족 오류와 함께 `403`을 반환합니다. **세션 유지(`save_api_request`, 기본값 `true`).** `true`인 경우 호출은 API 유형 세션으로 영구 보관됩니다. Business Console에 표시되고, 업로드된 문서가 저장되며, 반환된 `request_id`는 `GET /v3/session/{sessionId}/decision/`에 전달할 수 있는 실제 세션 id가 되고(결정에는 이 응답에서 생략된 `document_file` 및 `document_metadata` 포렌식이 추가로 표시됨), `status.updated` webhook이 발송됩니다. `false`인 경우 아무것도 저장되지 않으며 `request_id`는 나중에 조회할 수 없는 일회성 상관관계 UUID가 됩니다. **샌드박스.** 샌드박스 API 키는 모든 처리 및 결제를 건너뜁니다. 요청 유효성 검사 후(잘못된 형식의 입력은 여전히 `400`을 반환함), endpoint는 정적 `Approved` 모의 payload(가상의 "Sandbox Power Co." 전기 요금 고지서)를 반환하며, 세션이 저장되지 않고 크레딧도 차감되지 않습니다. **인증.** 애플리케이션의 API 키를 `x-api-key` 헤더에 담아 전송하세요. 자격 증명이 누락되었거나 유효하지 않으면 `403`(`{"detail": "You do not have permission to perform this action."}`)을 반환합니다. 이 API는 절대 `401`을 반환하지 않습니다. **속도 제한.** 모든 POST/PATCH/DELETE endpoint에 걸쳐 API 키당 분당 300건의 공유 쓰기 요청 한도가 적용되며, 초과 시 `429`가 반환됩니다. 참고: `FUTURE_ISSUE_DATE` 및 `POOR_DOCUMENT_QUALITY`는 워크플로 세션에 존재하지만 이 독립 실행형 endpoint에서는 생성되지 않습니다. 미래 날짜가 지정된 문서는 여기에서 자동으로 거부되지 않습니다. operationId: post_v3poa parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - document properties: document: type: string format: binary description: >- 주소 증명 문서입니다. 허용되는 확장자: `tiff`, `jpg`, `jpeg`, `png`, `pdf`, `webp`. 최대 업로드 크기: **15 MB**(더 큰 파일은 `400`으로 거부됨). 다중 페이지 PDF가 지원됩니다(대기 시간이 늘어날 수 있음). 암호화된 PDF는 `document_password`가 필요합니다. 이미지는 처리 전에 자동으로 압축됩니다. document_password: type: string description: >- `document`가 암호화된 PDF인 경우 복호화하기 위한 비밀번호입니다. 비밀번호 없이(또는 잘못된 비밀번호로) 암호화된 PDF를 전송하면 `400`이 반환됩니다. writeOnly: true expected_address: type: string description: >- 문서와 대조하여 확인할 주소입니다. 지오코딩되어 추출된 주소와 비교됩니다. 불일치하는 경우(또는 제공된 주소를 지오코딩/검증할 수 없는 경우) `poa_address_mismatch_action`에 따라 `ADDRESS_MISMATCH_WITH_PROVIDED`가 추가됩니다. 지오코딩된 형태는 `expected_details_formatted_address` / `expected_details_parsed_address`로 다시 반환됩니다. example: Av. Monseñor Tavella 1291, Salta, Argentina expected_country: type: string description: >- 문서와 대조하여 검증할 국가(ISO 3166-1 코드, 예: `ARG` 또는 `AR`). 문서의 국가와 일치하지 않으면 `POA_COUNTRY_MISMATCH_WITH_PROVIDED`가 추가되며, `poa_address_mismatch_action`의 적용을 받습니다. example: ARG expected_first_name: type: string description: >- `name_on_document`와 대조하여 검증할 이름입니다(퍼지 일치, 음차 인식). 일치 임계값보다 낮은 점수는 `NAME_MISMATCH_WITH_PROVIDED`를 추가하며, 이는 `poa_address_mismatch_action`의 제어를 받습니다. example: Sophia expected_last_name: type: string description: >- `name_on_document`와 대조하여 확인할 성으로, 일치 점수 산정을 위해 `expected_first_name`과 결합됩니다. example: Martinez poa_languages_allowed: type: string description: >- ISO 639-1 코드로 지정된 수락 가능한 문서 언어의 쉼표로 구분된 목록(예: `en,es,fr`). 생략하거나 비워 두면 **지원되는 51개 언어 모두**가 수락됩니다. 목록 외의 언어로 작성된 문서는 `UNSUPPORTED_DOCUMENT_LANGUAGE`를 추가하며(`poa_unsupported_language_action`에 의해 관리됨), 목록에 알 수 없는 코드가 포함되어 있으면 지원되는 전체 코드 세트와 함께 `400`을 반환합니다. example: en,es poa_document_age_months: type: string description: >- 문서 유형별 최대 문서 사용 기간(개월)을 설정하는 쉼표로 구분된 `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`), 문서 연령 확인을 건너뜁니다. example: utility_bill:3,bank_statement:6 poa_name_mismatch_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- 허용되지만 **현재 적용되지 않음** — 이름 불일치 경고(`NAME_MISMATCH_WITH_PROVIDED`)는 대신 `poa_address_mismatch_action`을 따릅니다. 이름과 주소 불일치 동작을 모두 제어하려면 `poa_address_mismatch_action`을 설정하십시오. poa_document_issues_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- 파일 무결성 문제 발생 시 수행할 작업입니다. 실제로는 이 endpoint에서 `DOCUMENT_METADATA_MISMATCH`만 생성됩니다. poa_document_authenticity_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- 문서 위변조가 의심될 때(`SUSPECTED_DOCUMENT_MANIPULATION`) 수행할 작업입니다(예: 전자 서명 후 PDF 수정, 알려진 PDF 편집기로 처리됨, 오버레이 텍스트 조작 확인, 일치하지 않는 EXIF 날짜 등). `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`(파일상에서 변경 여부를 입증할 수 없는 다시 입력된 텍스트 필드)에도 적용되며, `DECLINE`은 이 또한 거부하고 `NO_ACTION`은 경고로 유지합니다. poa_unsupported_language_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- 문서 언어가 `poa_languages_allowed`에 속하지 않을 때 수행할 작업입니다 (`UNSUPPORTED_DOCUMENT_LANGUAGE`). poa_address_mismatch_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- 추출된 세부 정보가 `expected_*` 필드와 일치하지 않을 때 수행할 작업입니다. `ADDRESS_MISMATCH_WITH_PROVIDED`, `NAME_MISMATCH_WITH_PROVIDED`, `POA_COUNTRY_MISMATCH_WITH_PROVIDED` 모두 이 작업을 따릅니다. poa_issuer_not_identified_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- 문서에서 발급 회사/조직을 식별할 수 없을 때(`ISSUER_NOT_IDENTIFIED`) 수행할 작업입니다. save_api_request: type: boolean default: true description: >- `true`(기본값)인 경우 호출을 API 유형 세션으로 저장합니다. Business Console에서 확인할 수 있고 반환된 `request_id`를 사용하여 `GET /v3/session/{sessionId}/decision/`을 통해 조회할 수 있으며 `status.updated` webhook을 통해 알림이 전송되고 업로드된 문서가 저장됩니다. `false`인 경우 아무것도 저장되지 않으며 `request_id`는 응답 상관관계 식별 전용의 일시적인 UUID입니다. example: true vendor_data: type: string description: >- 저장된 세션에 저장되고 응답에 다시 반환되는 선택적 불투명 문자열(내부 사용자 ID, 이메일, UUID 등)입니다. API 호출을 자체 기록과 연관 짓고 나중에 세션을 필터링하는 데 사용합니다. example: user-123 metadata: type: object additionalProperties: true description: >- 세션과 함께 저장되고(`save_api_request=true`인 경우) 응답에 그대로 반환되는 선택적 JSON 객체입니다. multipart 요청에서는 JSON 인코딩된 문자열 필드(예: `metadata={"flow":"onboarding"}`)로 전송하십시오. 객체로 파싱됩니다. example: flow: onboarding example: document: (binary JPEG/PNG/PDF of the utility bill or bank statement) expected_address: Av. Monseñor Tavella 1291, Salta, Argentina expected_country: ARG expected_first_name: Sophia expected_last_name: Martinez poa_languages_allowed: en,es save_api_request: true vendor_data: user-123 responses: '200': description: >- 문서가 처리되었습니다. `poa.status`는 `Approved` 또는 `Declined`입니다. 감지된 모든 문제는 `poa.warnings`에 항목별로 나열됩니다. 만료되었거나 불일치하거나 의심스러운 문서라도 `status: "Declined"`와 함께 `200`을 반환하므로 HTTP 코드뿐만 아니라 본문도 확인해야 합니다. `save_api_request=true`인 경우 `request_id`는 저장된 세션 ID입니다. content: application/json: examples: Approved: summary: 공과금 청구서가 명확하게 판독되었으며, 예상 세부 정보 확인이 수행되지 않았습니다 value: request_id: 4b523a8d-ed32-45e4-8aa8-a89eda459d88 poa: issuing_state: ARG document_type: UTILITY_BILL document_subtype: WATER_BILL document_language: es issuer: Aguas del Norte issue_date: '2026-04-10' expiration_date: null poa_address: >- AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA poa_formatted_address: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: street_1: Avenida Monseñor Tavella 1291 street_2: b city: Salta region: Salta country: AR postal_code: A4400 document_location: latitude: -24.8208682 longitude: -65.4130954 expected_details_address: null expected_details_formatted_address: null expected_details_parsed_address: null name_on_document: OESTE EMBOTELLADORA S.A. extra_fields: bank_account_number: null bank_iban: null bank_sort_code: null bank_routing_number: null bank_swift_bic: null bank_branch_name: null bank_branch_address: null document_phone_number: null additional_names: - LA EMBOTELLADORA DEL NORTE SA detected_codes: - type: QR_CODE page_number: 1 position: - - 820 - 1120 - - 1002 - 1120 - - 1002 - 1302 - - 820 - 1302 x: 820 'y': 1120 width: 182 height: 182 page_width: 1190 page_height: 1684 raw_payload: >- aHR0cHM6Ly9hZ3Vhc2RlbG5vcnRlLmNvbS9mYWN0dXJhLzk5ODgxMQ== parsed_payload: https://aguasdelnorte.com/factura/998811 - type: CODE_128 page_number: 1 position: - - 112 - 1480 - - 560 - 1480 - - 560 - 1540 - - 112 - 1540 x: 112 'y': 1480 width: 448 height: 60 page_width: 1190 page_height: 1684 raw_payload: MDA5OTg4MTEwMDA0Mg== parsed_payload: '0099881100042' status: Approved warnings: [] vendor_data: user-123 metadata: null created_at: '2026-06-12T02:29:02.439655+00:00' Declined - document too old: summary: 허용된 `poa_document_age_months`보다 오래된 발급일 value: request_id: f61681b8-9422-4378-ac3e-04c6a247fb45 poa: issuing_state: ARG document_type: UTILITY_BILL document_subtype: WATER_BILL document_language: es issuer: Aguas del Norte issue_date: '2021-02-10' expiration_date: null poa_address: >- AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA poa_formatted_address: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: street_1: Avenida Monseñor Tavella 1291 street_2: b city: Salta region: Salta country: AR postal_code: A4400 document_location: latitude: -24.8208682 longitude: -65.4130954 expected_details_address: null expected_details_formatted_address: null expected_details_parsed_address: null name_on_document: OESTE EMBOTELLADORA S.A. extra_fields: bank_account_number: null bank_iban: null bank_sort_code: null bank_routing_number: null bank_swift_bic: null bank_branch_name: null bank_branch_address: null document_phone_number: null additional_names: - LA EMBOTELLADORA DEL NORTE SA status: Declined warnings: - risk: POA_DOCUMENT_EXPIRED feature: PROOF_OF_ADDRESS additional_data: expiration_reason: age_window max_age_months: 3 document_subtype: WATER_BILL document_type: UTILITY_BILL issue_date: '2021-02-10' log_type: error short_description: Document expired long_description: >- The submitted document is older than the maximum accepted age of 3 months from its issue date, which exceeds the acceptable time period for validity. vendor_data: user-123 metadata: null created_at: '2026-06-12T02:23:02.165493+00:00' Declined - name mismatch: summary: >- `expected_first_name`/`expected_last_name`이 `name_on_document`와 일치하지 않음 value: request_id: 0a7f2f9c-58f1-4b8e-b1e3-2f6f9d4f7a21 poa: issuing_state: ARG document_type: UTILITY_BILL document_subtype: WATER_BILL document_language: es issuer: Aguas del Norte issue_date: '2021-02-10' expiration_date: null poa_address: >- AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA poa_formatted_address: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: street_1: Avenida Monseñor Tavella 1291 street_2: b city: Salta region: Salta country: AR postal_code: A4400 document_location: latitude: -24.8208682 longitude: -65.4130954 expected_details_address: null expected_details_formatted_address: null expected_details_parsed_address: null name_on_document: OESTE EMBOTELLADORA S.A. extra_fields: bank_account_number: null bank_iban: null bank_sort_code: null bank_routing_number: null bank_swift_bic: null bank_branch_name: null bank_branch_address: null document_phone_number: null additional_names: - LA EMBOTELLADORA DEL NORTE SA status: Declined warnings: - risk: NAME_MISMATCH_WITH_PROVIDED feature: PROOF_OF_ADDRESS additional_data: null log_type: error short_description: Name mismatch with provided information long_description: >- The full name on the document does not match the name from the user's verified identity documents, or the full name sent by API. vendor_data: user-123 metadata: null created_at: '2026-06-12T02:27:21.330172+00:00' schema: type: object properties: request_id: type: string format: uuid description: >- `save_api_request=true`일 때 유지된 세션 ID(`GET /v3/session/{sessionId}/decision/`와 함께 사용 가능), 그렇지 않으면 임시 상관관계 UUID입니다. poa: type: object properties: status: type: string enum: - Approved - Declined description: >- 어떤 경고도 거부로 이어지지 않는 경우 `Approved`, 그렇지 않은 경우 `Declined`가 됩니다. `warnings` 목록에 이유가 설명되어 있습니다. issuing_state: type: string nullable: true description: >- 문서에서 추출된 문서 발급 국가 — 일반적으로 ISO 3166-1 alpha-3(예: `ARG`). example: ARG document_type: type: string enum: - UTILITY_BILL - BANK_STATEMENT - GOVERNMENT_ISSUED_DOCUMENT - OTHER_POA_DOCUMENT - UNKNOWN description: >- 감지된 문서 카테고리입니다. `UNKNOWN`은 문서를 유효한 주소 증명으로 분류할 수 없음을 의미하며 `INVALID_DOCUMENT_TYPE`과 함께 자동으로 거부됩니다. 절대 null이 될 수 없으며, 분류 실패 시 `UNKNOWN`으로 대체됩니다. document_subtype: type: string description: >- `document_type` 내의 세부 분류입니다(예: 공과금 청구서의 경우 `ELECTRICITY_BILL`, `WATER_BILL`, `GAS_BILL`, `INTERNET_BILL`, `PHONE_BILL`, 은행 명세서의 경우 `ACCOUNT_STATEMENT`, `CREDIT_CARD_STATEMENT`, 정부 문서의 경우 `TAX_ASSESSMENT`, `RESIDENCY_CERTIFICATE`). 하위 유형을 확인할 수 없는 경우 `UNKNOWN`입니다. 절대 null이 아니며, 분류 실패 시 `UNKNOWN`으로 대체됩니다. example: WATER_BILL document_language: type: string nullable: true description: 감지된 문서 언어(ISO 639-1)입니다. example: es issuer: type: string nullable: true description: >- 문서를 발급한 기업 또는 조직입니다. `null`인 경우 `ISSUER_NOT_IDENTIFIED`가 추가됩니다. example: Aguas del Norte issue_date: type: string format: date nullable: true description: >- 문서 발급일(`YYYY-MM-DD`)입니다. 추출할 수 없는 경우 `null`이며, 이 endpoint에서는 `UNABLE_TO_EXTRACT_ISSUE_DATE`로 거부됩니다. example: '2021-02-10' expiration_date: type: string format: date nullable: true description: >- 문서에 인쇄된 명시적 만료일/유효일(있는 경우)입니다. `poa_document_age_months` 기간 확인과는 별개입니다. poa_address: type: string nullable: true description: >- 문서에 인쇄된 그대로의 주소입니다. `null`이면 `MISSING_ADDRESS_INFORMATION`으로 자동 거부됩니다. poa_formatted_address: type: string nullable: true description: '`poa_address`의 지오코딩되고 정규화된 버전입니다.' example: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: type: object nullable: true description: 문서 주소의 구조화된 지오코딩 세부 정보입니다. 주소를 파싱할 수 없는 경우 `null`입니다. properties: street_1: type: string nullable: true example: Avenida Monseñor Tavella 1291 street_2: type: string nullable: true city: type: string nullable: true example: Salta region: type: string nullable: true example: Salta country: type: string nullable: true description: ISO 3166-1 alpha-2 국가 코드입니다. example: AR postal_code: type: string nullable: true example: A4400 document_location: type: object nullable: true properties: latitude: type: number longitude: type: number description: 문서 주소의 지오코딩된 좌표입니다. expected_details_address: type: string nullable: true description: 전송한 `expected_address`의 에코 값 또는 `null`입니다. expected_details_formatted_address: type: string nullable: true description: >- `expected_address`의 지오코딩되고 정규화된 버전입니다. 제공되지 않았거나 지오코딩할 수 없는 경우 `null`입니다. expected_details_parsed_address: type: object nullable: true additionalProperties: true description: >- `expected_address`에 대한 전체 지오코딩 결과(도로명/시/지역/국가/우편번호 및 원시 지오코더 출력과 `is_verified` 플래그). `expected_address`가 제공되지 않은 경우 `null`입니다. name_on_document: type: string nullable: true description: >- 문서에서 추출된 주 소지자 성명입니다. 제공된 경우 `expected_first_name`/`expected_last_name`과 비교됩니다. `null`인 경우 이 endpoint에서 `POA_NAME_NOT_DETECTED`와 함께 거부됩니다. example: OESTE EMBOTELLADORA S.A. extra_fields: type: object description: >- 문서별 추가 항목입니다. 은행 관련 필드는 문서에 인쇄된 경우 은행 거래 내역서에 대해 채워지며, 그렇지 않은 경우 `null`입니다. properties: bank_account_number: type: string nullable: true bank_iban: type: string nullable: true bank_sort_code: type: string nullable: true bank_routing_number: type: string nullable: true bank_swift_bic: type: string nullable: true bank_branch_name: type: string nullable: true bank_branch_address: type: string nullable: true document_phone_number: type: string nullable: true description: 문서에 인쇄된 연락처 전화번호입니다. additional_names: type: array items: type: string description: '문서에서 발견된 다른 명의자 이름(예: 공동 계좌 명의자, 이전 계좌 이름)입니다.' warnings: type: array description: >- 문제없이 승인된 경우 비어 있습니다. 각 항목은 감지된 하나의 위험을 설명합니다. `log_type: "error"`인 항목은 `status`를 `Declined`로 설정합니다. items: type: object properties: risk: type: string description: >- 기계 판독 가능한 위험 코드입니다. 항상 거부: `MISSING_ADDRESS_INFORMATION`, `POA_DOCUMENT_EXPIRED`, `INVALID_DOCUMENT_TYPE`, `UNABLE_TO_VALIDATE_DOCUMENT_AGE` 및 `UNABLE_TO_EXTRACT_ISSUE_DATE`, `POA_NAME_NOT_DETECTED`(이 endpoint에서는 거부로 고정됨). 요청 옵션에 의해 제어됨: `NAME_MISMATCH_WITH_PROVIDED` / `ADDRESS_MISMATCH_WITH_PROVIDED` / `POA_COUNTRY_MISMATCH_WITH_PROVIDED`(`poa_address_mismatch_action`), `POOR_DOCUMENT_QUALITY`(이 endpoint에서는 생성되지 않음) / `DOCUMENT_METADATA_MISMATCH`(`poa_document_issues_action`), `SUSPECTED_DOCUMENT_MANIPULATION` 및 `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`(`poa_document_authenticity_action`), `UNSUPPORTED_DOCUMENT_LANGUAGE`(`poa_unsupported_language_action`), `ISSUER_NOT_IDENTIFIED`(`poa_issuer_not_identified_action`). 이 endpoint에서 정보 제공용: `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`, `UNPARSABLE_OR_INVALID_ADDRESS`. example: POA_DOCUMENT_EXPIRED feature: type: string enum: - PROOF_OF_ADDRESS description: >- 경고를 발생시킨 기능입니다. 이 엔드포인트에서는 항상 `PROOF_OF_ADDRESS`입니다. additional_data: type: object nullable: true additionalProperties: true description: >- 일부 위험에 대한 추가 컨텍스트 — 예: `POA_DOCUMENT_EXPIRED`에는 `expiration_reason`(`printed_expiration` 또는 `age_window`), `document_type`, `document_subtype`, `issue_date`가 포함되며, `printed_expiration` 경로에서는 `expiration_date`, `age_window` 경로에서는 `max_age_months`가 추가로 포함됩니다. `SUSPECTED_DOCUMENT_MANIPULATION`에는 `reason` 및 `detection_method`가 포함됩니다. `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`에는 `reason`, `detection_method`(`unproven_text_replacement`), `replaced_text`, `manipulated_regions`, `manipulated_blocks`가 포함됩니다. 대부분의 위험에 대해 `null`입니다. log_type: type: string enum: - error - information description: >- 심각도입니다. `error` 경고는 `status`를 `Declined`로 변경합니다. `information` 항목은 참고용이며 단독으로 거부되지 않습니다. (`warning`은 이 endpoint에서 생성되지 않습니다. 해당 옵션은 `DECLINE` 또는 `NO_ACTION`만 허용합니다.) short_description: type: string description: 사람이 읽을 수 있는 한 줄의 위험 요약입니다. long_description: type: string description: 위험에 대한 사람이 읽기 쉬운 설명입니다. detected_codes: type: array description: >- 문서의 처리된 모든 페이지에서 감지된 QR 코드 및 바코드입니다. 발견되지 않으면 비어 있습니다. 위치는 식별되었으나 디코딩할 수 없는 QR 코드는 `parsed_payload: null`을 가집니다. items: $ref: '#/components/schemas/DocumentAIDetectedCode' vendor_data: type: string nullable: true description: 전송한 `vendor_data`의 에코 값 또는 `null`입니다. metadata: type: object nullable: true additionalProperties: true description: 전송한 `metadata` 객체의 에코 값 또는 `null`입니다. created_at: type: string format: date-time description: 응답이 생성된 시점의 ISO 8601 타임스탬프(UTC)입니다. '400': description: >- 검증 또는 처리 오류입니다. 필드 수준의 문제는 DRF의 표준 엔벨로프(문제가 발생한 필드당 하나의 메시지 배열)를 반환합니다. 암호화된 PDF 문제는 `{"detail": ...}`를 반환합니다. 추출 파이프라인에서 처리할 수 없는 문서는 `{"error": ["Error extracting POA information"]}`를 반환합니다. content: application/json: examples: Missing document: summary: 폼 데이터에 `document`가 포함되지 않음 value: document: - No file was submitted. Unsupported file extension: summary: tiff/jpg/jpeg/png/pdf/webp 이외의 파일 확장자 value: document: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, pdf, webp. File too large: summary: 업로드가 15MB 제한을 초과함 value: document: - File size should not exceed 15 MB Encrypted PDF: summary: 필수 비밀번호 없이 업로드된 PDF입니다. value: detail: >- The PDF is encrypted. Please upload a decrypted PDF or a photo instead. Wrong PDF password: summary: '`document_password`로 PDF를 복호화할 수 없음' value: detail: >- The PDF password is incorrect. Please provide the correct password. Invalid language code: summary: '`poa_languages_allowed`에 지원되지 않는 코드가 포함됨' value: poa_languages_allowed: - >- Invalid language code: 'xx'. Must be one of the supported languages: ['ar', 'bn', 'hy', 'bg', 'bs', 'ca', 'cnr', 'sq', 'zh', 'hr', 'cs', 'da', 'nl', 'en', 'et', 'fi', 'fr', 'ka', 'kk', 'de', 'el', 'he', 'hi', 'hu', 'id', 'it', 'ja', 'ko', 'ky', 'lv', 'lt', 'mk', 'mn', 'ms', 'no', 'fa', 'pl', 'pt', 'ro', 'ru', 'sr', 'sk', 'sl', 'so', 'es', 'sv', 'th', 'tr', 'uk', 'uz', 'vi']. Invalid document age value: summary: '`poa_document_age_months` 값이 1–120 / -1 범위를 벗어남' value: poa_document_age_months: - >- Invalid integer value for 'utility_bill': '999'. Must be -1 (unlimited) or a positive integer between 1 and 120. Extraction failure: summary: 추출 파이프라인에서 문서를 처리할 수 없습니다. value: error: - Error extracting POA information '403': description: >- 권한이 거부되었습니다. `x-api-key` 헤더가 누락되었거나 호출한 조직의 잔액이 호출 비용을 충당할 수 없을 때 반환됩니다. 잘못되었거나 취소되었거나 만료된 키는 `401`을 반환합니다. 키가 누락된 경우 `{"detail": ...}`과 함께 `403`을 반환하고, 잘못되었거나 취소되었거나 만료된 키는 `401`을 반환합니다. 크레딧이 부족한 경우 어떠한 문서 처리도 진행되기 전에 `{"error": ...}`과 함께 `403`을 반환합니다. content: application/json: examples: Missing or invalid API key: summary: '`x-api-key` 헤더가 없거나, 키가 유효하지 않거나 해지되었습니다' value: detail: You do not have permission to perform this action. Not enough credits: summary: 조직 잔액이 호출 비용을 충당할 수 없습니다 value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- 속도 제한을 초과했습니다. POST/PATCH/DELETE endpoint는 API 키당 분당 300회의 쓰기 요청 한도를 공유합니다(거래 생성 및 이벤트 수집은 별도로 600회 한도 적용). 응답에는 `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `Retry-After` 헤더가 포함됩니다. content: application/json: examples: Write rate limit exceeded: summary: 현재 분 동안 300건을 초과하는 쓰기 요청 발생 value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string '503': $ref: '#/components/responses/DocumentProcessingBusy' security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/poa/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'document=@./utility-bill.pdf' \ -F 'expected_address=Av. Monseñor Tavella 1291, Salta, Argentina' \ -F 'expected_country=ARG' \ -F 'expected_first_name=Sophia' \ -F 'expected_last_name=Martinez' \ -F 'poa_languages_allowed=en,es' \ -F 'vendor_data=user-123' \ --max-time 45 - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.proof_of_address.verify( document=open("document.pdf", "rb"), expected_address="Av. Monseñor Tavella 1291, Salta, Argentina", expected_country="ARG", expected_first_name="Sophia", expected_last_name="Martinez", poa_languages_allowed="en,es", save_api_request=True, vendor_data="user-123", ) print(result) - lang: javascript label: Node.js source: |- import Didit, { fileFromPath } from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.proofOfAddress.verify({ document: await fileFromPath("document.pdf"), expected_address: "Av. Monseñor Tavella 1291, Salta, Argentina", expected_country: "ARG", expected_first_name: "Sophia", expected_last_name: "Martinez", poa_languages_allowed: "en,es", save_api_request: true, vendor_data: "user-123", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.ProofOfAddress.Verify(ctx, didit.ProofOfAddressVerifyParams{\n\tDocument: didit.FileFromPath(\"document.pdf\"),\n\tExpectedAddress: didit.String(\"Av. Monseñor Tavella 1291, Salta, Argentina\"),\n\tExpectedCountry: didit.String(\"ARG\"),\n\tExpectedFirstName: didit.String(\"Sophia\"),\n\tExpectedLastName: didit.String(\"Martinez\"),\n\tPOALanguagesAllowed: didit.String(\"en,es\"),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.nio.file.Path; import me.didit.Didit; import me.didit.types.ProofOfAddressVerifyParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.proofOfAddress().verify(ProofOfAddressVerifyParams.builder() .document(Path.of("document.pdf")) .expectedAddress("Av. Monseñor Tavella 1291, Salta, Argentina") .expectedCountry("ARG") .expectedFirstName("Sophia") .expectedLastName("Martinez") .poaLanguagesAllowed("en,es") .saveApiRequest(true) .vendorData("user-123") .build()); System.out.println(result); - lang: php label: PHP source: |- proofOfAddress->verify([ 'document' => File::fromPath('document.pdf'), 'expected_address' => 'Av. Monseñor Tavella 1291, Salta, Argentina', 'expected_country' => 'ARG', 'expected_first_name' => 'Sophia', 'expected_last_name' => 'Martinez', 'poa_languages_allowed' => 'en,es', 'save_api_request' => true, 'vendor_data' => 'user-123', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.proof_of_address.verify( document: Pathname("document.pdf"), expected_address: "Av. Monseñor Tavella 1291, Salta, Argentina", expected_country: "ARG", expected_first_name: "Sophia", expected_last_name: "Martinez", poa_languages_allowed: "en,es", save_api_request: true, vendor_data: "user-123" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.ProofOfAddress.VerifyAsync(new ProofOfAddressVerifyParams { Document = FileUpload.FromPath("document.pdf"), ExpectedAddress = "Av. Monseñor Tavella 1291, Salta, Argentina", ExpectedCountry = "ARG", ExpectedFirstName = "Sophia", ExpectedLastName = "Martinez", PoaLanguagesAllowed = "en,es", SaveApiRequest = true, VendorData = "user-123", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: DocumentAIDetectedCode: type: object required: - type - page_number - position - x - 'y' - width - height - page_width - page_height - raw_payload - parsed_payload properties: type: type: string description: >- 감지된 심볼로지(예: `QR_CODE`, `CODE_128`, `EAN_13`, `DATA_MATRIX` 또는 `PDF_417`)입니다. page_number: type: integer minimum: 1 description: 1부터 시작하는 페이지 번호입니다. position: type: array nullable: true description: >- 렌더링된 페이지의 픽셀 좌표로 감지된 다각형(polygon)입니다. 신뢰할 수 있는 위치를 찾을 수 없는 경우 `null`입니다. items: type: array minItems: 2 maxItems: 2 items: type: integer x: type: integer nullable: true description: 렌더링된 페이지 픽셀 단위의 경계 상자 왼쪽 가장자리입니다. 'y': type: integer nullable: true description: 렌더링된 페이지 픽셀 기준 경계 상자의 상단 가장자리입니다. width: type: integer nullable: true description: 렌더링된 페이지 픽셀 단위의 경계 상자 너비입니다. height: type: integer nullable: true description: 렌더링된 페이지 픽셀 단위의 경계 상자 높이입니다. page_width: type: integer description: 렌더링된 페이지 너비(픽셀 단위)입니다. page_height: type: integer description: 렌더링된 페이지 높이(픽셀 단위)입니다. raw_payload: type: string description: 사용 가능한 경우 base64 문자열 형식의 원시 디코더 payload이며, 그렇지 않은 경우 빈 문자열입니다. parsed_payload: nullable: true description: 디코딩된 문자열 또는 구조화된 값입니다. 코드가 감지되었으나 디코딩할 수 없는 경우 `null`입니다. responses: DocumentProcessingBusy: description: >- 현재 너무 많은 문서가 처리 중이므로 이 업로드가 처리되지 않았습니다. 아무것도 저장되지 않았으며 시도 횟수도 사용되지 않았습니다. `Retry-After`의 시간(초)이 지난 후 동일한 파일을 다시 전송하세요. 메시지 텍스트가 아닌 `code`를 기준으로 분기하세요. headers: Retry-After: description: 동일한 요청을 다시 전송하기 전에 대기해야 하는 시간(초)입니다. schema: type: integer example: 10 content: application/json: schema: type: object required: - detail - code properties: detail: type: string code: type: string enum: - document_processing_busy example: detail: We are busy processing documents. Please try again in a moment. code: document_processing_busy securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- 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 를 참고하십시오. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.