アラームボックス API Getting Start

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

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

目次

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

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

現在アラームボックス 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)

アプリケーションの登録 (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/token(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 にして保証依頼をしてください。
保証の金額は指定した審査の保証可能金額の残存枠の範囲になります。