IIJmioのSIMラインアップ

IIJmioクーポンスイッチAPI

<< もどる

「IIJmioクーポンスイッチAPI」について

概要

IIJmioモバイルサービスでは、お客様が用意したプログラムから各機能を操作するためのAPI機能を、実験的に提供しています。

※以降、IIJmioモバイルサービスが提供するAPIを「IIJmioクーポンスイッチAPI」と表記します

本リファレンスでは、IIJmioクーポンスイッチAPIを利用するために必要な技術情報をご説明しています。

注意事項

  • IIJmioクーポンスイッチAPIが期待通りに動作しなかったことによる不利益につきましては、保証いたしかねますので、あらかじめご了承ください。
  • IIJmioクーポンスイッチAPIについて、当社では技術的なサポートをいたしかねますので、あらかじめご了承ください。
  • IIJmioクーポンスイッチAPIはIIJmioのご契約者様向けに提供しています。そのため、デベロッパ登録には有効な mioID が必要です。

本ページの内容をすべてご確認いただいた上で、IIJmioクーポンスイッチAPIをご利用の際は、https://api.iijmio.jp/（新しいウインドウを開きます）よりログインの上、デベロッパIDを取得してください。

ご利用にあたって

デベロッパIDとアクセストークン

各アプリケーションからIIJmioクーポンスイッチAPIを利用する際には、デベロッパIDとアクセストークンが必要です。

  • デベロッパID
    • 開発者を識別する文字列です。
    • IIJmioクーポンスイッチAPIを利用する際に、X-IIJmio-Developer ヘッダに指定する必要があります。
  • アクセストークン
    • アプリケーションの利用者を識別する文字列で、mioIDとパスワードによって利用者の認証/認可を行うことで発行されます。
    • IIJmioクーポンスイッチAPIを利用する際に、X-IIJmio-Authorization ヘッダに指定する必要があります。

デベロッパIDの取得方法

使用許諾規約に同意の上、IIJmioクーポンスイッチAPIをご利用の際は、https://api.iijmio.jp/（新しいウインドウを開きます）​よりデベロッパコンソールにログインし、デベロッパIDを取得してください。 デベロッパ登録には有効な mioID が必要です。
デベロッパコンソールでは以下の操作が可能です。

  • デベロッパIDの発行（APIの利用登録）
    • ログインし、IIJmioアプリ連携画面で「許可する」を選択してください。
    • デベロッパコンソールにあなたのデベロッパIDが表示されます。
  • デベロッパIDの確認/再発行
    • 発行時と同じ手順でデベロッパコンソールよりデベロッパIDを確認できます。
    • デベロッパIDの再発行が必要な場合は右下のヘルプボタンから「デベロッパIDの再発行」を選択してください。
  • API利用アプリケーションの登録
    • 開発したアプリケーションをリダイレクトURIとして登録してください。

アクセストークンの取得方法

デベロッパコンソールにてリダイレクトURIを登録した後、以下の認可手順にそって取得できます。
IIJmioクーポンスイッチAPIのアクセストークン取得の仕組みはOAuth 2.0 Authorization FrameworkのImplicit Grantを元に構成されています。詳しくは OAuth 2.0 の RFC 6749, RFC6750 を参照してください。


アクセストークン取得フロー

  • リクエスト

Webブラウザにて以下のURLにアクセスしてください。
https://api.iijmio.jp/mobile/d/v1/authorization/
以下のクエリパラメータを指定してください。
パラメータ名 必須 指定する値
response_type ○ "token" という固定文字列を指定してください。
client_id ○ デベロッパIDを指定してください。
redirect_uri ○ デベロッパコンソールで設定済みのリダイレクトURIを指定してください。
state ○ ユーザの認可後に行われるリダイレクト時にこの値が含まれます。任意の値を設定してください。
リクエストのサンプルは以下の通りです。
https://api.iijmio.jp/mobile/d/v1/authorization/?response_type=token&client_id=example_developer_idS&state=example_state&redirect_uri=jp.ad.iij.couponswitch%3A%2F%2Fcb

  • レスポンス

ユーザ認可後、redirect_uri に指定した戻り先にリダイレクトされます。 その際、下記パラメータがハッシュフラグメントに付与されます。
パラメータ名 値
access_token アクセストークン文字列
token_type アクセストークンの種類。常に "Bearer" という値が返却されます。
expires_in アクセストークンが失効するまでの時間（秒）
state リクエスト時に指定された state 値が返却されます。このパラメータを使用してセッションが維持されていることを必ず確認してください。

  • エラー

