API リファレンス

https://<テナント>.cloudpaper.appz.jp/api/v1

• テナントはホスト名で決まる。 他のテナントの API キーは、そのホストでは 401。
• パネルでできることの多くは、この API でもできる（同じ処理を通る）。
• 送信先（Webhook）の追加・変更・API キーの発行・利用者の管理・受け口の OCR の設定・受け口の「API から受け取る」は、API に無い。 パネルだけ。
• 外に見える ID は推測できない形。新しいものは「接頭辞 + ULID」（itm_・job_・dev_・cal_・con_・dlv_・ocr_・evt_ + 26 文字。先頭 48 ビットが時刻、残り 80 ビットが毎回の乱数）。前からある 16 進 32 文字の ID もそのまま使える。ID は文字列として扱い、形に頼らないこと。

5.1 認証

Authorization: Bearer cpk_…

• API キーはパネルで作る（API キー・管理画面）。サーバーはハッシュだけを持つ。
• キーが無い・違う・取り消し済み・期限切れ・作り直しの猶予が過ぎたものは 401 {"error":"unauthorized"}（理由は区別しない）。失敗は IP ごとに 1 分 20 回まで（超えると 429）。
• API キーには期限がある（既定 1 年・最長 2 年）。最後に使った時刻とアドレスは、パネルの一覧に出る（記録は 1 分に 1 回まで）。キーの発行・作り直し・取り消しはパネルだけ（API には無い）。
• 範囲（scope）が足りないと 403。

scope	使える範囲
full	すべて。パネルでは所有者だけが作れる
print	印刷先・プリンターの一覧、ジョブの依頼と参照
inbox	受け口の一覧、品目の一覧・取得・確認・OCR の結果、履歴の一覧・取得・削除
calls	着信の一覧・取得
upload	受け口に書類を入れる（POST /inboxes/{name}/items）だけ。届いた書類は読めない。スマートフォンのアプリなどに持たせる

下の表の「scope」が print・inbox・calls・upload の操作は、full のキーでもできる。「—」はどのキーでもよい。pairing は PC の承認で、full のキーでできる。

• 操作した人は X-Actor 見出しか、本文の by・approved_by・changed_by に入れる。操作の記録に残る。利用者の権限の確認は、呼び出し側の責任。 量の上限で守る。
• 本文の JSON は 1 MiB まで。
• エラーは {"error": "<文>"}。ジョブの依頼だけは {"error", "code", "retry_after"}。テナントの状態（503・403・423）は 契約 の形。

5.2 一覧

メソッド	パス	scope
GET	/tenant	—
POST	/pause	full
POST	/resume	full
GET	/pairings/{code}	pairing
POST	/pairings/{code}/approve	pairing
POST	/pairings/{code}/deny	pairing
GET	/devices	full
POST	/devices	full
POST	/devices/{id}/{revoke｜pause｜resume｜confirm}	full
GET	/printers	print
GET	/destinations	print
PUT	/destinations/{name}	full
DELETE	/destinations/{name}	full
POST	/destinations/{name}/{pause｜resume}	full
GET	/budgets	full
PUT	/budgets	full
POST	/jobs	print
GET	/jobs	print
GET	/jobs/{id}	print
GET	/inboxes	inbox
PUT	/inboxes/{name}	full
DELETE	/inboxes/{name}	full
POST	/inboxes/{name}/{pause｜resume}	full
GET	/inboxes/{name}/items	inbox
POST	/inboxes/{name}/items	upload
GET	/items/{id}	inbox
GET	/items/{id}/ocr	inbox
GET	/items/{id}/ocr/tables.csv	inbox
GET	/items/{id}/fields	inbox
GET	/items/{id}/file	inbox
POST	/items/{id}/ack	inbox
GET	/history	inbox
GET	/history/{id}	inbox
GET	/history/{id}/link	inbox
DELETE	/history/{id}	inbox
GET	/calls	calls
GET	/calls/{id}	calls
GET	/events	full

5.3 テナント

GET /tenant

{"ref":"acme","name":"…","paused":false,"pause_reason":"","access":"full"}

POST /pause・POST /resume

テナント全体のキルスイッチ。本文 {"by":"…","reason":"…"}（任意）。→ {"ok":true}。 停止中は、新しいジョブが 423 tenant_paused、PC への配達が止まり、PC の取り込みが 423 になる。

5.4 PC（端末）

GET /pairings/{code}

