PII-FI API v2

概要 — PII-FI API v2 とは#

PII-FI API v2 は、日本語テキストに含まれる個人情報（PII）と機微情報を検出し、仮名化・マスキングした文章を返す HTTP API です。氏名・電話番号・住所・メールアドレスのような識別子から、マイナンバーなどの公的番号、API キーなどの認証情報まで、84 種類の型を対象にします。

日本語向けに設計した検出エンジンを使い、敬称・役職つきの氏名（「山田部長」「田中さま」）、丁目・番地の表記ゆれがある住所、全角・半角が混在する電話番号のような、汎用の多言語ツールが取りこぼしやすい日本語固有の書き方をそのまま扱います。

他社の PII 検出 API（Microsoft Presidio、Azure AI Language、Google Sensitive Data Protection、Amazon Comprehend）との違いは日本語 PII 検出 API の比較にまとめています。

クイックスタート — curl 1 本で試す#

API キーを取得してから最初の応答を受け取るまで、手順は 3 つです。細かい確認（scope の設計、/capabilities の確認、Node.js からの呼び出し）は詳しい Quickstart に続きます。

1. 1
   API キーを発行する

   app.pii-fi.com の API キー画面で、deidentify scope を付けたキーを発行します。発行値は一度だけ表示されるので、環境変数 PIIFI_API_KEY に保存します。

2. 2
   curl を 1 本送る

   ダミーの文章を POST /deidentify へ送ります。実データで試す前に、必ずダミーデータで接続を確認してください。

3. 3
   応答を確認する

   メールアドレスがラベルに置き換わった text と、値を含まない usage が返れば成功です。

export PIIFI_API_KEY='発行直後に受け取った値'

curl --request POST 'https://api.pii-fi.com/v2/deidentify' \
  --header "Authorization: Bearer $PIIFI_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Idempotency-Key: demo-order-0001' \
  --data '{"text":"担当者Aの連絡先はsample@example.testです。"}'

{
  "request_id": "req_example_quickstart_02",
  "text": "担当者Aの連絡先はメールアドレスAです。",
  "usage": {
    "processed_characters": 31,
    "consumed_units": 1
  }
}

同期処理 1 要求の上限は 1,000,000 Unicode コードポイントです。検出だけ行いたい場合は POST /detect、複数件をまとめて処理したい場合は Batch を使います。

検出エンティティ一覧 — 84 種類の型#

検出・仮名化の対象は 84 種類の型（識別子 40 型・属性 35 型・認証情報 9 型）に体系化されています。カテゴリごとの内訳は次のとおりです。各型の詳しい検出パターンはトップページの型カタログで確認できます。

何ができるのか#

どの処理を選ぶか#

「何を返してほしいか」と「処理完了を同じ接続で待てるか」で選びます。

最初の非識別化を実行する#

この手順では、APIキーが現在使えることを確認してから、ダミーの文章をdeidentifyします。実データで試す前に、必ずダミーデータで接続とエラー処理を確認してください。

まずはプロファイルを指定しない最小の要求を示します。画面で編集した設定を使いたい場合は、プロファイルの選択手順に従ってprofiles:readの権限とprofile_idを追加してください。

1. 1
   APIキーを必要最小限のscopeで発行する

   API画面でcapabilities:readとdeidentifyを付けます。元に戻す必要がある場合だけmapping:readとrestoreも付けます。

2. 2
   キーをサーバー側の秘密として設定する

   発行値は一度だけ表示されます。ソースコード、Git、ブラウザ向けJavaScript、モバイルアプリへ埋め込まず、secret managerまたは実行環境の秘密変数へ保存します。

3. 3
   /capabilitiesで現在の利用条件を確認する

   plan名をコードへ固定せず、返されたcapabilitiesとlimitsを実行時の判断に使います。

4. 4
   一意なIdempotency-Keyで処理する

   業務処理1件につき1つ生成し、同じ業務処理の再送でだけ同じ値を使います。異なる本文へ使い回さないでください。

1. キーを環境変数へ設定

export PIIFI_API_KEY='発行直後に受け取った値'

共有端末のshell履歴へ残る方法は避け、実際の配備では利用中のsecret managerを使ってください。