以下の場合はエラー画面を出力します。
  • client_id が不正
  • redirect_uri がデベロッパコンソールで設定済みのリダイレクトURIと一致しない
上記以外は redirect_uri で指定した URI に以下のエラー内容を返却します。
パラメータ名 値
error invalid_request パラメータ不正
unsupported_response_type サポート外のレスポンスタイプ
server_error 認可サーバのエラー
error_description エラー内容の詳細な説明
state リクエスト時に指定された state 値が返却されます。このパラメータを使用してセッションが維持されていることを必ず確認してください。

  • 注意事項

  • IIJmioクーポンスイッチAPIではOAuth 2.0 Authorization Framework の Implicit Grant のみをサポートします。
  • デベロッパIDをOAuth 2.0のclient_idパラメータとして利用するため、デベロッパIDは基本的に第三者から参照可能です。あらかじめご了承ください。
  • 認可は標準ブラウザなどを利用して行ってください。アプリケーション側にmioIDとパスワードを入力させて認可する実装はしないでください。

APIリファレンス

基本仕様

IIJmioクーポンスイッチAPIで利用するプロトコルは以下の通りです。
プロトコル HTTP/1.1 (https 443/tcp)
HTTPメソッド GET または PUT
リクエスト Content-Type application/json
レスポンス Content-Type application/json
APIサーバ https://api.iijmio.jp/
  • http (80/tcp) でのリクエストは受け付けません。
  • 短期間に多数のAPIリクエストが行われた場合、API リクエストを制限する場合があります。
  • 開発者及び利用者の認証のため、HTTPリクエストに X-IIJmio-Developer、X-IIJmio-Authorization ヘッダを付与してください。
  • エンドポイント、デベロッパID、利用者アクセストークン、JSON リクエストは case sensitive (大文字/小文字が区別される) です。
  • HTTP ヘッダのフィールド名は case insensitive (大文字/小文字は区別されない) です。
  • リファレンス中の JSON は可読性向上のために適宜インデントが含まれています。
各APIには、アクセストークンおよびAPI種別毎にカウントされる、一定時間毎のリクエスト上限数を設定しております。
クーポン残量照会・クーポンのON/OFF状態照会 1分間あたり5リクエスト
クーポンのON/OFF 1分間あたり1リクエスト
データ利用量照会 1分間あたり5リクエスト（データ利用量は数時間毎に更新されます）

クーポン残量照会・クーポンのON/OFF状態照会

  • リクエスト

メソッドとエンドポイント GET https://api.iijmio.jp/mobile/d/v2/coupon/
必須ヘッダ X-IIJmio-Developer: デベロッパIDを指定してください
X-IIJmio-Authorization: アクセストークンを指定してください

  • 正常レスポンス（エコプラン/従量制プラン以外）

HTTP ステータスコード 200
JSON 
{
    "returnCode" : "OK",
    "couponInfo" : [
        {
            "hddServiceCode": "hddXXXXXXXX",
            "plan" : "Light Start",
            "hdoInfo" : [
                {
                    "hdoServiceCode": "hdoXXXXXXXX",
                    "number" : "080XXXXXXXX",
                    "iccid" : "DN00XXXXXXXXXX",
                    "regulation" : true,
                    "sms" : true,
                    "voice" : true,
                    "couponUse" : true,
                    "coupon" : [
                       { "volume": 100, "expire": null, "type": "sim" }
                    ]
                },
             ...
           ],
           "hduInfo" : [
               {
                   "hduServiceCode": "hduXXXXXXXX",
                   "number" : "080XXXXXXXX",
                   "iccid" : "XXXXXXXXXXXXXXXXXXX",
                   "regulation" : true,
                   "sms" : true,
                   "voice" : true,
                   "couponUse" : true,
                   "coupon" : [
                      { "volume": 100, "expire": null, "type": "sim" }
                   ]
               },
            ...
           ],
           "coupon" : [
              {"volume":100, "expire":"201312", type:"bundle"},
              {"volume":200, "expire":"201401", type:"bundle"},
              {"volume":0, "expire":"201312", type:"topup"},
              {"volume":400, "expire":"201401", type:"topup"},
              {"volume":0, "expire":"201402", type:"topup"},
              {"volume":400, "expire":"201403", type:"topup"},
           ],
        },
        {
            "hddServiceCode": "hddXXXXXXXX",
            "plan" : "Light Start",
            "hdxInfo" : [
                {
                    "hdxServiceCode": "hdoXXXXXXXX",
                    "number" : "020XXXXXXXX",
                    "iccid" : "XXXXXXXXXXXXXXXXXXX",
                    "regulation" : true,
                    "sms" : false,
                    "voice" : false,
                    "couponUse" : true,
                    "coupon" : [
                       { "volume": 100, "expire": null, "type": "sim" }
                    ]
                },
             ...
           ],
           "coupon" : [
              {"volume":100, "expire":"201312", type:"bundle"},
              {"volume":200, "expire":"201401", type:"bundle"},
              {"volume":0, "expire":"201312", type:"topup"},
              {"volume":400, "expire":"201401", type:"topup"},
              {"volume":0, "expire":"201402", type:"topup"},
              {"volume":400, "expire":"201403", type:"topup"},
           ],
        }
    ]
}

  • 正常レスポンス（エコプラン/従量制プラン）

