REST API

API 문서

강력한 REST API로 애플리케이션에 배송 라벨을 통합하세요. 실시간 요금 조회, 라벨 생성, 배송 추적을 프로그래밍 방식으로 수행할 수 있습니다.

인증

모든 API 요청은 API 키와 시크릿을 사용한 인증이 필요합니다. 모든 요청에 다음 헤더를 포함하세요:

headers

X-API-Key: your_api_key
X-API-Secret: your_api_secret

보안 주의사항

API 시크릿을 안전하게 보관하세요. 클라이언트 측 코드나 공개 저장소에 노출하지 마세요.

요청 예시

bash

curl -X GET https://uspostage.io/api/v1/account/balance \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

계정 잔액

암호화폐 지갑 잔액과 거래 내역을 확인합니다. API는 결제에 암호화폐 지갑(BTC, LTC, LTCT)을 사용합니다.

GET

/api/v1/account/balance

암호화폐 지갑 잔액 및 거래 조회

쿼리 파라미터

파라미터	타입	필수	설명
includeTransactions	`boolean`	선택	거래 내역 포함
currency	`string`	선택	통화별 거래 필터링 (BTC, LTC, LTCT)
limit	`number`	선택	거래 수 (기본값: 20, 최대: 100)

요청 예시

bash

curl -X GET "https://uspostage.io/api/v1/account/balance?includeTransactions=true&limit=10" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

응답

json

{
  "success": true,
  "data": {
    "balances": [
      { "currency": "BTC", "balance": 0.00125000 },
      { "currency": "LTC", "balance": 0.50000000 },
      { "currency": "LTCT", "balance": 0.00000000 }
    ],
    "supportedCurrencies": ["BTC", "LTC", "LTCT"],
    "transactions": [
      {
        "id": "txn_abc123",
        "currency": "BTC",
        "type": "deposit",
        "amount": 0.00100000,
        "balanceAfter": 0.00125000,
        "description": "Deposit via CoinPayments",
        "createdAt": "2024-01-10T12:00:00Z"
      },
      {
        "id": "txn_def456",
        "currency": "BTC",
        "type": "label_purchase",
        "amount": -0.00015000,
        "balanceAfter": 0.00025000,
        "description": "API labels purchase for order USP-12345678",
        "createdAt": "2024-01-09T15:30:00Z"
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "total": 25,
      "hasMore": true
    }
  }
}

자금 추가

지갑에 자금을 추가하려면 내 지갑 페이지를 방문하여 BTC, LTC 또는 LTCT(테스트넷)로 입금하세요.

주소 확인

배송 주소를 확인하고 표준화하여 배송 가능성을 보장합니다.

POST

/api/v1/shipping/verify-address

배송 주소 확인 및 수정

요청 본문

파라미터	타입	필수	설명
address	`Address`	필수	확인할 주소
strict	`boolean`	선택	엄격한 확인 모드 활성화

요청 예시

bash

curl -X POST https://uspostage.io/api/v1/shipping/verify-address \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "address": {
      "name": "John Doe",
      "street1": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US"
    }
  }'

응답

json

{
  "success": true,
  "data": {
    "verified": true,
    "addressId": "adr_abc123",
    "verifiedAddress": {
      "name": "JOHN DOE",
      "street1": "123 MAIN ST",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip": "94102-1234",
      "country": "US"
    },
    "verification": {
      "success": true,
      "errors": []
    }
  }
}

배송 요금

USPS, UPS, FedEx, DHL 등 여러 운송업체의 실시간 배송 요금을 조회합니다.

POST

/api/v1/shipping/rates

패키지 배송 요금 계산

요청 본문

파라미터	타입	필수	설명
fromAddress	`Address`	필수	발송인 주소 객체
toAddress	`Address`	필수	수신인 주소 객체
packageDetails	`Package`	필수	패키지 크기 및 무게
carriers	`string[]`	선택	특정 운송업체 필터링 (USPS, UPS, FEDEX, DHL)
customsInfo	`CustomsInfo`	선택	국제 배송 시 필수

주소 객체

