KP-Link Open API 가이드

전자 봉투 상태 조회를 기준으로 위탁 처리와 선물 발송을 안전하게 연동하기 위한 공식 문서입니다.

Step 1. 환경 및 인증 Step 2. 실시간 조회 플로우 Step 3. 위탁·선물 처리 엔드포인트 상세 Webhook 연동 운영 가이드 샘플 코드

Step 1

환경 및 인증 설정

Base URL과 API 키 발급 절차를 확인하고 서버 간 통신 구조를 명확히 합니다.

Base URL

https://www.fastpt.kr/kplink/open-api/v1/

사용 가능한 경로는 고객센터를 통해 프로젝트 정보를 전달하면 안내해 드립니다.

https://www.fastpt.kr/kplink/open-api/v1 뒤에 엔드포인트를 바로 붙여 호출합니다.

인증 (Bearer Token)

모든 요청에 Authorization 헤더를 포함해야 합니다.

API 키는 고객센터를 통해 발급됩니다. 프로젝트 정보와 이용 목적을 전달해 주세요.

Authorization: Bearer kp_access_xxxxxxxxxxxxxxxxx

토큰은 서버 전용으로 사용하며 클라이언트, 로그, Front 코드에 노출하지 않습니다.

연결 확인

/envelope/holdings 호출로 네트워크 및 인증을 검증합니다.

사내 방화벽 사용 시 fastpt.kr 도메인 아웃바운드 허용이 필요합니다.

별도의 Sandbox는 제공하지 않으므로 개발 환경 구성은 연동사에서 자율적으로 준비해 주세요.

Step 2

실시간 조회 플로우

위탁/선물 처리 전, 항상 최신 상태를 API로 직접 조회합니다.

2-1. 링크 검증

GET /envelope/link로 e_key의 status, amount, expires_at을 확인합니다. status가 ready가 아니면 발송을 중단합니다.

2-2. 재고 확인

GET /envelope/holdings로 사용 가능한 봉투 재고를 조회합니다.

2-3. 위탁 상태 확인

GET /envelope/consignment로 이미 위탁된 건을 확인해 중복 위탁 및 발송을 방지합니다.

2-4. 이력 조회

GET /envelope/gift-history에 startDate·endDate를 전달해 사용·취소 이력을 조회하고 정산, 리포트, CS에 활용합니다.

Step 3

위탁 · 선물 처리

조회 결과를 기반으로 위탁 또는 선물 발송을 수행합니다.

위탁 처리 플로우

1. holdings/consignment 조회로 대상 봉투 상태 확인

2. POST /envelope/consignment로 위탁 요청 생성

3. GET /envelope/consignment 또는 Webhook으로 승인/거절 추적

4. 승인 완료 전 상태는 화면 노출 및 거래에서 제외

선물 발송 플로우

1. 직전 시점 GET /envelope/link로 ready 상태 재확인

2. 수신자 식별 값, senderName, message 세팅

3. POST /envelope/gift 호출 후 응답 상태 확인

4. Webhook과 /envelope/gift-history로 결과 추적

Reference

엔드포인트 상세

목록에서 선택하면 상세 정보, 파라미터, 예시 요청/응답을 확인합니다.

Endpoint 목록

GEThttps://www.fastpt.kr/kplink/open-api/v1/envelope/link

조회

봉투 링크 토큰(e_key)을 이용해 단일 봉투의 최신 상태를 조회합니다. 선물 발송 직전에 ready 여부를 재검증할 때 사용합니다.

Query Parameters

e_keystringrequired

봉투 링크 토큰. 호출 시점 기준 status, 금액, 만료 여부를 검증합니다.

Request 예시 (cURL)

curl -X GET "https://www.fastpt.kr/kplink/open-api/v1/envelope/link?e_key=ENVELOPE_TOKEN"

Response 예시

{
  "id": "env_1234567890",
  "e_key": "ENVELOPE_TOKEN",
  "status": "ready",
  "amount": 30000,
  "expires_at": "2025-12-31T14:59:59Z"
}

Step 4

Webhook 연동

상태 변경을 폴링 없이 수신하여 내부 시스템과 동기화합니다.

상태 알림 Webhook

HTTPS 엔드포인트만 허용합니다.
서명 헤더와 Webhook Secret으로 요청 유효성을 검증합니다.
2xx 외 응답 시 동일 이벤트가 재전송될 수 있으므로 멱등 처리해야 합니다.

POST /v1/webhooks/gifts
{
  "id": "evt_1234567890",
  "type": "gift.delivered",
  "data": {
    "gift_id": "gft_1234567890",
    "envelope_id": "env_1234567890",
    "delivered_at": "2025-11-05T12:34:56Z"
  },
  "signature": "t=1730790000,v1=..."
}

Step 5

운영 가이드

보안, 안정성, 관제 기준을 체크리스트로 정리했습니다.

보안 운영

Access Token은 최소 권한으로 발급하고 주기적으로 회전합니다.

토큰·Secret은 Secret Manager 또는 환경 변수에만 저장합니다.

로그·에러 메시지에 민감 정보를 노출하지 않습니다.

필요 시 IP 화이트리스트, WAF, VPN 등과 병행 운영합니다.

트래픽 · 멱등성

조회 API는 실시간 기준으로, 필요한 시점마다 직접 호출하는 것을 원칙으로 합니다.

429 응답 시 Retry-After를 기반으로 지수 백오프 재시도를 적용합니다.

POST /envelope/gift 등 상태 변경 API는 재시도 시 중복 발송이 될 수 있으므로 호출 전 상태를 다시 확인합니다.

에러 · 모니터링

에러는 공통 JSON 형식으로 반환됩니다.

에러 예시

{
  "error": {
    "code": "invalid_request",
    "message": "e_key is required",
    "field": "e_key",
    "request_id": "req_1234567890"
  }
}

code, field, request_id를 로그 및 알림에 포함하면 장애 분석과 KP-Link 지원 요청 시 추적이 용이합니다.

Example

Node.js 연동 예시

실제 운영 플로우에 바로 적용 가능한 최소 구현 샘플입니다.

Quick Start (Node.js + Axios)

샘플 코드 복사

import axios from "axios"

const client = axios.create({
    baseURL: "https://www.fastpt.kr/kplink/open-api/v1",
    headers: {
        Authorization: "Bearer kp_access_xxxxxxxxxxxxxxxxx"
    },
    timeout: 5000
})

async function sendGift() {
    const link = await client.get("/envelope/link", {
        params: { e_key: "ENVELOPE_TOKEN" }
    })

    if (link.data.status !== "ready") {
        throw new Error("Envelope not ready")
    }

    const res = await client.post("/envelope/gift", {
        e_key: "ENVELOPE_TOKEN",
        giftIdType: "sms",
        giftIdValue: "01012345678",
        senderName: "홍길동"
    })

    console.log(res.data)
}

sendGift().catch(console.error)