결과 받기
등록·검증·식별 결과를 앱이나 서버가 받는 방법(폴링, 웹훅, Web Integration 리다이렉트)과 무엇을 써야 하는지.
등록·검증·식별은 비동기입니다. 요청을 보내면 결과는 나중에 옵니다. 받는 방법은 연동 방식에 따라 다릅니다.
무엇을 쓸까
| 연동 방식 | 결과 받는 방법 | 웹훅 |
|---|---|---|
| 모바일 SDK + Server API(서버가 작업 제출) | 작업 폴링, 또는 서버로 웹훅 수신 | 가능 |
| Web Integration: Server Integration(서버가 세션 발급) | 사용자 리다이렉트의 결과 코드를 서버가 읽기, 또는 세션 폴링 | 불가 |
| Web Integration: Link Integration(콘솔 링크) | 사용자 리다이렉트(petify_status), 표시 코드, 콘솔 결과 목록 | 불가 |
Web Integration 세션은 현재 웹훅 이벤트를 보내지 않습니다. 사용자가 Web Integration 링크나 세션으로 촬영한다면 웹훅이 아니라 리다이렉트와 결과 코드를 쓰세요.
Server API: 폴링
제출(addFingerprints, verify, identify)은 202와 jobId를 돌려줍니다. status가 SUCCESS 또는 FAILED가 될 때까지 작업을 조회합니다.
| 작업 | 엔드포인트 |
|---|---|
| 등록 | GET /v2/fingerprint-addition-jobs/{jobId} |
| 검증 | GET /v2/verification-jobs/{jobId} |
| 식별 | GET /v2/identification-jobs/{jobId} |
2~3초 간격으로 최대 60초까지, 백오프를 두고 조회하세요. 결과 필드(isVerified, score, pets[])는 SUCCESS에서만 나옵니다. 작업 상태와 폴링을 참고하세요.
Server API: 웹훅
폴링 대신 콘솔에서 HTTPS 엔드포인트를 추가하고 서명된 이벤트를 받습니다: fingerprint_addition_job.succeeded / .failed, verification_job.succeeded / .failed, identification_job.succeeded / .failed.
- 엔드포인트 등록: Console → Integration → Webhooks 탭 → Add endpoint
- 이벤트 종류와 본문
- 서명 검증
Web Integration: 리다이렉트와 결과 코드
사용자가 촬영을 마치면 브라우저가 Redirect URL로 돌아오며 petify_status(completed, failed 등)와, 대부분의 세션에서 petify_code가 붙습니다.
- Server Integration: 서버가
GET /v2/hosted-results/{code}로 코드를 교환하거나GET /v2/hosted-sessions/{id}를 폴링합니다. 결과 수신을 참고하세요. - Link Integration: 등록 링크는
petify_status만 돌려주고, 검증·식별 링크는 페이지에서 보여줄 수 있는 표시 코드를 돌려줍니다. 결과 확인을 참고하세요. - 파라미터 규칙: Redirect URL과 결과 전달.
결과가 실패라면
실패 종류별 위치와 할 일은 등록은 왜 실패했나요?를 참고하세요.