Petnow LogoPetnow
Web Integration

Link Integration

Petify Console에서 촬영 링크를 발급·관리하고, 링크로 생성된 세션의 결과를 확인하는 방법을 안내합니다.

개요

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

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

링크 생성에는 결제수단 등록이 선행되어야 합니다. 결제수단 미등록 시 링크 생성 단계로 진행되지 않습니다. 자세한 절차는 Petify Console 문서를 참고하세요.

링크 생성

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

필드필수설명
이름✅링크를 구분하는 이름 (최대 120자)
기능✅등록 / 인증 / 검색 중 하나. 생성 후 변경할 수 없습니다
대상 동물조건부강아지 / 고양이. 등록·검색 링크에만 지정하며, 생성 후 변경할 수 없습니다. 인증 링크는 대상 반려동물의 종을 자동으로 따릅니다
Redirect URL✅촬영 완료 후 사용자가 돌아갈 전체 URL. 허용 목록에 없는 URL을 입력하면 링크 생성과 함께 자동 등록됩니다
등록 상한조건부등록 링크에만 지정합니다. 이 링크로 등록할 수 있는 반려동물 수의 상한 (기본 100, 최소 1)
체험(mock)❌카메라 대신 샘플 반려동물을 사용하는 체험(mock) 링크를 만듭니다. 생성 후 변경할 수 없습니다
  • 다른 종류의 대상 동물로 운영하려면 링크를 새로 만드세요.
  • 검색 링크는 지정한 대상 동물과 같은 종으로 등록된 반려동물 중에서만 후보를 찾습니다.
  • 검색(IDENTIFY) 기능은 플랜에 검색이 포함된 경우에만 선택할 수 있습니다.
  • Redirect URL 형식 규칙(HTTPS, 예약 파라미터 등)은 Redirect URL과 결과 전달을 참고하세요.

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

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

체험(mock) 링크

체험(mock) 플래그를 켜고 만든 링크는 실제 동물 없이 전체 파이프라인을 검증하는 용도입니다. 이 링크로 생성되는 모든 세션은 카메라를 건너뛰고 내장된 샘플 반려동물 선택 화면을 보여주며, 선택한 이미지는 실제 품질 검사 → 등록·매칭 → 결과 → 리다이렉트 과정을 그대로 거칩니다.

  • 플래그는 생성 후 변경할 수 없습니다 — 실서비스 링크를 체험 링크로 바꾸거나 그 반대도 불가능합니다. 용도별로 링크를 따로 만드세요.
  • 과금, 상한, 결과, 세션 목록은 일반 링크와 동일합니다. 등록된 반려동물, 결과, 콘솔의 세션 화면 어디에도 mock 표시가 남지 않으며, 플래그는 링크 자체에서만 확인할 수 있습니다.
  • 체험 등록 링크는 클릭 URL에 externalPetId가 없으면 플로우가 mock-<12 hex> 형식의 ID를 자동 발급하므로, 콘솔에 표시된 URL을 그대로 열 수 있습니다. ID를 직접 붙이면 일반 등록 규칙이 적용됩니다.
  • 체험 링크로 등록된 반려동물도 링크 상한에 포함되고 과금 대상입니다 — 테스트가 끝나면 콘솔에서 삭제하세요 (Petify Console 참고). 체험 링크를 실제 사용자에게 배포하지 마세요.

링크 URL 전달하기

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

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

https://capture.petify.petnow.io/l/hl_2Xy7Qa9Kd3Lm4Np5Rs6Tu?externalPetId=YOUR-PET-ID-123
기능externalPetId
등록✅ 필수 — 이 ID로 반려동물이 등록됩니다. 이미 등록된 ID면 촬영이 차단됩니다
인증✅ 필수 — 이 ID로 등록된 반려동물과 비교합니다. 등록 이력이 없는 ID면 촬영이 차단됩니다
검색❌ 무시 — 링크 URL을 그대로 전달하면 됩니다

링크 URL의 externalPetId는 사용자 브라우저를 거쳐 전달되는 값이므로 위·변조될 수 있습니다. 콘솔의 결과 화면과 서버 조회 결과에는 이 값이 신뢰 불가(bindingTrusted: false) 로 표시됩니다. 결과를 근거로 중요한 의사결정을 해야 한다면 Server Integration을 사용하세요.