PC に出たコード（XXXX-XXXX。ハイフンと大小は無視）の申請を見る。テナントごとに 1 分 30 回まで。

→ {"name","os","ip","status","created_at","expires_at"}（status: pending｜approved｜denied｜expired）。無ければ 404。

POST /pairings/{code}/approve・/deny

本文 {"approved_by":"…"}（必須・128 文字まで）。→ {"device_id":"…","ok":true}（拒否は device_id が空）。

状態	意味
422	approved_by が無い
409	コードが無い・期限切れ・使用済み、または契約の PC の数の上限
503	混み合っている

GET /devices

→ {"devices":[{"id","name","os","status","paused","approved_by","last_seen","created_at"}]}。 status: active｜stale（7 日接続が無く、再確認が必要）｜revoked。

POST /devices（貼り付けによる接続）

ブラウザで承認できない環境向け。PC の設定画面に出た「登録依頼」を貼る。

本文 {"request":"<登録依頼>","approved_by":"…"}。 登録依頼は base64url(JSON {pub, name, os, exp})。exp は 1 時間以内。

→ {"device_id":"…","bundle":"<接続情報>"}。接続情報は base64url(JSON {hub, tenant, device_id, signing_keys})。PC の設定画面に貼り戻す（PC との通信）。 不正は 422、PC の数の上限は 409。

POST /devices/{id}/{action}

本文 {"by":"…"}（任意）。

action	動き
revoke	失効。待っているジョブ（queued・delivered）は cancelled。PC の要求は以後 401
pause・resume	その PC への配達と取り込みを止める・再開する
confirm	stale の PC を active に戻す

対象が無ければ 404。

5.5 プリンターと印刷先

GET /printers

PC が知らせたプリンター（active の PC のものだけ）。

→ {"printers":[{"device_id","ref","name","kind","profiles":["…"]}]}。kind: document｜label｜fax。

GET /destinations

→ {"destinations":[{"name","kind","device_id","printer_ref","profile","allow_auto","max_pages_per_job","paused","pause_reason"}]}

PUT /destinations/{name}

本文 {"device_id","printer_ref","profile","allow_auto":false,"max_pages_per_job":50}。

• 名前は制御文字なしの 1〜64 文字。
• max_pages_per_job（部数 × ページ）は 0〜500。0 は 50。
• その PC にそのプリンターが無ければ 422。

DELETE /destinations/{name} → {"ok":true}

POST /destinations/{name}/{pause｜resume}

• pause は「手動で停止」。
• API の resume は、手動の停止だけを解く。上限による自動停止は、パネルでだけ解ける。
• 対象が無い・解けないときは 404。

5.6 予算

GET /budgets

{"budgets":[{"scope","key","per_minute","per_hour","per_day"}],
 "defaults":{"tenant":{"Min":60,"Hour":400,"Day":2000}, …},
 "hard_caps":{"per_minute":300,"per_hour":3000,"per_day":20000}}

PUT /budgets

本文 {"scope":"tenant|destination|user|auto","key":"…","per_minute","per_hour","per_day","changed_by":"…"}。

• tenant の key は空。destination・auto は印刷先の名前、user は利用者。
• 契約の天井（hard_caps）を超える値は 422。天井は API では変えられない。
• 上げたときは budget.raised、下げたときは budget.lowered を記録する。→ {"ok":true,"kind":"…"}

既定値と天井は 上限。

5.7 ジョブ（印刷・FAX）

POST /jobs（multipart/form-data）

項目	必須	内容
file	○	PDF（50 MiB まで）
destination	○	印刷先の名前
user	○	依頼した人（128 文字まで）
origin		manual（既定）｜batch｜auto
copies		1〜100（既定 1）。FAX は常に 1
fax_to	FAX は必須	FAX 番号。FAX でない印刷先では不可
request_id		64 文字まで。同じ値の再送は、最初のジョブを返す（200）
batch_id		64 文字まで
label		120 文字まで。履歴と job.finished に出す
allow_repeat		1 で、同じ文書の 5 分以内の再印刷を通す（人が確認した場合）

成功: 201 {"id","pages","state":"queued"}（request_id の再送は 200）。

確かめる順: テナントの停止 → 入力 → 印刷先と PC → FAX 番号 → PDF の検査（受け付ける PDF）→ 自動印刷の許可 → 1 回の上限 → request_id → FAX の回数 → 重複 → 待ち行列 → 予算。

