시작하기

Giftpack API를 사용하면 리워드, 인센티브, 굿즈, 수신자 선택 워크플로를 백엔드에서 생성하고 운영할 수 있습니다. 비즈니스 트리거와 고객 데이터는 고객사의 시스템에서 관리하고, 카탈로그 가용성, 수신자 경험, 풀필먼트, 배송 상태 업데이트는 Giftpack이 처리합니다.

프로덕션 환경의 기본 URL은 다음과 같습니다.

https://developer.giftpack.ai

전체 요청 및 응답 스키마는 API Reference에서 확인하세요. 이 가이드에서는 적합한 리소스 패밀리를 선택하는 방법과 생성 후 각 리소스의 상태가 어떻게 전환되는지 설명합니다.

워크플로 선택

리소스 모델

Smart Gifting에서는 Campaign이 프로그램 컨테이너 역할을 하고, Giftee가 수신자별 라이프사이클을 나타냅니다.

Campaign -> Giftee -> Redemption -> Fulfillment -> Delivery

카탈로그 직접 주문에서는 Marketplace Order가 주문 컨테이너 역할을 하고, Marketplace Order Receiver가 수신자별 라이프사이클을 나타냅니다.

Marketplace Order -> Receiver -> Claim or Selection -> Fulfillment -> Delivery

giftee와 marketplace_order_receiver를 서로 바꿔 사용할 수 있는 개념으로 취급하지 마세요. 풀필먼트 상태가 비슷해 보이더라도 이벤트 이름은 서로 다른 주문 패밀리를 식별합니다.

요청 라이프사이클

생성 및 업데이트 요청은 현재 리소스 상태를 반환합니다. 수신자의 작업, 풀필먼트, 발송, 배송은 이후에도 비동기로 진행됩니다.

안정적인 연동을 위해 다음 사항을 준수하세요.

• 반환된 리소스 ID를 저장합니다.
• 해당 Webhook 이벤트 패밀리를 구독합니다.
• Webhook 이벤트의 id를 중복 제거 키로 사용합니다.
• 이벤트 누락이나 지연이 감지되면 GET 엔드포인트로 상태를 대조합니다.
• API 작업에 멱등성 계약이 명시되어 있지 않다면 상태 변경 요청을 자동으로 재시도하지 않습니다.

첫 번째 요청

Giftpack에서 API 키를 생성한 후 Webhook 이벤트 카탈로그를 조회하여 접근 권한을 확인하세요.

curl https://developer.giftpack.ai/v1/webhookeventtypes \
  --header 'Accept: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY'

응답에는 현재 API가 지원하는 Webhook 이벤트 타입이 나열됩니다. 하드코딩된 클라이언트 목록이 아니라 이 엔드포인트가 공식 이벤트 카탈로그입니다.

다음 단계

1. API 키를 저장하거나 사용하기 전에 인증 및 보안을 확인합니다.
2. 구현 레시피에서 워크플로를 선택합니다.
3. 프로덕션 연동을 시작하기 전에 Webhook을 구성하고 검증합니다.
4. 엔드포인트별 필수 필드와 응답 모델은 API Reference에서 확인합니다.

용어 정의

이 정의 섹션은 Giftpack API 통합에서 사용하는 핵심 도메인 객체를 설명합니다. 워크플로를 구축하기 전에 객체 간 관계를 이해하는 것이 중요합니다. Giftpack은 세 가지 주요 레이어로 동작합니다:

1. 참여 레이어 (Engagement Layer)
2. 커머스 레이어 (Commerce Layer)
3. 공급 및 운영 레이어 (Supply & Operations Layer)

Recipient
  └─ may belong to Recipient Group
  └─ becomes Giftee when attached to Campaign

Campaign (Engagement Container)
  ├─ defines Redemption rules
  ├─ manages Giftee states
  └─ may generate Fulfillment Orders

Commerce Layer
  ├─ Marketplace Order (direct transaction)
  └─ Swag Order (inventory-based transaction)

Redemption
  ├─ Link-based
  ├─ Email-based
  └─ Transitions state before fulfillment

인증 및 보안