HTTP ステータスコード 200
JSON 
{
    "returnCode" : "OK",
    "couponInfo" : [
        {
            "hddServiceCode": "hddXXXXXXXX",
            "plan" : "Eco Minimum",
            "hduInfo" : [
                {
                    "hduServiceCode": "hduXXXXXXXX",
                    "number" : "080XXXXXXXX",
                    "iccid" : "XXXXXXXXXXXXXXXXXXX",
                    "regulation" : true,
                    "sms" : true,
                    "voice" : true,
                    "couponUse" : true
                },
             ...
           ],
           "history" : [
              {"date": "20170101", "event": "add", "volume": 3000, "type": "bundle"},
              {"date": "20170105", "event": "add", "volume": 1000, "type": "topup"}
           ],
           "remains": 50000
        }
    ]
}

  • 異常レスポンス

HTTP ステータスコード 異常に応じたステータスコード
JSON 
{ "returnCode" : (異常に応じたメッセージ) }

  • データ型

データ 型 説明
returnCode 文字列 リターンコード
plan 文字列 プラン名（Family Share, Minimum Start, Light Start, Eco Minimum, Eco Standard, Pay as you go のいずれか）
hddServiceCode 文字列 hddサービスコード
hdoServiceCode 文字列 hdoサービスコード
hduServiceCode 文字列 hduサービスコード
hdxServiceCode 文字列 hdxサービスコード
number 文字列 回線の電話番号
iccid 文字列 回線のICCID
regulation 真偽値 通信規制中の場合に true, それ以外は false
sms 真偽値 SMS機能付きの場合に true, それ以外は false（音声通話機能付きSIMカードの場合も true が返ります）
voice 真偽値 音声通話機能付きの場合に true, それ以外は false
couponUse 真偽値 クーポン使用中（クーポンON）の場合に true, それ以外は false
coupon オブジェクト クーポン残量（エコプラン/従量制プランは返却しない）
 volume 数値 クーポン残量 (MB単位)
 expire 文字列 クーポン有効期限月
 type 文字列 バンドルクーポンの場合に bundle, 追加クーポンの場合に topup, SIM内クーポンの場合に sim
history オブジェクト クーポン上限値変更履歴 (エコプラン/従量制プランの場合のみ返却)
 date 文字列 日付
 event 文字列 add (固定文字列)
 volume 数値 バンドルクーポン追加量 (MB単位)
 type 文字列 追加タイプ (毎月1日のバンドルクーポン割り当てを表す bundle, 上限値変更を表す topup のいずれか)
remains 数値 当月のクーポン残量 (エコプラン/従量制プランの場合のみ返却)

  • エラー一覧

HTTP ステータスコード returnCode 説明
403 X-IIJmio-Authorization is not found X-IIJmio-Authorization ヘッダが指定されていなかった
403 X-IIJmio-Developer is not found X-IIJmio-Developer ヘッダが指定されていなかった
403 Your application is not registered X-IIJmio-Developer ヘッダに指定されたデベロッパIDが登録されていなかった（間違っている）
405 Method not allowed HTTPメソッドが GET, PUT ではない
413 You send too large request PUTされたデータのサイズが大きすぎる
429 Your application sends too many requests X-IIJmio-Developer ヘッダに指定されたデベロッパIDを持つアプリケーション全体からのリクエスト数が上限を超過した
429 You send too many requests X-IIJmio-Authorization ヘッダに指定されたユーザからのリクエスト数が上限を超過した
403 User Authorization Failure X-IIJmio-Authorization ヘッダに指定されたアクセストークンでの認証ができなかった（再認証が必要）
500 Internal Server Error サーバ側でエラーが発生した
503 We are under maintenance サーバのメンテナンス中だった（しばらく待って再度お試しください）

