twilioのbundle登録をtwilio-php APIで実装

たなゆー（エンジニア）

2023.12.06

IT技術

twilioで電話番号を購入する際に「Regulatory Bundle」というものが必要になってきますが、それをtwilioが提供しているAPIで登録したので備忘録的にまとめていきます。

twilioの「Regulatory Bundle」とは

twilioの「Regulatory Bundle」とは電話番号を購入する際に必要な書類や個人または法人の情報をまとめたものです。twilioに限らず電話番号を購入する際はこういった情報が必要なのですが、twilioで電話番号を購入する際は、twilioに「Regulatory Bundle」を提出し承認を得て電話番号を購入する流れとなります。

コンソール画面からポチポチやって登録することもできますが、自動化する方が効率が良くなる場面もあるので今回はtwilioが提供しているライブラリを用いてAPIで登録していきます。

twilioのライブラリを用いて Regulatory Bundle を登録

これからライブラリを用いてRegulatory Bundleを登録していきますがその前に、Regulatory Bundleに含まれている情報の整理とAPIで登録する流れのイメージを共有していきたいと思います。このイメージができていないとコードを見ても何やってるかわからなくなる可能性があります。（体験談）

Regulatory Bundleに含まれている情報

以下の情報が含まれています。

エンドユーザー（登録する個人及び法人の情報）
ドキュメント（上記のエンドユーザーの証明書類）
- 登記簿謄本
- 委任状
- 免許証
- Regulatory Bundle 申請書
- マイナンバーカード

ドキュメントの中身は上記に限らないとは思いますが私が登録する際はこの内容で登録を行ったので今回はこれで行っていきます。

APIで登録する流れのイメージ

以下のイメージで登録していきます。

Regulatory Bundleを作成する
情報を保存するための箱を作るようなイメージでRegulatory Bundleを作成します。
エンドユーザーを作成
Regulatory Bundleに入れるエンドユーザーという情報を作成します。
今回は法人として登録していくので、法人及びその代表者情報をここに入れます。
ドキュメントを作成
Regulatory Bundleに入れるドキュメントを作成します。
先ほどの項目で記載した5つの証明書類を今回は作成します。
2と3で作成したエンドユーザーとドキュメントを１で作成したRegulatory Bundleにアサインする
1で作った箱に2と３で作った情報を入れるようなイメージです。これでRegulatory Bundleの作成が完了します。
4までの流れで作ったRegulatory Bundleのステータスを「レビュー待ち」状態にする。
ステータスを「レビュー待ち」にすることで申請したのと同じ状態になります。
twilioが承認するまで待つ
あとは待つだけです。ここまでの流れで正しい情報で申請できていれば承認してくれます。承認されれば登録完了です。

上記の1~6の流れのイメージで実装していきます。

実際にライブラリを使って実装していく

それではいよいよ実装していきましょう。さっきの流れをコードで書いていくだけです。

まずはtwilioのphpライブラリをインストールしましょう。

1$ composer require twilio/sdk

これでインストールが完了したのでコードを書いていきます。
まずは下準備でtwilio Clientインスタンスを作成します。
このインスタンスをこれから使っていきます。

1use Twilio\Rest\Client;
2
3$accountSid = 'ACxxxxxxxxxxxxxx'; // twilioのAccount SID
4$authToken = 'xxxxxxxxxxxxxxxxx';　// twilioのAuth Token
5
6$twilio = new Client($accountSid, $authToken);

準備も終わったので1のRegulatory Bundle作成からやっていきましょう。

1$bundle = $twilio->numbers->v2->regulatoryCompliance
2                        ->bundles
3                        ->create(
4                            'friendlyName', // Regulatory Bundleに適当に名前をつけます。
5                            'email@example', // 自身のメールアドレス
6                            [
7                                'endUserType' => 'business',
8                                'isoCountry' => 'JP',
9                                'numberType' => 'national',
10                            ]
11                        )
12                    ;

それぞれのパラメータには自身のtwilio登録情報や購入したい電話番号の種類等を入れます。

次に2のエンドユーザーを作成をします。

