문서 소개

별도의 리워드 포털을 새로 구축하거나 벤더를 수동으로 조율할 필요 없이, 기존의 CRM, HRIS, 내부 운영 시스템에서 선물 이벤트 (gifting events)를 직접 오케스트레이션할 수 있습니다. API를 통해 애플리케이션이 참여 순간 (engagement moments)을 프로그래밍 방식으로 트리거, 관리, 모니터링하는 동안 Giftpack은 운영 이행 (fulfillment), 재고 가용성, 물류, 컴플라이언스를 처리합니다.

Giftpack은 전통적인 이커머스 API처럼 설계되지 않았습니다. 상품 카탈로그와 결제 트랜잭션 중심이 아니라 선물 흐름 (gifting)을 관계 이벤트로 모델링합니다. 수신자 식별, 타이밍, 비즈니스 맥락이 발송 상품과 함께 핵심 입력값으로 취급됩니다. 덕분에 온보딩, 기념일, 딜 클로징, 리텐션 캠페인, 고객 참여 마일스톤 같은 실제 트리거에 자연스럽게 통합할 수 있습니다.

API는 redemption 상태, fulfillment 진행 상황, 배송 추적 (delivery tracking)을 포함해 프로세스 각 단계의 라이프사이클 가시성을 제공합니다. 이를 통해 시스템에서 결과를 측정하고 후속 조치를 자동화하며 선물 흐름 (gifting)을 리포팅 및 운영 워크플로에 통합할 수 있습니다.

핵심 개념

시스템 관점에서 Giftpack은 다음 라이프사이클 모델을 따릅니다:

Intent → Campaign → Recipient → Redemption → Fulfillment → Tracking

각 단계는 참여 라이프사이클의 상태 전환을 의미합니다:

• Intent는 비즈니스 트리거나 목적을 정의합니다.
• Campaign은 참여 컨테이너 역할을 합니다.
• Recipient는 캠페인에 참여하는 대상을 나타냅니다.
• Redemption은 수신자의 액션을 기록합니다.
• Fulfillment는 운영 이행 프로세스를 처리합니다.
• Tracking은 후속 가시성과 분석을 제공합니다.

라이프사이클

비즈니스 이벤트
    │
    ▼
[ Intent ]
    │
    │  (동기 API)
    ▼
[ Campaign Created ]
    │
    │  (동기 API)
    ▼
[ Recipient Attached ]
    │
    │  (동기 API)
    ▼
[ Redemption Link Issued ]
    │
    │  ────── 사용자 액션 (비동기) ──────
    ▼
[ Redemption Claimed ]
    │
    │  (Webhook: giftee.preparing)
    ▼
[ Shipment Processing ]
    │
    │  (Webhook: giftee.shipped)
    ▼
[ Tracking / Delivered ]
    │
    │  (Webhook: giftee.delivered / giftee.failed / giftee.returned)
    ▼
[ Final Tracking State ]
    │
    │  (Webhook: giftee.reviewed)
    ●

이 모델은 스마트 선물 (smart gifting) AutoMatch™ 캠페인, 마켓플레이스 주문 (marketplace orders), 브랜디드 굿즈 워크플로 (swag workflows), 엔터프라이즈 자동화 유스케이스에 일관되게 적용됩니다. 특히 비동기·이벤트 기반 환경에서 안정적인 통합을 구축하려면 이 모델을 이해하는 것이 필수입니다.

용어 정의

이 정의 섹션은 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 Integration API의 모든 요청은 유효한 API Key로 인증되어야 합니다.

모든 엔드포인트에서 인증은 필수이며 workspace 경계 기준으로 강제됩니다. 인증이 없거나 잘못된 요청은 비즈니스 로직 실행 전에 거부됩니다.

API 키

각 Giftpack workspace는 Giftpack 대시보드에서 하나 이상의 API Key를 생성할 수 있습니다.

API Key의 목적:

• API 요청 인증
• 요청 원본 workspace 식별
• 리소스 수준 권한 부여 적용
• 사용 제어 및 rate limit 적용

API Key는 workspace-scoped 입니다. 생성된 workspace 외부 리소스에는 접근할 수 없습니다.

Giftpack은 workspace 간 API Key를 공유하지 않습니다.

API Key 발급

API Key 생성 방법:

1. Giftpack 대시보드에 로그인
2. Integration Hub → API Keys 이동
3. Giftpack Integration에서 새 API Key 생성

API Key는 생성 즉시 활성화됩니다. 키 생성 이벤트는 감사 및 추적 목적으로 내부에 기록됩니다.

API Key 사용