クーポンのON/OFF

  • リクエスト

メソッドとエンドポイント PUT https://api.iijmio.jp/mobile/d/v2/coupon/
必須ヘッダ X-IIJmio-Developer: デベロッパIDを指定してください
X-IIJmio-Authorization: アクセストークンを指定してください
Content-Type: application/json
JSON 
{
    "couponInfo" : [
        {
            "hdoInfo" : [
                { "hdoServiceCode": "hdoXXXXXXXX", "couponUse"     : true },
                ...
            ],
            "hduInfo" : [
                { "hduServiceCode": "hduXXXXXXXX", "couponUse"     : true },
                ...
            ],
            "hdxInfo" : [
                { "hdxServiceCode": "hdxXXXXXXXX", "couponUse"     : true },
                ...
            ]
        }
    ]
}

  • 正常レスポンス

HTTP ステータスコード 200
JSON 
{ "returnCode" : "OK" }

  • 異常レスポンス

HTTP ステータスコード 異常に応じたステータスコード
JSON 
{ "returnCode" : (異常に応じたメッセージ) }

  • データ型

データ 型 説明
hdoServiceCode 文字列 hdoサービスコード
hduServiceCode 文字列 hduサービスコード
hdxServiceCode 文字列 hdxサービスコード
couponUse 真偽値 クーポンを使用する（クーポンONにする）の場合に true, 使用しない（クーポンOFFにする）場合に false を指定する

  • エラー一覧

HTTP ステータスコード returnCode 説明
400 Content-Type must be application/json Content-Type の指定が application/json に指定されていなかった
400 Your data may not be json リクエスト中のデータが JSON としてパースできなかった
400 Your data structure or data type is invalid リクエスト中の JSON の形式または値の型が仕様と異なっていた
403 X-IIJmio-Authorization is not found X-IIJmio-Authorization ヘッダが指定されていなかった
403 X-IIJmio-Developer is not found X-IIJmio-Developer ヘッダが指定されていなかった
403 Your application is not registered X-IIJmio-Developer ヘッダに指定されたデベロッパIDが登録されていなかった（間違っている）
405 Method not allowed HTTPメソッドが GET, PUT ではない
429 Your application sends too many requests X-IIJmio-Developer ヘッダに指定されたデベロッパIDを持つアプリケーション全体からのリクエスト数が上限を超過した
429 You send too many requests X-IIJmio-Authorization ヘッダに指定されたユーザからのリクエスト数が上限を超過した
403 User Authorization Failure X-IIJmio-Authorization ヘッダに指定されたアクセストークンでの認証ができなかった（再認証が必要）
500 Internal Server Error サーバ側でエラーが発生した
503 We are under maintenance サーバのメンテナンス中だった（しばらく待って再度お試しください）
※クーポン利用状態が変化しないリクエスト(現在 couponUse: true な回線に対する couponUse: true のリクエストなど)の場合もエラーとして判定されず、正常応答(200)が返ります

データ利用量照会

  • リクエスト

メソッドとエンドポイント GET https://api.iijmio.jp/mobile/d/v2/log/packet/
必須ヘッダ X-IIJmio-Developer: デベロッパIDを指定してください
X-IIJmio-Authorization: アクセストークンを指定してください

  • 正常レスポンス

