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

📮 住所サービス

住所サービス (addressService) は、認証済み郵便番号による住所検索を公開し、注入された findAddressDriver へ検索を委譲します。組み込みのデフォルトドライバーは存在せず — デフォルトドライバーを注入する必要があります（例えば createJapanPostDriver(...) 経由で）。または検索はブロックのラップされたサービスエラーで失敗します。ルートスキーマは部分郵便番号を受け付けますが、バンドルされた JapanPost ドライバーは最終的にハイフンを削除した後に正規化された 7 桁の郵便番号を必要とします。オプションのインメモリキャッシュも設定可能です。

🚀 クイックスタート​

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

const {nodeBlocksErrorMiddleware} = middlewares;
const {addressService} = services;
const {withMongo, createJapanPostDriver} = drivers;
const {createCache} = utils;

const connectToDatabase = withMongo('mongodb://localhost:27017/?authSource=admin', 'dev', 'user', 'password');

const findAddressDriver = createJapanPostDriver(
  process.env.JAPAN_POST_CLIENT_ID!,
  process.env.JAPAN_POST_SECRET_KEY!,
  // オプションの第3引数: ホスト名、デフォルト 'api.da.pf.japanpost.jp'
);

express()
  .use(
    addressService(
      {
        ...(await connectToDatabase('identities')),
      },
      {
        authSecrets: {
          authEncSecret: 'your-encryption-secret',
          authSignSecret: 'your-signing-secret',
        },
        authMode: 'bearer', // または 'cookie'
        findAddressCache: createCache(),
      },
      {findAddressDriver},
    ),
  )
  .use(nodeBlocksErrorMiddleware())
  .listen(8089, () => console.log('Server running'));

🍪 Cookie 認証: authMode: 'cookie' の場合、保護されたルートはクッキーからアクセストークンを読み取ります。ホストアプリは cookie-parser を登録する必要があります。

📋 エンドポイント一覧​

メソッドパス説明認証
GET/addresses?postalCode=...日本の郵便番号による住所検索認証済み

🗄️ レスポンス形状​

正常な検索は以下の内容を返します:

{
  prefecture: string;
  city: string;
  town?: string;
  postalCode: string;
}
フィールドタイプ説明
prefecturestring都道府県名
citystring市区町村名
townstringオプションの町名
postalCodestring正規化された郵便番号

🔐 認証ヘッダー​

Authorization: Bearer <access_token>
x-nb-fingerprint: <device_fingerprint>

x-nb-fingerprint ヘッダーは、ログイン時にフィンガープリントが指定された場合、認証済みリクエストに必須です。

🔧 API エンドポイント​

1. 住所検索​

リクエスト:

  • メソッド: GET
  • パス: /addresses
  • 認証: 認証済み

クエリパラメータ:

フィールドタイプ必須説明
postalCodestring✅部分または完全な日本の郵便番号 (^\d{3}-?\d{0,4}$、例: 100 または 100-0001)。createJapanPostDriver を使用する場合、正規化値は 7 桁である必要があります。

レスポンス: ルートは住所オブジェクトを返します。サービスは Express のデフォルト JSON ステータス (200) で送信します。

例:

curl "{{host}}/addresses?postalCode=100-0001" \
  -H "Authorization: Bearer <access-token>"

一般的なエラー:

ステータス説明
400バリデーションエラー (欠落/無効な postalCode)
401欠落または無効な認証
404住所が見つからない
500住所検索ドライバーの失敗

⚙️ 設定オプション​

interface AddressServiceConfiguration {
  authSecrets: {
    authEncSecret: string;
    authSignSecret: string;
  };
  authMode?: 'bearer' | 'cookie';
  identity?: {
    typeIds?: {
      admin: string;
      guest: string;
      regular: string;
    };
  };
  findAddressCache?: ReturnType<typeof createCache>;
}

データストア​

コレクション必須説明
identities✅サービスタイプに必須ですが、住所ルート自体では使用されません

オプション (第3引数)​

オプション必須説明
findAddressDriver✅ (検索の場合)住所検索ドライバー ({ findAddress(postalCode): Promise<Address> })。日本の郵便局には createJapanPostDriver を使用します。これがない場合、住所検索リクエストは失敗します。

🚨 エラーハンドリング​

ステータスエラーメッセージ説明
400バリデーションエラー欠落または無効な postalCode クエリパラメータ
401認証失敗認証レイヤーがリクエストを拒否しました
404一致する住所が見つかりません。検索結果に住所がありません
500住所の検索に失敗しました。住所検索ドライバーが失敗しました

🔗 関連ドキュメント​