iPC利用あり企業招待API
iPC利用あり企業招待API
1. API 概要
API名: iPC利用あり企業招待API
目的: 取引先企業にiPCに登録する依頼を送信する。
概要: このAPIは、クライアントから渡された取引先のメールアドレス宛にiPCへの登録依頼メールを送信します。 メールを受け取った取引先の担当者は、メール内にあるリンクからiPCに登録することができます。
2. リクエスト
2.1 リクエストURL
メソッド：POST
ドメイン：お問い合わせください。
エンドポイント：お問い合わせください。
2.2 リクエストヘッダー
| ヘッダー名 | 値 | 説明 |
|---|---|---|
| Content-Type | application/json | リクエストボディのフォーマット。 |
| Authorization | Bearer {access_token} | 認証トークン。 |
2.3 リクエストボディ
リクエストボディにはJSON形式でデータを含めます。以下はその例です。
例
{
"partners":[
{
"emailAddress": "partner_001@example.com",
"lastName": "山田",
"firstName": "太郎"
},
{
"emailAddress": "partner_002@example.com",
"lastName": "佐藤",
"firstName": "花子"
}
],
"notices": [
"notice_001@example.com", "notice_002@example.com"
]
}
2.4 パラメータ説明
| パラメータ名 | JSONキー | 型 | 必須 | 制約 | 説明 |
|---|---|---|---|---|---|
| 取引先 | partners | array |
○ | - | - |
| - メールアドレス | emailAddress | string |
○ | 最大255文字、メールアドレス形式 | 招待メール送信用メールアドレス。 |
| - 姓 | lastName | string |
○ | 最大50文字 | 招待する取引先担当者の姓。 |
| - 名 | firstName | string |
○ | 最大50文字 | 招待する取引先担当者の名。 |
| 通知先メールアドレス | notices | array |
- | 配列でメールアドレスを複数指定可能。最大50件まで。 | 招待した取引先が登録を完了したら、この項目が指定されている場合はこのリストのメールアドレスにのみ完了通知メールが送信されます。 |
※メールアドレスの形式は、 英数字および . _ % + - を含む文字列で、@の前後に連続したドットを含まず、@以降は英数字・ドット・ハイフン、末尾は英字
3. レスポンス
3.1 レスポンス成功時
ステータスコード: 201 Created
レスポンス例
{
"invitationEmailAddresses" : [
"partner_001@example.com",
"partner_002@example.com"
]
}
レスポンス説明
| パラメーター名 | Jsonキー | 型 | 説明 |
|---|---|---|---|
| 取引先メールアドレス | invitationEmailAddresses |
array |
招待メールを送信したメールアドレスのリストを返します |
3.2 レスポンス失敗時
ステータスコード: 400 Bad Request (入力が不正な場合)
レスポンス例(バリデーションエラー)
{
"code": "METHOD_ARGUMENT_NOT_VALID",
"title": "リクエストの入力データが無効",
"cause": "メールアドレスの形式が不正です。XXXX",
"requestId": "0699939e"
}
{
"code": "METHOD_ARGUMENT_NOT_VALID",
"title": "リクエストの入力データが無効",
"cause": "姓は50文字以内で入力してください。",
"requestId": "0699939e"
}
{
"code": "METHOD_ARGUMENT_NOT_VALID",
"title": "リクエストの入力データが無効",
"cause": "招待する取引先は1つ以上必要です。",
"requestId": "0699939e"
}
ステータスコード: 403 Forbidden (Keycloakの認証エラー)
レスポンス例(権限エラー)
なし
ステータスコード: 500 Internal Server Error(サーバーエラーが発生した場合)
レスポンス例(サーバーエラー)
{
"code": "RUNTIME_ERROR",
"title": "予期せぬエラーが発生",
"cause": "予期せぬエラーが発生しました。",
"requestId": "0699939e"
}
失敗レスポンス説明
| パラメーター名 | Jsonキー | 型 | 説明 |
|---|---|---|---|
| コード | code |
string |
発生したエラーを種類ごとに識別するためのコード |
| タイトル | title |
string |
エラーやイベントの概要を示す短い見出し |
| 原因 | cause |
string |
問題の根本的な要因を説明 |
| 取引先メールアドレス | requestId |
string |
リクエストで一意に振り分けられるID。問い合わせの際に送信してください。 |
4. エラーハンドリング
| ステータスコード | エラーの種類 | 説明 |
|---|---|---|
| 400 | Bad Request | リクエストが不正な場合(例えば、必須パラメータの欠如、フォーマットエラーなど)。 |
| 403 | Forbidden | レスポンスが存在しない場合、Keycloakの認証エラー(全API共通)。 |
| 500 | Internal Server Error | サーバー側の問題。 |
5. 認証
このAPIには、認証が必要です。リクエストのヘッダーにBearerトークンを含めてください。
- Authorizationヘッダー:
Bearer {access_token}ここで、access_tokenは認証を通過したユーザーのアクセストークンです。
6. その他
6.1 メール文面