1$endUser = $twilio->numbers->v2->regulatoryCompliance 
2                         ->endUsers 
3                         ->create(
4                             'friendlyName', // 適当に名前をつけます。
5                             'business', // エンドユーザーのタイプを入れます。
6                             [ 
7                                 'attributes' => [ 
8                                     'business_description' => 'businessDescription', // 法人の事業の説明
9                                     'business_name' => 'businessName', // 法人名
10                                     'birth_date' => '19xx-xx-xx', // 代表者の誕生日
11                                     'first_name' => 'firstName', // 代表者の名
12                                     'last_name' => 'lastName', // 代表者の姓
13                                  ], 
14                              ] 
15                          )
16                      ;

次にドキュメントの作成ですがその前にまた下準備をします。
各ドキュメントには法人の住所か代表者の住所及びその両方を入れる必要があるので、
この2つの住所をこれまたtwilioのライブラリで作成します。

1$businessAddress = $twilio->addresses 
2　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　->create( 
3　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　'businessName', // 法人名 　
4　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　'businessStreet', // street 
5　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　'businessCity', // city 
6　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　'businessRegion', // region 
7　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　'businessPostalCode', // 法人の郵便番号 
8　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　'JP', // isoCountry 
9　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　[ 
10　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　'friendlyName' => 'businessName', //適当に名前をつける。 
11　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　] 
12　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　) 
13　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　; 
14
15$personalAddress = $twilio->addresses 
16　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　->create( 
17　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　'firstName lastName', // 代表者名 
18　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　'personalStreet', // street 
19　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　'personalCity', // city 
20　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　'personalRegion', // region 
21　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　'personalPostalCode', // 代表者の郵便番号
22　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　 'JP', // isoCountry 
23　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　[ 
24　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　'friendlyName' => 'firstName lastName', // 適当に名前をつける。 
25　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　] 
26　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　) 
27　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　;

下準備も終わったのでいよいよ３のドキュメント作成していきます。
実はここではライブラリを使わずに直接APIを叩きます。
ドキュメントのファイルデータを送信する必要があり、この作業だけはtwilioのライブラリでは提供されていないためです。
私はLravelを使って開発していたので今回LaravelのHttpファサードを使ってAPIを叩きます。
本来は5つのドキュメントを作成しますが同じようなコードになるので、今回は登記簿謄本の作成のみコードを載せます。

1// 登記簿謄本の作成 
2$attributes = json_encode([ 
3　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　'address_sids' => ["{$businessAddress->sid}"],
4　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　 'first_name' => 'firstName',
5　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　 'last_name' => 'lastName', 
6　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　'business_name' => 'businessName', 
7　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　'business_description' => 'businessDescription', 
8　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　]); 
9
10$response = Http::withHeaders([ 
11　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　// 認証のためにsidとtokenを入れる。
12　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　 'Authorization' => 'Basic'.base64_encode(’ACxxxxxxxxxxxxxx:xxxxxxxxxxxxxxxxx’), 
13　　　　　　　　　　　　　　　　　　　　　　　　　　      　]) 
14                      ->attach('File', '登記簿謄本のファイルデータ', '適当に名前をつける') 
15                      ->post('https://numbers-upload.twilio.com/v2/RegulatoryCompliance/SupportingDocuments', [ 
16                          'Attributes' => $attributes, 
17                          'FriendlyName' => 'friendlyName', //適当に名前をつける。
18                          'Type' => 'corporate_registry', //　ここでドキュメントの種類を選択。 
19                      ]) 
20                    ; 
21
22$responseBody = json_decode($response->body());
23$corporateRegistrySid = $responseBody->sid;

次は４です。作成したエンドユーザーとドキュメントをRegulatory Bundleにアサインします。

1// 書類をbundleにアサイン。本来は5つのドキュメント毎にそれぞれ行いますが今回は登記簿謄本のみ記載。
2 $twilio->numbers->v2->regulatoryCompliance 
3                          ->bundles($bundle->sid) 
4                          ->itemAssignments 
5                          ->create($corporateRegistrySid) 
6                    ; 
7
8// エンドユーザーをbundleにアサイン 
9$twilio->numbers->v2->regulatoryCompliance 
10                         ->bundles($bundle->sid) 
11                         ->itemAssignments 
12                         ->create($endUser->sid) 
13                    ;

それでは最後に5のRegulatory Bundleのステータスを「レビュー待ち」状態にします。

1$bundle = $twilio->numbers->v2->regulatoryCompliance 
2                        ->bundles($bundle->id) 
3                        ->update( 
4                             [ 
5                               'status' => 'pending-review',
6                             ] 
7                        )
8                   ;