Server Integration

개요

Server Integration은 고객사 서버가 API로 1회용 촬영 세션을 사용자마다 발급하고, 완료 결과를 신뢰 가능한 형태로 서버에서 수신하는 방식입니다. Server API와 동일한 호스트·인증(x-petnow-api-key)을 사용합니다.

전체 라운드트립

1. 서버가 POST /v2/hosted-sessions로 세션을 발급받고, 응답의 1회용 웹 URL을 사용자에게 전달합니다.
2. 사용자가 Petnow 촬영 페이지에서 촬영을 마치면 브라우저가 redirectUrl로 복귀합니다. 완료 시 petify_code에 1회용 결과 코드가 담깁니다.
3. 서버가 GET /v2/hosted-results/{code}로 코드를 1회 소비하여 신뢰 가능한 결과를 받습니다.
4. 리다이렉트나 코드를 유실했다면 언제든 GET /v2/hosted-sessions/{id}로 같은 결과를 조회할 수 있습니다.

반려동물 식별 모델

이 API에서 반려동물은 고객사 시스템의 ID(externalPetId)로만 참조됩니다. Petify 내부 ID는 노출되지 않습니다. 등록(REGISTER) 시 externalPetId가 반려동물과 연결(매핑)되고, 이후 인증·검색 결과도 이 ID로 반환됩니다.

사전 준비

1. Petify Console에서 API Key를 발급합니다. (콘솔 Integration → API & SDK 탭에서도 관리할 수 있습니다.)
2. 콘솔의 Integration → Links → 허용 Redirect URL에서 사용할 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",
    "expiresInSeconds": 1800,
    "locale": "ko"
  }'

import requests

response = requests.post(
    "https://api.petify.petnow.io/v2/hosted-sessions",
    headers={
        "x-petnow-api-key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "action": "REGISTER",
        "species": "DOG",
        "redirectUrl": "https://your-service.example.com/petify/return",
        "externalPetId": "YOUR-PET-ID-123",
        "expiresInSeconds": 1800,
        "locale": "ko",
    },
)
session = response.json()["data"]
# session["id"]  → 폴링 핸들 (반드시 저장)
# session["url"] → 사용자에게 전달할 1회용 촬영 URL

const response = await fetch("https://api.petify.petnow.io/v2/hosted-sessions", {
  method: "POST",
  headers: {
    "x-petnow-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    action: "REGISTER",
    species: "DOG",
    redirectUrl: "https://your-service.example.com/petify/return",
    externalPetId: "YOUR-PET-ID-123",
    expiresInSeconds: 1800,
    locale: "ko"
  })
});

const { data: session } = await response.json();
// session.id  → 폴링 핸들 (반드시 저장)
// session.url → 사용자에게 전달할 1회용 촬영 URL

요청 파라미터

응답 (201)

{
  "success": true,
  "data": {
    "id": "8f6a1f9e-4c2d-4b7a-9e1a-2f3b4c5d6e7f",
    "url": "https://capture.petify.petnow.io/s/hs_QzR4c2VjcmV0dG9rZW4",
    "action": "REGISTER",
    "species": "DOG",
    "integrationMethod": "SERVER_INTEGRATION",
    "bindingSource": "SERVER_ISSUED",
    "externalPetId": "YOUR-PET-ID-123",
    "expiresAt": "2026-08-26T05:30:00Z",
    "createdAt": "2026-08-26T05:00:00Z",
    "mock": false
  }
}

체험(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
  }'

결과 수신

촬영이 끝나면 사용자 브라우저가 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"

import requests

response = requests.get(
    "https://api.petify.petnow.io/v2/hosted-results/hrc_1a2b3c4d5e6f",
    headers={"x-petnow-api-key": "YOUR_API_KEY"},
)
result = response.json()["data"]

const response = await fetch(
  "https://api.petify.petnow.io/v2/hosted-results/hrc_1a2b3c4d5e6f",
  { headers: { "x-petnow-api-key": "YOUR_API_KEY" } }
);
const { data: result } = await response.json();

