KWS API を統合する

KWS API を呼び出して製品検証プロセスをトリガーする方法

KWS API 仕様は、こちら で参照できます。

統合の詳細情報を取得する

KWS API と統合するには、アクセスと認証を有効にするための特定のデータ項目が必要です。以下の手順に従います。

  1. KWS Developer Portal の ダッシュボード を開きます。 2.必要な製品を選択します。製品の [Basic information (基本情報)] の下には、以下の統合の詳細が表示され、コピーすることができます。 integration_info.png

    • [Product ID (製品 ID)] - 製品の KWS ID。

    • [Product client ID (製品クライアント ID)] - 認証 に使用します。

    • [Product API key (製品 API キー)] - Developer Access token の取得に必要なクライアント シークレット。

Parent Verification フローを開始する

  1. お使いのインターフェースで以下の情報を取得します。

    • 親のメールアドレス

    • 子どもの住所

    • 親が使用している言語

  2. 上記の詳細情報を send-parent-email エンドポイントへの認証された API コールを介して KWS に送信します。

このポイントから、フロー全体が KWS によって管理されます。

  1. KWS が、提供されたアドレスにメールを送信し、親の身元を確認し、検証フローを開始します。KWS が、検証用の Web ベース インターフェースを使用します。

  2. 検証が成功すると、KWS は通知メールを保護者に送信し、それらをインターフェースにリダイレクトします。リダイレクト URL は Developer Portal で構成します

認証

API コールは、「Developer Access トークン」と呼ばれる Bearer トークンで認証される必要があります。

Developer Access トークン

Developer Access トークンは、トークン エンドポイントからの client_credentials OAuth 許可と Developer Portal からのクライアント ID およびシークレット を使用して KWS 認証から取得されます。上記の認証情報とトークンは、機密情報として扱い、クライアント アプリケーションに渡さないようにしてください。

注記:各製品にはテストとプロダクションの両方の資格情報があります。

トークンの取得方法:

POST https://auth.kws.superawesome.com/auth/realms/kws/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded
Authorization: basic <base64 of client-id:client-secret>
Request:
grant_type=client_credentials&scope=verification
Response (OAuth2 Token Response):
{
  "access_token": "..."
  "refresh_token": "..."
}

注記:デベロッパー アクセス トークンの有効期限は短く設定されています。oauth トークン リクエストへの応答に、トークンの有効期限が記載されています (変更される場合があります)。OAuth2 の仕様 に従って、トークンの更新を実装します。

リトライ動作

KWS API に統合するシステムには、API コールの再試行メカニズムが実装されているはずです。再試行メカニズムが実装されている場合、エクスポネンシャル バックオフを実行し、API コールから送信されるレート制限ヘッダーに準拠する必要があります。

再試行動作は、サーバーが POST リクエストを返すステータス コードに依存します。

ステータス コード

ステータス コード

動作

100 から 399 まで

コールは成功したと考えられる。

400 から 499 まで

恒久的な失敗。コールが失敗したと記録され、再試行しない。

500 以上、タイムアウト (3 秒) またはネットワーク エラー

一時的な失敗。コールは 1、5、15、30 分後、続いて 1、6、24 時間後に再試行される。最後の再試行が失敗した場合 (ステータス コードは 400以上)、コールは失敗したと記録される。

リダイレクト先 URL

検証が成功 / 失敗した後、KWS が保護者にリダイレクトする URL です。Developer Portal で構成します

Webhooks

KWS は webhook コールを通じてあなたのシステムにイベントを通知します。Webhooks は Developer Portal で設定します。

検証が成功した場合のイベント

KWS は保護者の検証が成功した場合、下記の parent-verified イベントを送信します。

Body
{
  "name": "parent-verified",
  "time":"ISO8601 timestamp",
  "orgId": "uuid",
  "productId": "uuid",
  "environmentId": "uuid",
  "payload": {
    "parentEmail": "...",
    "externalPayload": "...",
    "status: {
      "verified": true,
      "transactionId": "..."
    }
  }
}