サードパーティ通知連携

クイックスタート

Web 管理画面で対象企業に紐づくサードパーティアプリを作成し、App ID と App Secret を取得します。最終結果が必要な場合は、任意の Callback URL も設定します。

Engine は任意の audience で選択されたユーザー（既定は企業内の対象ユーザー全員）にレコードを作成し、条件を満たす登録済み端末にのみシステム 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"],"displayFields":[{"label":"店舗名","value":"小韓麺（望京店）"},{"value":"ORD-10086"}],"tags":["完了","本店"]}'

リクエスト仕様

フィールド一覧

画像: imageUrls

• 画像なしは省略、null、[]。画像ありは表示順に 1-9 URL を指定します。
• URL は trim され、重複せず、ユーザー名やパスワードのない絶対 HTTPS URL が必要です。
• 1 URL は最大 2048 Unicode 文字です。1 件でも無効ならリクエスト全体を拒否します。
• Engine は URL のみを保存し、画像の取得、確認、proxy、cache は行いません。

表示フィールド: displayFields

{
  "displayFields": [
    { "label": "店舗名", "value": "Little Han Noodles (Wangjing)" },
    { "value": "ORD-10086" }
  ]
}

• 省略、null、[] は追加行なしです。最大 10 オブジェクトです。
• label がない場合、または null の場合、value を横幅いっぱいの 1 行として表示します。
• 常に plain text です。HTML、Markdown、リンク、ネストしたデータ、型、スタイル指定は非対応です。

詳細タグ tags

• タグなしは省略、null、[]。タグありは表示順に最大 8 strings を指定します。
• 各タグは trim 後 1-20 Unicode 文字が必要です。空、文字列以外、長すぎる値、trim 後の重複はリクエスト全体を INVALID_REQUEST にします。
• タグは操作できない plain text で、通知 detail にだけ表示され、順序を維持します。

送信先: audience

会社メンバー ID は Web Admin の会社メンバー一覧からコピーします。そのメンバーはサードパーティアプリケーションに紐づく会社に所属している必要があります。

{
  "audience": { "type": "USERS", "userIds": ["companyMemberId"] }
}

{
  "audience": { "type": "ROLES", "roles": ["roleId"] }
}

• audience の省略または null は、紐づく企業の対象となる有効ユーザー全員です。
• 対応配列は元の文字列で 1-100 件です。ID は trim され、空白は無視され、集合として重複排除・sort されます。
• 存在しない、無効、削除済み、他社の ID は無視され、残りの有効対象には送信されます。
• 有効対象が 0 件でも受理され recipientCount=0 で完了し、全社送信へ fallback しません。
• type と一致しない selector は省略または null にできます。その他の混在、未知の type/field、欠落・空配列、文字列以外、100 件超は INVALID_REQUEST です。

制限と idempotency

• body 全体は 256 KiB 以下です。requestId、title、body は最大 128、100、1000 Unicode 文字です。
• App ID ごとに毎分 10 回、毎時 100 回までです。
• 同じ requestId と等価な正規化内容は保存済み結果を返します。画像、表示フィールド、tags は順序を区別し、audience の順序と重複は区別しません。
• 異なる内容なら IDEMPOTENCY_CONFLICT です。完了後の status は SUCCESS、PARTIAL_SUCCESS、FAILED のいずれかです。

受付レスポンス

有効なリクエストは 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 を照合し、公開範囲を制限して冪等に処理してください。

エラー一覧

セキュリティと配信範囲

• App ID と App Secret はサーバー間の認証情報です。ブラウザー、モバイルアプリ、公開リポジトリ、URL、クライアント保存領域に含めないでください。漏えい時は App Secret を再設定します。
• 非公開の対象 ID はアプリケーション logs に書き込まれません。非公開 selector と対象 ID は GraphQL、Push、Callback、realtime、navigation の payload にも含まれません。
• audience なしでは企業内の対象となる有効ユーザー全員、audience ありでは解決された有効対象だけが含まれます。有効な各受信者に通知センターのレコードが作成され、recipientCount に計上されます。
• システム Push は BUSINESS カテゴリを許可する有効な PushInstallation にのみ試行され、全端末でのシステム通知表示は保証されません。
• 完全な imageUrls リストは認可済みの通知 detail でのみ利用できますが、Engine はネイティブのシステムバナー表示用に imageUrls の先頭 URL を APNs/FCM へ送信する場合があります。displayFields と tags は Push や Callback には含まれません。どちらも操作できない plain text なので、秘密情報、アクセストークン、決済データを含めないでください。
• title と body は画像がなくても通知内容を完全に理解できるようにしてください。画像の取得または表示に失敗しても accepted、Callback、Push の status は変わりません。
• Mobile client は画像 1 枚につき最大 5 MiB を受け付け、画像ダウンロード処理全体のタイムアウトは 10 秒です。3xx redirect は追跡しないため、各 URL が画像を直接返す必要があります。
• Mobile client は public CDN から画像を直接取得します。認証や Cookie が不要な URL を使用して 90 日以上利用可能にし、CDN がユーザーの IP、request time、User-Agent を受け取ることを考慮してください。
• 過去の表示を固定する必要がある場合は immutable object URL を使用してください。