アラームボックス API Getting Start

アラームボックス API のご利用を検討してくださり、ありがとうございます。
本ページではアラームボックス API の概要と利用手順を説明します。

※ アラームボックス API のご利用にはアラームボックスのサービス(モニタリング・パワーサーチ、またはギャランティ)の利用登録が必要です。
※ API リファレンスはこちらです。
※ Sandbox 環境のご用意はありません。
※ API に関するご相談やご不明の点などはこちらからお問い合わせください。

---

目次

• アラームボックス API 概要
  • API エンドポイント
  • 認証
  • データフォーマット
• 利用手順
  • アプリケーションの登録
  • 認証の取得
    • 認可コードの取得
    • アクセストークンの取得
    • リフレッシュトークンの利用
  • アラームボックス API をコールする
• エンドユーザーのアプリ利用手順
• API リファレンスの利用
• テストアカウントについて
  • パワーサーチ
  • モニタリング
  • ギャランティ

アラームボックス API 概要 (overview)

アラームボックス API はアラームボックスのモニタリング、パワーサーチ、ギャランティサービスに関する API を提供します。
API を活用することで、お客様のシステムや利用しているサービスでアラームボックスをご利用いただくことが可能になります。

現在アラームボックス API で提供している機能は以下のとおりです。

<機能一覧>

• モニタリング
  • 取引先の一覧取得
  • 取引先の登録
  • 取引先の削除
  • 取引先の情報取得
  • アラーム情報の取得
• パワーサーチ
  • 調査レポート購入
  • 反社チェック購入
  • 登記チェック購入
  • 信用チェック購入
  • 調査レポート一覧取得
  • 調査レポート詳細取得
  • 反社チェック一覧取得
  • 反社チェック詳細取得
  • 登記チェック一覧取得
  • 登記チェック詳細取得
  • 信用チェック一覧取得
  • 信用チェック詳細取得
  • 購入企業一覧取得
• ギャランティ
  • 保証審査依頼
  • 保証審査一覧取得
  • 限度額廃止依頼
  • 保証依頼
  • 保証一覧取得

API エンドポイント (endpoint)

https://api.alarmbox.jp
(httpsのみ)

認証 (authentication)

OAuth 2.0 を使用します。 アプリケーション利用者はアラームボックスの ID とパスワードをアプリケーションに教えることなくアラームボックスの連携を認証でき、連携したアプリケーションでは付与した権限に応じてアラームボックス API を経由して情報の取得や登録などができるようになります。

アラームボックス API では下記２つのフローをサポートしています。

• Authorization Code Flow (Web アプリ向け)
• Implicit Flow (Mobile アプリ向け)

データフォーマット (data format)

リクエスト、レスポンスともに JSON 形式をサポートしています。
詳細はAPI リファレンスを確認してください。

---

利用手順(開発者向け) (how to develop)

• アカウント登録
  • API のご利用にはアラームボックスのアカウントが必要です。
  • 未登録の場合はアカウント登録をしてください。
• アプリケーションの登録
  • アラームボックスと連携するアプリケーションを登録します。
  • まずは最初の API コールを簡単にしてみたい！という場合は、アプリケーション登録後にAPI リファレンスの利用をお試しください。
• アクセストークンの取得
  • アクセストークンを取得します。
• アラームボックス API をコールする
  • アクセストークンを利用してアラームボックス API をコールします。
  • API の詳細はアラームボックス API リファレンスをご覧ください。
• API リファレンスの利用
  • API リファレンスを利用してアラームボックス API をコールします。
  • 呼び出しのサンプルなどもご覧いただけます。

---

アプリケーションの登録 (create app)

アラームボックス API を利用するアプリケーションを登録します。登録によりアプリケーションの ID と Secret が発行され、アラームボックスユーザーが当該アプリを利用できる状態となります。

• 開発者のアカウントでアラームボックス API 管理にログインします。
  • ユーザー ID、パスワードはアラームボックスサービスにログインするものと同じです。
• アプリケーション一覧にアクセスします。
• 「+新しいアプリケーションを登録」をクリックします。
• アプリケーション名、コールバック URI を入力し保存します。
  ※ ローカル環境用のアプリケーションでは、コールバック URI に「urn:ietf:wg:oauth:2.0:oob」をご利用ください。
• アプリケーションが登録され、ID と Secret が表示されます。
• アプリケーションの一覧にアプリケーションが追加されます。
• アプリケーション名をクリックすると登録内容が確認できます。

---

認証の取得 (authenticate)

アクセストークンを取得するには、認証用 URL にて認可コード（Authorization code）を取得し、それを用いて http リクエストを送る必要があります。

認可コードの取得 (get auth-code)

