콜백 응답 예시

콜백 응답 예시 섹션은 사용자가 API 상호작용에서 받게 될 예상 응답을 엿볼 수 있게 하여 응답 구조와 형식을 이해하는 데 도움을 줍니다. 이러한 예시를 활용하여 개발자들은 통합 프로세스를 향상시키고 개발 노력을 간소화할 수 있으며, 애플리케이션과 API 간의 원활한 통신을 보장할 수 있습니다. 이 섹션은 통합을 효과적으로 테스트하고 개선하기 위한 귀중한 리소스 역할을 합니다.

개요

콜백 URL과 함께 Global ID Recognition API를 사용할 때, 시스템은 요청을 비동기적으로 처리하고 결과를 지정된 콜백 엔드포인트로 전송합니다. 이 접근 방식은 배치 처리나 애플리케이션을 차단하지 않고 여러 요청을 처리해야 할 때 이상적입니다.

응답 구조

콜백 응답에는 다음과 같은 주요 구성 요소가 포함됩니다:

statusCode: 결과를 나타내는 HTTP 상태 코드
apiType: API 유형 식별자 (“id_recognition”)
transactionId: 요청을 추적하기 위한 고유 식별자
result: 상세한 인식 결과를 포함하는 객체
- data: 추출된 데이터 객체
  - raw: 원본 OCR 데이터 및 좌표 정보
    - 각 필드(address, name, number 등)는 coordinates와 original_coordinates를 포함할 수 있습니다
    - coordinates: 처리된 이미지 기준의 좌표 정보
    - original_coordinates: 신분증 사진 촬영 시 원본 이미지 기준의 좌표 정보 (선택적)
  - ocr: 아르고스가 정의해둔 구조화된 OCR 데이터

성공 응답 예시

{
  "statusCode": 200,
  "apiType": "id_recognition",
  "result": {
    "data": {
      "raw": {
        "address": {
          "value": "ADRESS 110, SOMEWHERE",
          "score": 89,
          "coordinates": {
            "first": {
              "x": 95,
              "y": 221
            },
            "fourth": {
              "x": 95,
              "y": 258
            },
            "second": {
              "x": 430,
              "y": 221
            },
            "third": {
              "x": 430,
              "y": 258
            }
          },
          "original_coordinates": {
            "first": {
              "x": 211,
              "y": 714
            },
            "fourth": {
              "x": 213,
              "y": 752
            },
            "second": {
              "x": 553,
              "y": 713
            },
            "third": {
              "x": 554,
              "y": 751
            }
          }
        },
        "authority": {
          "value": "{{value}}",
          "score": 4,
          "coordinates": {
            "first": {
              "x": 796,
              "y": 1460
            },
            "fourth": {
              "x": 799,
              "y": 1637
            },
            "second": {
              "x": 1931,
              "y": 1461
            },
            "third": {
              "x": 1925,
              "y": 1641
            }
          }
        },
        "name": {
          "value": "{{value}}",
          "score": 61,
          "coordinates": {
            "first": {
              "x": 367,
              "y": 462
            },
            "fourth": {
              "x": 375,
              "y": 669
            },
            "second": {
              "x": 1379,
              "y": 454
            },
            "third": {
              "x": 1378,
              "y": 663
            }
          }
        },
        "name_chn": {
          "value": "{{value}}",
          "score": 61,
          "coordinates": {
            "first": {
              "x": 367,
              "y": 462
            },
            "fourth": {
              "x": 375,
              "y": 669
            },
            "second": {
              "x": 1379,
              "y": 454
            },
            "third": {
              "x": 1378,
              "y": 663
            }
          }
        },
        "number": {
          "value": "{{value}}",
          "score": 95,
          "accepted": true,
          "coordinates": {
            "first": {
              "x": 248,
              "y": 698
            },
            "fourth": {
              "x": 256,
              "y": 867
            },
            "second": {
              "x": 1423,
              "y": 691
            },
            "third": {
              "x": 1421,
              "y": 861
            }
          }
        },
        "rotate": {
          "value": "0"
        }
      },
      "ocr": {
        "ocr_fullName": "{{ocr_fullName}}",
        "ocr_firstName": "{{ocr_firstName}}",
        "ocr_middleName": "{{ocr_middleName}}",
        "ocr_lastName": "{{ocr_lastName}}",
        "ocr_gender": "{{ocr_gender}}",
        "ocr_nationality": "{{ocr_nationality}}",
        "ocr_birthDate": "{{ocr_birthDate}}",
        "ocr_identityNumber": "{{ocr_identityNumber}}",
        "ocr_issueDate": "{{ocr_issueDate}}",
        "ocr_expireDate": "{{ocr_expireDate}}",
        "ocr_version": "{{ocr_version}}",
        "ocr_number": "{{ocr_number}}",
        "full_mrz": "{{full_mrz}}",
        "mrz_line1": "{{mrz_line1}}",
        "mrz_line2": "{{mrz_line2}}"
      }
    },
    "review_front": true,
    "review_back": false,
    "document_type": "{{document_type}}"
  },
  "transactionId": "e0nvom3caiis7"
}

오류 응답 예시

{
  "statusCode": 400,
  "apiType": "id_recognition",
  "transactionId": "{{transactionId}}",
  "errorCode": "1011",
  "message": "ID 카드 인식에 실패했습니다"
}

통합 가이드라인

콜백 엔드포인트 설정: POST 요청을 받을 수 있도록 설정
transactionId 검증: 올바른 응답을 처리하고 있는지 확인
statusCode 확인: 요청이 성공했는지 판단
result 객체 파싱: 문서 및 개인 정보 추출
오류 처리: 응답에서 오류 객체를 확인하여 적절히 처리

모범 사례

멱등성 구현: transactionId를 사용하여 중복 처리 방지
적절한 타임아웃 설정: 콜백 엔드포인트에 대한 타임아웃 설정
모든 응답 로깅: 디버깅 및 모니터링을 위한 로그 기록
응답 구조 검증: 데이터 처리 전 응답 구조 유효성 검사
네트워크 오류 처리: 네트워크 오류 처리 및 재시도 로직 구현
추출된 데이터 보안 저장: 데이터 보호 규정에 따른 보안 저장

ID Liveness

Global ID Recognition

Documentation Index

​콜백 응답 예시

​개요

​응답 구조

​성공 응답 예시

​오류 응답 예시

​통합 가이드라인

​모범 사례