Link Integration

개요

Link Integration은 Petify Console에서 재사용 가능한 촬영 링크를 만들어 사용자에게 배포하는 방식입니다. 서버 개발 없이 시작할 수 있으며, 링크 하나로 여러 사용자가 촬영할 수 있습니다.

콘솔의 Integration 메뉴에서 링크 발급·관리(Links 탭)와 API 인증 정보 관리(API & SDK 탭)를 함께 제공합니다.

링크 생성

콘솔의 Integration → Links → 링크 생성에서 링크를 만듭니다.

• 다른 종류의 대상 동물로 운영하려면 링크를 새로 만드세요.
• 검색 링크는 지정한 대상 동물과 같은 종으로 등록된 반려동물 중에서만 후보를 찾습니다.
• 검색(IDENTIFY) 기능은 플랜에 검색이 포함된 경우에만 선택할 수 있습니다.
• Redirect URL 형식 규칙(HTTPS, 예약 파라미터 등)은 Redirect URL과 결과 전달을 참고하세요.

생성된 링크는 다음 형식의 URL을 갖습니다:

https://capture.petify.petnow.io/l/hl_2Xy7Qa9Kd3Lm4Np5Rs6Tu

링크 URL 전달하기

반려동물 식별자 전달 (externalPetId)

등록·인증 링크는 어떤 반려동물에 대한 촬영인지 알아야 하므로, 링크를 전달할 때 고객사 시스템의 반려동물 ID를 externalPetId 쿼리 파라미터로 붙여야 합니다:

https://capture.petify.petnow.io/l/hl_2Xy7Qa9Kd3Lm4Np5Rs6Tu?externalPetId=YOUR-PET-ID-123

진입이 차단되는 경우

다음의 경우 촬영 페이지가 열리지 않고 사용자에게 안내 화면이 표시됩니다:

• 등록·인증 링크에 externalPetId가 없는 경우
• 등록: 이미 등록에 사용된 externalPetId인 경우
• 인증: 등록 이력이 없는 externalPetId인 경우

링크 상태

• 링크에는 만료일이나 자동 종료가 없습니다 — 비활성화·삭제·상한 도달 전까지 계속 사용할 수 있습니다.
• 활성/비활성 전환은 링크 상세 화면에서 즉시 적용됩니다.
• 비활성화·삭제는 새 촬영 진입뿐 아니라 아직 접수되지 않은 제출도 차단합니다. 다만 최종 제출이 이미 접수된 세션은 이후 링크 상태가 바뀌어도 끝까지 처리됩니다.

링크 관리

• 수정: 이름, Redirect URL, 등록 상한을 수정할 수 있습니다. 기능과 대상 동물은 변경할 수 없습니다.
• 등록 상한 하향 제한: 현재 누적 등록 수보다 낮게 설정할 수 없습니다. 누적 등록 수는 링크 생애 기준이며, 등록된 반려동물을 삭제해도 줄지 않습니다.
• 삭제: 삭제는 영구적이며 복구할 수 없고, 링크 주소도 재사용되지 않습니다. 이 링크로 등록된 반려동물 데이터는 유지됩니다.
• 개수 제한: 계정당 링크는 최대 500개(삭제된 링크 제외)까지 생성할 수 있습니다.

결과 확인

촬영이 끝나면 사용자 브라우저가 링크에 설정된 Redirect URL로 이동하며, petify_status(및 조건부 petify_code) 쿼리 파라미터가 추가됩니다. 파라미터 규칙 전체는 Redirect URL과 결과 전달을 참고하세요.

돌아온 사용자 식별하기

Redirect URL은 링크에 고정된 값이고(허용 목록 정확 일치), 리다이렉트에 사용자·세션 식별자가 붙지 않습니다. 완료 페이지에서 "누가 돌아왔는지"는 다음과 같이 판별합니다:

• 복귀하는 브라우저는 링크를 연 바로 그 브라우저입니다. 서비스 화면의 CTA로 링크를 열었다면 고객사 로그인 세션(쿠키)이 그대로 유지되므로, 완료 페이지에서 자체 세션으로 사용자를 식별하는 것이 기본 방법입니다. 문자·QR처럼 로그인 세션이 없는 채널로 전달했다면 완료 페이지에서 로그인을 요구하거나 콘솔에서 externalPetId로 확인하세요.
• 결과가 어느 반려동물의 것인지는 링크 전달 시 붙인 externalPetId가 기준이며, 콘솔 결과 화면에서도 이 ID로 확인할 수 있습니다.
• Redirect URL에 사용자별 파라미터를 동적으로 붙이는 방식은 지원되지 않습니다. 세션 단위의 확실한 대응이 필요하면 Server Integration을 사용하세요 — 발급 시 저장한 세션 id와 결과의 sessionId·externalPetId로 대응됩니다.

등록 링크: 리다이렉트가 곧 결과

등록 링크의 완료 리다이렉트에는 petify_code가 붙지 않습니다. petify_status=completed가 곧 등록 성공을 의미하며, 추가로 조회할 것이 없습니다. 등록된 반려동물의 상세 정보는 콘솔에서 확인합니다.

인증·검색 링크: 표시 전용 코드

인증·검색 링크의 완료 리다이렉트에는 1회성 표시용 코드(petify_code=hrc_...)가 붙습니다. 고객사 완료 페이지의 프런트엔드에서 인증 없이 조회해 사용자에게 결과를 보여줄 수 있습니다:

// 고객사 완료 페이지 (프런트엔드)
const params = new URLSearchParams(window.location.search);
if (params.get("petify_status") === "completed") {
  const code = params.get("petify_code");
  const response = await fetch(
    `https://api.petify.petnow.io/hosted/v1/results/${code}:display`
  );
  const { data } = await response.json();
  // 인증: { action: "VERIFY", outcome: "MATCH", isVerified: true, completedAt: "..." }
  // 검색: { action: "IDENTIFY", outcome: "MATCH", isVerified: null, completedAt: "..." }
}

• 코드는 세션 완료 후 약 10분간 유효하며, 유효 기간 내에는 페이지를 새로고침해도 다시 조회할 수 있습니다.
• 응답에는 대략적인 결과(outcome, 인증의 경우 isVerified)만 담깁니다. 점수, 후보 목록, 반려동물 ID는 노출되지 않습니다.

콘솔에서 확인

콘솔은 완료된 세션의 전체 결과(Petify Pet ID, 검색 후보 목록과 점수 포함)를 보여주는 유일한 화면입니다. 링크별 등록 진행 현황(누적 등록 수 / 상한)도 링크 상세에서 확인할 수 있습니다.

서버에서 확인 (선택)

API Key가 있다면 링크로 생성된 세션도 GET /v2/hosted-sessions/{id}로 서버에서 조회할 수 있습니다. 세션 ID는 콘솔의 세션 화면에서 확인합니다. 자세한 내용은 Server Integration의 세션 상태 폴링 항목을 참고하세요.

다음 단계

• Server Integration - 서버에서 세션 발급·신뢰 가능한 결과 수신
• Redirect URL과 결과 전달 - 허용 목록 관리와 리다이렉트 파라미터