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

スマートフォンのアプリなどで撮った写真（帳票・名刺・注文書など）を、PC を通さずに受け口へ入れる口です。 入ったあとは、PC から届いた書類と同じ流れ（Webhook の item.received → OCR → item.recognized）になります。

約束

エンドポイント: POST /api/v1/inboxes/{name}/items（multipart/form-data。file を 1〜10 個。1 つ 20 MiB・合計 100 MiB まで）。形と状態コードは API リファレンス の 5.8。

• 認証: API キー（scope upload。書類を入れるだけで読めない）。
• 形式: JPEG・PNG・PDF。HEIC は 415（heic）なので、アプリで JPEG にしてから送る（iPhone の既定は HEIC）。EXIF の向きはサーバーが画素に反映してから落とす（アプリで回さなくてよい。位置情報もサーバーが落とすが、アプリで付けないほうがよい）。
• 1 枚の写真 = 1 品目。名刺は 1 枚ずつ、帳票は 1 ページずつ品目になる（複数ページの帳票を 1 件にしたいときは、アプリで PDF にまとめて送る）。
• Idempotency-Key を必ず付ける（送る単位ごとに作った ULID・UUID。通信が切れて送り直すときは同じキー）。24 時間、同じ結果（200・Idempotent-Replayed: true）が返る。
• 応答 201 {item_id, inbox, ocr:{status}, items:[{item_id, kind, duplicate, ocr:{status}, …}]}。その後は、出来事（item.received → item.ocr.done／failed／skipped → item.recognized）で進める（同じ item_id は 1 回だけ処理する）。 画面で待ち合わせるときは GET /api/v1/items/{id} の ocr.status（と ocr.recognition）を数秒おきに読む。skipped・failed は、人の確認に回す。
• 品目は source = api・kind = photo（PDF は file）。
• 断られたとき: 403 not_accepted（受け口の設定が切）・423 paused（受け口の自動停止など）・429 limit（送り手ごとの件数。1 分 20 件・1 時間 200 件・1 日 1000 件）は、送り直さず、画面に理由を出す（「Cloud Paper の受け口の設定を確かめてください」など）。503 busy だけは少し待って同じキーで送り直す。

受け口の推奨設定（Cloud Paper のパネル → 受け口。所有者・管理者だけ。API では変えられない）:

設定	値
名前	例「現場の写真」（送れる PC は選ばなくてよい）
API から受け取る	入（既定は切）
読み取り（mode）	text+tables+recognize（文字と表と項目）
撮り方（capture）	photo（写真）
知らせ（deliver）	immediate（すぐ）