パラメータにアプリケーション登録で生成された情報を指定して認証用 URLにリクエストを送信してください。
リクエストが成功すると、リダイレクトのパラメータに code が付加されますので格納してください。
※リダイレクト URI にurn:ietf:wg:oauth:2.0:oobを指定している場合はアプリケーション画面の Web アプリ認証用 URL にアクセスして取得することも可能です。

• 認証用 URL
  https://api.alarmbox.jp/oauth/authorize(GET)
• パラメータ一覧 (全て必須)

  項目名	説明
  client_id	アプリケーション ID
  redirect_uri	アプリケーションに登録したコールバック URL
  response_type	"code"(固定)
  scope	read , customer:create , customer:delete , survey_report:create , anti_social_check:create , registration_info:create , credit_check:create

• リクエストサンプル

  https://api.alarmbox.jp/oauth/authorize?
      client_id=xiBZpDIlKt1q0koE8uNLqmxfeUhLAxJ6n3oqdGMlo4w&
      redirect_uri=urn:ietf:wg:oauth:2.0:oob&
      response_type=code&
      scope=read+customer:delete+customer:create
  

• リダイレクト URL

  https://hoge.example.com/callback?code=jflkajklfjlahroihalrhalkhrklahra
  

アクセストークンの取得 (get access-token)

前項で取得した認可コードを使用して、アクセストークンを取得します。
下記パラメータを指定してトークン取得用 URLにリクエストをPOST送信してください。

• トークン取得用 URL
  https://api.alarmbox.jp/oauth/authorize(POST)

• パラメータ一覧 (全て必須)

  パラメータキー	設定値
  grant_type	"authorization_code"(固定)
  client_id	アプリケーション ID
  client_secret	シークレットキー
  code	認証コード
  redirect_uri	遷移先の URL

• curl コマンドを使ってアクセストークンを取得する場合のサンプル

  curl -i -X POST -d grant_type=authorization_code \
  -d client_id=xiBZpDIlKt1q0koE8uNLqmxfeUhLAxJ6n3oqdGMlo4w \
  -d client_secret=q_Qr14VQml1b4vPw7dWeDK_tsotcUGV7Ri5i7TLFBUE \
  -d code=CU8wbymHIiKUYy6tsY8dbCbzsZNdEucx70d2ZpBLz3Q \
  -d redirect_uri=urn:ietf:wg:oauth:2.0:oob \
  https://api.alarmbox.jp/oauth/token
  

• レスポンス

  パラメータキー	設定値
  access_token	アクセス トークン
  refresh_token	リフレッシュ トークン
  token_type	Bearer（固定）
  expires_in	有効期間
  scope	許可された権限
  redirect_uri	遷移先の URL
  created_at	トークンを生成したタイムスタンプ

• 例

  {
    "access_token": "l-TGspUX-fPghhcKpxWfkyQXbTQnvSejqeTVXlKiKo8",
    "token_type": "Bearer",
    "expires_in": 86400,
    "refresh_token": "JlV8SeYcWwGrsAMh8ylftHQGttitwd2NRibImg3QUes",
    "scope": "read customer:delete customer:create",
    "created_at": 1618206635
  }
  

リフレッシュトークンの利用 (use refresh-token)

アクセストークンやアクセストークンの取得に利用する認可コードには有効期限があり、UI を伴わないバッチ処理やシステム連携での継続的な利用には不向きです。 その場合にリフレッシュトークン(refresh_token)の仕組みを使うことで継続的にアクセストークンの取得をすることができます。 アクセストークン取得時にリフレッシュトークンも同時に発行されています。 そのリフレッシュトークンを保管することで、次回に保管したリフレッシュトークンを使って アクセストークンを取得していただくことができます。
※ 最初の一度は通常のアクセストークン取得の手順を行う必要があります。
※ リフレッシュトークンには有効期限はありませんので前回の認証から時間が経過しても継続的に使うことができます。 ※ リフレッシュトークンを用いてアクセストークンを取得するたびにリフレッシュトークンも更新されますのでご注意ください。

• curl コマンドを使ってリフレッシュトークンからアクセストークンを取得する場合のサンプル

  curl -i -X POST -d grant_type=refresh_token \
  -d client_id=xiBZpDIlKt1q0koE8uNLqmxfeUhLAxJ6n3oqdGMlo4w \
  -d client_secret=q_Qr14VQml1b4vPw7dWeDK_tsotcUGV7Ri5i7TLFBUE \
  -d refresh_token=CU8wbymHIiKUYy6tsY8dbCbzsZNdEucx70d2ZpBLz3Q \
  -d redirect_uri=urn:ietf:wg:oauth:2.0:oob \
  https://api.alarmbox.jp/oauth/token
  

• レスポンス

  パラメータキー	設定値
  access_token	アクセス トークン
  refresh_token	リフレッシュ トークン
  token_type	Bearer（固定）
  expires_in	有効期間
  scope	許可された権限
  redirect_uri	遷移先の URL
  created_at	トークンを生成したタイムスタンプ