모든 요청의 X-API-KEY header에 API Key를 포함해야 합니다.

GET /v1/recipients HTTP/1.1
Host: developer.giftpack.ai
X-API-KEY: YOUR_API_KEY

유효한 API Key가 없는 요청은 인증 오류를 반환합니다. 인증은 요청 처리 및 리소스 평가 전에 수행됩니다.

권한 모델

권한은 workspace 수준에서 강제됩니다. API Key는 다음 리소스만 접근할 수 있습니다:

• Recipients
• Campaigns
• Marketplace Orders
• Swag Orders
• Credits
• Providers
• 해당 workspace에 속한 기타 리소스

workspace 간 접근은 엄격히 금지됩니다. 권한 결정은 서버 측에서 처리되며 클라이언트 파라미터로 우회할 수 없습니다.

키 생명주기 관리

엔터프라이즈 통합에서는 키 생명주기 관리가 필요합니다.

권장 사항:

• staging/production 환경별로 API Key 분리
• API Key 정기 교체
• 유출 의심 시 즉시 API Key 폐기
• 팀/시스템 간 API Key 공유 금지

API Key가 폐기되면 해당 키를 사용하는 모든 후속 요청은 거부됩니다.

Giftpack은 API Key 자동 교체를 제공하지 않습니다. 키 관리는 통합 조직의 책임입니다.

전송 보안

모든 API 요청은 HTTPS로 전송되어야 합니다.

• 최소 TLS 버전: TLS 1.2
• Plain HTTP 요청은 거부

전송 중 데이터는 업계 표준 TLS 암호화로 보호됩니다.

포함 항목:

• Recipient 데이터
• 배송 정보
• 주문 메타데이터
• 인증 headers

Giftpack은 비보안 전송 연결을 지원하지 않습니다.

속도 제한

플랫폼 안정성과 공정 사용을 위해 API 요청에는 rate limiting이 적용됩니다. 제한 초과 시 API는 다음을 반환합니다:

• HTTP 상태 429
• RATE_LIMIT_EXCEEDED 에러 코드

통합 시스템은 다음을 구현해야 합니다:

• 재시도 로직
• exponential backoff 전략
• 과도한 폴링 회피

대규모 또는 버스트 트래픽이 예상되면 Giftpack에 문의해 rate 설정을 협의하세요.

데이터 프라이버시 및 PII 처리

Giftpack API는 다음과 같은 개인정보(PII)를 처리할 수 있습니다:

• 수신자 이름
• 이메일 주소
• 배송 주소

개발자 책임:

• 데이터 처리의 합법적 근거 확보
• 필요한 경우 수신자 동의 확보
• 관련 규정(GDPR, CCPA 등) 준수
• 불필요한 데이터 저장 최소화

Giftpack은 선물 및 리워드 워크플로 수행 목적에 한해 데이터를 처리합니다. Giftpack은 수신자 데이터를 광고나 무관한 프로파일링에 사용하지 않습니다.

로깅 및 감사 고려사항

엔터프라이즈 환경에서 통합 시스템은 다음을 권장합니다:

• outbound API requests 로깅
• 응답 코드 및 오류 상태 로깅
• 비정상 인증 실패 모니터링
• 비정상 rate-limit 이벤트 모니터링

Giftpack 내부 로그 항목:

• 인증 시도
• 키 사용 내역
• 보안 관련 이벤트

인증 오류 응답

인증/권한 오류는 일관된 구조를 따릅니다.

{
  "error_code": "UNAUTHORIZED",
  "message": "Invalid or missing API key",
  "action": "Verify your API key and include it in the X-API-KEY header"
}

주요 인증 관련 오류 코드:

• UNAUTHORIZED
• FORBIDDEN
• RATE_LIMIT_EXCEEDED

보안 모범 사례

운영 환경 권장 사항:

• API Key를 안전한 환경 변수에 저장
• 프론트엔드 또는 client-side 앱에 API Key 노출 금지
• API Key를 버전 관리에 커밋하지 않기
• production key 내부 접근 최소화
• 가능한 경우 server-to-server 통합 사용

API Key 유출이 의심되는 경우:

1. 즉시 키를 폐기
2. 새 키 생성
3. 최근 API 로그에서 비정상 사용 확인

오류 처리 및 상태 맵

Giftpack API는 표준 HTTP 상태 코드를 사용하며 구조화된 오류 payload를 반환합니다.

모든 오류 응답에는 기계 판독 가능한 오류 코드와 request_id가 포함됩니다. 지원팀에 문의할 때는 반드시 request_id를 함께 제공하세요.

