メインコンテンツまでスキップ
バージョン: 0.13.0 (Previous)

📮 Japan Post ドライバー

Japan Post ドライバーは、郵便番号による住所検索のために Japan Post Digital Address API (v1) と統合します。OAuth2 クライアント認証、トークンキャッシュ、レスポンス正規化を処理します。

ドライバーを findAddressDriver として注入し、住所サービス とともに使用します。

🎯 概要​

import {drivers} from '@nodeblocks/backend-sdk';

const {createJapanPostDriver} = drivers;

const findAddressDriver = createJapanPostDriver(
  process.env.JAPAN_POST_CLIENT_ID!,
  process.env.JAPAN_POST_SECRET_KEY!,
  process.env.JAPAN_POST_HOSTNAME, // 省略可。既定値は 'api.da.pf.japanpost.jp'
);

📋 利用可能な Japan Post ドライバー​

createJapanPostDriver​

Japan Post の住所検索ドライバーを作成します。これは同期ファクトリーのため、await は不要です。

パラメーター:

パラメーター型既定値説明
clientIdstring—Japan Post Digital Address API のクライアント ID
secretKeystring—Japan Post Digital Address API のシークレットキー
hostname?string'api.da.pf.japanpost.jp'API ホスト名（テストにはサンドボックスのホスト名を使用）

戻り値: findAddress(postalCode) を持つ JapanPostDriver オブジェクト

使用例:

import {drivers} from '@nodeblocks/backend-sdk';

const {createJapanPostDriver} = drivers;

const driver = createJapanPostDriver(
  process.env.JAPAN_POST_CLIENT_ID!,
  process.env.JAPAN_POST_SECRET_KEY!,
  process.env.JAPAN_POST_HOSTNAME,
);

const address = await driver.findAddress('100-0001');
// { prefecture: '東京都', city: '千代田区', town: '千代田', postalCode: '1000001' }

JapanPostDriver​

SDK ソースの src/drivers/japan-post.ts で、ReturnType<typeof createJapanPostDriver> として定義される型エイリアスです。

type JapanPostDriver = {
  findAddress(postalCode: string): Promise<{
    prefecture: string;
    city: string;
    town?: string;
    postalCode: string;
  } | null>;
};

この型は drivers 名前空間からエクスポートされます。JapanPostDriver は src/blocks/address.ts の FindAddressDriver 契約を満たし、住所サービスが findAddressDriver として注入します。検索結果がない場合、ドライバーは null を返します。住所ブロックはその値を err(new AddressNotFoundError('No matching address found.')) に変換します。

findAddress​

郵便番号から日本の住所を検索します。

パラメーター型説明
postalCodestringハイフンの有無を問わない郵便番号（7 桁へ正規化できる必要があります）

戻り値: Promise<{ prefecture: string; city: string; town?: string; postalCode: string } | null>

結果動作
住所あり{ prefecture, city, town?, postalCode }。postalCode は API の zip_code フィールド（最初の住所エントリー）から取得します。
未検出（HTTP 404）null
addresses 配列が空（HTTP 200）null
形式が不正Error: Invalid postal code format: "${postalCode}". Expected 7 digits (hyphens allowed). をスローします。
API エラー（有効なエラースキーマ）Error(data.message) をスローします。
トークン／レスポンススキーマの不一致Error('Japan Post driver error.', { cause }) をスローします。

動作の詳細:

  • 検証および API リクエストの前にハイフンを取り除きます。
  • 正規化後の郵便番号が /^\d{7}$/ に一致することを検証します。
  • トークンおよび住所レスポンスは、返す前に AJV スキーマで検証します。
  • 本文 { client_id, grant_type: 'client_credentials', secret_key } を使って POST https://{hostname}/api/v1/j/token で OAuth2 トークンを取得し、期限切れまで accessTokenExpiresAt にキャッシュします。
  • Authorization: Bearer {token} を付けて GET /api/v1/searchcode/{postalCode}?searchtype=2 で住所を検索します。
  • 返されたすべての住所に町名が 1 つだけ存在する場合にのみ town を設定します（'以下に掲載がない場合' を除く）。

住所サービスを通じた正規化: 住所ブロック（src/blocks/address.ts の findAddress）はドライバー呼び出し前にハイフンを取り除き、その後ドライバーが再度 /^\d{7}$/ を検証します。ドライバーの直接呼び出しではハイフン付き入力を受け入れますが、住所サービス経由の呼び出しは正規化済みでドライバーに到達します。

例:

await driver.findAddress('100-0001'); // ハイフンあり
await driver.findAddress('1000001'); // ハイフンなし
await driver.findAddress('999-9999'); // null — 見つからない場合

await driver.findAddress('12');
// Error をスロー: Invalid postal code format: "12". Expected 7 digits (hyphens allowed).

🔧 Japan Post ドライバーの使用​

サービスでの使用​

addressService の第 3 引数のオプションを通じてドライバーを注入します。

import {services, drivers, utils} from '@nodeblocks/backend-sdk';

const {addressService} = services;
const {createJapanPostDriver} = drivers;
const {createCache} = utils;

const findAddressDriver = createJapanPostDriver(
  process.env.JAPAN_POST_CLIENT_ID!,
  process.env.JAPAN_POST_SECRET_KEY!,
  process.env.JAPAN_POST_HOSTNAME,
);

addressService(
  {identities},
  {
    authSecrets: {
      authEncSecret: process.env.AUTH_ENC_SECRET!,
      authSignSecret: process.env.AUTH_SIGN_SECRET!,
    },
    findAddressCache: createCache(),
  },
  {findAddressDriver},
);

完全な Express 配線、認証、キャッシュ設定は、住所サービス を参照してください。

🔗 関連ドキュメント​