whereparcel — WhereParcel荷物追跡APIの公式Node.js SDKをリリースしました。

npm install whereparcel

SDKが必要な理由

REST APIはどのHTTPクライアントでも使用できますが、SDKでより良い開発体験を提供します：

  • 型安全なレスポンス — すべてのAPIレスポンスのTypeScript型定義
  • ゼロ依存 — ネイティブfetch使用（Node.js 18+）、追加依存なし
  • 簡単な認証 — APIキーを一度設定するだけ
  • 組み込みエラーハンドリング — AuthenticationError、RateLimitErrorなどの型付きエラークラス

クイックスタート

import { WhereParcel } from 'whereparcel';

const wp = new WhereParcel('your-api-key', 'your-secret-key');

// 単件追跡
const response = await wp.track([
  { carrier: 'us.usps', trackingNumber: '9400111899562537866361' },
]);

console.log(response.summary);
// { total: 1, success: 1, failed: 0, usageIncremented: 1 }

ヘッダー設定、JSONパース、URLビルド不要ですぐに使えます。

一括追跡

1回のリクエストで最大5件を追跡できます：

const response = await wp.track([
  { carrier: 'us.usps', trackingNumber: '9400111899562537866361' },
  { carrier: 'us.fedex', trackingNumber: '123456789012' },
  { carrier: 'kr.cj', trackingNumber: '1234567890', clientId: 'order-42' },
]);

console.log(response.summary);
// { total: 3, success: 2, failed: 1, usageIncremented: 2 }

配送業者検索

500以上のサポート配送業者をプログラムで探索：

// 全配送業者
const carriers = await wp.getCarriers();

// 国別フィルター
const usCarriers = await wp.getCarriersByCountry('us');

// 地域別フィルター
const caCarriers = await wp.getCarriersByRegion('us', 'ca');

Webhookサポート

リアルタイム配送通知を設定：

const endpoint = await wp.createWebhookEndpoint({
  name: 'Production',
  url: 'https://myapp.com/webhooks/whereparcel',
});

await wp.registerWebhook({
  trackingItems: [{ carrier: 'us.usps', trackingNumber: '...' }],
  recurring: true,
  webhookEndpointId: endpoint.endpointId,
});

エラーハンドリング

型付きエラークラスでエラーを適切に処理：

import { WhereParcel, AuthenticationError, RateLimitError } from 'whereparcel';

try {
  const result = await wp.track([{ carrier: 'us.usps', trackingNumber: '...' }]);
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('API認証情報を確認してください');
  } else if (error instanceof RateLimitError) {
    console.error(`レート制限。${error.retryAfter}秒後にリトライ`);
  }
}

今後の予定

現在バージョン0.1.0で、次の機能を準備中です：

  • Python SDK — Python開発者向けSDK
  • Webhook署名検証 — Webhookペイロード検証ヘルパー
  • 自動リトライ — 指数バックオフによる自動リトライロジック

始めよう

npm install whereparcel