ドキュメントレポートとデータ

API

自分のツールからスタディ、結果、機械、カタログを読み、または稼働データを送る。連携ごとにキーはひとつ。

1 分で読了7 セクション

APIは、見積ツールがレポートから数字を書き写すことなくスタディのスループットと投資回収を得たいとき、あるいは車両管理者がスプレッドシートなしで日次の稼働データを送りたいときのためのものです。TeamとEnterpriseで、auddomate.comでも自社ホストのインストールでも利用できます。返すものはすべてアプリで見えるものと同じです：同じ車両群、同じ前提、同じ算数。

キー

オーナーは設定 → APIキーでキーを作ります。使用するシステムにちなんで名前を付け、できることにチェックを入れ、表示されたときにキーをコピーします — 表示は一度きりで、ハッシュ化して保存されます。キーはひとつ以上のスコープを持ちます：

read: スタディ、結果、機械、カタログ。すべてのキーがこれを持ちます。
telemetry: スタディにテレメトリ行を書き込む。
audit: 監査ログを読む。

同じページからキーを取り消せます。取り消した瞬間から、それを使うものはすべて401を受け取ります。キーの作成と取り消し自体も監査ログに書かれます。組織あたり有効なキーは20個まで。

呼び出し

すべてのリクエストはキーをベアラートークンとして持ちます。ベースアドレスはAuddomateのアドレスに/api/v1を付けたものです。

bash

curl -H "Authorization: Bearer aud_…" https://auddomate.com/api/v1/me

あなたとサーバーの間でAuthorizationヘッダーが落とされる場合は、代わりにX-Api-Key: aud_…として送ってください。応答は安定した形のJSONです：

json

{ "ok": true, "data": …, "meta": { "page": 1, "per_page": 50, "total": 132, "pages": 3 } }
{ "ok": false, "error": "not_found", "message": "No study ST-9999 in this organisation." }

一覧は?page=と?per_page=（最大200）でページ送りします。時刻はサーバーのローカル時刻でYYYY-MM-DD HH:MM:SS、長さはミリメートル、距離はメートル、レートは1時間または1日あたり、アプリとまったく同じです。各キーは毎分300リクエストまで可能で、超えるとRetry-Afterヘッダー付きの429が返ります。

エンドポイント

GET /api/v1/me: 組織、キーの名前とスコープ、エディション、レート制限。キーが動くかの確認に使います。
GET /api/v1/studies: すべてのスタディ：参照番号、名前、現場、顧客、ステータス、現在のシナリオのスループット判定と余裕、車両群の台数。?status=、?client=、?updated_since=2026-09-01で絞り込めます。
GET /api/v1/studies/{ref}: 参照番号（ST-1001）またはIDによるスタディ全体：図面（ファイル、縮尺、範囲、ラック・通路・ドック・障害物の数）と、各シナリオの車両群の行、前提、行ごとのスループット結果、最も要求の厳しい機械に対する通路検査、そしてその機械がどれか。
GET /api/v1/studies/{ref}/telemetry: スタディの稼働データ。1機械1日につき1行。
GET /api/v1/studies/{ref}/pdf: サーバーで生成したPDFファイルとしてのレポート。?lang=と?units=imperialで言語と単位を選びます。保存済みバージョンは/versions/{n}/pdf。
GET /api/v1/studies/{ref}/versions: スタディの保存済みバージョン、新しい順。/versions/{n}はスタディ自体と同じ形でひとつを丸ごと返し、?diff=1でそれ以降の変更が加わります。
POST /api/v1/studies/{ref}/telemetry: 稼働データの書き込み。telemetryスコープが必要です。{"rows": [...]}を最大5 000行まで送ります。各行はmachine_idまたはmachine（正確な名前）で機械を指定し、dayと、moves、run_minutes、idle_minutes、distance_km、faultsのいずれかを持ちます。すでに存在する機械と日の行は置き換えられます。応答は書き込んだ数を示し、スキップされた最初の50行と理由を一覧します。
GET /api/v1/machines: 機械ライブラリ。各プロファイルの数値と、カタログ機種の場合はその出所の仕様書。1件は/machines/{id}。
GET /api/v1/catalogue: 実在するメーカーと機種のカタログと出所の仕様書。?vendor=または?class=で絞り込めます。
GET /api/v1/audit: 監査ログ、新しい順。auditスコープが必要です。?group=、?from=、?to=、?q=で絞り込めます。

スタディの形

json

{
  "ref": "ST-1002", "name": "Cold store aisle audit", "status": "review",
  "plan": { "file": "cold-store.dxf", "scale": { "mm_per_unit": 1, "source": "dxf" },
            "extent_mm": { "width": 61000, "height": 45000 },
            "shapes": { "rack": 6, "aisle": 5, "dock": 1, "block": 3 } },
  "scenarios": [ {
    "name": "Base", "current": true,
    "fleet": [ { "machine": "VNA turret, 1.0 t", "class": "vna", "qty": 3, "shifts": 2 } ],
    "assumptions": { "moves_required": 2110, "hours_per_shift": 8, "days_per_year": 300,
                     "distance_m": 14, "distance_source": "plan", "handling_s": 55 },
    "throughput": { "verdict": "meets", "moves_per_day": 3024.6, "required_per_day": 2110,
                    "headroom_per_day": 914.6, "utilisation_pct": 69.8, "lines": [ … ] },
    "aisles": { "verdict": "fail", "aisle_min_mm": 2100, "narrowest_mm": 1800, "aisles": 5, "below": 5 },
    "checked_against": { "machine": "Pallet truck, pedestrian 1.6 t", "aisle_min_mm": 2100 }
  } ]
}

throughput.verdictはmeets、short、nofleet、nodistance、notargetのいずれか、aisles.verdictはpass、fail、noplan、noscale、noaisles、noneのいずれかです。distance_sourceは、シミュレーションページと同様に、走行距離が入力されたか図面から導かれたかを示します。

稼働データの送信

bash

curl -X POST https://auddomate.com/api/v1/studies/ST-1002/telemetry \
  -H "Authorization: Bearer aud_…" -H "Content-Type: application/json" \
  -d '{"rows": [
        {"machine": "VNA turret, 1.0 t", "day": "2026-09-01", "moves": 412, "run_minutes": 480, "idle_minutes": 60, "distance_km": 18.4, "faults": 1},
        {"machine_id": 327, "day": "2026-09-02", "moves": 390}
      ]}'

json

{ "ok": true, "data": { "written": 2, "skipped": 0, "errors": [] } }

エラー

401 unauthorised: キーがない、または認識できないキー。
401 revoked: キーは取り消されています。メッセージがいつかを示します。
403 plan: 組織は無料またはStudioプランです。
403 scope: キーにエンドポイントが必要とするスコープがありません。
404 not_found: 該当するスタディ、機械、またはエンドポイントがありません。
400 json / empty: 本文がJSONオブジェクトでないか、行がありません。
413 too_many: 1回のテレメトリリクエストで5 000行を超えています。
429 rate_limited: 1分間に300リクエストを超えました。Retry-After秒待ってください。

バージョニング

パスがバージョンを持ちます。項目は時間とともにv1に追加されますが、名前の変更や削除はされません。クライアントを壊すものはv2となり、v1は少なくとも1年間並行して動き続けます。変更は他のすべてと同様に変更履歴に記載されます。

APIはキーが属する組織だけを読み書きし、それ以外には触れません — どのキーでも他の組織のスタディに到達する方法はありません。キーはパスワードと同じように扱ってください：システムごとにひとつ、そのシステムを廃止したら取り消す。