파라미터	타입	필수	설명
name	`string`	필수	전체 이름
company	`string`	선택	회사명
street1	`string`	필수	주소 1
street2	`string`	선택	주소 2
city	`string`	필수	도시
state	`string`	필수	주/도 코드
zip	`string`	필수	우편번호
country	`string`	필수	국가 코드 (US, CA 등)
phone	`string`	선택	전화번호
email	`string`	선택	이메일 주소

패키지 객체

파라미터	타입	필수	설명
length	`number`	필수	길이 (인치)
width	`number`	필수	너비 (인치)
height	`number`	필수	높이 (인치)
weight	`number`	필수	무게 (온스)

CustomsInfo 객체

국제 배송

국제 배송 시 필수 (fromAddress.country와 toAddress.country가 다른 경우).

파라미터	타입	필수	설명
contents_type	`string`	필수	내용물 유형: documents, gift, merchandise, returned_goods, sample, dangerous_goods, humanitarian_donation, other
contents_explanation	`string`	선택	contents_type이 'other'인 경우 필수
customs_certify	`boolean`	필수	true여야 함 - 신고 정확성 인증
customs_signer	`string`	필수	세관 신고서를 인증하는 사람의 이름
eel_pfc	`string`	필수	수출 면제 코드 ($2,500 미만 배송의 경우 'NOEEI 30.37(a)' 사용)
non_delivery_option	`string`	필수	배송 불가 시 조치: 'return' 또는 'abandon'
restriction_type	`string`	필수	제한 유형: 'none', 'other', 'quarantine', 또는 'sanitary_phytosanitary_inspection'
restriction_comments	`string`	선택	restriction_type이 'none'이 아닌 경우 필수
customs_items	`CustomsItem[]`	필수	배송 품목 배열 (1-100개 품목)

CustomsItem 객체

파라미터	타입	필수	설명
description	`string`	필수	품목의 상세 설명
quantity	`number`	필수	품목 수량 (최소: 1)
value	`number`	필수	USD 가치 (0보다 커야 함)
weight	`number`	필수	무게 (온스, 0보다 커야 함)
origin_country	`string`	필수	2자리 국가 코드 (예: 'US', 'CN')
hs_tariff_number	`string`	필수	6-10자리 HS 관세 코드

요청 예시

bash

curl -X POST https://uspostage.io/api/v1/shipping/rates \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "fromAddress": {
      "name": "John Doe",
      "street1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US"
    },
    "toAddress": {
      "name": "Jane Smith",
      "street1": "456 Oak Ave",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90001",
      "country": "US"
    },
    "packageDetails": {
      "length": 10,
      "width": 8,
      "height": 4,
      "weight": 16
    }
  }'

응답

json

{
  "success": true,
  "data": {
    "shipmentId": "shp_abc123",
    "rates": [
      {
        "id": "rate_xyz789",
        "carrier": "USPS",
        "service": "Priority Mail",
        "rate": 8.95,
        "currency": "USD",
        "delivery_days": 2,
        "delivery_date": "2024-01-15"
      },
      {
        "id": "rate_def456",
        "carrier": "UPS",
        "service": "Ground",
        "rate": 12.50,
        "currency": "USD",
        "delivery_days": 5,
        "delivery_date": "2024-01-18"
      }
    ]
  }
}

국제 배송 예시

국제 배송의 경우 품목 신고가 포함된 customsInfo 객체를 포함하세요:

bash

curl -X POST https://uspostage.io/api/v1/shipping/rates \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "fromAddress": {
      "name": "John Doe",
      "street1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US",
      "phone": "4155551234"
    },
    "toAddress": {
      "name": "Jane Smith",
      "street1": "456 Queen St W",
      "city": "Toronto",
      "state": "ON",
      "zip": "M5V 2A8",
      "country": "CA",
      "phone": "4165551234"
    },
    "packageDetails": {
      "length": 10,
      "width": 8,
      "height": 4,
      "weight": 16
    },
    "customsInfo": {
      "contents_type": "merchandise",
      "customs_certify": true,
      "customs_signer": "John Doe",
      "eel_pfc": "NOEEI 30.37(a)",
      "non_delivery_option": "return",
      "restriction_type": "none",
      "customs_items": [
        {
          "description": "Cotton T-Shirt",
          "quantity": 2,
          "value": 25.00,
          "weight": 8,
          "origin_country": "US",
          "hs_tariff_number": "6109100010"
        }
      ]
    }
  }'