externalPetId 매핑은 Web Integration의 등록을 통해서만 생성됩니다. 기존 모바일 SDK나 Server API로 등록한 반려동물에는 매핑이 없어 인증 대상으로 지정할 수 없으며, 기존 반려동물에 매핑을 추가하는 기능은 제공되지 않습니다. 인증·검색을 사용하려면 대상 반려동물이 먼저 Web Integration 등록을 거쳐야 합니다.

진입이 차단되는 경우

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

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

진입이 차단되면 세션이 생성되지 않으므로 Redirect URL로의 이동도 일어나지 않습니다. 고객사 완료 페이지는 호출되지 않고 콘솔 결과 목록에도 남지 않으므로, petify_status=failed를 기다리는 방식으로는 감지할 수 없습니다. 링크를 전달하기 전에 ID의 중복·등록 여부를 고객사 쪽에서 미리 확인하는 것을 권장합니다.

링크 상태

상태의미
활성사용자가 링크를 열어 촬영할 수 있습니다
비활성직접 비활성화한 링크. 새 촬영 진입이 차단됩니다. 다시 활성화하기 전까지 유지됩니다
상한 도달등록 상한에 도달해 자동으로 중지된 등록 링크. 상한을 현재 등록 수보다 높이면 자동으로 다시 활성화됩니다
플랜 제한현재 플랜에서 검색 기능을 사용할 수 없어 중지된 검색 링크. 링크와 설정은 유지되며, 검색이 포함된 플랜으로 변경하면 자동으로 복구됩니다 (직접 비활성화한 링크는 자동 복구되지 않습니다)
  • 링크에는 만료일이나 자동 종료가 없습니다 — 비활성화·삭제·상한 도달 전까지 계속 사용할 수 있습니다.
  • 활성/비활성 전환은 링크 상세 화면에서 즉시 적용됩니다.
  • 비활성화·삭제는 새 촬영 진입뿐 아니라 아직 접수되지 않은 제출도 차단합니다. 다만 최종 제출이 이미 접수된 세션은 이후 링크 상태가 바뀌어도 끝까지 처리됩니다.

링크 관리

  • 수정: 이름, 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가 곧 등록 성공을 의미하며, 추가로 조회할 것이 없습니다. 등록된 반려동물의 상세 정보는 콘솔에서 확인합니다.

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

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

// 고객사 완료 페이지 (프런트엔드)
const KEY = "petify_code";
const url = new URL(window.location.href);
let code = url.searchParams.get(KEY);
if (code) {
  // 새로고침에 대비해 코드를 보관한 뒤 주소창에서 제거
  sessionStorage.setItem(KEY, code);
  window.history.replaceState(null, "", url.pathname);
} else {
  code = sessionStorage.getItem(KEY);
}

if (code) {
  try {
    const response = await fetch(
      `https://api.petify.petnow.io/v2/hosted-results/${code}:display`
    );
    if (!response.ok) throw new Error(`display read failed: ${response.status}`);
    const { data } = await response.json();
    // data.action, data.outcome, data.completedAt, data.result (아래 참고)
  } catch {
    // 네트워크(CORS) 오류 또는 404: "결과를 불러올 수 없음" 표시
  }
}

이 호출은 GET /v2/hosted-results/{code}:display입니다(레퍼런스). 브라우저에서 비밀 API Key(x-petnow-api-key)를 보내지 마세요. 이 경로는 키가 필요 없습니다. 공용 fetch나 axios 기본 설정 등으로 이 헤더가 추가된 요청은 CORS preflight에서 실패합니다.

성공 응답은 표준 봉투(envelope) { "success": true, "data": { ... } } 형식입니다. data에는 다음이 담깁니다:

필드설명
actionVERIFY 또는 IDENTIFY
outcomeMATCH 또는 NO_MATCH. null일 수 있습니다
completedAt세션 완료 시각. null일 수 있습니다
result기능별 결과(아래). null일 수 있습니다

점수는 0에서 100 사이입니다.

인증:

{
  "success": true,
  "data": {
    "action": "VERIFY",
    "outcome": "MATCH",
    "completedAt": "2026-10-31T09:12:44Z",
    "result": { "isVerified": true, "score": 93 }
  }
}

검색:

{
  "success": true,
  "data": {
    "action": "IDENTIFY",
    "outcome": "MATCH",
    "completedAt": "2026-10-31T09:12:44Z",
    "result": {
      "candidates": [
        { "externalPetId": "YOUR-PET-ID-123", "score": 91 },
        { "externalPetId": "YOUR-PET-ID-456", "score": 68 }
      ],
      "unmappedCandidates": 1
    }
  }
}