응답 예시 (인증):

{
  "success": true,
  "data": {
    "sessionId": "8f6a1f9e-4c2d-4b7a-9e1a-2f3b4c5d6e7f",
    "action": "VERIFY",
    "externalPetId": "YOUR-PET-ID-123",
    "bindingTrusted": true,
    "outcome": "MATCH",
    "completedAt": "2026-08-26T05:10:00Z",
    "alreadyConsumed": false,
    "result": {
      "isVerified": true,
      "score": 93
    }
  }
}

기능별 result 스키마:

소비 규칙:

• 결과 코드 조회는 1회 소비(one-shot consume) 입니다. 코드는 세션 완료 후 약 10분간 유효합니다.
• 소비에 성공했지만 응답을 유실한 경우(타임아웃, 장애), 같은 API Key로 5분(기본) 안에 다시 조회하면 alreadyConsumed: true와 함께 동일한 결과가 반환됩니다. 그 이후에는 410이 반환됩니다.
• 코드 자체를 유실했다면 아래의 세션 폴링으로 대체하세요.

세션 상태 폴링

리다이렉트·코드 유실 시의 복구 경로이자, 세션 진행 상태를 확인하는 수단입니다. 소비형이 아니므로 여러 번 호출해도 됩니다.

엔드포인트: GET /v2/hosted-sessions/{id}

{
  "success": true,
  "data": {
    "id": "8f6a1f9e-4c2d-4b7a-9e1a-2f3b4c5d6e7f",
    "linkId": null,
    "action": "VERIFY",
    "species": "DOG",
    "integrationMethod": "SERVER_INTEGRATION",
    "bindingSource": "SERVER_ISSUED",
    "externalPetId": "YOUR-PET-ID-123",
    "bindingTrusted": true,
    "status": "COMPLETED",
    "outcome": "MATCH",
    "errorCode": null,
    "result": { "isVerified": true, "score": 93 },
    "expiresAt": "2026-08-26T05:30:00Z",
    "completedAt": "2026-08-26T05:10:00Z",
    "createdAt": "2026-08-26T05:00:00Z"
  }
}

세션 상태 (status):

• outcome은 COMPLETED일 때만 채워집니다: 등록 SUCCEEDED, 인증·검색 MATCH / NO_MATCH.

• FAILED의 errorCode는 닫힌 enum이 아닌 일반 문자열이므로 목록이 늘어날 수 있다고 가정하세요. 현재 값:

  errorCode	의미
  CAPTURE_FAILED	촬영에서 결과를 만들지 못함 (예: 품질 부족)
  DUPLICATE_EXTERNAL_PET_ID	완료 시점에 open 모드의 중복 externalPetId가 감지됨
  IDENTIFICATION_NOT_IN_PLAN / IDENTIFICATION_PLAN_SELECTION_REQUIRED	IDENTIFY 세션이 발급과 최종 제출 사이에 검색 권한을 잃음 (예: 사용자가 촬영하는 동안 플랜 변경). 제출이 거부되고 결과는 생성되지 않으며 과금되지 않습니다. 브라우저 리다이렉트에는 petify_code=FEATURE_UNAVAILABLE이 붙습니다. 이 코드들은 향후 릴리즈부터 반환될 수 있습니다. 지금 미리 처리해 두면 전환 시 영향이 없습니다

• 이 엔드포인트는 Link Integration 링크로 생성된 세션도 조회할 수 있습니다 (링크 세션은 linkId가 채워지고, 사용자 전달 externalPetId는 bindingTrusted: false).

에러 코드

에러 응답은 { "errors": [{ "code": "..." }] } 형식입니다. PETNOWB2B10001(요청 검증 실패)은 details 필드로 필드별 오류를 함께 반환합니다.

다음 단계

• Redirect URL과 결과 전달 - 허용 목록 관리와 리다이렉트 파라미터
• Link Integration - 콘솔에서 링크 발급·관리