메인 콘텐츠로 건너뛰기
POST
Python
문서 한 개와 그 문서에서 읽어 올 필드 목록을 전송하십시오. Didit은 파일에 기본 추출 모델을 실행해 모든 필드를 타입과 함께 반환합니다(text, number, 또는 YYYY-MM-DD 형식의 date). 또한 지원되는 QR 코드와 바코드를 감지해 디코딩하고, 파일의 변조 여부를 확인하며, 원하는 경우 문서상의 이름을 기대하는 개인 또는 회사와 비교합니다. 급여명세서, 은행 거래내역서, 세무 서류, 청구서, 자금 증명, 또는 고정된 양식에 맞지 않는 모든 문서에 사용하십시오. 이 기능은 호스팅 Document AI 단계의 서버 간 버전입니다. 요청은 multipart/form-data이며, 파일은 document에, 필드 정의는 fields에 하나의 JSON 인코딩 배열 문자열로 담아 보냅니다.

추출할 필드 정의

fields는 하나의 문자열로 전송되는 1개에서 30개 사이의 JSON 배열입니다. 각 항목에는 key(소문자, 숫자, 밑줄만 사용하며 요청 내에서 고유해야 함), 사람이 읽을 수 있는 name, 모델이 무엇을 찾아야 하는지 알려 주는 instruction, type(text, number, date 중 하나), 그리고 두 개의 플래그인 required와 is_full_name이 있습니다.
multipart 요청에서는 배열 전체가 하나의 폼 값입니다.
응답은 정규화된 fields를 그대로 반환하고, extracted_data에 key 값을 기준으로 추출 결과를 담습니다. 모델이 찾지 못한 값은 null로 반환됩니다. 각 항목의 name, instruction, type은 선택 사항이며(type의 기본값은 text), key만 필수입니다. fields를 대괄호 형식의 폼 키(fields[0][key]=...)로 보내거나 JSON 배열이 아닌 형식으로 보내면, 추출이 시작되기 전에 400이 반환되며 요금은 청구되지 않습니다.

QR 코드 및 바코드

성공한 모든 응답에는 document_ai.detected_codes가 포함됩니다. 각 항목에는 다음 필드가 있습니다. 이 배열은 PDF의 처리된 모든 페이지를 포함하며, 지원되는 코드가 없으면 비어 있습니다. Didit은 payload를 추측하지 않습니다. 손상된 QR 코드는 위치 정보와 함께 parsed_payload: null로 반환될 수 있으며, 코드 감지에 실패하더라도 Document AI 요청은 실패하지 않습니다.

이름 대조

is_full_name: true는 최대 한 개의 필드에만 설정하고, 문서의 소유자로 예상하는 사람 또는 회사를 함께 전송합니다. 두 그룹을 함께 보내지 말고 둘 중 하나만 보내야 합니다. 이름이 추출되고 예상 이름이 있으면, 응답에 name_match_score(0~100)와 name_on_document가 포함됩니다. 점수가 document_ai_name_match_score_threshold(기본값 80)보다 낮으면 DOCUMENT_AI_NAME_MISMATCH 경고가 발생하고 document_ai_name_mismatch_action이 적용됩니다. is_full_name으로 표시된 필드가 없으면, Didit은 키가 name, holder, full_name, account_holder처럼 이름으로 보이는 첫 번째 텍스트 필드를 사용합니다. 비교할 값을 직접 지정하려면 해당 필드에 명시적으로 표시하십시오. 문서에서 이름 값을 찾을 수 없거나 예상 이름을 보내지 않으면 이름 검사는 건너뛰며, name_match_score는 null이 됩니다.

위험 및 작업

아래의 각 위험은 요청별로 설정할 수 있는 작업 파라미터에 대응하며, 값은 DECLINE, REVIEW, NO_ACTION 중 하나입니다. 발생한 작업 중 가장 엄격한 작업이 document_ai.status를 결정하며(Declined > In Review > Approved), 발생한 모든 위험은 document_ai.warnings에 나열됩니다. 기본값은 호스팅 워크플로 단계와 같습니다. 각 위험이 감지되는 방식은 Document AI 규칙 및 경고를 참조하십시오.

파일, 저장 및 요금 청구

  • 지원 파일: PDF(여러 페이지 지원), JPG, JPEG, PNG, TIFF, WebP, 또는 문서가 포함된 ZIP 파일이며, 최대 30MB입니다. 암호화된 PDF는 400을 반환합니다. 복호화된 PDF나 사진을 업로드하십시오.
  • save_api_request(기본값 true): 요청, 추출된 필드, 감지된 코드가 Manual Checks 메뉴에서 Business Console에 표시되어 팀이 검토할 수 있습니다. 저장을 건너뛰려면 false로 설정하십시오.
  • vendor_data와 metadata는 응답에 변경 없이 그대로 반환되므로, 결과를 자체 기록과 연결할 수 있습니다.
  • 요금: 문서당 $0.20이며, 문서가 처리되고 상태가 반환될 때 청구됩니다. 요금제에 따른 할인이 적용됩니다. 요금을 참조하십시오.
