サードパーティ通知連携

クイックスタート

Web 管理画面で対象企業に紐づくサードパーティアプリを作成し、App ID と App Secret を取得します。最終結果が必要な場合は、任意の Callback URL も設定します。Engine は紐づく企業の有効な全ユーザーに通知センターのレコードを作成し、条件を満たす登録済み端末にのみシステム Push を試行します。

エンドポイントと認証

API 環境：

• テスト環境：https://aim-api-test.proton-system.com
• 本番環境：https://aim-api.proton-system.com

サーバー間の各 JSON リクエストでは HTTP Basic Authentication を使用して Authorization: Basic Base64(KEY:SECRET) を送信します。KEY は App ID、SECRET は App Secret です。

Endpoint: POST /openapi/v1/notifications。

curl --request POST 'https://<your-engine-host>/openapi/v1/notifications' \
  --header 'Authorization: Basic <Base64(AppID:AppSecret)>' \
  --header 'Content-Type: application/json' \
  --data '{"requestId":"order-20260819-001","title":"注文が完了しました","body":"ご注文が完了しました。","imageUrls":["https://cdn.example.com/order/001-1.webp","https://cdn.example.com/order/001-2.webp"]}'

リクエスト仕様

厳密な JSON は必須の requestId、title、body に加え、任意の imageUrls を受け付けます。imageUrls を省略するか、null または [] を送ると画像なしになります。それ以外は表示順に 1-9 個の URL を送ってください。各値は前後の空白が除去され、重複せず、ユーザー名やパスワードを含まない絶対 HTTPS URL で、2048 Unicode 文字以内である必要があります。1 件でも無効ならリクエスト全体が拒否されます。Engine は URL のみを保存し、画像の取得、確認、proxy、cache は行いません。本文全体は 256 KiB 以下、requestId は 128 Unicode 文字、title は 100 文字、body は 1000 文字までです。App ID ごとに毎分 10 回、毎時 100 回まで送信できます。

同じ requestId、title、body、同じ順序の imageUrls を再送すると保存済みの元の結果を返します。そのため処理完了後の status は ACCEPTED ではなく SUCCESS、PARTIAL_SUCCESS、FAILED のいずれかになることがあります。同じ requestId を異なる内容または画像順で再利用すると IDEMPOTENCY_CONFLICT です。

受付レスポンス

有効なリクエストは HTTP 202 を返します。

{
  "requestId": "order-20260819-001",
  "notificationId": "00000000-0000-0000-0000-000000000001",
  "status": "ACCEPTED"
}

ACCEPTED は Engine が配信待ちとして保存したことだけを表し、APNs/FCM や端末での表示完了を保証しません。

Callback の結果

Callback URL が設定されている場合、Engine は次の最終結果を送信します。

{
  "requestId": "order-20260819-001",
  "status": "PARTIAL_SUCCESS",
  "recipientCount": 8,
  "pushAcceptedCount": 1,
  "pushFailedCount": 1
}

recipientCount は通知センターの受信ユーザー数です。pushAcceptedCount と pushFailedCount は Push Outbox のバッチ数であり、ユーザー数、端末数、またはシステムバナーの配信数ではありません。

Callback テスト

管理画面で Callback をテストするたびに、個別のプローブイベントが送信されます。

{
  "requestId": "callback-test-<unique-id>",
  "status": "SUCCESS",
  "recipientCount": 1,
  "pushAcceptedCount": 1,
  "pushFailedCount": 0,
  "test": true
}

test が true の場合は、形式を検証して 2xx を返してください。このプローブを送信済み通知リクエストに関連付けたり、業務上の配信状態を更新したりしないでください。各件数は固定のテスト値であり、実際の受信者数や Push Outbox バッチ数ではありません。

最終 status は SUCCESS、PARTIAL_SUCCESS、FAILED のいずれかです。任意の 2xx で受領を通知してください。失敗時は 1 分、5 分、30 分、2 時間、6 時間、24 時間後に再試行されます。現在 HMAC 署名はありません。HTTPS を必須にし、テスト以外の結果では requestId を照合し、公開範囲を制限して冪等に処理してください。

エラー一覧

セキュリティと配信範囲

Mobile client は画像 1 枚につき最大 5 MiB を受け付け、画像ダウンロード処理全体のタイムアウトは 10 秒です。3xx redirect は追跡しないため、各 URL が画像を直接返す必要があります。

App ID と App Secret はサーバー間の認証情報です。ブラウザー、モバイルアプリ、公開リポジトリ、URL、クライアント保存領域に含めないでください。漏えい時は App Secret を再設定します。紐づく企業の有効な全ユーザーに通知センターのレコードが作成され、recipientCount に計上されます。システム Push は BUSINESS カテゴリを許可する有効な PushInstallation にのみ試行され、全端末でのシステム通知表示は保証されません。imageUrls は通知 detail にだけ表示され、Push や Callback の payload には含まれません。title と body は画像がなくても通知内容を完全に理解できるようにしてください。画像の取得または表示に失敗しても accepted、Callback、Push の status は変わりません。Mobile client は public CDN から画像を直接取得するため、認証や Cookie が不要な URL を使用して 90 日以上利用可能にし、CDN がユーザーの IP、request time、User-Agent を受け取ることを考慮してください。過去の表示を固定する必要がある場合は immutable object URL を使用してください。