Giftpack의 주요 /v1 작업은 워크스페이스 범위 API 키를 X-API-KEY 헤더에 담아 사용합니다. API 키는 신뢰할 수 있는 서버 측 애플리케이션에서만 사용해야 합니다.

접근 요구사항

API 키는 Developer Settings에서 관리할 수 있습니다. 워크스페이스와 현재 사용자에게 Giftpack Open API 기능 접근 권한 및 필요한 개발자 설정 권한이 있어야 합니다.

Developer 페이지를 사용할 수 없다면 연동 개발을 시작하기 전에 워크스페이스 관리자에게 워크스페이스 요금제와 본인의 역할을 확인하세요.

키 생성 및 보관

1. Giftpack에 로그인합니다.
2. Developer Settings를 엽니다.
3. 사용할 환경에 맞는 API 키를 생성합니다.
4. 키를 서버 측 시크릿 관리자에 저장합니다.

API 키를 브라우저 JavaScript, 모바일 애플리케이션, 로그, 스크린샷, 지원 티켓 또는 버전 관리 시스템에 포함하지 마세요.

스테이징과 프로덕션에는 서로 다른 인증 정보를 사용하세요. 키가 노출되었을 가능성이 있다면 즉시 폐기하세요.

요청 인증

curl https://developer.giftpack.ai/v1/webhookeventtypes \
  --header 'Accept: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY'

API 키는 워크스페이스를 식별합니다. 리소스 권한은 서버 측에서 적용되므로 다른 워크스페이스의 ID를 알아도 해당 리소스에 접근할 수 없습니다.

환경 및 전송

• 프로덕션 요청은 https://developer.giftpack.ai로 전송합니다.
• 모든 요청에 HTTPS를 사용합니다.
• 인증 정보는 환경별 시크릿 저장소에 보관합니다.
• 로컬 개발 환경에서 프로덕션 키를 재사용하지 않습니다.

API Reference의 일부 커넥터 작업은 Bearer Token 또는 공급자별 인증을 사용합니다. 각 작업에 표시된 보안 스키마를 따르고, Giftpack API 키로 커넥터 엔드포인트를 호출할 수 있다고 가정하지 마세요.

운영 수칙

• 조직의 보안 정책에 따라 인증 정보를 교체합니다.
• 키 접근 권한을 해당 키가 필요한 서비스로 제한합니다.
• 요청 및 오류 로그에서 X-API-KEY를 마스킹합니다.
• 지원 진단을 위해 작업, 리소스 ID, HTTP 상태, 타임스탬프를 기록합니다.
• API 요청 인증과 별도로 Webhook 서명을 검증합니다.

공개 API 계약은 모든 작업에 공통으로 적용되는 속도 제한이나 단일 재시도 정책을 보장하지 않습니다. 제공되는 경우 엔드포인트별 헤더와 API Reference를 확인하고, 대량의 버스트 요청을 계획하기 전에 Giftpack에 문의하세요.

오류 및 복구

Giftpack 작업은 표준 HTTP 상태 코드를 사용합니다. API Reference에 문서화된 오류 응답의 미디어 타입은 application/problem+json입니다.

Problem 응답

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Property email is required but is missing.",
  "instance": "https://developer.giftpack.ai/errors/example",
  "errors": [
    {
      "location": "body.email",
      "message": "The email field is required.",
      "value": null
    }
  ]
}

필드

• type: 문제 유형을 식별하는 URI입니다. about:blank일 수 있습니다.
• title: 사람이 읽을 수 있는 일관된 문제 요약입니다.
• status: 이 응답에 해당하는 HTTP 상태입니다.
• detail: 이번에 발생한 구체적인 실패에 대한 설명입니다.
• instance: 제공되는 경우 이번 오류 발생을 식별하는 URI입니다.
• errors: location, message, value를 포함하는 선택적 필드 단위 세부 정보입니다.

모든 오류에 모든 필드가 포함된다고 보장할 수 없습니다. 선택적 필드가 생략되거나 향후 알 수 없는 필드가 추가되어도 처리할 수 있도록 파서를 구현하세요.

상태별 복구 방법

각 작업에 문서화된 응답은 API Reference가 공식 기준입니다.

안전한 재시도

GET 요청은 일반적으로 상한을 둔 지수 백오프로 재시도할 수 있습니다. 상태 변경 요청은 더 신중하게 처리해야 합니다.