오류 응답 형식

모든 오류는 다음 구조를 따릅니다:

{
  "error": {
    "code": "invalid_request",
    "message": "Recipient email is required.",
    "request_id": "req_123"
  }
}

필드

• code – 기계 판독 가능한 오류 식별자
• message – 사람이 읽을 수 있는 설명
• request_id – 디버깅 추적을 위한 고유 요청 식별자

운영 트러블슈팅을 위해 request_id는 로그에 보관해야 합니다.

HTTP 상태 코드

Giftpack은 표준 HTTP 상태 의미를 사용합니다:

• 200 / 201 – 요청 성공
• 400 – 검증 실패 또는 잘못된 요청 형식
• 401 – API Key 누락 또는 무효
• 403 – 권한 부족
• 404 – 리소스 없음
• 409 – 충돌(예: 중복 리소스 또는 상태 위반)
• 429 – 속도 제한 초과
• 5xx – 서버 내부 오류

재시도 가이드라인

모든 오류를 재시도하면 안 됩니다.

안전하게 재시도 가능

• 429 (속도 제한 초과)
• 5xx (서버 오류)

재시도 시 exponential backoff를 사용하세요. 즉시 반복 재시도는 피하세요.

재시도 금지

• 400 (검증 오류)
• 401 / 403 (인증 또는 권한 오류)
• 404 (잘못된 리소스 참조)
• 409 (비즈니스 로직 충돌)

이 오류들은 재전송 전에 클라이언트 측 수정이 필요함을 의미합니다.

비동기 상태와 HTTP 상태

HTTP 성공 응답은 fulfillment 완료를 보장하지 않습니다.

예:

• 201 Created는 campaign 생성 성공만 의미
• redemption 완료를 의미하지 않음
• shipment 완료를 의미하지 않음
• delivery 완료를 의미하지 않음

Giftpack 작업은 비동기로 진행되는 경우가 많습니다.

라이프사이클 상태를 확인하려면:

• GET 엔드포인트로 리소스 상태를 조회
• 또는 webhook 이벤트를 구독

HTTP 성공은 “요청 수락”으로 해석하고, “업무 완료”로 해석하지 마세요.

멱등성 고려사항

통합에서 재시도를 수행한다면, 중복 요청으로 인한 부작용을 방지해야 합니다.

가능한 경우:

• 고유 external identifier 사용
• 자체 request tracking ID 저장
• 4xx 오류에 대한 무분별한 재시도 금지

Giftpack은 엔드포인트 로직에 따라 중복 리소스 생성을 거부할 수 있습니다.

속도 제한 동작

속도 제한 초과 시:

• HTTP 상태 429 반환
• 지연 후 재시도

통합 시스템은:

• exponential backoff 구현
• 촘촘한 폴링 루프 회피
• 빈번한 GET 폴링보다 webhook 기반 업데이트 선호

지원 및 진단

예상치 못한 오류가 발생하면:

• 전체 오류 payload 로깅
• request_id 기록
• Giftpack 지원팀 문의 시 request_id 제공

이렇게 하면 서버 로그에서 빠르게 추적할 수 있습니다.

Webhook 및 비동기 이벤트

Giftpack 워크플로는 비동기로 동작합니다.

API 성공 응답은 요청이 수락되었음을 의미할 뿐입니다. redemption, fulfillment, shipping, delivery 같은 라이프사이클 업데이트는 webhook 이벤트로 전달됩니다.

운영 환경 통합에서는 webhook을 기본 상태 업데이트 채널로 사용해야 합니다. 상태 endpoint 폴링은 정합성 확인 또는 복구 용도로만 사용하세요.

지원 이벤트 타입

Webhook 이벤트 타입은 Giftpack 대시보드에서 직접 관리/표시됩니다. 사용 가능한 트리거 확인 및 설정:

https://giftpack.ai/app/developer/webhooks

현재 운영 가능 이벤트의 기준은 대시보드 UI입니다.

현재 지원 예시:

• giftee.created
• giftee.launched
• giftee.preparing
• giftee.shipped
• giftee.delivered
• giftee.failed
• giftee.returned
• giftee.reviewed

이벤트 지원 범위는 변경될 수 있습니다. 운영 구성은 항상 대시보드를 기준으로 하세요.

Webhook 구성

Webhook은 workspace 단위로 대시보드에서 구성합니다. 각 구성에는 다음이 포함됩니다:

• name
• endpoint
• event_types
• active 토글
• workspace 범위의 secret key

구성 예시:

