빠른 시작

# bash + openssl + curl. 키·시크릿은 환경변수로 넘깁니다(명령 기록에 남지 않게).
URL="https://api.billingplus.co.kr/api/v1/ping"
PATH_Q="/${URL#*://*/}"                      # 서명할 경로 — 쿼리가 있으면 쿼리까지
TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
BODY=""
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | sed 's/^.*= //')
SIG=$(printf '%s\n%s\n%s\n%s\n%s' "GET" "$PATH_Q" "$TS" "$NONCE" "$BODY_HASH" \
  | openssl dgst -sha256 -hmac "$BILLINGPLUS_API_SECRET" -hex | sed 's/^.*= //')

curl -s "$URL" \
  -H "X-BillingPlus-Key: $BILLINGPLUS_API_KEY" \
  -H "X-BillingPlus-Timestamp: $TS" \
  -H "X-BillingPlus-Nonce: $NONCE" \
  -H "X-BillingPlus-Signature: $SIG"

{
  "ok": true,
  "tenant": "예시상점",
  "api_key": "bpk_live_3…9f2e",
  "server_time": "2026-10-28T05:00:03.512031+00:00"
}

import hashlib
import hmac
import json
import os
import secrets
import time
from urllib.parse import urlsplit

import requests

API_BASE = "https://api.billingplus.co.kr/api/v1"
API_KEY = os.environ["BILLINGPLUS_API_KEY"]        # bpk_live_ 로 시작
API_SECRET = os.environ["BILLINGPLUS_API_SECRET"]  # bos_ 로 시작 — 서버에만 둡니다


def sign(method: str, path_with_query: str, timestamp: str, nonce: str,
         body: bytes, secret: str) -> str:
    body_hash = hashlib.sha256(body).hexdigest()          # 본문이 없으면 b"" 의 해시
    message = "\n".join([method.upper(), path_with_query, timestamp, nonce, body_hash])
    return hmac.new(secret.encode("utf-8"), message.encode("utf-8"),
                    hashlib.sha256).hexdigest()


def call(method: str, path: str, payload=None, idempotency_key: str | None = None):
    """path 예: "/ping", "/customers?limit=5" — 기준 주소 뒤에 붙는 부분"""
    method = method.upper()
    url = API_BASE + path
    parts = urlsplit(url)
    path_with_query = parts.path + (f"?{parts.query}" if parts.query else "")

    body = b"" if payload is None else json.dumps(
        payload, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
    timestamp = str(int(time.time()))                      # 밀리초가 아니라 초
    nonce = secrets.token_hex(16)                          # 요청마다 새 32자

    headers = {
        "X-BillingPlus-Key": API_KEY,
        "X-BillingPlus-Timestamp": timestamp,
        "X-BillingPlus-Nonce": nonce,
        "X-BillingPlus-Signature": sign(method, path_with_query, timestamp, nonce,
                                        body, API_SECRET),
    }
    if body:
        headers["Content-Type"] = "application/json; charset=utf-8"
    if method == "POST":
        if not idempotency_key:
            raise ValueError("POST 에는 Idempotency-Key 가 필요합니다. "
                             "재시도 때 같은 값을 쓰도록 미리 만들어 저장하세요.")
        headers["Idempotency-Key"] = idempotency_key

    # 서명한 바이트를 그대로 보냅니다. json= 으로 넘기면 다시 직렬화되어 서명이 어긋날 수 있습니다.
    return requests.request(method, url, data=body, headers=headers, timeout=(5, 60))


if __name__ == "__main__":
    print(call("GET", "/ping").json())

res = call("POST", "/ping", {"hello": "빌링플러스"}, idempotency_key="ping-check-0001")
print(res.status_code, res.json())
# 200 {'ok': True, 'tenant': '예시상점', 'idempotency_key': 'ping-check-0001', 'received_bytes': 27}

res = call("POST", "/ping", {"hello": "빌링플러스"}, idempotency_key="ping-check-0001")
print(res.headers.get("Idempotent-Replay"))   # "true" — 다시 실행하지 않고 처음 응답을 돌려줬다