• 타임아웃 후 POST 또는 PATCH 요청을 무조건 재시도하지 않습니다.
• 먼저 해당 작업에 멱등성이 명시되어 있는지, 또는 대조 가능한 리소스를 반환하는지 확인합니다.
• 다음 단계로 진행하기 전에 반환된 ID를 영구 저장합니다.
• 엔드포인트에서 지원하는 경우 자체 비즈니스 참조 필드를 사용합니다.
• 여러 워커가 동일한 논리 작업을 제출하지 못하도록 방지합니다.

전송 타임아웃은 클라이언트가 응답을 받지 못했다는 뜻일 뿐, 서버가 요청을 완료하지 않았음을 증명하지는 않습니다.

지원 진단 정보

문제를 에스컬레이션할 때는 엔드포인트, 메서드, UTC 타임스탬프, HTTP 상태, 관련 리소스 ID, 민감 정보를 마스킹한 Problem 응답을 제공하세요. API 키나 마스킹되지 않은 수신자 데이터는 절대 포함하지 마세요.

Webhook 및 비동기 이벤트

Webhook은 API 요청이 반환된 후 발생하는 수신자 및 풀필먼트 상태 전환을 알립니다. Webhook을 주요 라이프사이클 신호로 사용하고, 상태 대조에는 GET 작업을 사용하세요.

이벤트 카탈로그

이전 목록을 하드코딩하지 말고 현재 카탈로그를 조회하세요.

curl https://developer.giftpack.ai/v1/webhookeventtypes \
  --header 'Accept: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY'

현재 카탈로그에는 두 개의 리소스 패밀리가 있습니다.

giftee

연동을 통해 시작된 Campaign, 예약 프로그램, 자동 리워드 워크플로를 포함한 Smart Gifting 주문의 수신자 라이프사이클 이벤트입니다.

• giftee.created
• giftee.launched
• giftee.preparing
• giftee.shipped
• giftee.delivered
• giftee.failed
• giftee.returned
• giftee.reviewed
• giftee.cancel
• giftee.resume
• giftee.delete

marketplace_order_receiver

Smart Gifting Campaign 워크플로 외부에서 Gift Mall 또는 Merchandise Catalog를 통해 직접 주문한 건의 수신자 라이프사이클 이벤트입니다.

• marketplace_order_receiver.created
• marketplace_order_receiver.launched
• marketplace_order_receiver.shipped
• marketplace_order_receiver.delivered
• marketplace_order_receiver.failed
• marketplace_order_receiver.returned
• marketplace_order_receiver.reviewed
• marketplace_order_receiver.delete

페이로드 계약

각 전달 항목은 JSON 객체입니다. data는 구조화된 리소스 스냅샷이며 이스케이프된 JSON 문자열이 아닙니다.

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "type": "giftee.shipped",
  "data": {
    "id": "23e4567-e89b-12d3-a456-426655440000",
    "type": "giftee",
    "email": "recipient@example.com",
    "status": 12,
    "delivery_status": 2,
    "budget": 100,
    "campaign": {
      "id": "323e4567-e89b-12d3-a456-426655440000"
    },
    "recipient": {
      "id": "423e4567-e89b-12d3-a456-426655440000"
    },
    "delivery_tracking_code": "TRACKING-CODE"
  },
  "created_at": "2026-09-01 15:23:33"
}

• id는 영구적인 이벤트 발생 ID이며 중복 제거 키로 사용해야 합니다.
• type은 리소스 패밀리와 상태 전환을 식별합니다.
• data는 이벤트 발생 시점의 리소스 상태를 담습니다. 필드는 리소스 패밀리와 라이프사이클 단계에 따라 달라집니다.
• created_at은 이벤트 발생 시각입니다. 전달 순서가 뒤바뀔 수 있으므로 상태 전환의 순서를 정할 때 이 값을 사용하세요.
• 삭제 이벤트는 활성 리소스가 제거된 후에도 마지막으로 저장된 스냅샷을 유지합니다.

서명 검증

Giftpack은 원본 요청 본문의 HMAC-SHA256 다이제스트를 소문자 16진수 문자열로 계산하여 X-Giftpack-Signature에 담아 전송합니다.

