まずは使ってみましょう

KREISEL API を使い始めるための最初のステップへようこそ！

このページでは、API の認証方法から、実際に API を呼び出して基本的な情報を取得する方法、そしてエラーが発生した際の対処法までを解説します。

認証

KREISEL JSON API では、リクエストの認証にAPIトークンを使用します。

API トークンは、KREISEL のシステム管理者が [システム] > [アカウント] > [APIトークン管理] メニューから発行します。セキュリティの観点から、API トークンに紐づくアカウントには、API で実行したい処理に必要な権限のみを付与することを強く推奨します。

API を呼び出すには、すべてのリクエストのAuthorizationヘッダーに、発行された API トークンをBearer形式で含める必要があります。

Authorization: Bearer <YOUR_API_TOKEN>

API トークンの管理

API トークンはパスワードと同様に非常に重要な情報です。第三者に漏洩しないよう、厳重に管理してください。ソースコード内に直接書き込むことは避け、環境変数などを利用することをお勧めします。

リクエストのサンプル (PHP)

以下に、get_environment_name API を呼び出す PHP のサンプルコードを示します。

<?php

// 環境IDとAPIトークンを設定
$environmentId = 'YOUR_ENVIRONMENT_ID';
$apiToken = 'YOUR_API_TOKEN';

// エンドポイントURL
$url = "https://krs.bz/{$environmentId}/api/v1/get_environment_name";

// cURLセッションを初期化
$ch = curl_init();

// cURLオプションを設定
curl_setopt_array($ch, [
    CURLOPT_URL => $url,
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    // ボディは空でも良いが、JSON形式であることを明示
    CURLOPT_POSTFIELDS => json_encode(new stdClass()),
]);

// APIを実行し、レスポンスを取得
$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

// cURLセッションを終了
curl_close($ch);

// 結果をデコードして表示
if ($http_code == 200) {
    $data = json_decode($response, true);
    echo "環境名: " . $data['envname'] . PHP_EOL;
} else {
    echo "エラーが発生しました。 HTTP_CODE: {$http_code}" . PHP_EOL;
    echo $response . PHP_EOL;
}

APIを呼び出してみる

それでは、実際に API を呼び出してみましょう。ここでは、汎用的なコマンドラインツールであるcURLと、Web 開発で広く使われているPHPを使ったサンプルコードを紹介します。

API のエンドポイント URL は、ご利用の環境によって異なります。基本的には以下の形式になります。

環境	ベースURL
通常環境	https://krs.bz/{environmentId}/api/v1/{apiName}
カスタムドメイン	https://{customDomainName}/api/v1/{apiName}
APIテスト環境	https://apitest.krs.bz/{environmentId}/api/v1/{apiName}
API検証環境	https://apibeta.krs.bz/{environmentId}/api/v1/{apiName}

• {environmentId}: 弊社から発行される環境 ID に置き換えてください。
• {customDomainName}: カスタムドメインをご利用の場合のドメイン名です。

注意

KREISEL にてカスタムドメインのオプションをご利用の場合や、デモ版をご利用の場合は、接続先 URL が上記と異なる場合があります。

KREISELのバージョンを取得する (cURL)

最初に、認証が不要な API を試してみましょう。get_version API は、現在の KREISEL のバージョンを返します。

ターミナルから以下のコマンドを実行してみてください。

curl -X POST -H "Content-Type: application/json" https://krs.bz/{environmentId}/api/v1/get_version

成功すると、以下のような JSON レスポンスが返ってきます。

{
  "version": "1.5.0"
}

環境名を取得する (PHP)

次に、認証が必要な API を PHP で呼び出してみましょう。get_environment_name API は、設定されている環境名を返します。

以下のサンプルコードでは、PHP の cURL 拡張機能を利用して API を呼び出します。

<?php

/**
 * KREISEL APIを呼び出す関数
 *
 * @param string $apiName 呼び出すAPI名 (例: get_environment_name)
 * @param string $token APIトークン
 * @param array $params APIに渡すパラメータ
 * @return array APIからのレスポンス(連想配列)
 * @throws Exception API呼び出しでエラーが発生した場合
 */
function callKreiselApi(string $apiName, string $token, array $params = []): array
{
    // {environmentId}をご自身の環境IDに置き換えてください
    $environmentId = 'YOUR_ENVIRONMENT_ID';
    $endpoint = "https://krs.bz/{$environmentId}/api/v1/{$apiName}";

    $headers = [
        'Content-Type: application/json; charset=utf-8',
        'Authorization: Bearer ' . $token,
    ];

    $ch = curl_init($endpoint);

    // オプション設定
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $responseBody = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

    if (curl_errno($ch)) {
        $error = curl_error($ch);
        curl_close($ch);
        throw new Exception('cURL Error: ' . $error);
    }

    curl_close($ch);

    $response = json_decode($responseBody, true);

    // HTTPステータスコードが400以上はエラーレスポンスとして処理
    if ($httpCode >= 400) {
        $errorMessage = "KREISEL API Error: (HTTP {$httpCode})";
        if (isset($response['error_code'], $response['error_desc'])) {
            $errorMessage .= " {$response['error_code']} - {$response['error_desc']}";
        } else {
            $errorMessage .= " " . $responseBody;
        }
        throw new Exception($errorMessage);
    }

    return $response;
}

// --- APIの呼び出し実行 ---

// YOUR_API_TOKENをご自身のAPIトークンに置き換えてください
$apiToken = 'YOUR_API_TOKEN';

try {
    // 1. バージョン情報を取得 (認証不要API)
    $versionInfo = callKreiselApi('get_version', $apiToken);
    echo 'KREISEL Version: ', $versionInfo['version'], PHP_EOL;

    // 2. 環境名を取得 (認証必要API)
    $envInfo = callKreiselApi('get_environment_name', $apiToken);
    echo 'Environment Name: ', $envInfo['envname'], PHP_EOL;

} catch (Exception $e) {
    echo 'エラーが発生しました: ', $e->getMessage(), PHP_EOL;
}

備考

get_version API は認証が不要ですが、他の多くの API（get_environment_nameなど）では、リクエストヘッダーに有効な API トークンを含める必要があります。トークンがない、または無効な場合はエラーとなります。

エラーハンドリング

API の呼び出し時に何らかの問題が発生した場合、KREISEL API は HTTP ステータスコード4xxまたは5xxと共に、エラーの詳細を含む JSON レスポンスを返します。

エラーレスポンスの基本的な形式は以下の通りです。

{
  "error_code": "KR_API_F1001",
  "error_desc": "Authentication Failed.",
  "message": "Bearer token is missing or invalid."
}

キー	内容
error_code	KREISEL APIが定義するエラーコードです。
error_desc	エラーコードに対応する説明です。
message	(オプション) エラーに関する追加の詳細情報が含まれる場合があります。

上記の PHP サンプルコードのように、API を呼び出す際は HTTP ステータスコードを必ず確認し、エラーレスポンスを適切に処理するように実装してください。

各 API 固有のエラーコードについては、それぞれの API リファレンスページを参照してください。