状態	code	意味
422	user・origin・copies・fax_to・pdf・too_many_pages	入力の不備。fax_to は国内の番号だけ（国際・有料番号は不可）
404	destination	印刷先が無い
423	tenant_paused	テナントが停止中
423	device_stale・device_revoked	印刷先の PC が使えない
423	paused	印刷先か PC が停止中
403	auto_not_allowed	自動印刷を許可していない印刷先に origin=auto
409	duplicate	同じ文書を 5 分以内に同じ印刷先へ（allow_repeat=1 で通す）
429	fax_number_limit	同じ番号へ 1 日 5 回を超えた（retry_after: 86400）
429	fax_hour_limit	印刷先の FAX が 1 時間 30 回を超えた。印刷先を自動停止（retry_after: 3600）
429	queue_full	その PC の待ち行列が 50 件
429	budget_tenant・budget_destination・budget_user・budget_auto	予算を超えた。budget_destination は印刷先を自動停止。retry_after は窓の秒数
413	—	本文が大きすぎる・multipart が壊れている
503	busy	混み合っている
500	storage・db	保存できない
409	conflict	登録できない

• ページ数は、サーバーが自分で数える（PDF リーダーが数えた数）。予算は「ページ × 部数」で計る。
• 予算の 80% を超えたときは budget.warning を記録する。

GET /jobs・GET /jobs/{id}

GET /jobs は新しい順に 200 件。

{"id","destination","user","origin","batch_id","pages","copies","state","detail","label","request_id","fax_to":"******5678","created_at","updated_at"}

state	意味
queued	PC が取りに来るのを待っている
delivered	PC に渡した
accepted・printing	PC が受け付けた・印刷中（今のクライアントは送らない）
done	終わった（FAX は FAX サービスに渡した）
refused	PC が断った（detail に理由）
failed	失敗。渡してから 5 分報告が無いときも
expired	2 分以内に PC が取りに来なかった
cancelled	PC が失効した

fax_to は末尾 4 桁だけ。

5.8 受け口と品目

PC の取り込みで届いた書類の行き先。どの PC が送れるかは、ここで許可する。 PC のどのフォルダやスキャナーを読むかは、PC の利用者だけが決める。 「API から受け取る」（accept_api）を入れた受け口には、API（POST /inboxes/{name}/items）でも書類を入れられる（スマートフォンの写真など。PC を通さない）。

GET /inboxes

→ {"inboxes":[{"name","paused","pause_reason","accept_api","device_ids":["…"],"ocr":{"mode","lang","deliver","capture"}}]}

ocr は受け口の OCR の設定（OCR と書類の認識 の 20.2。変えるのはパネルだけ）。accept_api は「API から受け取る」（既定 false。変えるのはパネルだけ。PUT の本文に入れても無視する）。

PUT /inboxes/{name}

本文 {"device_ids":["…"]}（100 台まで。このテナントの PC だけ）。許可する PC を置き換える。→ {"ok":true}

DELETE /inboxes/{name} → {"ok":true}

POST /inboxes/{name}/{pause｜resume}

印刷先と同じ。API の resume は手動の停止だけを解く。

GET /inboxes/{name}/items[?state=all]

既定は未確認（received）だけ。古い順に 200 件。

{"items":[{"id","device_id","source","filename","mime","kind","caller","size","sha256","state","uploaded_by","created_at",
  "ocr":{"ocr_id","status","code","message","pages_total","pages_done","tables","url"}}]}

• kind: scan｜fax｜file｜photo（API で受け取った画像。API で受け取った PDF は file）。
• source: PC の取り込み元の名前。API で受け取った書類は api（device_id は空）。
• uploaded_by: API で入れた者（key:<鍵の印 8 文字>）。PC から届いた書類は空。
• mime: application/pdf・image/jpeg・image/png・image/tiff。
• caller: FAX の送信元の番号（PC の利用者が送ると決め、分かった場合だけ）。
• state: received（未確認）｜acked（確認済み。1 時間後に消す）｜archived（履歴）｜deleted。
• ocr: OCR の要約（OCR と書類の認識）。status は none（OCR をしない受け口）｜queued｜running｜done｜partial｜unreadable｜failed｜skipped。 code・message は終わりの理由があるときだけ（20.4 の表）。

POST /inboxes/{name}/items（multipart/form-data）

API で受け口に書類を入れる。スマートフォンで撮った写真（帳票・名刺・注文書など）を、PC を通さずに OCR・認識・送信先へ流すための口。 受け口の「API から受け取る」（パネル）が入っていなければ 403。 scope は upload（full でも可）。