일치하는 후보가 없으면 검색 결과는 "outcome": "NO_MATCH", "candidates": []입니다.

  • candidates는 가장 유사한 후보가 먼저 오도록 정렬됩니다. 활성 externalPetId가 없는 매칭 반려동물은 목록에서 빠지고 unmappedCandidates로 집계됩니다.
  • 응답에는 임계값, Petify Pet ID, 반려동물 프로필, 기타 내부 ID가 노출되지 않습니다. 이런 정보는 콘솔에서 확인합니다.
  • 코드는 세션 완료 후 약 10분간 유효합니다. 1회용이 아니므로 만료될 때까지 여러 번 조회할 수 있어, 결과 화면을 새로고침해도 계속 동작합니다(위 예시는 이를 위해 코드를 sessionStorage에 보관합니다). 만료되면 조회가 실패합니다.
  • 읽을 수 있는 404({ "errors": [{ "code": "PETNOWB2B21005" }] })는 실제 Link Integration 코드이면서 만료됐거나 아직 완료되지 않은 경우에만 돌아옵니다. 없는 코드, 잘못 입력한 코드, Server Integration 코드는 응답에 CORS 헤더가 없으므로 브라우저에서는 fetch()가 네트워크(CORS) 오류로 거부됩니다. 두 경우 모두 "결과를 불러올 수 없음"으로 처리하세요.
  • 429(PETNOWB2B21009)는 한 클라이언트 주소 또는 한 계정에서 조회가 너무 많다는 뜻입니다. Retry-After 헤더의 초만큼 기다린 뒤 다시 시도하세요. 없는 코드에 대한 429도 CORS 헤더가 없어 브라우저에서는 네트워크 오류로 보입니다.

CORS. 브라우저는 세션을 시작한 Redirect URL의 origin(scheme://host[:port])에서만 이 경로를 조회할 수 있습니다. 호출하는 페이지가 그 origin과 같아야 하며, 다른 origin에서의 호출은 CORS로 차단됩니다. 복귀 흐름에서 사용자가 다른 호스트나 포트로 이동한다면(예: example.com에서 app.example.com), 결과 페이지가 실행되는 origin에 Redirect URL을 등록하세요.

코드를 안전하게 다루기

유효 기간 안에 코드를 얻은 사람은 누구나 결과를 조회할 수 있으므로, 수명이 짧은 비밀값처럼 다루세요.

  • externalPetId에 개인정보를 넣지 마세요. 검색 결과에 그대로 반환됩니다.
  • 코드를 읽은 즉시 주소창에서 제거하세요(예시의 history.replaceState). 새로고침용으로는 sessionStorage에만 보관하세요.
  • 결과 페이지는 Referrer-Policy: no-referrer 헤더로 응답하세요. 서드파티 리소스로 Referer를 통해 코드가 새는 것을 막습니다.
  • 표시용 조회는 사용자에게 결과를 보여주는 용도로만 사용하세요. 비즈니스·보안 의사결정에는 아래의 서버 교환을 사용하세요. 링크 세션의 externalPetId는 보증되지 않는 값입니다(bindingTrusted: false).

이전 경로. GET /hosted/v1/results/{code}:display는 최소 2026년 11월 30일(UTC)까지 계속 동작하며 이후 제거됩니다. 이 경로의 응답에는 Deprecation, Sunset, Link: ...; rel="successor-version" 헤더가 붙습니다. GET /v2/hosted-results/{code}:display로 전환하세요. 성공 응답 본문은 그대로입니다. 이 페이지의 이전 버전은 최상위 isVerified를 보여줬지만, 두 경로 모두 result.isVerified로 반환합니다. 경로와 오류 형식만 다릅니다. 새 경로는 hosted envelope 대신 v2 오류 envelope({ "errors": [{ "code": "..." }] })을 반환합니다.

콘솔에서 확인

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

서버에서 확인 (선택)

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

비밀 API Key로 호출하는 서버 교환 GET /v2/hosted-results/{code}도 Link Integration 세션의 petify_code를 받습니다. 코드는 한 번 소비되며(Server Integration과 같은 재조회 유예 적용), 링크 세션에는 bindingTrusted: false가 보고됩니다. externalPetId가 사용자 브라우저를 거친 값이므로, 결과가 어느 반려동물의 것인지에 따라 의사결정이 달라진다면 Server Integration(서버가 발급한 세션)을 사용하세요. 코드를 소비해도 코드가 만료될 때까지 브라우저의 표시용 조회는 계속 동작합니다.

다음 단계

On this page