const crypto = require('crypto');

function verifyGiftpackWebhook(rawBody, signature, secret) {
  if (!signature) return false;

  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const actualBuffer = Buffer.from(signature, 'utf8');
  const expectedBuffer = Buffer.from(expected, 'utf8');

  return (
    actualBuffer.length === expectedBuffer.length &&
    crypto.timingSafeEqual(actualBuffer, expectedBuffer)
  );
}

페이로드를 파싱하거나 처리하기 전에 서명을 검증하세요. Webhook 시크릿은 서버 측 시크릿 저장소에 보관합니다.

전달 및 재시도 동작

• Giftpack은 JSON 본문이 포함된 HTTP POST를 전송합니다.
• 2xx 응답은 전달 성공으로 처리됩니다.
• 요청은 최대 60초 동안 열린 상태로 유지될 수 있습니다.
• 전달 실패 시 약 1분, 5분, 15분 후에 재시도합니다. 최초 요청을 포함해 최대 4번 전달을 시도합니다.
• 중복 전달이 발생할 수 있습니다. id를 기준으로 멱등하게 처리하세요.
• 전달 순서는 보장되지 않습니다.

이벤트를 검증하고 영구적으로 수락한 후 신속하게 2xx를 반환하세요. 처리 비용이 큰 작업은 큐로 넘깁니다.

이벤트 로그 상태

Webhook 이벤트 및 요청 로그는 다음 숫자 상태를 사용합니다.

• -1: 실패
• 0: 처리 중
• 1: 성공

이벤트 상세 응답에는 문제 해결을 위한 구조화된 webhook_event_data, 시도 횟수, 개별 요청 레코드가 포함됩니다.

프로덕션 체크리스트

• 워크플로에서 생성하는 이벤트 패밀리만 구독합니다.
• 변경되지 않은 원본 본문을 기준으로 X-Giftpack-Signature를 검증합니다.
• 이벤트 id로 중복을 제거합니다.
• created_at을 저장하고 이벤트가 순서 없이 도착해도 처리할 수 있도록 합니다.
• 이벤트를 안전하게 수락한 후에만 2xx를 반환합니다.
• 실패 상태에 도달한 이벤트를 모니터링합니다.
• 프로덕션 엔드포인트를 활성화하기 전에 대시보드 테스트 기능을 사용합니다.

구현 레시피

수신자가 리워드를 받는 방식에 맞는 리소스 패밀리를 선택하세요. 모든 필수 필드와 응답 모델은 API Reference가 공식 기준입니다.

curl https://developer.giftpack.ai/v1/marketplaceorders \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "marketplace_order_name": "September employee rewards",
    "marketplace_order_start_date": "2026-09-01",
    "marketplace_order_end_date": "2026-09-30",
    "marketplace_order_type": "Normal",
    "submit": false,
    "receivers": [
      {
        "member_id": "9a1232aa-238f-421c-82e7-45693d1b25b4",
        "country": "US",
        "gift_message": "Thank you for your contribution.",
        "email_notification": true,
        "sms_notification": false,
        "marketplace_feature": false,
        "donation_feature": false,
        "products": [
          {
            "marketplace_product_id": "961be65a-88d8-4040-8808-843ccf5da624",
            "marketplace_product_variant_id": "961be65a-a96a-412d-b22a-325f07d85647",
            "product_quantity": 1
          }
        ]
      }
    ]
  }'

curl https://developer.giftpack.ai/v1/pointrecipients/MEMBER_ID/points \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "credits": 1,
    "points": 100,
    "expired_at": "2027-09-01",
    "notes": "Annual recognition allocation"
  }'

프로덕션 전 확인 사항

• 현재 API Reference를 기준으로 필수 필드를 검증합니다.
• 프로덕션용이 아닌 수신자와 인증 정보로 테스트합니다.
• 반환된 모든 리소스 ID를 영구 저장합니다.
• 해당 Webhook 이벤트 패밀리를 구성합니다.
• 서명을 검증하고 이벤트 중복을 제거합니다.
• 상태 변경 요청을 재시도하기 전에 타임아웃 발생 시 시스템에서 상태를 대조하는 방법을 정의합니다.