주문 생성

배송 주문을 생성하고 관리합니다. 주문에는 하나 이상의 배송 라벨 항목이 포함됩니다.

GET

/api/v1/orders

모든 주문 조회

POST

/api/v1/orders

새 주문 생성

GET

/api/v1/orders/{id}

주문 상세 조회

주문 목록 - 쿼리 파라미터

파라미터	타입	필수	설명
limit	`number`	선택	결과 수 (기본값: 50, 최대: 100)
offset	`number`	선택	페이지네이션 오프셋

주문 생성 - 요청 본문

파라미터	타입	필수	설명
items	`OrderItem[]`	필수	주문 항목 배열
email	`string`	선택	고객 이메일
externalReference	`string`	선택	참조 ID

OrderItem 객체

간소화된 API

shipmentId와 rateId만 필수입니다. 주소, 패키지 세부정보, 세관 정보는 배송에서 자동으로 추출됩니다.

파라미터	타입	필수	설명
shipmentId	`string`	필수	요금 엔드포인트의 배송 ID
rateId	`string`	필수	요금 엔드포인트의 요금 ID

예시: 주문 생성

bash

curl -X POST https://uspostage.io/api/v1/orders \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "items": [
      {
        "shipmentId": "shp_abc123",
        "rateId": "rate_xyz789"
      }
    ],
    "externalReference": "ORDER-12345"
  }'

응답

json

{
  "success": true,
  "data": {
    "orderId": "ord_abc123",
    "trackingId": "USP-12345678",
    "totalAmount": 8.95,
    "paymentStatus": "pending",
    "items": [
      {
        "orderItemId": "item_xyz789",
        "rateId": "rate_xyz789"
      }
    ]
  }
}

라벨 구매

주문의 모든 항목에 대한 배송 라벨을 구매합니다. 라벨은 암호화폐 지갑 잔액(BTC, LTC 또는 LTCT)으로 구매됩니다.

POST

/api/v1/labels/purchase

주문용 배송 라벨 구매

요청 본문

암호화폐 결제

API가 라벨 비용을 USD에서 현재 환율로 암호화폐로 변환합니다. 충분한 잔액이 필요합니다 (가격 변동에 대비한 10% 버퍼 포함).

파라미터	타입	필수	설명
orderId	`string`	필수	라벨을 구매할 주문 ID
currency	`string`	선택	결제에 사용할 암호화폐 (BTC, LTC, LTCT). 지정하지 않으면 충분한 잔액이 있는 첫 번째 통화가 자동 선택됩니다.

요청 예시

bash

curl -X POST https://uspostage.io/api/v1/labels/purchase \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "orderId": "ord_abc123",
    "currency": "BTC"
  }'

응답

json

{
  "success": true,
  "data": {
    "orderId": "ord_abc123",
    "externalReference": "ORDER-12345",
    "totalLabels": 2,
    "successCount": 2,
    "failCount": 0,
    "labels": [
      {
        "orderItemId": "item_xyz789",
        "success": true,
        "trackingCode": "9400111899223456789012",
        "labelUrl": "https://easypost.com/labels/lbl_abc123.pdf",
        "carrier": "USPS",
        "service": "Priority Mail",
        "labelFormats": {
          "pdf": "https://easypost.com/labels/lbl_abc123.pdf",
          "png": "https://easypost.com/labels/lbl_abc123.png"
        }
      },
      {
        "orderItemId": "item_def456",
        "success": true,
        "trackingCode": "9400111899223456789013",
        "labelUrl": "https://easypost.com/labels/lbl_def456.pdf",
        "carrier": "FedEx",
        "service": "Ground",
        "labelFormats": {
          "pdf": "https://easypost.com/labels/lbl_def456.pdf"
        }
      }
    ]
  }
}

402 잔액 부족

지갑 잔액이 부족하면 API가 필요한 암호화폐 금액과 함께 402 상태를 반환합니다.

잔액 부족 응답

