イベント
注文の作成や支払い、カートの放棄、商品の閲覧など、自社システムでの連絡先の行動を送信します。イベントは一度だけ保存され、組織のデフォルトワークスペースでメールアドレスまたは電話番号により連絡先と照合され、そのタイムラインに表示されます。このルートには events:write を持つキーが必要です。スコープ導入前に作成されたキーには、この権限がありません。
イベントの記録
本文には、1~100 件のイベントの配列である events を指定します。保存前にすべてを検証し、1 件でも拒否されるとリクエスト全体が拒否され、何も保存されません。
- 名前
id- タイプ
- string
- 説明
必須:独自のイベント識別子です。空白を含まない 1~128 文字で、例は
order-1001-paidです。同じ識別子で再送したイベントは一度しか保存されないため、重複させずにリクエストを再試行できます。
- 名前
type- タイプ
- string
- 説明
必須:発生した行動を、下記のいずれかの種類で指定します。
- 名前
occurredAt- タイプ
- string
- 説明
必須:発生時刻を ISO 8601 で指定します。例は
2026-10-20T10:00:00Zです。現在より五分を超える未来、または 3650 日を超える過去は指定できません。
- 名前
email- タイプ
- string
- 説明
対象者のメールアドレスです。メールアドレス、電話番号、または両方を指定します。
- 名前
phone- タイプ
- string
- 説明
国番号を含む電話番号です。例は
+919812345678です。
- 名前
value- タイプ
- number
- 説明
イベントの金額です。0 以上で、整数部は最大 14 桁、小数部は最大四桁です。例は
1299.50です。対応するcurrencyも指定します。customer.createdイベントには金額がありません。
- 名前
currency- タイプ
- string
- 説明
金額の通貨を ISO 4217 コードで指定します。例は
INRです。
- 名前
properties- タイプ
- object
- 説明
種類ごとに許可される詳細は下表のとおりです。それ以外のプロパティは拒否されます。
| イベントの種類 | 発生した行動 | 許可されるプロパティ |
|---|---|---|
order.placed | 注文が作成された | orderNumber, itemCount, productIds |
order.paid | 注文が支払われた | orderNumber, itemCount, productIds |
order.fulfilled | 注文の履行が完了した | orderNumber, itemCount, productIds |
order.cancelled | 注文がキャンセルされた | orderNumber, itemCount, productIds |
order.refunded | 注文が返金された | orderNumber, itemCount, productIds |
checkout.started | チェックアウトが開始された | itemCount, productIds |
cart.abandoned | 商品入りのカートが放棄された | itemCount, productIds |
product.viewed | 商品が閲覧された | productId |
customer.created | 対象者が顧客になった | プロパティなし |
orderNumber、productId、productIds内の各識別子は、1~64 文字の ASCII です。先頭は英字、数字、または#とし、それ以降は. _ : / -も使用できます。例は#1001、gid://shopify/Product/2です。itemCountは 0~10000 の整数です。productIdsには 1~50 個の識別子を指定します。- プロパティの上限は 4 KB で、上記の識別子と件数のみを受け付けます。支払いカード情報、住所、自由記述文は含めず、対象者は
emailとphoneで識別してください。
支払い済みの注文と放棄されたカート
curl -X POST https://api.oblic.app/external/v1/events \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"events": [
{
"id": "order-1001-paid",
"type": "order.paid",
"occurredAt": "2026-10-20T10:00:00Z",
"email": "asha@example.org",
"value": 1299.50,
"currency": "INR",
"properties": { "orderNumber": "#1001", "itemCount": 2, "productIds": ["SKU-1", "SKU-2"] }
},
{
"id": "cart-7781",
"type": "cart.abandoned",
"occurredAt": "2026-10-20T11:30:00Z",
"phone": "+919812345678",
"properties": { "itemCount": 1, "productIds": ["SKU-3"] }
}
]
}'
レスポンス
{
"status": "success",
"data": { "received": 2, "stored": 2, "duplicates": 0, "unmatched": 1 },
"errors": null
}
レスポンスのステータスは 202 です。
storedは新たに保存したイベント数、duplicatesは同じidですでに保存済みのため再保存しなかったイベント数です。unmatchedは、保存済みで連絡先がまだ見つからないイベント数です。デフォルトワークスペースでメールアドレスに一致する最も古い連絡先を優先し、なければ電話番号または WhatsApp 番号で照合します。一致しないイベントは待機します。照合サービスが有効な場合、通常は10分ごとに実行されますが、滞留や障害で遅延することがあります。受信から 30 日たっても未照合のイベントは、このサービスが削除します。イベント自体が連絡先を作成することはありません。- サブアカウントのイベント は、そのメッセージと同様に
X-Oblic-On-Behalf-Ofを指定して送信します(サブアカウントを参照)。
| 拒否ステータス | cd | 理由 |
|---|---|---|
| 400 | UNKNOWN_EVENT_TYPE | イベントの type が許可された種類ではない |
| 400 | PERSON_REQUIRED | イベントに email も phone もない |
| 400 | INVALID_VALUE | value があるのに currency がない、currency があるのに金額がない、負の金額、整数部が 14 桁または小数部が四桁を超える金額、または customer.created に金額がある |
| 400 | INVALID_PROPERTIES | その種類で許可されないプロパティ、または形式の不一致 |
| 400 | INVALID_OCCURRED_AT | occurredAt が現在より五分を超える未来、または 3650 日を超える過去である |
| 400 | 該当フィールド。例:EVENTS[0].ID | events がない、空である、100 件を超える、またはフィールドの欠落・形式不正がある |
| 403 | INSUFFICIENT_SCOPE | キーに events:write がない |
拒否の説明は、メール、電話番号、プロパティ値を繰り返す代わりに、events[2].type のようなフィールドや配列内の位置を示します。不明なプロパティ名は説明に含まれる場合があるため、名前にも機密情報を入れないでください。形式の検証が種類固有の検証に先行し、レスポンスはその段階で見つかった問題を列挙します。
ジャーニーの開始
ワークスペースでジャーニー実行基盤が有効な場合、Journeys で作成したジャーニーを連絡先の行動で開始できます。エディターで ストアで何かを行う を選び、イベントの種類を指定します。絞り込むには、ストアが送る商品識別子と、通貨を含む最低金額を追加します。
- イベントごとに一度:同じ連絡先が二つの注文を支払うと、ジャーニーは二度開始します。同じ
idのイベントを再送した場合は一度だけです。 - 最近のイベントのみ:イベントが連絡先とともに保存されるか、後から照合される時点が
occurredAtから 24 時間以内なら、ジャーニーを開始します。過去の注文の取り込みなど、それより古いイベントはタイムラインとセグメントに反映されますが、ジャーニーは開始しません。 - 商品と金額:商品条件は注文、チェックアウト、カートの
productIdsまたは閲覧されたproductIdに照合します。金額は指定通貨の最低額以上である必要があります。customer.createdにはどちらもないため、この二つの条件では絞り込めません。
Shopify から
Shopify 連携とインストールリンクが設定済みなら、設定 → 統合 → Shopify ストア から接続します。Shopify に Oblic アプリをインストールしてから、ストアを組織に接続してください。連携を利用できない場合は、先に管理者へ設定を依頼します。注文は上記のイベントとなり、直接送信するイベントと同様にメールまたは電話番号で照合されます。メールや SMS マーケティングを購読した顧客は、その同意を伴う連絡先になります。
| Shopify の元データ | 生成されるイベント |
|---|---|
| 作成、支払い、履行、キャンセルされた注文 | order.placed, order.paid, order.fulfilled, order.cancelled |
| 返金 | order.refunded。注文した対象者に対し、返金額を記録する |
| メールアドレスまたは電話番号のあるチェックアウト | checkout.started |
| 注文がなく、一時間操作されていないチェックアウト | cart.abandoned。チェックアウトごとに一度 |
| マーケティングを購読し、まだ連絡先ではない顧客 | customer.created。Oblic が連絡先を作成したとき |
- イベントの内容:ストア通貨の注文金額、注文番号、商品数、Shopify 商品識別子による商品です。それ以外の注文詳細はイベントに保存しません。
- 購読した顧客:Shopify でメールまたは SMS マーケティングを購読した顧客を、イベントと同じ規則で連絡先から探します。いなければ、メールまたは番号を名前としてデフォルトワークスペースに連絡先を作成し、そのアドレスまたは番号に同意を記録します。未購読の顧客から連絡先を作成することはありません。
- 購読解除:Shopify で解除した顧客には、そこで再購読するまでメール、またはキャンペーン・自動化・ジャーニーの SMS を送りません。メール内のリンクなどを使って Oblic で行ったメール購読解除を、Shopify が取り消すことはありません。
- 接続解除:同じページでストアを切断し、Shopify で Oblic アプリをアンインストールします。切断時にはイベントを保持します。ストアとイベントは、後続の Shopify
shop/redactリクエストを処理した際に削除し、切断だけでは削除しません。 - 顧客のプライバシー:Shopify が顧客データの削除を求めると、そのストア由来のイベントを削除します。連絡先に同意が記録されていた場合は、組織の所有者に Oblic で通知し、連絡先の削除を求めます。顧客が自身のデータを請求した場合も、所有者に Oblic で通知します。