사용자가 직접 문서를 업로드하도록 하거나, 한 번의 흐름에서 문서를 최대 3개까지 수집하거나, 업로드 화면을 자동 번역하거나, 추출된 필드를 신분증 또는 설문지 데이터와 대조해야 합니까? 그렇다면 대신 호스팅 Document AI 워크플로 단계를 사용하십시오.

인증

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, zip. 최대 업로드 크기: 30 MB(더 큰 파일은 400으로 거부됨). 다중 페이지 PDF가 지원됩니다(지연 시간이 길어질 수 있음). 암호화된 PDF는 400으로 거부됩니다. 이미지는 처리 전에 자동으로 압축됩니다.

fields
string
필수

1–30개의 필드 정의가 포함된 JSON 인코딩 배열 문자열(최대 16KB)입니다. 각 항목: key(필수, ^[a-z0-9_]{1,64}$, 고유값 — extracted_data에서 반환되는 키), name(100자 이하, 메시지에 표시됨), instruction(500자 이하, 모델이 읽어야 하는 내용), type(기본값 text | number | date), required(부울, 기본값 false), is_full_name(부울, 기본값 false, 요청당 최대 1개). 대괄호 스타일 폼 배열, 잘못된 JSON, 중복된 키 또는 둘 이상의 is_full_name은 처리나 결제가 진행되기 전에 400을 반환합니다.

예시:

"[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]"

expected_first_name
string

문서의 이름 필드와 대조하여 검증할 이름입니다(퍼지 일치, 음차 인식). expected_last_name과 함께 사용해야 하며, expected_company_name과 결합할 수 없습니다.

예시:

"Sophia"

expected_last_name
string

문서의 이름 필드와 대조하여 검증할 성으로, name_match_score를 위해 expected_first_name과 결합됩니다.

예시:

"Martinez"

expected_company_name
string

문서의 이름 필드와 대조하여 확인할 기업명입니다(기업 문서용). expected_first_name / expected_last_name과 함께 사용할 수 없습니다(예시 값은 의도적으로 제공되지 않음 — 생성된 요청 샘플에는 개인 필드가 사용되므로, 기업 문서를 확인할 때는 이 필드로 교체하십시오).

expected_company_country
string

expected_company_name에 대한 기업명 정규화를 조정하는 선택적 ISO 3166-1 alpha-2 국가 코드(ASCII 2글자, 예: FR)입니다. expected_company_name과 함께만 사용됩니다.

document_ai_name_match_score_threshold
integer
기본값:80

이름이 일치하는 것으로 간주하기 위한 최소 name_match_score(0–100)입니다. 점수가 이보다 낮으면 DOCUMENT_AI_NAME_MISMATCH가 추가되며, document_ai_name_mismatch_action의 제어를 받습니다.

필수 범위: 0 <= x <= 100
예시:

80

document_ai_unreadable_document_action
enum<string>
기본값:REVIEW

문서에서 어떤 필드도 읽을 수 없을 때(DOCUMENT_AI_UNREADABLE_DOCUMENT) 수행할 작업입니다.

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

required 필드 중 하나 이상을 읽을 수 없을 때(DOCUMENT_AI_MISSING_REQUIRED_FIELDS, 해당 필드는 additional_data.missing_fields에 나열됨) 수행할 작업입니다.

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

PDF/EXIF 포렌식에서 전자 서명 후 수정, 알려진 PDF 편집기 사용, 오버레이 텍스트 조작, 의심스러운 재내보내기, 이미지 이상 현상 등 위변조가 의심될 때(DOCUMENT_AI_SUSPECTED_MANIPULATION) 수행할 작업입니다.

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

name_match_score가 임계값 미만일 때(DOCUMENT_AI_NAME_MISMATCH) 수행할 작업입니다.

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

업로드된 항목이 비어 있거나 처리할 수 없는 파일일 때 수행할 작업입니다 (DOCUMENT_AI_UNSUPPORTED_FILE).

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

true(기본값)인 경우 호출을 API 유형 세션으로 저장합니다. Business Console에서 확인할 수 있고 반환된 request_id를 사용하여 GET /v3/session/{sessionId}/decision/을 통해 조회할 수 있으며 업로드된 문서, 추출된 값, 필드 정의 및 이름 일치 스냅샷이 저장됩니다. 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"})로 전송하십시오. 객체로 파싱됩니다.

예시:

응답

문서가 처리되었습니다. document_ai.status는 Approved, Declined 또는 In Review입니다. 감지된 모든 문제는 document_ai.warnings에 항목별로 나열됩니다. 문제가 있는 문서라도 200을 반환하므로 HTTP 코드뿐만 아니라 본문도 검사해야 합니다. save_api_request=true인 경우 request_id는 저장된 세션 ID입니다.

request_id
string<uuid>

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

document_ai
object
vendor_data
string | null

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

metadata
object | null

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

created_at
string<date-time>

요청이 처리된 시점(UTC, ISO 8601).

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