json

{
  "success": false,
  "error": "Insufficient balance",
  "message": "Need 0.00011000 BTC (includes 10% buffer), have 0.00005000",
  "currency": "BTC",
  "required": 0.00011000,
  "requiredUsd": 5.50,
  "available": 0.00005000,
  "balanceEndpoint": "/api/v1/account/balance"
}

추적

구매한 라벨의 추적 코드를 사용하여 배송을 추적합니다.

GET

/api/v1/tracking/{code}

추적 정보 조회

경로 파라미터

파라미터	타입	필수	설명
code	`string`	필수	추적 코드

요청 예시

bash

curl -X GET https://uspostage.io/api/v1/tracking/9400111899223456789012 \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

응답

json

{
  "success": true,
  "data": {
    "trackingCode": "9400111899223456789012",
    "carrier": "USPS",
    "status": "in_transit",
    "statusDetail": "In Transit to Next Facility",
    "estDeliveryDate": "2024-01-15T00:00:00Z",
    "publicUrl": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111899223456789012",
    "trackingDetails": [
      {
        "status": "in_transit",
        "message": "In Transit to Next Facility",
        "datetime": "2024-01-12T14:30:00Z",
        "location": "San Francisco, CA"
      },
      {
        "status": "accepted",
        "message": "Accepted at USPS Origin Facility",
        "datetime": "2024-01-11T09:15:00Z",
        "location": "San Francisco, CA"
      }
    ],
    "updatedAt": "2024-01-12T14:30:00Z"
  }
}

Webhooks

라벨 생성이나 추적 업데이트와 같은 이벤트 발생 시 실시간 알림을 받습니다.

GET

/api/v1/webhooks

등록된 webhooks 조회

POST

/api/v1/webhooks

새 webhook 등록

GET

/api/v1/webhooks/{id}

webhook 상세 조회

DELETE

/api/v1/webhooks/{id}

webhook 삭제

사용 가능한 이벤트

label.created

라벨이 성공적으로 구매되었을 때

label.failed

라벨 생성이 실패했을 때

Webhook 등록 - 요청 본문

파라미터	타입	필수	설명
webhookUrl	`string`	필수	webhook 이벤트를 수신할 URL
events	`string[]`	필수	구독할 이벤트 유형 배열

예시: Webhook 등록

bash

curl -X POST https://uspostage.io/api/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "webhookUrl": "https://yoursite.com/webhooks/uspostage",
    "events": ["label.created", "label.failed"]
  }'

응답

json

{
  "success": true,
  "data": {
    "id": "whk_abc123",
    "webhookUrl": "https://yoursite.com/webhooks/uspostage",
    "events": ["label.created", "label.failed"],
    "secret": "whsec_abc123xyz789..."
  }
}

Webhook 서명 검증

각 webhook에는 검증을 위한 서명 헤더가 포함됩니다. HMAC-SHA256을 사용하여 서명을 검증하세요:

javascript

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Webhook 페이로드 예시

json

{
  "event": "label.created",
  "timestamp": "2024-01-12T14:30:00Z",
  "data": {
    "orderId": "ord_abc123",
    "orderItemId": "item_xyz789",
    "externalReference": "ORDER-12345",
    "label": {
      "trackingCode": "9400111899223456789012",
      "carrier": "USPS",
      "service": "Priority Mail",
      "labelUrl": "https://uspostage.io/labels/lbl_abc123.pdf"
    }
  }
}

REST API

API 문서

강력한 REST API로 애플리케이션에 배송 라벨을 통합하세요. 실시간 요금 조회, 라벨 생성, 배송 추적을 프로그래밍 방식으로 수행할 수 있습니다.

인증

모든 API 요청은 API 키와 시크릿을 사용한 인증이 필요합니다. 모든 요청에 다음 헤더를 포함하세요:

headers

X-API-Key: your_api_key
X-API-Secret: your_api_secret

보안 주의사항

API 시크릿을 안전하게 보관하세요. 클라이언트 측 코드나 공개 저장소에 노출하지 마세요.

요청 예시

bash

curl -X GET https://uspostage.io/api/v1/account/balance \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

계정 잔액

