APIリファレンス

1. 認証

APIキーを Authorization ヘッダに付けてください。ヘッダを自由に足せないクライアント向けに X-API-Key でも受け付けます。

Authorization: Bearer ck_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

キーはアプリの 外部連携（API） タブから管理者が発行します。発行時に一度だけ表示され、あとから再表示はできません（当社側にもハッシュしか残していないためです）。漏えいが疑われる場合は同じ画面で失効させ、新しいキーを発行してください。

すべてのエンドポイントの基底URLは https://check.manda.bz です。

2. 基本の流れ

1件のチェックは、AIによるWeb調査を含むため 1〜2分 かかります。これをHTTPの応答時間で待つと連携先のタイムアウトに掛かりやすいため、起票と結果取得を分けています。

1. POST /api/v1/checks で起票する → 202 とジョブIDが返る
2. 結果を受け取る。いずれかの方法で：
   • Webhook（推奨）… 完了時にこちらから POST します
   • ポーリング … GET /api/v1/checks/{id} を10〜15秒間隔で
3. 必要なら GET /api/v1/checks/{id}/report でレポート本体（HTML／PDF）を取得する

3. チェックの起票と取得

チェックを起票する

curl -X POST https://check.manda.bz/api/v1/checks \
  -H "Authorization: Bearer $CHECK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: account-00123" \
  -d '{
    "companyName": "株式会社サンプル",
    "companyUrl": "https://example.co.jp",
    "people": [{ "name": "山田太郎", "role": "代表者" }]
  }'

HTTP/1.1 202 Accepted
Location: /api/v1/checks/chk_1a2b3c4d5e6f7a8b9c0d1e2f

{
  "id": "chk_1a2b3c4d5e6f7a8b9c0d1e2f",
  "status": "queued",
  "target": { "companyName": "株式会社サンプル", "companyUrl": "https://example.co.jp",
              "people": [{ "name": "山田太郎", "role": "代表者" }], "country": null },
  "createdAt": "2026-09-18 04:12:07"
}

結果を取得する

{
  "id": "chk_1a2b3c4d5e6f7a8b9c0d1e2f",
  "status": "succeeded",
  "score": "caution",
  "risk": "中",
  "summary": {
    "overallScore": "caution",
    "overallRisk": "中",
    "overallComment": "…",
    "scoreReason": "…"
  },
  "checks": {
    "antisocial":     { "riskLevel": "低", "findings": [], "comment": "", "sources": [] },
    "closeAssociate": { "riskLevel": "低", "findings": [], "comment": "", "sources": [] },
    "criminal":       { "riskLevel": "低", "findings": [], "comment": "", "sources": [] },
    "administrative": { "riskLevel": "中", "findings": ["…"], "comment": "…", "sources": ["https://…"] },
    "financial":      { "riskLevel": "低", "findings": [], "comment": "", "sources": [] },
    "legal":          { "riskLevel": "低", "findings": [], "comment": "", "sources": [] },
    "media":          { "riskLevel": "中", "findings": ["…"], "comment": "…", "sources": ["https://…"] },
    "news":           { "riskLevel": "低", "findings": [], "comment": "", "sources": [] }
  },
  "peopleChecks": [{ "name": "山田太郎", "role": "代表者", "riskLevel": "低", "findings": [] }],
  "sanctionsWatchlist": {
    "checked": true, "found": false, "totalCount": 0, "hits": []
  },
  "historyId": 4821,
  "reportUrl": "https://check.manda.bz/api/v1/checks/chk_1a2b…/report",
  "createdAt": "2026-09-18 04:12:07",
  "finishedAt": "2026-09-18 04:13:41"
}

レポート本体を取得する

既定はHTML。?format=pdf でPDFを返します。完了前に呼ぶと 409 not_ready です。

curl -H "Authorization: Bearer $CHECK_API_KEY" \
  "https://check.manda.bz/api/v1/checks/chk_1a2b…/report?format=pdf" -o report.pdf

一覧

起票したジョブを新しい順に返します（本文の結果は含みません）。

4. 制裁リストの即時照合