項目・見出し	必須	内容
file	○	書類。1〜10 個（同じ名前で繰り返す）。1 つ 20 MiB まで。本文の合計は 100 MiB まで
Idempotency-Key（見出し）		1〜255 文字の表示できる ASCII。同じ送り手が 24 時間以内に同じキーで送り直すと、前の結果を返す（二重に入らない）
X-Actor（見出し）		操作した人。操作の記録に残る

受け付ける形式（名前や Content-Type ではなく中身で見分ける）:

形式	扱い	kind
JPEG・PNG	読んで書き直す。EXIF の向きを画素に反映してから、EXIF・XMP・ICC・PNG の文字のチャンクなど画素のほかをすべて落とす（位置情報は残らない）。6000 万画素まで	photo
PDF	印刷の入口と同じ厳格な検査（受け付ける PDF。構文の検査 + PDF リーダーの検査 + ページ数の突き合わせ）を通ったものだけ。中身は書き換えない	file
HEIC・HEIF	変換できないので 415（heic）。送る側で JPEG にする	—
そのほか（TIFF など）	415（unsupported）	—

成功: 201

{"item_id":"itm_01JA…","inbox":"現場","ocr":{"status":"queued"},
 "items":[{"item_id":"itm_01JA…","filename":"IMG_0001.jpg","mime":"image/jpeg","kind":"photo","size":812345,"duplicate":false,"ocr":{"status":"queued"}}]}

• 1 ファイル = 1 品目。item_id・ocr は 1 つ目のファイルのもの（1 枚だけ送るときに使いやすいように）。全部は items。
• ocr.status は受け取った時点の状態（OCR と書類の認識 の 20.3。OCR をしない受け口は none、契約に OCR が無ければ skipped）。その後は GET /items/{id} か出来事で追う。
• 同じ受け口に 24 時間以内に届いた同じ内容は、保存し直さずに前の品目を返す（duplicate: true）。全部が重複なら 200。
• Idempotency-Key の再送は 200 と見出し Idempotent-Replayed: true。本文は最初と同じ品目（ocr.status はいまの状態）。
• すべて受け取るか、1 つも受け取らないか。1 つでも断るものがあれば、何も保存しない。
• 受け取ったあとは、PC から届いた書類と同じ（item.received → 受け口の OCR〈mode・capture〉→ 認識 → 出来事）。
• 件数・量の上限は PC と同じ数え方で、送り手ごとに数える（送り手は API キーごと）。超えると 429 で、受け口を自動停止する（上限 の 12.6）。

状態	code	意味
403	not_accepted	受け口が無い・「API から受け取る」が切（あるかどうかは区別しない）
403	—	scope が足りない（inbox・print・calls の鍵）
423	paused	受け口かテナントが停止中
413	too_large・too_many_files	1 ファイル 20 MiB・本文 100 MiB・10 ファイルを超えた
415	heic・unsupported	受け付けない形式
422	file・image・pdf・idempotency_key	ファイルが無い・空／画像として読めない（偽物・壊れている・6000 万画素を超える）／PDF が検査を通らない／キーの形が違う
409	idempotency_key_reused	同じキーが、別の内容（受け口・ファイル）の依頼に使われている
429	limit・limit_bytes	送り手ごとの件数（1 分 20・1 時間 200・1 日 1000）・1 日の量（2 GiB）を超えた。受け口を自動停止
507	storage_full	保管の容量がいっぱい。受け口を自動停止
503	busy	混み合っている

GET /items/{id}

品目 1 件（received・acked・archived。消したものは 404）。一覧の 1 行に inbox・ack_by・ack_result・updated_at を足した形。

GET /items/{id}/ocr

OCR の状態と結果（文字・Markdown・表・ページごとの状態・位置）。形は OCR と書類の認識 の 20.6。品目が無ければ 404、OCR をしない品目は {"status":"none"}。

GET /items/{id}/fields

認識（書類の種類と項目）の結果。text+tables+recognize の受け口の書類だけ。無ければ 404。形は OCR と書類の認識 の 20.9。

GET /items/{id}/ocr/tables.csv

表の CSV（UTF-8・BOM つき・attachment）。結果・表が無ければ 404。

GET /items/{id}/file

未確認の品目の本体。Content-Disposition: attachment、X-Content-SHA256。無ければ 404。

POST /items/{id}/ack

