イベント

注文の作成や支払い、カートの放棄、商品の閲覧など、自社システムでの連絡先の行動を送信します。イベントは一度だけ保存され、組織のデフォルトワークスペースでメールアドレスまたは電話番号により連絡先と照合され、そのタイムラインに表示されます。このルートには events:write を持つキーが必要です。スコープ導入前に作成されたキーには、この権限がありません。


POST/external/v1/events

イベントの記録

本文には、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理由
400UNKNOWN_EVENT_TYPEイベントの type が許可された種類ではない
400PERSON_REQUIREDイベントに email も phone もない
400INVALID_VALUEvalue があるのに currency がない、currency があるのに金額がない、負の金額、整数部が 14 桁または小数部が四桁を超える金額、または customer.created に金額がある
400INVALID_PROPERTIESその種類で許可されないプロパティ、または形式の不一致
400INVALID_OCCURRED_AToccurredAt が現在より五分を超える未来、または 3650 日を超える過去である
400該当フィールド。例:EVENTS[0].IDevents がない、空である、100 件を超える、またはフィールドの欠落・形式不正がある
403INSUFFICIENT_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 で通知します。
このページは役に立ちましたか?