Server API 개요

개요

Petnow Server API는 서버에서 직접 호출하여 반려동물 생체 인식 기능을 구현할 수 있는 RESTful API입니다. 모바일 SDK의 API Module 대신 서버에서 직접 API를 호출하는 것을 권장합니다.

왜 Server API를 사용해야 하나요?

API Key를 서버에서 안전하게 관리할 수 있습니다
클라이언트 앱의 네트워크 오류에 독립적으로 처리할 수 있습니다
비즈니스 로직과 데이터 처리를 서버에서 통합 관리할 수 있습니다

Base URL

환경	URL
Production	`https://api.petify.petnow.io`

API 문서(Redoc): https://api.petify.petnow.io/redoc

인증

모든 API 요청에는 x-petnow-api-key 헤더가 필요합니다.

curl -X GET "https://api.petify.petnow.io/v2/pets" \
  -H "x-petnow-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

import requests

headers = {
    "x-petnow-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

response = requests.get(
    "https://api.petify.petnow.io/v2/pets",
    headers=headers
)

const response = await fetch("https://api.petify.petnow.io/v2/pets", {
  method: "GET",
  headers: {
    "x-petnow-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
});

API Key 발급

API Key는 Petnow 담당자에게 이메일로 요청하여 발급받을 수 있습니다.

연락처: support@petnow.io

API Key는 서버에서만 사용하고, 클라이언트 앱에 포함하지 마세요. API Key가 노출되면 즉시 담당자에게 연락하여 재발급 받으세요.

캡처 세션 개념

API v2는 캡처 세션(Capture Session) 개념을 사용합니다. 생체 정보를 업로드하고 처리하는 전체 과정을 세션으로 관리합니다.

세션 생명주기

세션 상태

상태	설명
`STARTED`	세션이 활성화되어 업로드를 받을 준비가 됨
`FINISHED`	캡처된 데이터로 세션이 성공적으로 종료됨
`ABORTED`	세션이 취소되거나 실패함
`TIMEOUT`	세션이 정상적으로 종료되지 않고 만료됨

세션 목적(Purpose)

Purpose	설명	Pet ID 필요
`PET_PROFILE_REGISTRATION`	새 반려동물 등록	✅ Yes
`PET_VERIFICATION`	특정 반려동물 검증 (1:1)	✅ Yes
`PET_IDENTIFICATION`	반려동물 식별 (1:N)	❌ No

전체 워크플로우

반려동물 등록 플로우

반려동물 검증 플로우

반려동물 식별 플로우

API 엔드포인트 요약

캡처 세션

메서드	엔드포인트	설명
POST	`/v2/capture-sessions`	캡처 세션 생성

펫 관리

메서드	엔드포인트	설명
POST	`/v2/pets`	펫 생성
GET	`/v2/pets`	펫 목록 조회
GET	`/v2/pets/{petId}`	펫 상세 조회
PATCH	`/v2/pets/{petId}`	펫 정보 수정
DELETE	`/v2/pets/{petId}`	펫 삭제

생체 정보 업로드

메서드	엔드포인트	설명
POST	`/v2/fingerprints:upload?sessionId={sessionId}`	지문(코) 이미지 업로드
POST	`/v2/appearances:upload?sessionId={sessionId}`	외관 이미지 업로드

검증 및 식별

메서드	엔드포인트	설명
POST	`/v2/pets/{petId}:addFingerprints`	지문 추가
POST	`/v2/pets/{petId}:verify`	펫 검증
POST	`/v2/pets:identify`	펫 식별

작업 상태 조회

메서드	엔드포인트	설명
GET	`/v2/fingerprint-addition-jobs/{jobId}`	지문 추가 작업 상태
GET	`/v2/verification-jobs/{jobId}`	검증 작업 상태
GET	`/v2/identification-jobs/{jobId}`	식별 작업 상태