{
  "name": "Giftpack Delivery Updates",
  "endpoint": "https://example.com/webhooks/giftpack",
  "event_types": [
    "giftee.created",
    "giftee.shipped",
    "giftee.delivered"
  ]
}

하나의 workspace에 여러 webhook 구성을 둘 수 있습니다.

전달 모델

Webhook 전달은 at-least-once delivery 모델을 따릅니다.

즉:

• 동일 이벤트가 여러 번 전달될 수 있음
• 전달 순서가 엄격히 보장되지 않음
• 통합 측 핸들러는 멱등성 보장이 필요함

엔드포인트가 2xx HTTP 상태 코드를 반환하면 전달 성공으로 간주됩니다.

2xx가 아닌 응답은 재시도를 유발합니다.

수신 엔드포인트 계약

Webhook 엔드포인트는 다음을 충족해야 합니다:

• POST + JSON payload 수신
• 성공 확인을 위한 2xx HTTP 응답
• 합리적인 timeout 내 응답 완료
• 중복 이벤트 안전 처리

응답 예시:

HTTP/1.1 200 OK
Content-Type: application/json

{"ok": true}

중복 제거 키로 webhook event ID 사용을 권장합니다.

이벤트 로그 및 전달 시도

Giftpack 대시보드는 전체 webhook 이벤트 로그를 제공합니다. 각 이벤트에는 다음이 포함됩니다:

• 이벤트 메타데이터
• 원본 payload
• 전달 상태
• 시도 횟수
• 시도별 요청/응답 진단 데이터

로그 상태 코드:

• 0 – failed
• 1 – processing
• 2 – success

이벤트 상세 API는 다음을 제공합니다:

• Webhook event(논리 이벤트)
• Webhook event requests(개별 전달 시도)

이벤트 상세 예시:

{
  "webhook_event_id": "wev_01H...",
  "webhook_setting_id": "whs_01H...",
  "webhook_event_type": "giftee.shipped",
  "webhook_event_resource_type": "giftee",
  "webhook_event_resource_id": "gft_01H...",
  "webhook_event_status": 2,
  "webhook_event_attempts": 1,
  "webhook_event_data": "{...raw payload...}",
  "webhook_event_created_at": "2026-02-20T02:00:00.000Z",
  "webhook_event_updated_at": "2026-02-20T02:00:01.000Z"
}

각 시도 레코드는 다음을 포함합니다:

• 대상 endpoint
• HTTP 응답 상태
• 응답 headers
• 응답 body
• 타임스탬프

이 로그는 전달 추적성과 통합 디버깅을 크게 개선합니다.

Webhook 테스트 콘솔

Giftpack은 대시보드 내장 Webhook 테스트 콘솔을 제공합니다. 가능한 작업:

• webhook endpoint 선택
• 이벤트 타입 선택
• 시뮬레이션 payload 전송
• endpoint 실시간 응답 확인

활용:

• end-to-end 검증
• payload 점검
• 즉시 응답 진단

테스트 응답 예시:

{
  "event_data": {
    "type": "giftee.created",
    "resource_type": "giftee",
    "resource_id": "gft_01H..."
  },
  "response_http_status": "200",
  "response_http_headers": {"content-type": "application/json"},
  "response_http_body": "{\"ok\":true}"
}

테스트 콘솔은 운영 활성화 전 개발/검증 용도입니다.

전송 요구사항

현재 UI에서 http와 https를 모두 허용할 수 있어도, 운영 통합은 반드시 HTTPS를 사용해야 합니다.

HTTPS 사용 효과:

• 전송 구간 암호화
• 가로채기 방지
• 엔터프라이즈 보안 요구사항 충족

통합 베스트 프랙티스

안정적인 webhook 처리를 위해:

• 멱등 이벤트 처리 구현
• 모든 수신 이벤트 로깅
• 이벤트 ID 저장(중복 제거)
• handler 내부 장시간 동기 처리 지양
• 무거운 작업은 백그라운드 작업으로 위임
• 실패 전달 시도 모니터링

Webhook은 라이프사이클 업데이트의 권위 소스입니다. 동기 API 성공 응답을 최종 상태로 가정하지 마세요.

Webhook 서명 검증

Webhook 이벤트가 Giftpack에서 발생했고 변조되지 않았는지 확인하기 위해, 각 요청은 workspace별 secret으로 서명됩니다.

운영 통합에서는 서명 검증이 필수입니다.

서명 헤더 형식

각 webhook 요청은 다음 헤더를 포함합니다:

X-GIFTPACK-SIGNATURE: t=1708459200,v1=abcdef1234567890...

구성 요소

• t — Unix timestamp(초)
• v1 — HMAC SHA-256 서명

