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"
        }
      ]
    }
  }'

注文作成

配送注文を作成・管理します。注文には1つ以上の配送ラベルアイテムが含まれます。

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"
        }
      ]
    }
  }'

注文作成

配送注文を作成・管理します。注文には1つ以上の配送ラベルアイテムが含まれます。

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