すいそう台帳 連携API

すいそう台帳の連携APIを使うと、管理会社や検査機関のシステムから、建物の清掃の期限・作業予定・報告書を受け取れます。使うには、つなぎたい清掃会社に鍵を発行してもらってください。

できること

建物の期限と状態、作業予定、報告書の番号と判定を受け取れます。

建物の住所と顧客の連絡先は、鍵に pii:read があり、清掃会社が設定でオンにした場合だけ含まれます。

鍵のもらい方

つなぎたい清掃会社に連絡し、「設定 → 連携」で鍵を発行してもらってください。鍵は発行したときに1回だけ表示されます。

鍵は Authorization ヘッダーに Bearer で付けます。1本の鍵で1分に60回まで呼べます。

curl https://suiso-daicho.com/api/partner/v1/ping \
  -H "Authorization: Bearer su_live_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

使えるエンドポイント（OpenAPI の定義から表示）

お知らせ（Webhook）

送る出来事：job.scheduled（日程の確定）、job.rescheduled（日程の変更）、report.issued（報告書の確定）、report.corrected（報告書の訂正）、site.due_soon（期限が近い）。中身はIDと日付と判定だけです。

X-SBGG-Signature ヘッダーの t と v1 で署名を確かめてください。v1 は、署名用の秘密で「t.本文」を HMAC-SHA256 にした16進数です。300秒以上ずれていたら捨ててください。

{"id":"evt_job_scheduled_…","type":"job.scheduled","created_at":"2026-10-13T09:00:00+09:00","org_id":"…",
 "data":{"job_id":"…","site_id":"…","scheduled_on":"2026-11-12"}}

// Node.js：署名の確かめ方
import crypto from 'node:crypto';
function verify(secret, rawBody, header) {
  const p = Object.fromEntries(header.split(',').map((kv) => kv.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(p.t)) >= 300) return false;
  const v1 = crypto.createHmac('sha256', secret).update(p.t + '.' + rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(p.v1));
}

エラー

401 鍵が無い・違う・止められた。403 スコープが足りない。404 見つからない（ほかの会社のIDも404）。429 回数の上限（Retry-After を見てください）。

OpenAPI 3.1 の定義（openapi.json）