本文 {"by":"…","result":"ok|rejected"}（両方必須）。→ {"ok":true}。確認の 1 時間後に消す。未確認でも 7 日で消す。 契約に履歴（history_days）があれば、消さずに履歴に移す（5.9）。未確認のまま 7 日たったものも履歴に移す。

届いた書類は信用しないこと。開く前に検査する。サーバー自身は中身を解釈しない（OCR の結果は OCR と書類の認識。これも書類から来た文字として扱う）。

5.9 履歴

契約に履歴（history_days が 1 以上。契約）があるとき、受け取りの確認が済んだ書類を残す。読むだけ。 履歴から送信先へ届け直す・印刷する道は無い。 日数を過ぎたもの、件数・容量（未確認の書類と履歴の合計）を超えた分は、受け取った時刻の古い順に自動で消える。未確認の書類は、この順番では消えない。

GET /history?inbox=&kind=&since=&until=&limit=&cursor=

新しい順。limit は 1〜200（既定 50）。since・until は受け取った時刻（unix 秒。since 以上・until 未満）。kind は scan｜fax｜file｜photo。 続きがあれば next_cursor を次の cursor に渡す（無ければ ""）。

{"items":[{"id","inbox","device_id","source","filename","mime","kind","caller","size","sha256","uploaded_by","ack_by","ack_result","created_at","archived_at","ocr":{…}}],
 "next_cursor":"…",
 "usage":{"used_bytes","history_bytes","history_items","capacity_bytes","history_days","history_max_items","expiring_24h","near_capacity","near_max_items", …}}

• created_at は受け取った時刻、archived_at は履歴に移した時刻。
• ocr は品目の一覧と同じ OCR の要約。履歴は OCR の結果も品目といっしょに残し、消すときもいっしょに消す。
• used_bytes は未確認の書類と履歴の合計、capacity_bytes は契約の容量。
• expiring_24h は 24 時間以内に日数の期限を過ぎる件数。near_capacity・near_max_items は 90% を超えたとき true。
• 品目のページ数は返さない（サーバーは書類の中身を解釈しない）。OCR をした品目は、ocr.pages_total が OCR の数えたページ数。

GET /history/{id}

1 件（一覧の 1 行と同じ形）。履歴に無ければ 404（未確認の書類も 404）。

GET /history/{id}/link

→ {"url":"https://…/hdl/{id}?a=…&exp=…&sig=…","expires_at":…}。5 分だけ有効な取得のリンク。認証なしの GET で、書類を attachment で返す（X-Content-SHA256・nosniff）。

• 署名は、このサーバーの鍵から作った履歴専用の鍵（API キー）。送信先のリンク（/dl/…）とは別。確認（ack）はできない。
• リンクには鍵の印（key:…）だけを入れる（X-Actor の名前は入れない）。
• リンクを出したとき history.link（X-Actor・鍵の印）、取りに来たとき history.downloaded を記録する。中身は記録しない。
• 署名・期限・状態のどれが違っても 404。アドレスごとに 1 分 120 回まで。

DELETE /history/{id}

1 件消す。→ {"ok":true}。履歴に無ければ 404。history.deleted を記録する。読込専用のテナントでは 423。

5.10 着信

PC のモデムが受け取った電話の番号。PC の利用者が「送る」にした場合だけ届く。番号は個人情報。 30 日で消す。

GET /calls?since=<unix 秒>&limit=<1〜200>

limit の既定は 100。新しい順。読み出しは calls.read として記録する（件数とキーの印）。

{"calls":[{"id","device_id","line","number","name","reason","at"}]}

reason: ""｜withheld（非通知。number は空）｜unavailable（取れなかった）。

GET /calls/{id}

1 件。無ければ 404。リアルタイムには送信先の call.incoming を使う（Webhook）。

5.11 操作の記録

GET /events

新しい順に 200 件。→ {"events":[{"id","at","kind","actor","detail":{…}}]}。id は evt_…（推測できない ID。表の連番は出さない）。 承認・失効・印刷・拒否・予算の変更・自動停止・送信先の変更・ログインなど。

5.12 受け付ける PDF（要約）

印刷・FAX の PDF は、2 つの独立した検査（構文の検査と PDF リーダーの検査）を両方通り、2 つのページ数が同じものだけを受け付ける。 スクリプト・アクション・フォーム・添付・3D・動画・音声・リンク以外の注釈・暗号化・JBIG2・JPEG 2000・壊れた構造などが 1 つでもあれば 422 pdf。