암호화폐 지갑 잔액과 거래 내역을 확인합니다. API는 결제에 암호화폐 지갑(BTC, LTC, LTCT)을 사용합니다.

GET

/api/v1/account/balance

암호화폐 지갑 잔액 및 거래 조회

쿼리 파라미터

파라미터	타입	필수	설명
includeTransactions	`boolean`	선택	거래 내역 포함
currency	`string`	선택	통화별 거래 필터링 (BTC, LTC, LTCT)
limit	`number`	선택	거래 수 (기본값: 20, 최대: 100)

요청 예시

bash

curl -X GET "https://uspostage.io/api/v1/account/balance?includeTransactions=true&limit=10" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

응답

json

{
  "success": true,
  "data": {
    "balances": [
      { "currency": "BTC", "balance": 0.00125000 },
      { "currency": "LTC", "balance": 0.50000000 },
      { "currency": "LTCT", "balance": 0.00000000 }
    ],
    "supportedCurrencies": ["BTC", "LTC", "LTCT"],
    "transactions": [
      {
        "id": "txn_abc123",
        "currency": "BTC",
        "type": "deposit",
        "amount": 0.00100000,
        "balanceAfter": 0.00125000,
        "description": "Deposit via CoinPayments",
        "createdAt": "2024-01-10T12:00:00Z"
      },
      {
        "id": "txn_def456",
        "currency": "BTC",
        "type": "label_purchase",
        "amount": -0.00015000,
        "balanceAfter": 0.00025000,
        "description": "API labels purchase for order USP-12345678",
        "createdAt": "2024-01-09T15:30:00Z"
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "total": 25,
      "hasMore": true
    }
  }
}

자금 추가

지갑에 자금을 추가하려면 내 지갑 페이지를 방문하여 BTC, LTC 또는 LTCT(테스트넷)로 입금하세요.

주소 확인

배송 주소를 확인하고 표준화하여 배송 가능성을 보장합니다.

POST

/api/v1/shipping/verify-address

배송 주소 확인 및 수정

요청 본문

파라미터	타입	필수	설명
address	`Address`	필수	확인할 주소
strict	`boolean`	선택	엄격한 확인 모드 활성화

요청 예시

bash

curl -X POST https://uspostage.io/api/v1/shipping/verify-address \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "address": {
      "name": "John Doe",
      "street1": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US"
    }
  }'

응답

json

{
  "success": true,
  "data": {
    "verified": true,
    "addressId": "adr_abc123",
    "verifiedAddress": {
      "name": "JOHN DOE",
      "street1": "123 MAIN ST",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip": "94102-1234",
      "country": "US"
    },
    "verification": {
      "success": true,
      "errors": []
    }
  }
}

배송 요금

USPS, UPS, FedEx, DHL 등 여러 운송업체의 실시간 배송 요금을 조회합니다.

POST

/api/v1/shipping/rates

패키지 배송 요금 계산

요청 본문

파라미터	타입	필수	설명
fromAddress	`Address`	필수	발송인 주소 객체
toAddress	`Address`	필수	수신인 주소 객체
packageDetails	`Package`	필수	패키지 크기 및 무게
carriers	`string[]`	선택	특정 운송업체 필터링 (USPS, UPS, FEDEX, DHL)
customsInfo	`CustomsInfo`	선택	국제 배송 시 필수

주소 객체

파라미터	타입	필수	설명
name	`string`	필수	전체 이름
company	`string`	선택	회사명
street1	`string`	필수	주소 1
street2	`string`	선택	주소 2
city	`string`	필수	도시
state	`string`	필수	주/도 코드
zip	`string`	필수	우편번호
country	`string`	필수	국가 코드 (US, CA 등)
phone	`string`	선택	전화번호
email	`string`	선택	이메일 주소

패키지 객체

파라미터	타입	필수	설명
length	`number`	필수	길이 (인치)
width	`number`	필수	너비 (인치)
height	`number`	필수	높이 (인치)
weight	`number`	필수	무게 (온스)

CustomsInfo 객체

국제 배송

국제 배송 시 필수 (fromAddress.country와 toAddress.country가 다른 경우).