HTTP ステータスコード 200
JSON 
{
  "returnCode"      : "OK"
  "packetLogInfo"   : [
      {
        "hddServiceCode": "hddXXXXXXXX",
        "plan"          : "Light Start",
        "hdoInfo"       : [
            {
                "hdoServiceCode": "hdoXXXXXXXX",
                "packetLog"     : [
                    { "date": "20131101", "withCoupon": 50, "withoutCoupon": 50 },
                    { "date": "20131102", "withCoupon": 50, "withoutCoupon": 50 },
                    { "date": "20131103", "withCoupon": 50, "withoutCoupon": 50 },
                    { "date": "20131104", "withCoupon": 0, "withoutCoupon": 0 },
                    ...
                ]
            },
            ...
         ],
         "hduInfo"       : [
             {
                 "hduServiceCode": "hduXXXXXXXX",
                 "packetLog"     : [
                     { "date": "20131101", "withCoupon": 50, "withoutCoupon": 50 },
                     { "date": "20131102", "withCoupon": 50, "withoutCoupon": 50 },
                     { "date": "20131103", "withCoupon": 50, "withoutCoupon": 50 },
                     { "date": "20131104", "withCoupon": 0, "withoutCoupon": 0 },
                     ...
                 ]
             },
             ...
        ]
      },
      {
        "hddServiceCode": "hddXXXXXXXX",
        "plan"          : "Light Start",
        "hdxInfo"       : [
            {
                "hdxServiceCode": "hdxXXXXXXXX",
                "packetLog"     : [
                    { "date": "20131101", "withCoupon": 50, "withoutCoupon": 50 },
                    { "date": "20131102", "withCoupon": 50, "withoutCoupon": 50 },
                    { "date": "20131103", "withCoupon": 50, "withoutCoupon": 50 },
                    { "date": "20131104", "withCoupon": 0, "withoutCoupon": 0 },
                    ...
                ]
            },
            ...
        ]
      }
  ]
}
  • 過去30日分と当日のデータ利用量（MB単位）が日付順に返ります。
  • 通信が行われなかった日についても、0 として値が返ります。

  • 異常レスポンス

HTTP ステータスコード 異常に応じたステータスコード
JSON 
{ "returnCode" : (異常に応じたメッセージ) }

  • データ型

データ 型 説明
returnCode 文字列 リターンコード
hddServiceCode 文字列 hddサービスコード
plan 文字列 プラン名（Family Share, Minimum Start, Light Start, Eco Minimum, Eco Standard, Pay as you go のいずれか）
hdoServiceCode 文字列 hdoサービスコード
hduServiceCode 文字列 hduサービスコード
hdxServiceCode 文字列 hdxサービスコード
date 文字列 通信を行った日付
withCoupon 数値 クーポン使用状態でのデータ利用量（MB単位）
withoutCoupon 数値 クーポン不使用状態でのデータ利用量（MB単位）

  • エラー一覧

HTTP ステータスコード returnCode 説明
403 X-IIJmio-Authorization is not found X-IIJmio-Authorization ヘッダが指定されていなかった
403 X-IIJmio-Developer is not found X-IIJmio-Developer ヘッダが指定されていなかった
403 Your application is not registered X-IIJmio-Developer ヘッダに指定されたデベロッパIDが登録されていなかった（間違っている）
405 Method not allowed HTTPメソッドが GET ではない
429 Your application sends too many requests X-IIJmio-Developer ヘッダに指定されたデベロッパIDを持つアプリケーション全体からのリクエスト数が上限を超過した
429 You send too many requests X-IIJmio-Authorization ヘッダに指定されたユーザからのリクエスト数が上限を超過した
403 User Authorization Failure X-IIJmio-Authorization ヘッダに指定されたアクセストークンでの認証ができなかった（再認証が必要）
500 Internal Server Error サーバ側でエラーが発生した
503 We are under maintenance サーバのメンテナンス中だった（しばらく待って再度お試しください）

mioIDの貸し出し

貸出用mioIDについて

  • アプリを開発し登録する際、登録先がmioIDとパスワードの貸出を開発者に対して要求する場合があります。
  • 以下の「同意事項」にご同意いただける場合に限り、当社より登録先確認用のmioIDを開発者に貸出いたします。
  • 貸出期間は当社よりmioIDを通知してから1週間とします。審査に時間が掛かりそうな場合はご連絡ください。

同意事項

  • 貸し出したmioIDの契約内容や登録情報の変更・修正を禁止します。
  • mioID及びパスワードを第三者に貸し出した場合、その管理責任は開発者が負うものとします。
  • 開発者またはその貸出先がこのmioIDを利用して第三者に与えた損害について当社が当該第三者に当該損害の賠償をしたときは、当社は、開発者に対し、当該賠償について求償することができます。
  • その他当社が不適切と判断した利用方法が確認できた場合、貸出mioIDのご利用を停止するとともに、開発者のIIJmioとの契約を解除する場合があります。

申請方法

  • Twitterの@iijmioアカウントにmioIDの貸出を希望する旨をダイレクトメッセージでご連絡ください。
  • ※この申請方法はTwitterのみとなります。@iijmioとダイレクトメッセージのやり取りが出来るTwitterアカウントをご用意ください。

お問い合わせ

IIJmioクーポンスイッチAPIについて、ご不明な点がございましたら、@iijmioまでお問い合わせください。