Server Integration
고객사 서버에서 촬영 세션을 발급하고, 신뢰 가능한 결과를 수신하는 Server Integration API를 안내합니다.
개요
Server Integration은 고객사 서버가 API로 1회용 촬영 세션을 사용자마다 발급하고, 완료 결과를 신뢰 가능한 형태로 서버에서 수신하는 방식입니다. Server API와 동일한 호스트·인증(x-petnow-api-key)을 사용합니다.
| 항목 | 값 |
|---|---|
| Base URL | https://api.petify.petnow.io |
| 인증 | x-petnow-api-key 헤더 (API Key 발급) |
| 응답 형식 | 성공: { "success": true, "data": ... } / 실패: { "errors": [{ "code": "PETNOWB2B..." }] } |
전체 라운드트립
- 서버가
POST /v2/hosted-sessions로 세션을 발급받고, 응답의 1회용 웹 URL을 사용자에게 전달합니다. - 사용자가 Petnow 촬영 페이지에서 촬영을 마치면 브라우저가
redirectUrl로 복귀합니다. 완료 시petify_code에 1회용 결과 코드가 담깁니다. - 서버가
GET /v2/hosted-results/{code}로 코드를 1회 소비하여 신뢰 가능한 결과를 받습니다. - 리다이렉트나 코드를 유실했다면 언제든
GET /v2/hosted-sessions/{id}로 같은 결과를 조회할 수 있습니다.
반려동물 식별 모델
이 API에서 반려동물은 고객사 시스템의 ID(externalPetId)로만 참조됩니다. Petify 내부 ID는 노출되지 않습니다. 등록(REGISTER) 시 externalPetId가 반려동물과 연결(매핑)되고, 이후 인증·검색 결과도 이 ID로 반환됩니다.
매핑은 Web Integration의 등록을 통해서만 생성됩니다. 기존 모바일 SDK나 Server API(/v2/pets)로 등록한 반려동물에는 매핑이 없으므로 인증 대상으로 지정할 수 없고(404 PETNOWB2B21002), 검색에서도 후보 ID로 반환되지 않고 unmappedCandidates 개수로만 집계됩니다. 기존 반려동물에 매핑을 추가하는 기능은 제공되지 않습니다.
사전 준비
- Petify Console에서 API Key를 발급합니다. (콘솔 Integration → API & SDK 탭에서도 관리할 수 있습니다.)
- 콘솔의 Integration → Links → 허용 Redirect URL에서 사용할 Redirect URL을 미리 등록합니다.
Server Integration은 허용 목록에 사전 등록된 Redirect URL만 사용할 수 있습니다(정확 일치). 미등록 URL로 세션을 발급하면 400 에러(PETNOWB2B21003)가 반환됩니다. 등록 규칙은 Redirect URL과 결과 전달을 참고하세요.
세션 발급
엔드포인트: POST /v2/hosted-sessions
요청
curl -X POST "https://api.petify.petnow.io/v2/hosted-sessions" \
-H "x-petnow-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"action": "REGISTER",
"species": "DOG",
"redirectUrl": "https://your-service.example.com/petify/return",
"externalPetId": "YOUR-PET-ID-123"
}'요청 필드(action, species, redirectUrl, externalPetId, petMetadata, expiresInSeconds, locale, mock), 응답, 에러 응답은 호스티드 세션 발급에 있습니다. externalPetId는 REGISTER와 VERIFY에서 필수이고 IDENTIFY에서는 보내면 안 됩니다. VERIFY에서 species는 대상 펫의 종과 같아야 합니다.
id는 반드시 저장하세요 — 발급 시점에 자체 사용자·주문 정보와 함께 저장해 두면 결과의sessionId·externalPetId를 그 값과 대응시켜 어떤 사용자의 건인지 확정할 수 있고, 리다이렉트가 유실됐을 때 결과를 조회할 유일한 수단이기도 합니다.url은 발급 응답에서 한 번만 제공되며 다시 조회할 수 없습니다. 각url은 한 명의 사용자에게 한 번만 전달하세요 — 같은 URL을 여러 채널로 재전송하는 설계는 피해야 합니다. 전달에 실패하면 재전송 대신 새 세션을 발급하세요.
체험(mock) 세션
"mock": true로 발급하면 실제 동물 없이 연동을 검증·평가할 수 있는 체험 세션이 됩니다. url을 연 사용자는 카메라 대신 내장된 샘플 반려동물을 선택하며, 그 이후 — 품질 검사, 등록·매칭, 소비·폴링하는 결과, 리다이렉트, 과금, 상한 — 는 모두 실제 파이프라인입니다.
curl -X POST "https://api.petify.petnow.io/v2/hosted-sessions" \
-H "x-petnow-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"action": "REGISTER",
"species": "DOG",
"redirectUrl": "https://your-service.example.com/petify/return",
"externalPetId": "TEST-PET-001",
"mock": true
}'- 등록된 반려동물과 결과에는 mock 표시가 어디에도 남지 않습니다 — 이 요청/응답 쌍에만 있습니다. mock 등록도 실제 과금 대상 등록이므로, 테스트 후 콘솔에서 테스트 반려동물을 삭제하세요 (Petify Console 참고).
externalPetId규칙은 동일합니다: ID는 고객사 서버가 직접 발급합니다.- mock
url을 실제 사용자에게 전달하지 마세요.
결과 수신
촬영이 끝나면 사용자 브라우저가 redirectUrl로 이동하며 petify_status(및 조건부 petify_code)가 쿼리 파라미터로 추가됩니다. 파라미터 규칙 전체는 Redirect URL과 결과 전달을 참고하세요.
호스팅 세션이 만든 작업은 현재 Webhook 이벤트를 보내지 않으므로, 아래의 결과 코드와 세션 폴링을 사용하세요.
결과 코드 소비
petify_status=completed로 받은 1회용 결과 코드를 서버에서 교환합니다.
엔드포인트: GET /v2/hosted-results/{code}
curl -X GET "https://api.petify.petnow.io/v2/hosted-results/hrc_1a2b3c4d5e6f" \
-H "x-petnow-api-key: YOUR_API_KEY"기능별 result(REGISTER, VERIFY, IDENTIFY)를 포함한 응답은 결과 코드로 결과 조회에 있습니다. IDENTIFY 결과에서 externalPetId 매핑이 없는 후보는 목록에서 제외되고 unmappedCandidates에 개수로 집계됩니다.
소비 규칙:
- 결과 코드 조회는 1회 소비(one-shot consume) 입니다. 코드는 세션 완료 후 약 10분간 유효합니다.
- 소비에 성공했지만 응답을 유실한 경우(타임아웃, 장애), 같은 API Key로 5분(기본) 안에 다시 조회하면
alreadyConsumed: true와 함께 동일한 결과가 반환됩니다. 그 이후에는 410이 반환됩니다. - 코드 자체를 유실했다면 아래의 세션 폴링으로 대체하세요.
- 이 교환은 Link Integration 세션의 결과 코드도 받으며, 이 경우
bindingTrusted: false가 보고됩니다.
세션 상태 폴링
리다이렉트·코드 유실 시의 복구 경로이자, 세션 진행 상태를 확인하는 수단입니다. 소비형이 아니므로 여러 번 호출해도 됩니다.
엔드포인트: GET /v2/hosted-sessions/{id}
세션 필드, status 값, errorCode 값은 호스티드 세션 조회에 있습니다.
outcome은COMPLETED일 때만 채워집니다: 등록SUCCEEDED, 검증·식별MATCH/NO_MATCH.FAILED의errorCode는 닫힌 enum이 아닌 일반 문자열입니다. 값 목록이 늘어날 수 있다고 가정하세요.IDENTIFY세션은 발급과 최종 제출 사이에 식별 권한을 잃을 수 있습니다(예: 사용자가 촬영하는 동안 플랜 변경). 이때 서버는 제출을 거부하고 결과를 만들지 않으며 과금하지 않습니다. 브라우저 리다이렉트에는petify_code=FEATURE_UNAVAILABLE이 붙고, 세션은IDENTIFICATION_NOT_IN_PLAN또는IDENTIFICATION_PLAN_SELECTION_REQUIRED로 실패합니다. 이 코드들을 미리 처리해 두세요.- 이 엔드포인트는 Link Integration 링크로 생성된 세션도 조회할 수 있습니다 (링크 세션은
linkId가 채워지고, 사용자 전달externalPetId는bindingTrusted: false).
에러 코드
각 레퍼런스 페이지에 해당 엔드포인트의 에러 응답이 에러 코드별 예시와 함께 있습니다: 호스티드 세션 발급, 호스티드 세션 조회, 결과 코드로 결과 조회. 각 코드의 의미와 해결 방법은 에러 코드를 참고하세요.
API 레퍼런스
다음 단계
- Redirect URL과 결과 전달 - 허용 목록 관리와 리다이렉트 파라미터
- Link Integration - 콘솔에서 링크 발급·관리