파라미터	타입	필수	설명
contents_type	`string`	필수	내용물 유형: documents, gift, merchandise, returned_goods, sample, dangerous_goods, humanitarian_donation, other
contents_explanation	`string`	선택	contents_type이 'other'인 경우 필수
customs_certify	`boolean`	필수	true여야 함 - 신고 정확성 인증
customs_signer	`string`	필수	세관 신고서를 인증하는 사람의 이름
eel_pfc	`string`	필수	수출 면제 코드 ($2,500 미만 배송의 경우 'NOEEI 30.37(a)' 사용)
non_delivery_option	`string`	필수	배송 불가 시 조치: 'return' 또는 'abandon'
restriction_type	`string`	필수	제한 유형: 'none', 'other', 'quarantine', 또는 'sanitary_phytosanitary_inspection'
restriction_comments	`string`	선택	restriction_type이 'none'이 아닌 경우 필수
customs_items	`CustomsItem[]`	필수	배송 품목 배열 (1-100개 품목)

CustomsItem 객체

파라미터	타입	필수	설명
description	`string`	필수	품목의 상세 설명
quantity	`number`	필수	품목 수량 (최소: 1)
value	`number`	필수	USD 가치 (0보다 커야 함)
weight	`number`	필수	무게 (온스, 0보다 커야 함)
origin_country	`string`	필수	2자리 국가 코드 (예: 'US', 'CN')
hs_tariff_number	`string`	필수	6-10자리 HS 관세 코드

요청 예시

bash

curl -X POST https://uspostage.io/api/v1/shipping/rates \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "fromAddress": {
      "name": "John Doe",
      "street1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US"
    },
    "toAddress": {
      "name": "Jane Smith",
      "street1": "456 Oak Ave",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90001",
      "country": "US"
    },
    "packageDetails": {
      "length": 10,
      "width": 8,
      "height": 4,
      "weight": 16
    }
  }'

응답

json

{
  "success": true,
  "data": {
    "shipmentId": "shp_abc123",
    "rates": [
      {
        "id": "rate_xyz789",
        "carrier": "USPS",
        "service": "Priority Mail",
        "rate": 8.95,
        "currency": "USD",
        "delivery_days": 2,
        "delivery_date": "2024-01-15"
      },
      {
        "id": "rate_def456",
        "carrier": "UPS",
        "service": "Ground",
        "rate": 12.50,
        "currency": "USD",
        "delivery_days": 5,
        "delivery_date": "2024-01-18"
      }
    ]
  }
}

국제 배송 예시

국제 배송의 경우 품목 신고가 포함된 customsInfo 객체를 포함하세요:

bash

curl -X POST https://uspostage.io/api/v1/shipping/rates \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "fromAddress": {
      "name": "John Doe",
      "street1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US",
      "phone": "4155551234"
    },
    "toAddress": {
      "name": "Jane Smith",
      "street1": "456 Queen St W",
      "city": "Toronto",
      "state": "ON",
      "zip": "M5V 2A8",
      "country": "CA",
      "phone": "4165551234"
    },
    "packageDetails": {
      "length": 10,
      "width": 8,
      "height": 4,
      "weight": 16
    },
    "customsInfo": {
      "contents_type": "merchandise",
      "customs_certify": true,
      "customs_signer": "John Doe",
      "eel_pfc": "NOEEI 30.37(a)",
      "non_delivery_option": "return",
      "restriction_type": "none",
      "customs_items": [
        {
          "description": "Cotton T-Shirt",
          "quantity": 2,
          "value": 25.00,
          "weight": 8,
          "origin_country": "US",
          "hs_tariff_number": "6109100010"
        }
      ]
    }
  }'

주문 생성

배송 주문을 생성하고 관리합니다. 주문에는 하나 이상의 배송 라벨 항목이 포함됩니다.

GET

/api/v1/orders

모든 주문 조회

POST

/api/v1/orders

새 주문 생성

GET

/api/v1/orders/{id}

주문 상세 조회

주문 목록 - 쿼리 파라미터

파라미터	타입	필수	설명
limit	`number`	선택	결과 수 (기본값: 50, 최대: 100)
offset	`number`	선택	페이지네이션 오프셋

