はじめに

API キーを作って、印刷を 1 枚送り、届いた書類を受け取るまで。curl の例つき。

このページの見出し

1. 用意するもの
2. つながるか確かめる
3. 印刷する
4. FAX を送る
5. 届いた書類を受け取る
6. 読み取った文字と項目を使う（OCR プラン）
7. スマートフォンの写真を送る
エラーの形

Cloud Paper の API で、自社の Web アプリから印刷・FAX を送り、スキャン・FAX で届いた書類を受け取るまでの流れです。 API の全体は API リファレンス、通知は Webhook を見てください。

1. 用意するもの

もの	どこで
テナント（契約）	`https://<テナント>.cloudpaper.appz.jp`。契約すると届きます
PC のクライアント	プリンター・FAX・スキャナーがつながった PC に入れて、管理画面でつなぎます（PC のクライアント）
印刷先	管理画面の「印刷先」で、どの PC のどのプリンターに、どの設定（プロファイル）で出すかに名前を付けます
API キー	管理画面の「API キー」で作ります。範囲（scope）を選べます（API キー）

以下の例では、テナントを acme、API キーを環境変数 KEY に入れています。

export API=https://acme.cloudpaper.appz.jp/api/v1
export KEY=cpk_...   # 管理画面で作ったキー（一度だけ表示されます）

2. つながるか確かめる

curl -s "$API/tenant" -H "Authorization: Bearer $KEY"

{"ref":"acme","name":"株式会社アクメ","paused":false,"pause_reason":"","access":"full"}

3. 印刷する

印刷先の一覧を見て、PDF を送ります。request_id を付けると、通信が切れて送り直しても二重に印刷されません。

curl -s "$API/destinations" -H "Authorization: Bearer $KEY"

curl -s "$API/jobs" -H "Authorization: Bearer $KEY" \
  -F file=@invoice.pdf \
  -F destination=倉庫の伝票 \
  -F user=yamada \
  -F request_id=order-10023 \
  -F label="受注 10023 の納品書"

{"id":"job_01JA2B3C4D5E6F7G8H9JKMNPQR","pages":1,"state":"queued"}

結果は GET /jobs/{id} か、Webhook の job.finished で分かります。

curl -s "$API/jobs/job_01JA2B3C4D5E6F7G8H9JKMNPQR" -H "Authorization: Bearer $KEY"

`state`	意味
`queued`	PC が取りに来るのを待っている
`delivered`	PC に渡した
`done`	終わった
`refused`	PC が断った（`detail` に理由。PC の上限・許可していない番号など）
`failed`	失敗した

4. FAX を送る

FAX の印刷先に、fax_to を付けて送ります。送ってよい番号は、FAX をつないだ PC の側で決めてあります。

curl -s "$API/jobs" -H "Authorization: Bearer $KEY" \
  -F file=@purchase-order.pdf \
  -F destination=事務所の FAX \
  -F user=yamada \
  -F fax_to=0781234567

5. 届いた書類を受け取る

スキャン・FAX の受信フォルダから届いた書類は、受け口に入ります。受け取り方は 2 つです。

Webhook（おすすめ）: 管理画面の「送信先」に自社の URL を登録すると、item.received が届きます。
API で取りに行く: GET /inboxes/{name}/items で未確認の書類を読みます。

Webhook を受けたら、署名を確かめてから download_url で書類を取り、ack_url で確認します。

// Node.js（Express）の例。秘密は送信先を作ったときに一度だけ表示される whs_...
import crypto from 'node:crypto';

app.post('/cloudpaper', express.raw({ type: 'application/json' }), async (req, res) => {
  const ts = req.get('X-CloudPaper-Timestamp');
  const sig = req.get('X-CloudPaper-Signature');            // sha256=<hex>
  const mac = crypto.createHmac('sha256', process.env.WEBHOOK_SECRET).update(`${ts}.${req.body}`).digest('hex');
  const ok = sig && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(`sha256=${mac}`));
  if (!ok || Math.abs(Date.now / 1000 - Number(ts)) > 300) return res.sendStatus(401);

  const ev = JSON.parse(req.body);
  res.sendStatus(200);                                      // 先に 200 を返し、取り込みは後で
  if (ev.event === 'item.received') {
    const pdf = await fetch(ev.download_url).then((r) => r.arrayBuffer);  // 15 分有効
    // sha256 を照合して保存 → 確認（1 時間有効）
    await fetch(ev.ack_url, { method: 'POST' });
  }
});

API で取りに行く場合:

curl -s "$API/inboxes/受付/items" -H "Authorization: Bearer $KEY"
curl -s "$API/items/itm_01JA.../file" -H "Authorization: Bearer $KEY" -o received.pdf
curl -s "$API/items/itm_01JA.../ack" -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -d '{"by":"order-system","result":"ok"}'

届いた書類は信用しないでください。開く前に検査します。

6. 読み取った文字と項目を使う（OCR プラン）

受け口の OCR を管理画面で入れると、届いた書類の文字・表・項目が API で読めます。

curl -s "$API/items/itm_01JA.../ocr" -H "Authorization: Bearer $KEY"      # 文字・表・位置
curl -s "$API/items/itm_01JA.../fields" -H "Authorization: Bearer $KEY"   # 書類の種類と項目（認識）

{"item_id":"itm_…","status":"recognized","document_type":"business_card","needs_review":true,
 "business_card":{"company":{"value":"株式会社…","confidence":0.97,"needs_review":false},
                  "tel":{"value":"078-…","confidence":0.5,"needs_review":true}}}

読み取った値は、人が確かめる前提で使ってください（needs_review の項目を目立たせるなど）。くわしくは OCR と書類の認識。

7. スマートフォンの写真を送る

受け口の「API から受け取る」を管理画面で入れると、PC を通さずに写真を入れられます。アプリには、書類を入れるだけの upload の鍵を持たせます。

curl -s "$API/inboxes/現場の写真/items" -H "Authorization: Bearer $UPLOAD_KEY" \
  -H "Idempotency-Key: 01JA2B3C4D5E6F7G8H9JKMNPQR" \
  -F file=@IMG_0001.jpg

くわしくはスマートフォンの写真を送る。

エラーの形

エラーは {"error":"<文>"}。印刷・FAX の依頼だけは {"error","code","retry_after"} です。

状態	よくある原因
401	キーが無い・違う・期限切れ（理由は区別しません）
403	キーの範囲（scope）が足りない
409	同じ文書を 5 分以内に同じ印刷先へ（`allow_repeat=1` で通せます）
422	入力の不備・PDF が検査を通らない（受け付ける PDF）
423	テナント・印刷先・PC が止まっている
429	上限を超えた（`retry_after` 秒待つ。上限）

次 →概要と用語

ご不明な点はお問い合わせください。