Redirect URL과 결과 전달

허용 Redirect URL 관리 규칙과, 촬영 완료 후 리다이렉트에 전달되는 파라미터를 안내합니다.

허용 Redirect URL이란?

촬영 완료 후 사용자가 돌아갈 Redirect URL은 허용 목록(allow-list)에 등록된 URL만 사용할 수 있습니다. 임의의 주소로 사용자를 보내는 것(open redirect)을 막기 위한 안전장치입니다.

허용 목록은 콘솔의 Integration → Links → 허용 Redirect URL에서 관리하며, Link Integration 링크 설정과 Server Integration 세션 발급에 공통으로 사용됩니다.

등록 방법	설명
콘솔에서 직접 추가	허용 Redirect URL 화면에서 URL을 추가합니다
링크 생성/수정 시 자동 등록	링크에 미등록 URL을 입력하면 허용 목록에 자동으로 추가됩니다

Server Integration은 자동 등록되지 않습니다. POST /v2/hosted-sessions는 사전 등록된 URL만 허용하며, 미등록 URL은 400 에러(PETNOWB2B21003)가 반환됩니다.

규칙	설명
HTTPS 필수	`https://` URL만 등록할 수 있습니다. 예외로 로컬 개발용 loopback 호스트(`localhost`, `127.0.0.1`, `::1`)는 `http://`를 허용합니다 (포트·경로·쿼리 무관)
정확 일치	링크·세션의 Redirect URL은 등록된 항목과 문자 단위로 정확히 일치해야 합니다 (loopback도 포트까지 포함해 정확히 등록)
예약 파라미터 금지	쿼리 문자열에 `petify_status`, `petify_code` 키를 포함할 수 없습니다 — 완료 리다이렉트 시 Petnow가 추가하는 예약 파라미터입니다
길이 제한	URL은 최대 500자입니다

삭제되지 않은 링크가 해당 URL을 사용하고 있으면 URL을 삭제할 수 없습니다. 먼저 연결된 링크의 Redirect URL을 변경하거나 링크를 삭제하세요.
삭제된 링크가 과거에 사용한 URL은 연결된 링크 수가 0으로 표시되더라도 삭제가 제한될 수 있습니다. 이 경우 기존 URL은 허용 목록에 남겨 두고, 필요한 새 URL을 별도로 등록해 사용하세요. 사용 중인 링크가 없는 URL이 허용 목록에 남아 있어도 촬영이나 리다이렉트 동작에는 영향을 주지 않습니다.
진행 중인 촬영 세션은 생성 시점의 Redirect URL을 사용하므로, 허용 목록을 수정해도 이미 발급된 세션에는 영향이 없습니다.

촬영 세션이 종료되면 사용자 브라우저가 Redirect URL로 이동하며, Petnow가 쿼리 파라미터를 추가합니다. 기존 쿼리 파라미터와 프래그먼트는 유지된 채 결과 파라미터만 추가되며, 다른 파라미터(세션 ID, 점수, 토큰 등)는 절대 붙지 않습니다.

리다이렉트는 세션이 생성된 경우에만 발생합니다. 진입 자체가 차단된 경우(중복·미등록 externalPetId, 비활성 링크 등)에는 세션이 없으므로 완료 페이지가 호출되지 않습니다.

https://your-service.example.com/petify/return?petify_status=completed&petify_code=hrc_1a2b3c4d5e6f

인증 불일치와 검색 후보 없음은 실패가 아니라 completed입니다 — 기능 결과가 정상 생성된 것이며, 일치 여부·후보 유무는 결과 조회로 확인합니다. failed는 결과 자체가 만들어지지 못한 경우입니다.

petify_code는 상태에 따라 의미가 다릅니다:

`petify_status`	`petify_code`
`completed`	1회성 결과/표시 코드 (`hrc_...`) — 아래 발급 기준 참고
`failed`	기계 판독용 사유. 현재는 `FEATURE_UNAVAILABLE` 하나뿐 — 플랜/계약 상태로 기능을 사용할 수 없는 경우이며, 콘솔에서 플랜을 확인하세요
`cancelled`, `expired`	없음

완료(completed) 시 코드 발급 기준:

세션 종류	`petify_code`
Link Integration — 등록	없음 — `petify_status=completed`가 곧 등록 성공이며, 상세는 콘솔에서 확인
Link Integration — 인증·검색	있음 — 표시 전용 코드 (Link Integration의 결과 확인 참고)
Server Integration — 모든 기능	있음 — 신뢰 가능한 결과 코드 (Server Integration의 결과 수신 참고)

완료 페이지는 세션 종류를 구분해서 구현할 필요가 없습니다 — 전달받은 파라미터를 그대로 읽어서 처리하면 됩니다. petify_ 접두사는 고객사 페이지가 이미 사용 중인 status, code 같은 쿼리 파라미터와 충돌하지 않도록 붙어 있습니다.

리다이렉트에는 사용자·세션 식별자가 붙지 않고, Redirect URL에 사용자별 파라미터를 동적으로 붙이는 것도 지원되지 않습니다(허용 목록 정확 일치). Link Integration에서는 복귀하는 브라우저의 고객사 로그인 세션으로 사용자를 식별하고, Server Integration에서는 결과의 sessionId·externalPetId를 발급 시 저장한 값과 대응시키세요.
petify_status가 completed가 아닌 경우(취소·실패·만료)도 처리하세요. 실패·만료 상태의 사용자에게 재시도 경로(새 링크/세션)를 안내하는 것을 권장합니다.
결과 코드는 세션 완료 후 약 10분간 유효합니다. 리다이렉트는 그 안에 도착하므로 일반적인 흐름에서는 문제가 없지만, 코드 처리를 배치로 미루는 설계는 피하세요.
Server Integration에서는 리다이렉트가 유실될 수 있음을 전제로 설계하세요 — 사용자가 이동 중 브라우저를 닫아도 GET /v2/hosted-sessions/{id} 폴링으로 결과를 회수할 수 있습니다.