本ガイドは、チャネルトークの AI エージェント（ALF）タスクから日本郵便の公式API（郵便番号・デジタルアドレスAPI）を使って住所検索を行うアプリのご利用ガイドです。チャネル側での設定は不要で、インストール後すぐに関数を利用できます。

このアプリでできること

チャネルトークの ALF タスクから、日本郵便の公式データに基づく住所検索を行えます。

郵便番号・事業所個別郵便番号・デジタルアドレスから住所を取得（正引き）
住所（フリーワード・都道府県/市区町村など）から郵便番号を検索（逆引き）
ヒアリングした郵便番号の実在確認と、確認メッセージへの住所自動転写

提供関数一覧

タスクビルダーの関数ノードから利用できる関数です。いずれも参照のみでデータを書き換えません。

関数	種別	機能
searchZipcode	参照	郵便番号・事業所個別郵便番号・デジタルアドレスから住所を返します
searchAddress	参照	住所の一部から該当する郵便番号・住所候補を返します

各関数の詳細と戻り値

すべての関数は、失敗時も例外にはならず ok: false とエラー情報を返します。タスク側では ok の値で成否を分岐できます。customerMessage はそのままお客様向けメッセージに使える一行文です。

searchZipcode — コードから住所を検索（正引き）

郵便番号（7桁）・事業所個別郵便番号・デジタルアドレス（英数字7桁）のいずれかから住所を検索します。ハイフン・〒・空白・全角は自動で正規化されるため、お客様の入力をそのまま渡せます。7桁未満（3桁以上）は前方一致検索になり、複数件が返ります。

入力

項目	型	必須	説明
code	文字列	○	郵便番号 / 事業所個別郵便番号 / デジタルアドレス（3〜7桁。ハイフン可）
excludeBiz	真偽		true で事業所個別郵便番号を検索対象外にします。空欄可
choikitype	数値		町域の表記 1:括弧なし（既定）/ 2:括弧あり。空欄可
page / limit	数値		ページ番号 / 取得件数（最大1000）。空欄可

戻り値

{
  "ok": true,
  "zipCode": "1000004",
  "address": "〒100-0004 東京都千代田区大手町",
  "count": 1,
  "searchtype": "zipcode",
  "addresses": [
    {
      "zipCode": "1000004",
      "bizZipCode": null,
      "dgacode": null,
      "prefName": "東京都",
      "cityName": "千代田区",
      "townName": "大手町",
      "blockName": null,
      "bizName": null,
      "display": "〒100-0004 東京都千代田区大手町"
    }
  ],
  "customerMessage": "〒100-0004 東京都千代田区大手町"
}

項目	型	説明
ok	真偽	検索成功なら true。失敗時は false（この値で分岐できます）
notFound	真偽	該当なしの場合 true（失敗時のみ）
zipCode	文字列	先頭ヒットの郵便番号（メモリー保存用）。該当なしの場合は null
address	文字列	先頭ヒットの一行住所（メモリー保存用）。「〒100-0004 東京都千代田区大手町」形式
count	数値	ヒット件数
searchtype	文字列	ヒット種別: zipcode / bizzipcode / dgacode
addresses	配列	住所候補の一覧。各候補に display（一行表示）を含みます
customerMessage	文字列	お客様向けにそのまま使える一行文（1件ヒット時は住所、複数時は件数）
adminMessage	文字列	担当者向けのエラー詳細（失敗時のみ。お客様には表示しないでください）

searchAddress — 住所から郵便番号を検索（逆引き）

住所の一部から該当する郵便番号・住所候補を検索します。マッチングは町域レベルまでで、丁目・番地は解釈されません。