주문 생성 - 요청 본문

파라미터	타입	필수	설명
items	`OrderItem[]`	필수	주문 항목 배열
email	`string`	선택	고객 이메일
externalReference	`string`	선택	참조 ID

OrderItem 객체

간소화된 API

shipmentId와 rateId만 필수입니다. 주소, 패키지 세부정보, 세관 정보는 배송에서 자동으로 추출됩니다.

파라미터	타입	필수	설명
shipmentId	`string`	필수	요금 엔드포인트의 배송 ID
rateId	`string`	필수	요금 엔드포인트의 요금 ID

예시: 주문 생성

bash

curl -X POST https://uspostage.io/api/v1/orders \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "items": [
      {
        "shipmentId": "shp_abc123",
        "rateId": "rate_xyz789"
      }
    ],
    "externalReference": "ORDER-12345"
  }'

응답

json

{
  "success": true,
  "data": {
    "orderId": "ord_abc123",
    "trackingId": "USP-12345678",
    "totalAmount": 8.95,
    "paymentStatus": "pending",
    "items": [
      {
        "orderItemId": "item_xyz789",
        "rateId": "rate_xyz789"
      }
    ]
  }
}

라벨 구매

주문의 모든 항목에 대한 배송 라벨을 구매합니다. 라벨은 암호화폐 지갑 잔액(BTC, LTC 또는 LTCT)으로 구매됩니다.

POST

/api/v1/labels/purchase

주문용 배송 라벨 구매

요청 본문

암호화폐 결제

API가 라벨 비용을 USD에서 현재 환율로 암호화폐로 변환합니다. 충분한 잔액이 필요합니다 (가격 변동에 대비한 10% 버퍼 포함).

파라미터	타입	필수	설명
orderId	`string`	필수	라벨을 구매할 주문 ID
currency	`string`	선택	결제에 사용할 암호화폐 (BTC, LTC, LTCT). 지정하지 않으면 충분한 잔액이 있는 첫 번째 통화가 자동 선택됩니다.

요청 예시

bash

curl -X POST https://uspostage.io/api/v1/labels/purchase \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "orderId": "ord_abc123",
    "currency": "BTC"
  }'

응답

json

{
  "success": true,
  "data": {
    "orderId": "ord_abc123",
    "externalReference": "ORDER-12345",
    "totalLabels": 2,
    "successCount": 2,
    "failCount": 0,
    "labels": [
      {
        "orderItemId": "item_xyz789",
        "success": true,
        "trackingCode": "9400111899223456789012",
        "labelUrl": "https://easypost.com/labels/lbl_abc123.pdf",
        "carrier": "USPS",
        "service": "Priority Mail",
        "labelFormats": {
          "pdf": "https://easypost.com/labels/lbl_abc123.pdf",
          "png": "https://easypost.com/labels/lbl_abc123.png"
        }
      },
      {
        "orderItemId": "item_def456",
        "success": true,
        "trackingCode": "9400111899223456789013",
        "labelUrl": "https://easypost.com/labels/lbl_def456.pdf",
        "carrier": "FedEx",
        "service": "Ground",
        "labelFormats": {
          "pdf": "https://easypost.com/labels/lbl_def456.pdf"
        }
      }
    ]
  }
}

402 잔액 부족

지갑 잔액이 부족하면 API가 필요한 암호화폐 금액과 함께 402 상태를 반환합니다.

잔액 부족 응답

json

{
  "success": false,
  "error": "Insufficient balance",
  "message": "Need 0.00011000 BTC (includes 10% buffer), have 0.00005000",
  "currency": "BTC",
  "required": 0.00011000,
  "requiredUsd": 5.50,
  "available": 0.00005000,
  "balanceEndpoint": "/api/v1/account/balance"
}

추적

구매한 라벨의 추적 코드를 사용하여 배송을 추적합니다.

GET

/api/v1/tracking/{code}

추적 정보 조회

경로 파라미터

파라미터	타입	필수	설명
code	`string`	필수	추적 코드

요청 예시

bash

curl -X GET https://uspostage.io/api/v1/tracking/9400111899223456789012 \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

응답