서명 생성 방식:

HMAC_SHA256(secret, `${timestamp}.${raw_body}`)

raw_body는 수신한 원문 그대로 사용해야 합니다.

검증 절차

검증 단계:

1. X-GIFTPACK-SIGNATURE 헤더 추출
2. t(timestamp), v1(signature) 파싱
3. JSON 파싱 전 raw body 확보
4. 계산:

expected_signature = HMAC_SHA256(secret, `${timestamp}.${raw_body}`)

1. timing-safe comparison으로 v1 비교
2. 아래 조건이면 거부:

• 서명이 일치하지 않음
• timestamp가 너무 오래됨(권장: 5분 초과)

리플레이 공격 방지

리플레이 공격 방지를 위해:

• timestamp가 허용 범위(±300초)인지 검증
• 처리된 event ID 저장 후 중복 거부
• 미서명 payload 거부

시간 윈도우 예시:

current_time - timestamp <= 300 seconds

예시 (Node.js)

const crypto = require('crypto');

function verifySignature(rawBody, signatureHeader, secret) {
  if (!signatureHeader) return false;

  const elements = signatureHeader.split(',');
  const timestamp = elements.find(e => e.startsWith('t='))?.split('=')[1];
  const signature = elements.find(e => e.startsWith('v1='))?.split('=')[1];

  if (!timestamp || !signature) return false;

  const payload = `${timestamp}.${rawBody}`;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  const isValid = crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );

  const currentTime = Math.floor(Date.now() / 1000);
  const tolerance = 300;

  if (Math.abs(currentTime - Number(timestamp)) > tolerance) {
    return false;
  }

  return isValid;
}

Express 예시:

app.post('/webhooks/giftpack',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-giftpack-signature'];
    const isValid = verifySignature(
      req.body.toString(),
      signature,
      process.env.GIFTPACK_WEBHOOK_SECRET
    );

    if (!isValid) {
      return res.status(400).send('Invalid signature');
    }

    const event = JSON.parse(req.body.toString());

    // Process event safely

    res.status(200).json({ ok: true });
});

Secret 관리

Webhook secret은:

• webhook 구성별 고유
• 환경 변수로 안전 저장
• client-side 코드 노출 금지
• 유출 의심 시 즉시 로테이션

secret을 로테이션하면 통합 설정도 즉시 갱신하세요.

실패 처리

서명 검증 실패 시:

• non-2xx HTTP 상태 반환
• payload 처리 금지
• 보안 모니터링용 실패 로그 기록

서명 실패가 반복되면 다음을 의심해야 합니다:

• secret 불일치
• endpoint 설정 오류
• 악성 트래픽

전달 모델 재확인

Webhook 전달은 at-least-once 모델입니다. 중복 이벤트가 발생할 수 있습니다.

사례 기반 구현

Giftpack API는 실제 비즈니스 워크플로를 중심으로 설계되었습니다.

엔드포인트를 직접 따라가기보다, 먼저 구현할 비즈니스 사례를 선택하세요. 각 사례는 다음을 설명합니다:

• 비즈니스 목적
• API 호출 순서
• 예상 라이프사이클
• 관련 webhook 이벤트

Webhook 서명 검증/처리 상세는 Webhook 및 비동기 이벤트 섹션을 참고하세요.

Create Campaign
      ↓
Add Giftee
      ↓
Generate Redemption Link
      ↓
Recipient Claims
      ↓
Order Processing
      ↓
Shipped
      ↓
Delivered / Failed / Returned

POST /v1/campaigns

POST /v1/giftees

POST /v1/campaigns/{campaignId}/giftees/{gifteeId}/redeemlink

giftee.created
giftee.launched
giftee.preparing
giftee.shipped
giftee.delivered
giftee.failed
giftee.returned
giftee.reviewed

Select Product
      ↓
Create Marketplace Order
      ↓
Preparing
      ↓
Shipped
      ↓
Delivered / Failed / Returned

GET /v1/providers/{providerCode}/products

GET /v1/providers/{providerCode}/products/{productId}

POST /v1/marketplaceorders

giftee.preparing
giftee.shipped
giftee.delivered
giftee.failed
giftee.returned

Enable Points
      ↓
Allocate Points
      ↓
Recipient Redeems
      ↓
Giftee Created
      ↓
Fulfillment Lifecycle

POST /v1/pointrecipients/{memberId}/enablepointfeature

PATCH /v1/pointrecipients/{memberId}/points

giftee.created
giftee.preparing
giftee.shipped
giftee.delivered
giftee.failed
giftee.returned