OFAC（米財務省）・EU統合リスト・財務省（外為法の資産凍結対象）への名称照合だけを行います。取り込み済みのリストへのローカル照合なので、AIも外部通信も使いません。応答は数十ms、残回数は消費しません。

取引先マスタの一括スクリーニングや、レコード作成時の即時チェックのように、頻度の高い用途に向いています。

curl -X POST https://check.manda.bz/api/v1/sanctions/screen \
  -H "Authorization: Bearer $CHECK_API_KEY" -H "Content-Type: application/json" \
  -d '{ "companyName": "株式会社サンプル", "englishName": "Sample Co., Ltd.",
        "people": [{ "name": "山田太郎", "role": "代表者" }] }'

{
  "checked": true, "found": false, "totalCount": 0, "exactCount": 0,
  "targets": ["株式会社サンプル", "Sample Co., Ltd.", "山田太郎"],
  "hits": [],
  "sources": [
    { "code": "ofac", "label": "OFAC（米財務省）", "count": 0, "publishedAt": "2026-09-16" },
    { "code": "eu",   "label": "EU 制裁リスト",    "count": 0, "publishedAt": "2026-08-05" },
    { "code": "mof",  "label": "財務省 資産凍結等", "count": 0, "publishedAt": "2026-09-01" }
  ],
  "lastSync": "2026-09-18 01:02:03", "entryCount": 28964, "elapsedMs": 118
}

漢字の商号が当たるのは和文表記を持つ財務省リストだけです。OFAC・EUはラテン文字表記のため、englishName を渡すと精度が上がります。照合できないとき（同期未完了など）は 503 watchlist_unavailable を返します。黙って「該当なし」にはしません。

5. 残回数の確認

{
  "organization": { "id": 12, "name": "株式会社サンプル" },
  "plan": "business", "planQuota": 100, "planRenewsAt": "2026-10-01 00:00:00",
  "balance": 63,
  "apiKey": { "id": 3, "name": "基幹システム連携" },
  "queue": { "running": 1, "queued": 0 }
}

country に指定できる国コードの一覧を返します。

6. Webhook

アプリの 外部連携（API） タブで送信先URLを登録すると、完了時にこちらから POST します。送信先は https:// のみで、社内・プライベートアドレスは登録できません。

本文は { "event": "...", "createdAt": "...", "data": { …GET /api/v1/checks/{id} と同じ形… } } です。

署名の検証（必須）

次のヘッダが付きます。

署名は HMAC-SHA256(署名鍵, "<X-Check-Timestamp>.<リクエストボディ>") です。署名鍵は送信先ごとに発行され、同じ画面で確認できます。

// Node.js での検証例
const crypto = require('crypto');

function verify(req, rawBody, secret) {
  const ts  = req.headers['x-check-timestamp'];
  const sig = req.headers['x-check-signature'];
  // 古い本文の送り直しを弾く（5分より古いものは受け取らない）
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = 'v1=' + crypto.createHmac('sha256', secret)
    .update(`${ts}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

再送

2xx 以外、または10秒以内に応答が無い場合は失敗として、1分・5分・15分・1時間・3時間・6時間の間隔で最大7回まで再送します。受信側は X-Check-Delivery で重複を弾ける作りにしてください。配信状況はアプリの配信ログで確認できます。

7. エラー

エラーは常に次の形です。

{ "error": { "code": "no_balance", "message": "残回数がありません。…" } }

8. 制限事項

• レート制限：1キーあたり60リクエスト／分。X-RateLimit-Limit / X-RateLimit-Remaining を返します。
• 同時実行：組織をまたいだ共有のワーカーで実行します。混み合っているときは queued の時間が延びます（GET /api/v1/account の queue で確認できます）。
• 課金：succeeded になったチェック1件につき残回数を1回消費します。failed と need_refine は消費しません。/v1/sanctions/screen は消費しません。
• 保存期間：レポートは組織の履歴保存期間の設定に従います。期間を過ぎたものは 404 になります。
• APIキーの権限：キーは組織単位です。エンドポイントごとの権限分けや、他組織のデータへのアクセスはできません。