2. 利用可能な機能を確認

curl --request GET 'https://api.pii-fi.com/v2/capabilities' \
  --header "Authorization: Bearer $PIIFI_API_KEY" \
  --header 'Accept: application/json'

{
  "request_id": "req_example_quickstart_01",
  "occurred_at": "2026-08-08T00:00:00.000Z",
  "plan": "standard",
  "workspace": "personal",
  "capabilities": {
    "api": true,
    "sync": true,
    "batch": false
  },
  "limits": {
    "requests_per_minute": 60,
    "concurrency": 2,
    "sync_unicode_code_points": 1000000,
    "batch_result_retention_hours": 24,
    "webhook_retry_hours": 24
  }
}

3. ダミー文章を非識別化

curl --request POST 'https://api.pii-fi.com/v2/deidentify' \
  --header "Authorization: Bearer $PIIFI_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Idempotency-Key: demo-order-0001' \
  --data '{"text":"担当者Aの連絡先はsample@example.testです。"}'

{
  "request_id": "req_example_quickstart_02",
  "text": "担当者Aの連絡先はメールアドレスAです。",
  "usage": {
    "processed_characters": 31,
    "consumed_units": 1
  }
}

4. Node.jsから呼ぶ

import {randomUUID} from 'node:crypto';

const response = await fetch('https://api.pii-fi.com/v2/deidentify', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PIIFI_API_KEY}`,
    'Content-Type': 'application/json',
    Accept: 'application/json',
    'Idempotency-Key': randomUUID()
  },
  body: JSON.stringify({
    text: '担当者Aの連絡先はsample@example.testです。'
  })
});

const body = await response.json();
if (!response.ok) {
  throw new Error(`${body.code}: ${body.title} (${body.request_id})`);
}

console.log(body.text); // request bodyやmappingはログへ出さない

実装前に知っておく概念#

認証とAPIキーの管理#

全ての要求でAPIキーをBearer値として送ります。キーの平文は発行直後に一度だけ表示され、その後は再表示できません。

Authorization: Bearer $PIIFI_API_KEY

本番で守ること

安全な切り替え手順

1. 1

   既存キーを残したまま、同じ用途・必要最小限のscopeで新しいキーを発行します。

2. 2

   新しいキーをsecret managerへ登録し、対象システムを再配備します。

3. 3

   新しいキーでGET /capabilitiesが200になり、必要な機能・上限が返ることを確認します。

4. 4

   古いキーをAPI画面で利用停止し、古いキーが401になることを確認します。

Scope

実際の許可は、現在のplan機能、APIキーscope、workspace、Team roleの共通部分で決まります。Teamのキー管理はownerまたはadminが行います。

接続先・形式・共通ヘッダー#

パスは全てbase URL https://api.pii-fi.com/v2へ連結します。本文を送る要求はJSON、通常応答もJSONです。SSEを選ぶ場合だけ応答形式がtext/event-streamになります。

成功時にも確認する値

エラーをどう処理するか#

エラーはapplication/problem+jsonで返ります。呼び出し側はHTTP statusと機械判定用のcodeで分岐し、調査用にrequest_idとoccurred_atを記録してください。入力本文や検出値はエラー本文へ含まれません。

{
  "type": "about:blank",
  "title": "Invalid API key",
  "status": 401,
  "code": "invalid_api_key",
  "detail": "Authentication failed",
  "request_id": "req_example_error_01",
  "occurred_at": "2026-08-08T00:00:00.000Z"
}

エラー本文を捨てずに分岐する

async function readPiifiResponse(response) {
  const contentType = response.headers.get('content-type') || '';
  const body = contentType.includes('json')
    ? await response.json()
    : { title: await response.text() };

  if (response.ok) return body;

  const error = new Error(body.title || `HTTP ${response.status}`);
  error.status = response.status;
  error.code = body.code;
  error.requestId = body.request_id || response.headers.get('x-request-id');
  error.occurredAt = body.occurred_at || response.headers.get('x-occurred-at');
  error.retryAfter = Number(response.headers.get('retry-after')) || null;
  throw error;
}

契約・検出型・利用量を先に確認する#

処理を始める前に使う3つの参照endpointです。plan名や検出型一覧をコードへ固定する代わりに、現在の応答を使って判断できます。

使う場面：起動時、キー切替後、403を受けたとき。現在のworkspace、機能、request頻度、同時処理、保持時間を確認します。

使う場面：entity_typesを指定するUIや設定を作るとき。現在のランタイムが扱える型だけを返します。

{
  "request_id": "req_example_metadata_01",
  "occurred_at": "2026-08-08T00:00:00.000Z",
  "entity_types": [
    "JPII_PERSON_NAME",
    "JPII_CONTACT_EMAIL_ADDRESS"
  ]
}

一覧は設定の選択肢として扱い、未取得時に過去の全型を送るfallbackは避けてください。

使う場面：実行前の残量表示、月次集計、APIとWebUIを合わせた利用量の確認。periodは省略可能で、指定する場合はYYYY-MMです。

{
  "request_id": "req_example_usage_01",
  "occurred_at": "2026-08-08T00:00:00.000Z",
  "period": "2026-08",
  "monthly_units": 100,
  "additional_units": 0,
  "consumed_units": 12
}

画面と同じプロファイルで処理する#

プロファイルは「何を検出し、どのように置き換えるか」をまとめた設定です。プロファイル画面で編集した設定をAPIでも使えます。標準プロファイル、ソースコード用プロファイル、自作・複製したプロファイルは同じ仕組みで、名前によって利用先が制限されることはありません。

どちらも利用者が編集できます。上の説明は初期状態であり、現在の設定は詳細APIで確認してください。GitHubでも標準プロファイルを選べます。

必要な権限を確認する

一覧・詳細の取得にはprofiles:readが必要です。処理でprofile_idを指定する場合も、処理用scopeに加えてこの権限が必要です。既存キーの権限は自動追加されません。403の場合はキーを繰り返し送らず、API画面で現在の権限を確認してください。

1. 一覧から使いたい設定のIDを選ぶ

画面で保存したユーザープロファイルを選ぶには、source=workspaceで絞り込みます。返された一覧のidを、処理要求のprofile_idへ渡してください。名前では指定しません。

成功応答はrequest_id、occurred_atとprofiles配列です。各要素にid、名前・説明・保存元、初期設定属性、enabled_entity_type_count／total_entity_type_count、updated_at、著名人名設定を含みます。具体的な検出型や処理方式は次の詳細APIで確認します。

curl --request GET 'https://api.pii-fi.com/v2/profiles?source=workspace' \
  --header "Authorization: Bearer $PIIFI_API_KEY" \
  --header 'Accept: application/json'

source省略時は内蔵設定とユーザープロファイルの両方、source=built_inでは内蔵設定だけを返します。それ以外の値は400です。APIキーが属するワークスペースの範囲で選んでください。

2. 詳細で現在の設定を確認する

次の例のpol_example_replace_meは説明用です。一覧で受け取ったidに置き換えてください。成功時はrequest_id、occurred_atと、以下の項目を含むprofileオブジェクトを返します。

curl --request GET 'https://api.pii-fi.com/v2/profiles/pol_example_replace_me' \
  --header "Authorization: Bearer $PIIFI_API_KEY" \
  --header 'Accept: application/json'

この応答には、辞書語句、正規表現、追加ルール本文、入力本文を含めません。追加ルールの編集内容はプロファイル画面で確認してください。存在しないIDと別ワークスペースのIDは、どちらも404です。

503の場合は必要な設定や稼働情報を取得できていません。別のプロファイルへ自動的に切り替えず、エラー処理の手順に従ってください。

3. 1件ずつ処理する場合

POST /detectまたはPOST /deidentifyのJSON本文へprofile_idを加えます。以下はdeidentifyの例です。detectではreturn_mappingを除いてください。URL、認証、Idempotency-KeyはQuickstartと同じです。

{
  "text": "連絡先はsample@example.testです。",
  "profile_id": "pol_example_replace_me",
  "return_mapping": false
}

検出対象、置換方式、著名人名の扱い、有効な追加ルールが現在の契約に従って適用されます。設定を二重指定しないよう、entity_typesや著名人名設定の直接指定とは併用できません（400）。

4. 複数件を一括処理する場合

POST /batchesの最上位へprofile_idを指定します。itemsの中ではありません。全itemへ同じプロファイルを適用し、itemのentity_typesとは併用できません（400）。登録後の追跡と結果取得はBatchの手順に従います。

{
  "operation": "deidentify",
  "profile_id": "pol_example_replace_me",
  "items": [
    {"id": "document-001", "text": "連絡先はalpha@example.testです。"},
    {"id": "document-002", "text": "連絡先はbeta@example.testです。"}
  ]
}

受付済みBatchは受付時の設定を保持します。後からプロファイルを編集したり追加ルールを停止したりしても、そのBatchの内容は変わりません。次の同期要求や新しいBatchから変更が適用されます。成功itemにはprofile_idが加わり、著名人名の扱いを使う場合はpublic_person_policyも返ります。

著名人名の扱いを選ぶ

プロファイルに保存した設定をそのまま使えます。プロファイルを使わない同期detect／deidentifyでは、以下をJSONへ直接指定することもできます。Batchでは直接指定せず、プロファイルに保存してください。

public_person_protection_levelはpublic_person_modeと一緒に指定します。strong（既定）は辞書情報と公開人物を扱う文脈がそろい、私的な文脈がない場合に限定します。balancedは私的な文脈を除きつつ、歴史人物・故人の単独言及にも広げます。weakは辞書内の一意な正式名との完全一致を条件とし、患者・連絡先などの文脈でもその人名候補を外すため、用途を十分確認してください。住所・電話番号など別の型は通常どおり処理します。

off以外ではpublic_person_policyに位置と一般化した判断理由が加わります。この項目には氏名・周辺文を含めませんが、通常の検出応答やmappingの取り扱いには引き続き注意が必要です。

設定を変えるとき・これまでの呼び出しを続けるとき

• profile_idを指定しない：これまでの動作を維持します。同期のentity_types指定、Batchのitemごとのentity_types指定もそのまま使えます。画面の標準プロファイルが自動適用されることはありません。
• 追加ルール：有効でも現在の契約で利用できないルールは実行対象に入りません。active_custom_rule_countで確認します。実行対象のルールを処理できない場合は、黙って省略せずエラーを返します。
• 設定変更後の再送：同じIdempotency-Keyで異なる設定を送ると409です。変更した設定で新しく処理する場合は新しいキーを使います。通信切断だけを理由にキーを変えず、再送時の判断に従ってください。
• 編集・複製・初期状態に戻す：プロファイル画面で行います。これらの書込み操作やGitHub監視の管理は公開APIでは提供していません。
• 画面から試す：API Sandboxでもプロファイルを選べ、要求JSONとBash用curlへ反映されます。実行すると通常のAPIと同じ使用量へ加算されます。

detect — 候補を見つける#

使う場面：文章を置き換える前に、何がどこで検出されたかを呼び出し側で確認・表示・判断したいとき。入力そのものは変更せず、個人情報候補のspansを返します。

Request fields

Response fields

{
  "text": "担当者Aの連絡先はsample@example.testです。",
  "entity_types": [
    "JPII_CONTACT_EMAIL_ADDRESS"
  ]
}

{
  "request_id": "req_example_detect_01",
  "spans": [{
    "entity_type": "JPII_CONTACT_EMAIL_ADDRESS",
    "text": "sample@example.test",
    "start": 9,
    "end": 28
  }],
  "usage": {
    "processed_characters": 31,
    "consumed_units": 1
  }
}

受け取った後に行うこと

• 確認画面：spanを入力へ重ねて表示し、業務上の共有可否を利用者が判断できるようにする。
• 機械判定：entity_type単位のルールは、現在の型一覧に存在する値だけで構成する。
• 記録：監査や集計が必要でも、検出値span.textは保存せず、request ID、型、件数など必要最小限にする。
• 分割：呼び出し側で本文を分割する場合、順序、各断片の対応、境界をまたぐ文脈の扱いは呼び出し側で管理する。

deidentify — 渡せる形へ置き換える#

使う場面：検出候補を元の値を直接含まないラベルへ置き換えた文章が必要なとき。検出と置換を一続きで行い、入力文字数を共通台帳へ1回だけ計上します。

Request fields

Response fields

{
  "text": "担当者Aの連絡先はsample@example.testです。",
  "return_mapping": true
}

{
  "request_id": "req_example_deidentify_01",
  "text": "担当者Aの連絡先はメールアドレスAです。",
  "mapping": {
    "メールアドレスA": "sample@example.test"
  },
  "usage": {
    "processed_characters": 31,
    "consumed_units": 1
  }
}

用途別の推奨

restore — 利用者のmappingで戻す#

使う場面：deidentifyで置き換えた文章を、利用者が保管しているmappingで元の値へ戻すとき。PII-FIはmapping、対象本文、復元結果を通常の記録へ残さず、共通ユニットも消費しません。

{
  "text": "連絡先はメールアドレスAです。",
  "mapping": {
    "メールアドレスA": "sample@example.test"
  }
}

{
  "request_id": "req_example_restore_01",
  "text": "連絡先はsample@example.testです。"
}

streamable HTTP — 同じ接続で進捗を受け取る#

/detectと/deidentifyへAccept: text/event-streamとstream: trueを送ると、受付・進捗・終端結果をSSEで受信できます。処理モデルと利用量は通常の同期処理と同じで、別のBatchは作りません。

curl --no-buffer --request POST 'https://api.pii-fi.com/v2/detect' \
  --header "Authorization: Bearer $PIIFI_API_KEY" \
  --header 'Accept: text/event-stream' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: demo-stream-0001' \
  --data '{"text":"sample@example.test","stream":true}'

event: accepted
data: {"request_id":"req_example_stream_01","occurred_at":"2026-08-08T00:00:00.000Z"}

event: progress
data: {"request_id":"req_example_stream_01","stage":"processing","done":false}

event: result
data: {"request_id":"req_example_stream_01","spans":[],"usage":{"processed_characters":19,"consumed_units":1}}

クライアント実装の順序

1. 1

   HTTP statusとContent-Type: text/event-streamを確認します。

2. 2

   空行までを1eventとして読み、eventとdataを分けます。TCP chunkの境界をevent境界として扱わないでください。

3. 3

   acceptedのrequest IDを保持し、progressは値を含まない進捗として表示します。

4. 4

   resultまたはerrorだけを終端として扱います。keep-aliveは15秒以内です。

Batch — 複数件を登録して後から受け取る#

使う場面：複数の文章をまとめて処理する、HTTP接続を結果まで維持したくない、切断後にも状態と結果を取り直したい場合。登録時にBatch IDと後続URLを受け取り、処理はバックグラウンドで進みます。

Batch request fields

curl --request POST 'https://api.pii-fi.com/v2/batches' \
  --header "Authorization: Bearer $PIIFI_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: demo-batch-20260808-001' \
  --data '{
    "operation": "deidentify",
    "items": [
      {"id":"document-001","text":"連絡先はalpha@example.testです。"},
      {"id":"document-002","text":"担当者Bへ連絡してください。"}
    ],
    "webhook_endpoint_id": "whe_example_00000001"
  }'

{
  "request_id": "req_example_batch_01",
  "occurred_at": "2026-08-08T00:00:00.000Z",
  "batch_id": "bat_example_0001",
  "status_url": "https://api.pii-fi.com/v2/batches/bat_example_0001",
  "events_url": "https://api.pii-fi.com/v2/batches/bat_example_0001/events",
  "result_url": "https://api.pii-fi.com/v2/batches/bat_example_0001/results",
  "created_at": "2026-08-08T00:00:00.000Z",
  "usage": {
    "processed_characters": 40,
    "consumed_units": 1
  }
}

receiptを受け取った直後に行うこと

• 保存する：batch_id、3つの後続URL、自システムの業務ID、作成時刻。本文は保存要件に従い別管理する。
• 保存しない：APIキー、request body、各itemの本文をジョブログへ複製しない。
• 確認する：HTTP 202を受付成功として扱い、まだ処理完了ではないことを画面・状態機械へ反映する。
• 再送する場合：同じBatch登録には同じIdempotency-Keyを使う。既存receiptが返り、二重登録・二重計上されない。

Batch endpoint一覧

状態をpollingする

固定のpolling間隔はAPI契約で強制しません。workspaceのrequest/分上限を超えないよう、状態が変わらない間は呼び出し間隔を広げ、429ではRetry-Afterに従ってください。

{
  "request_id": "req_example_batch_02",
  "occurred_at": "2026-08-08T00:00:01.000Z",
  "batch_id": "bat_example_0001",
  "operation": "deidentify",
  "status": "running",
  "progress": {"completed": 1, "total": 2},
  "created_at": "2026-08-08T00:00:00.000Z",
  "updated_at": "2026-08-08T00:00:01.000Z",
  "result_expires_at": null,
  "error_code": null
}

結果をitem IDで対応付ける

結果は登録したitem順です。ただし、順番だけに依存せずidで自システムの対象へ対応付けてください。partialでは成功itemと失敗itemを分けて扱います。

{
  "request_id": "req_example_batch_03",
  "occurred_at": "2026-08-08T00:00:03.000Z",
  "batch_id": "bat_example_0001",
  "operation": "deidentify",
  "items": [
    {"id":"document-001","status":"succeeded","text":"連絡先はメールアドレスAです。"},
    {"id":"document-002","status":"succeeded","text":"担当者Bへ連絡してください。"}
  ]
}

detect成功itemにはspans、deidentify成功itemには置換済みtextが入ります。失敗itemには値を含まないerror.codeと定型messageだけが入ります。

SSE — Batch進捗を続きから受け取る#

使う場面：サーバーまたは画面が接続中のあいだ、pollingより少ない要求で進捗を更新したいとき。progress、complete、errorを受信します。

curl --no-buffer 'https://api.pii-fi.com/v2/batches/bat_example_0001/events' \
  --header "Authorization: Bearer $PIIFI_API_KEY" \
  --header 'Accept: text/event-stream'

curl --no-buffer 'https://api.pii-fi.com/v2/batches/bat_example_0001/events' \
  --header "Authorization: Bearer $PIIFI_API_KEY" \
  --header 'Accept: text/event-stream' \
  --header 'Last-Event-ID: 12'

再接続アルゴリズム

1. 1

   受信したeventのidを、本文を含めずBatch IDと一緒に保存します。

2. 2

   切断したら、最後に処理済みのIDをLast-Event-IDへ設定して再接続します。

3. 3

   同じevent IDを再受信しても状態更新を二重適用しないようにします。

4. 4

   completeまたはerrorを終端として接続を閉じます。complete後はresults endpointを呼びます。

Webhook — 接続を維持せず完了を受け取る#

使う場面：Batch登録後に接続を閉じ、PII-FIから自システムの公開endpointへ状態・進捗通知を届けたいとき。送信先はAPI画面の「完了通知」で事前登録し、Batch登録時にwebhook_endpoint_idで選びます。

受信endpointの条件

Headersとbody

Content-Type: application/json
PII-FI-Webhook-ID: evt_example_0001
PII-FI-Webhook-Timestamp: 1786147200
PII-FI-Webhook-Signature: v1=<hex-digest>

{
  "event_id": "evt_example_0001",
  "type": "batch.progress",
  "batch_id": "bat_example_0001",
  "created_at": "2026-08-08T00:00:01.000Z",
  "status": "running",
  "progress": {"completed":1,"total":2}
}

署名をraw bodyで検証する

timestamp + "." + raw_bodyのHMAC-SHA256をWebhook secretで計算し、header内のいずれかのv1署名と定数時間比較します。JSON parseや再serializeをする前のbodyが必要です。

import crypto from 'node:crypto';

function verifyPiifiWebhook({ rawBody, timestamp, signatureHeader, secret }) {
  const ageSeconds = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!Number.isFinite(ageSeconds) || ageSeconds > 300) return false;

  const expected = crypto.createHmac('sha256', secret)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest();

  return String(signatureHeader).split(',').some((entry) => {
    const [version, hex] = entry.trim().split('=', 2);
    if (version !== 'v1' || !/^[0-9a-f]+$/i.test(hex || '')) return false;
    const received = Buffer.from(hex, 'hex');
    return received.length === expected.length
      && crypto.timingSafeEqual(received, expected);
  });
}

受信処理の安全な順序

1. 1
   raw bodyのまま署名を検証

   秘密が一致しない、timestamp差が5分を超える場合は受け付けません。

2. 2
   Webhook IDの重複を確認

   PII-FI-Webhook-IDまたはbodyのevent_idを一意制約つきで記録し、同じeventの再適用を防ぎます。

3. 3
   受領を永続化して2xxを返す

   重い業務処理やresults取得は自システムのqueueへ渡し、10秒の送信timeout内に応答します。

4. 4
   完了時にresultsを取得

   Webhook body自体を処理結果として扱わず、APIキーでBatch statusとresultsを取得します。

secret rotationと再送

secretは作成・rotation直後に一度だけ表示されます。rotation後24時間は新旧両方のv1署名がheaderへ入り、その後に旧secret暗号文を削除します。受信側は切替期間中、新旧secretのどちらでも検証できるようにしてください。

送信失敗時は1分、5分、15分、1時間、3時間、6時間の間隔で再送し、最長24時間で打ち切ります。再送ごとに重複を無害化してください。

冪等性と再試行を正しく実装する#

処理系POSTには8〜160文字のIdempotency-Keyが必要です。同じworkspace・操作で24時間一意にし、業務上の1処理と1対1で対応させます。ネットワークエラーのたびに新しいキーを生成すると、二重処理・二重計上を防げません。

キーを作るタイミング

プロファイルを使う要求では、IDだけでなく実行設定も同一要求の判定に含めます。プロファイルや有効な追加ルールを変更して同じキーで送ると409です。新設定での新しい処理と、同じ処理の通信再送を区別してください。受付済みBatchは受付時の設定を保持します。

1. 1
   要求を送る前に生成する

   UUIDなど衝突しにくい値を作り、自システムの値を含まない業務処理IDと対応付けます。

2. 2
   送信開始前に保存する

   process再起動後も同じ業務処理で同じキーを使えるようにします。本文を冪等台帳へ複製しないでください。

3. 3
   異なる処理へ使い回さない

   endpoint、workspace、本文、operationが異なる処理には新しいキーを使います。

4. 4
   結果の扱いを記録する

   成功、明示エラー、結果不明を分けます。「timeout＝未実行」と決めつけないでください。

同期処理とBatchの違い

再試行の判断表

rate・concurrency・文字数上限#

request頻度と同時処理数はAPIキーごとではなくworkspace全体の合算です。同じPersonalまたはTeamで複数キー・複数serverを使っても、枠は共有します。同時処理数には同期処理と実行中Batchの両方が入ります。

三つの上限を別々に扱う

呼び出し側へqueueを置く

複数serverから直接一斉送信すると、各serverは自分以外の同時処理を把握できません。workspace単位のqueueまたは共有semaphoreを置き、/capabilitiesの現在値を上限として流量を制御してください。

limits = GET /capabilities → limits

enqueue(job)

while queue has jobs:
  wait until active_processing < limits.concurrency
  wait until request_budget is available
  send job with its persisted Idempotency-Key

  if response is 429:
    pause until Retry-After
  if response is 502 or 503:
    retry with bounded exponential backoff
  otherwise:
    do not retry automatically

上限超過の要求ではユニットを消費しません。実際の受付数はplan上限とサービス全体の稼働上限の小さい方です。

どこに何が残るか#

「PII-FIが通常の記録へ残さないこと」と「呼び出し側が保存してよいこと」は別です。以下の表を、自システムのログ・DB・queue・監視・backupまで含めて確認してください。

データ経路の確認範囲

PII-FIへの送信部分だけでなく、入力前と応答後を含む経路全体で値の保持を設計してください。

本番投入前のチェックリスト#

ダミーデータによる結合試験で、次を全て確認してから実データを扱ってください。

困ったときの確認順序#

上限値・scope・APIパスは、④アプリ側の契約JSONとOpenAPIから生成・照合しています。例は全てダミーデータです。