• 例

  {
    "access_token": "l-TGspUX-fPghhcKpxWfkyQXbTQnvSejqeTVXlKiKo8",
    "token_type": "Bearer",
    "expires_in": 86400,
    "refresh_token": "JlV8SeYcWwGrsAMh8ylftHQGttitwd2NRibImg3QUes",
    "scope": "read customer:delete customer:create",
    "created_at": 1618206635
  }
  

---

アラームボックス API をコールする (call ab-api)

リクエストヘッダにアクセストークンを指定してください。

Authorization: Bearer {ACCESS TOKEN}

• サンプル
  • /common/v1/users/me をコールする

  curl -H "Authorization: Bearer 123456abc" https://api.alarmbox.jp/common/v1/users/me
  

  • 下記のような JSON が返ってきたら成功です。

  user":{"id":XXXX,"member_id":XXX,"email":"[your_email_address]"}}
  

---

エンドユーザーのアプリ利用手順 (how to use)

エンドユーザーとは上記手順で作成したアプリケーションを経由してアラームボックスを利用(連携)するユーザーを指します。 連携アプリケーション側ではこのタイミングでユーザーと紐づいたアクセストークンを取得します。
（必要ならリフレッシュトークンを格納します。）
エンドユーザーの連携設定は基本的にはアラームボックスへログインし「承認」をクリックするだけで完了します。

一般的な流れは以下のようになります。

1. 連携元アプリケーションにて実装される連携ボタンをクリックする
2. 下記のような画面が表示される
3. ユーザーが「承認」する
4. アプリケーションに設定されているリダイレクト URI に遷移
   → 元のアプリケーションに戻る

API リファレンスの利用 (use swagger-ui)

アラームボックス API リファレンスを下記サイトで提供しております。
https://alarmbox.github.io/alarmbox_api_docs/refs/
認証情報を入力することで API の挙動を確認すことができますのでご利用ください。
また同サイトから openapi 形式(yaml)をファイルでダウンロードできますのでご活用ください。

＜利用手順＞

1. 認証設定をします
   • 鍵マークをクリックします
     
   • 認証設定画面が表示されたらアクセストークンを入力します。
     
   • 「Authorize」で問題なければ下記の画面が表示されます。
     「Close」で閉じてください。
     
   • 鍵マークが施錠した状態になっていることを確認します。
     
2. API のコール
   • 利用したい API のリファレンスを開きます
   • 「Try It Out」をクリックします。
   • 必要なパラメータを入力し、「Execute」をクリックします。
     • 問題なければ URL や実際のレスポンスなどが表示されます。

※ 画面操作等は swagger-ui のリファレンスや情報をご参照ください。

テストアカウントについて (test account)

アラームボックス API では開発用にテストアカウントモードを用意しております。
テストアカウントモードの詳細は下記サービスごとの項でご確認ください。

※ テストアカウントモードを利用するには弊社での設定が必要になりますので、
　テストアカウント設定をご希望の場合は開発用のアカウントを登録後、
　こちらからアカウントのメールアドレスをご連絡ください。

パワーサーチ(ps)

反社チェック

専門会社調査のレスポンスで実際の調査結果ではなくダミーの調査結果を返します。
調査結果なしのテストしたい場合は下記を指定してください。

• 企業調査の場合：会社名に「アラームボックス」を指定
• 個人名調査の場合：個人名に「アラーム太郎」を指定

信用チェック

以下のダミーの法人番号を指定することで、
対応する調査結果を返します。
ダミーの法人番号以外では、指定した法人番号に該当する法人が見つからない旨のメッセージを返します。

ダミー法人番号	結果
0000000000001	OK
0000000000002	HOLD
0000000000003	NG

モニタリング(mn)

テストアカウントの機能はありません。

ギャランティ(gt)

保証審査依頼

テストアカウントの場合はすべての保証審査依頼が自動的に承認されます。
「クライアントからの連絡事項」にタグを設定することで審査の可決否決と 審査の可決金額をコントロールできます。 タグがない場合は希望金額通り可決になります。 どちらもある場合は否決が優先されます。

• タグ一覧
  • [[result:ng]]・・・否決されます。
  • [[limit_amount:99999]]・・・指定した金額で可決されます。0 を指定した場合は否決と同義になります。

保証依頼

テストアカウントの場合はすべての保証依頼が自動的に承認されます。
ただし、一連の保証依頼の最後の保証依頼が完了するまで承認が有効にならないので注意してください。
一連の保証依頼の最後の保証依頼を要求する場合、または、保証依頼を 1 件毎に承認するにはend_of_guarantee_requestを true にして保証依頼をしてください。
保証の金額は指定した審査の保証可能金額の残存枠の範囲になります。