json

{
  "success": true,
  "data": {
    "trackingCode": "9400111899223456789012",
    "carrier": "USPS",
    "status": "in_transit",
    "statusDetail": "In Transit to Next Facility",
    "estDeliveryDate": "2024-01-15T00:00:00Z",
    "publicUrl": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111899223456789012",
    "trackingDetails": [
      {
        "status": "in_transit",
        "message": "In Transit to Next Facility",
        "datetime": "2024-01-12T14:30:00Z",
        "location": "San Francisco, CA"
      },
      {
        "status": "accepted",
        "message": "Accepted at USPS Origin Facility",
        "datetime": "2024-01-11T09:15:00Z",
        "location": "San Francisco, CA"
      }
    ],
    "updatedAt": "2024-01-12T14:30:00Z"
  }
}

Webhooks

라벨 생성이나 추적 업데이트와 같은 이벤트 발생 시 실시간 알림을 받습니다.

GET

/api/v1/webhooks

등록된 webhooks 조회

POST

/api/v1/webhooks

새 webhook 등록

GET

/api/v1/webhooks/{id}

webhook 상세 조회

DELETE

/api/v1/webhooks/{id}

webhook 삭제

사용 가능한 이벤트

label.created

라벨이 성공적으로 구매되었을 때

label.failed

라벨 생성이 실패했을 때

Webhook 등록 - 요청 본문

파라미터	타입	필수	설명
webhookUrl	`string`	필수	webhook 이벤트를 수신할 URL
events	`string[]`	필수	구독할 이벤트 유형 배열

예시: Webhook 등록

bash

curl -X POST https://uspostage.io/api/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "webhookUrl": "https://yoursite.com/webhooks/uspostage",
    "events": ["label.created", "label.failed"]
  }'

응답

json

{
  "success": true,
  "data": {
    "id": "whk_abc123",
    "webhookUrl": "https://yoursite.com/webhooks/uspostage",
    "events": ["label.created", "label.failed"],
    "secret": "whsec_abc123xyz789..."
  }
}

Webhook 서명 검증

각 webhook에는 검증을 위한 서명 헤더가 포함됩니다. HMAC-SHA256을 사용하여 서명을 검증하세요:

javascript

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Webhook 페이로드 예시

json

{
  "event": "label.created",
  "timestamp": "2024-01-12T14:30:00Z",
  "data": {
    "orderId": "ord_abc123",
    "orderItemId": "item_xyz789",
    "externalReference": "ORDER-12345",
    "label": {
      "trackingCode": "9400111899223456789012",
      "carrier": "USPS",
      "service": "Priority Mail",
      "labelUrl": "https://uspostage.io/labels/lbl_abc123.pdf"
    }
  }
}

API 문서

인증

요청 예시

계정 잔액

쿼리 파라미터

요청 예시

응답

주소 확인

요청 본문

요청 예시

응답

배송 요금

요청 본문

주소 객체

패키지 객체

CustomsInfo 객체

CustomsItem 객체

요청 예시

응답

국제 배송 예시

주문 생성

주문 목록 - 쿼리 파라미터

주문 생성 - 요청 본문

OrderItem 객체

예시: 주문 생성

응답

라벨 구매

요청 본문

요청 예시

응답

잔액 부족 응답

추적

경로 파라미터

요청 예시

응답

Webhooks

사용 가능한 이벤트

Webhook 등록 - 요청 본문

예시: Webhook 등록

응답

Webhook 서명 검증

Webhook 페이로드 예시

장바구니

장바구니가 비어 있습니다

API 문서

인증

요청 예시

계정 잔액

쿼리 파라미터

요청 예시

응답

주소 확인

요청 본문

요청 예시

응답

배송 요금

요청 본문

주소 객체

패키지 객체

CustomsInfo 객체

CustomsItem 객체

요청 예시

응답

국제 배송 예시

주문 생성

주문 목록 - 쿼리 파라미터

주문 생성 - 요청 본문

OrderItem 객체

예시: 주문 생성

응답

라벨 구매

요청 본문

요청 예시

응답

잔액 부족 응답

추적

경로 파라미터

요청 예시

응답

Webhooks