目的および適用範囲
本書は、Loxia AI が提供する SaaS ならびに関連する API について、開発者向けの技術仕様を整理したドキュメンテーションです。対象は、エンドポイント、認証、リクエスト、レスポンス形式、Webhook、エラー処理、レート制限、ならびに運用上の前提条件を含みます。実装、検証、保守の各工程において、利用者が参照すべき基本事項を明確化することを目的とします。
本書は、開発、保守、監査、セキュリティ確認、社内レビューのための仕様書として機能することを意図しています。日本国内の企業利用、特に複数部門にまたがる業務自動化、顧客対応フロー、営業支援、社内申請処理などにおいて、API を経由した連携要件を確認する際の基準として用いることができます。なお、個別契約、個別設定、保守条件、SLA、データ取扱条件は、別途の契約書、注文書、または運用合意に従います。
API の基本構造
Loxia AI の API は、HTTPS を介して提供される JSON ベースのインターフェースです。各エンドポイントは機能単位で分割され、リクエストは明確なスキーマに従って送信されます。一般に、入力値は最小限の必須項目と任意項目で構成され、レスポンスには処理結果、識別子、状態情報、必要に応じてエラー詳細が含まれます。これにより、社内システム、CRM、問い合わせ管理、予約管理、在庫管理などとの接続を前提とした自動化が可能になります。
エンドポイント設計においては、機能の分離と可読性が重視されます。たとえば、作成、取得、更新、削除の各操作は個別のリソースとして扱われ、一覧取得にはページネーションが適用される場合があります。開発者向けの実装では、単一のエンドポイントに過度な責務を持たせず、仕様書に記載された粒度に従って呼び出すことが必要です。これにより、監査、障害切り分け、権限管理、将来の拡張に対応しやすくなります。
認証およびアクセス制御
Loxia AI の API へのアクセスには、認証が必須です。通常、認証情報は API キー、トークン、または同等の資格情報として発行され、リクエストヘッダーまたは定められた認証方式に従って送信されます。認証情報は秘密情報として管理し、ソースコード、ログ、チケット、共有文書へ直接記載してはなりません。特に、開発環境、検証環境、本番環境でキーを分離する運用が求められます。
アクセス制御は、利用契約、組織単位、役割単位、または用途単位で設定されることがあります。たとえば、東京の本社と大阪の拠点で同一 SaaS を利用する場合でも、部門ごとに利用可能な API 群を限定し、Webhook の送信先やデータ閲覧範囲を分ける設計が適切です。これにより、最小権限の原則を維持し、内部統制および情報管理の要件に適合させることができます。
リクエスト形式とレスポンス形式
リクエストは JSON 形式を基本とし、文字コードは通常 UTF-8 を前提とします。値の型は、文字列、数値、真偽値、配列、オブジェクトとして定義され、日付時刻は仕様書で指定された形式に従います。実装側は、必須項目の未設定、型不一致、長さ制限超過、フォーマット不備を送信前に検査することが推奨されます。これにより、不要な再試行やエラー増加を防止できます。
レスポンス形式も JSON を基本とし、成功時には処理結果と関連メタデータが返されます。典型的には、識別子、ステータス、作成日時、更新日時、参照用リンク、関連オブジェクトが含まれます。失敗時には、エラーコード、説明文、検証失敗箇所、必要に応じて再試行可否が返されます。システム連携では、画面表示用の文言ではなく、機械処理向けのフィールドを優先して利用し、表示層は利用側で独立して管理することが望ましいです。
Webhook と非同期連携
Webhook は、Loxia AI の処理結果や状態変化を外部システムへ通知するための仕組みです。同期的な API 呼び出しだけでは処理完了のタイミングを追跡しにくい場合に、Webhook を用いることで、予約確定、更新完了、処理失敗、状態遷移などを即時に受信できます。これにより、社内システム側はポーリング処理を抑制し、不要なトラフィックを減らすことができます。
Webhook の受信側では、署名検証、再送制御、重複排除を実装する必要があります。特に、業務自動化の場面では、通知の到達順序が前後した場合でも整合性が保たれる設計が重要です。たとえば、商談予約の自動登録、問い合わせのチケット生成、在庫引当、配送準備などでは、Webhook を契機として複数の内部処理が連鎖します。このため、受信確認の応答を速やかに返し、重い処理は非同期キューに移す実装が一般的です。
エラー処理、再試行、レート制限
エラー処理は、API 連携の安定性を左右する重要な要素です。Loxia AI の API では、認証失敗、権限不足、入力不備、対象未存在、競合、処理失敗、内部障害などを区別して扱うべきです。利用者は、エラーコードだけでなく、HTTP ステータス、メッセージ、補足情報を組み合わせて判定し、再送、修正、停止のいずれに該当するかを実装上で分岐させる必要があります。
レート制限は、サービス安定運用のために適用されます。一定時間内の過剰なリクエストは制限対象となり、超過時には所定のステータスまたは案内が返されます。開発者向けの実装では、指数バックオフ、キュー制御、バッチ化、キャッシュの利用を検討することが望まれます。日本企業の業務自動化では、月末月初、祝前日、キャンペーン期間、展示会開催日などに処理が集中しやすいため、ピーク時の負荷分散を含めた設計が必要です。
データ保護、監査、運用上の留意事項
API を通じて送受信される情報には、個人情報、連絡先、注文情報、予約情報、取引履歴、運用ログが含まれる場合があります。したがって、送信内容は必要最小限に限定し、保存期間、アクセス権限、マスキング、暗号化、バックアップ方針を明確にする必要があります。特に、EU 圏のデータ主体に関する取扱いが含まれる場合は GDPR、米国の州法の対象となる場合は CCPA など、適用法令を確認したうえで設計する必要があります。
監査可能性の確保のため、主要な操作には実行主体、実行時刻、対象リソース、結果状態、関連識別子を記録することが推奨されます。これにより、障害解析、権限確認、再処理、内部監査に対応できます。SaaS の利用においては、利用者側システムと Loxia AI 側の両方でログの粒度や保存期間が異なる場合があるため、運用開始前に整合性を確認し、必要な証跡が取得可能であることを検証してください。
仕様変更、互換性、開発者向け確認事項
API 仕様は、機能追加、セキュリティ強化、非推奨化、形式変更により更新されることがあります。利用者は、仕様書のバージョン、変更履歴、非推奨期限、後方互換性の有無を定期的に確認し、継続利用に支障がないかを検証する必要があります。特に、レスポンス形式の追加項目、必須項目の変更、Webhook イベント名の変更は、既存実装へ影響を与えるため注意が必要です。
開発者向けの確認事項としては、以下が含まれます。認証情報の保管方法、環境別の設定値、エラーハンドリング方針、再試行条件、タイムアウト値、Webhook の署名検証、レート制限の把握、テスト用データの取り扱いです。社内の承認フローにおいては、実装担当、セキュリティ担当、業務主管部門が同一の仕様書を参照し、設定差異を文書化することが望まれます。これにより、SaaS と社内システムの接続を、安定的かつ統制の取れた形で運用できます。