既存のメッセージングブランドを修正する
事業者の連絡先情報や住所が変わった場合は、既存のブランドを更新します。ブランド ID は維持してください。既存の事業者情報を修正するために、別の登録を作成してはいけません。有効な API アカウントを使用し、許可された送信元 IP アドレスから HTTPS 経由でアクセスしてください。ブランドはそのアカウントに属している必要があります。
まず、現在のレコードを取得します。事業者の識別情報と連絡先情報が含まれるため、ローカルコピーは非公開で保管してください。
curl --silent --show-error --fail-with-body --user "$API_USER:$API_PASSWORD" \
"https://api.multitel.net/tcr/v2/brand/$BRAND_ID" \
--output current-brand.json現在のブランドフィールドを保持する
現在のレコードから、書き込み可能なブランドフィールドだけを選んで brand-update.json を作成します。事業者の識別情報やその他の必須値を保持しながら、必要な修正を適用してください。GET レスポンス全体を送信してはいけません。brandId、本人確認やステータスの結果、タイムスタンプなど、レスポンス専用のフィールドは更新に含めません。
更新スキーマでは、entityType、displayName、country、email、brandRelationship が必須です。事業主体の種類ごとのルールも引き続き適用されます。組織の場合は、正式な会社名、納税者識別番号とその発行国、住所、業種を、該当する範囲で保持してください。個人事業主の場合は、代わりに該当する氏名と携帯電話の連絡先フィールドを保持します。登録例のプレースホルダーではなく、実際の現在の値を使用してください。
| フィールド | 使用方法 |
|---|---|
| displayName, email, phone | 識別しやすいブランド名と有効な連絡先情報です。最大文字数は、それぞれ 255、100、20 文字です。電話番号には、+ に国番号を続ける国際形式を使用してください。 |
| street, city, state, postalCode, country | 各項目に整合性のある、実在する事業所の住所です。文字数の上限は、それぞれ 255、100、20、10、2 文字です。該当する場合は、現行の米国の州コードを使用してください。 |
| entityType, companyName, ein, einIssuingCountry | 法的な事業者識別情報です。キャンペーンまたは外部審査が保留中または有効な状態にある場合、これらの情報の変更は制限されます。識別情報の変更制限を回避するためだけに、稼働中のキャンペーンを削除してはいけません。 |
| firstName, lastName, mobilePhone, businessContactEmail | 事業主体の種類に応じて使用する、識別情報または確認用の連絡先です。文字数の上限は、それぞれ 100、100、20、255 文字です。 |
| brandRelationship, vertical | 現在の関係区分と業種のコードです。関係区分の変更は、三か月に一度に制限されています。ポータルの通常の編集フォームでは、関係区分を変更できません。 |
| website, altBusinessIdType, altBusinessId, stockSymbol, stockExchange | 該当するウェブサイト、代替の事業者識別情報、上場企業に関する情報です。事業主体の検証に必要な値を保持してください。 |
| referenceId, ipAddress | サポートされている、事業者の参照情報と送信元 IP のメタデータです。いずれもアカウントへの所属を設定するものではなく、リクエストの冪等性キーとしても機能しません。 |
コードについては、最新のメッセージングカタログを参照してください。更新スキーマでは、ブランドの環境を変更する手段として mock は提供されていません。編集時にこのフラグを変更するのではなく、レビュー済みの別の手順に従って、サンドボックスから本番環境へ移行してください。
確認済みの修正内容を送信する
curl --silent --show-error --fail-with-body --user "$API_USER:$API_PASSWORD" \
--request PUT \
--header 'Content-Type: application/json' \
--header "Idempotency-Key: $IDEMPOTENCY_KEY" \
--data-binary @brand-update.json \
"https://api.multitel.net/tcr/v2/brand/$BRAND_ID"今回の更新には一つのキーを使用し、リクエスト本文のバイト列をそのまま保持してください。メソッド、パス、クエリ、本文を変更して同じキーを再利用すると、競合が発生します。JSON の整形を変更しただけでも、フィンガープリントは変わります。処理中のリクエストと重複した場合、Retry-After を伴う 409 が返されることがあります。完了済みのリクエストでは、エラーも含めて、保存された結果が再返却されることがあります。タイムアウト後に処理結果を確認する際は、自動的に新しいキーを生成せず、リクエストの詳細を保持してください。
保存されたレコードと検証状態を確認する
更新が成功すると、HTTP 200 とブランドの JSON オブジェクトが直接返されます。従来の v3 の status/response エンベロープは付きません。brandId を確認し、同じブランドを再度 GET で取得して、修正対象のフィールドを比較してください。公開されている更新ルートは、ポータルの changes/version ラッパーを受け付けず、ポータルの楽観的同時実行制御によるチェックも提供しません。同時に編集する担当者同士で調整してください。冪等性キーは重複送信を防ぎますが、別の担当者による変更を防ぐものではありません。
現在のポータルは、ブランドを取得し、書き込み可能なフィールドを保持し、保存前にフォームのバージョンを確認したうえで、結果を再取得します。有効なキャンペーンが見つかった場合は、法的な事業者識別情報の主要フィールドをロックします。フォームで入力可能になっていたフィールドでも、登録機関が外部審査に関する制限などの追加制限を適用する場合があります。
修正した情報を保存しても、新たな本人確認が自動的に申請されるわけではなく、承認が保証されるわけでもありません。再確認は別の操作であり、料金が発生する場合があります。ポータルで現在の状態を確認し、提示された料金があれば明示的に承認してください。現在の API サービスでは、通常のブランドの PUT 更新によって、別途登録料が引き落とされることはありません。既存のキャンペーン、メッセージング、その他の料金は、引き続き別に扱われます。
重複登録を作成せずにエラーを解決する
HTTP ステータスと JSON のエラー詳細を確認してください。400 の場合は、該当するフィールドを修正するか、識別情報や関係区分の変更制限に従ってください。401、403、404 の場合は、認証情報、許可された送信元 IP、アカウントへの所属を確認してください。429 の場合は、Retry-After に従ってください。登録機関が更新を受け付けた後に 500 または 502 が発生することもあります。requestId があれば保持し、再送信する前に既存のレコードを取得してください。
更新レスポンスが空でなくても内容が不完全な場合、ローカルのスナップショットが不完全になることがあります。成功レスポンスの本文が空の場合は、スナップショットに古いフィールドが残ることがあります。成功ステータスだけで、フィールドが保持されたと判断してはいけません。ブランドの完全な情報を再取得し、不一致があればサポートを通じて解消してください。このガイドは、登録機関、ローカルキャッシュ、課金の更新がアトミックに行われることを保証するものではありません。