開発者向けドキュメント

OKAERI の公開 API の使い方です。リード・配信・レポートの取得、除外リストの登録、キャンペーン・シナリオ・文面の下書きの作成、Webhook の送信先の管理を、自社のシステムや AI エージェントから行えます。各操作の詳細は API リファレンス を参照してください。

AI・コーディングエージェント向けにこのページの Markdown 版とllms.txtがあります。

はじめに

認証とスコープ

API キーを Authorization ヘッダに Bearer で付けて送ります。クエリ文字列でのキーの受け渡しは受け付けません。

Authorization: Bearer okr_test_XXXXXXXXXXXXXXXXXXXXXX
キーの種類形動き
本番キーokr_live_…読み取り・書き込みとも本番のデータに反映します
テストキーokr_test_…書き込みはドライランです（下記）。読み取りは本番のデータを返します

スコープ

キーには発行時にスコープ（<資源>:<操作> の形の権限）を付けます。各操作に必要なスコープは、リファレンスと openapi.json の x-okaeri-scopes に載っています。足りない時は 403 permission_error（code は scope_insufficient）を返します。

スコープ使える操作
campaigns:readtestSiteUrlRules・listCampaigns・getCampaign
campaigns:writecreateCampaign・updateCampaign・replaceCampaignUrlRules・replaceCampaignFormProfile・duplicateCampaign
deliveries:readlistDeliveries・getDelivery
leads:readlistLeads・getLead
messages:readlistMessages・getMessage・listMessageVariables・listMessageExamples・previewMessage・estimateSmsSegments
messages:writeduplicateCampaign・createCampaignScenarioFromPreset・duplicateScenario・createMessage・updateMessage・deleteMessage・duplicateMessage
reports:readgetFunnelReport・getDailyReport
scenarios:readlistCampaignScenarios・getScenario・listScenarioPresets・getDeliveryStatus
scenarios:writeduplicateCampaign・createCampaignScenario・updateScenario・deleteScenario・replaceScenarioSteps・createCampaignScenarioFromPreset・duplicateScenario
sites:readlistSites・getSite・getSiteTagConfig・listSitePpChecks・getSitePpCheck・getConsentSettings
suppressions:readlistSuppressions
suppressions:writecreateSuppression・deleteSuppression
webhooks:writelistWebhookEndpoints・createWebhookEndpoint・getWebhookEndpoint・deleteWebhookEndpoint・listWebhookEndpointDeliveries・redeliverWebhookDelivery

API キーではできない操作

レート制限

API キーのリクエストは、テナント単位（テナントの全キーの合計）で直近60秒の回数を数えます。上限はプランごとに次のとおりです。

プラン上限（直近60秒）
Free60 回
Starter60 回
Growth300 回
Pro1,000 回

ドライラン（テストキー）

テストキー（okr_test_…）の書き込み（POST・PUT・PATCH・DELETE）はドライランです。検証・上限の判定・エラーの応答は本番キーと同じに行い、応答も同じ形で返しますが、何も保存しません。AI エージェントに試行錯誤させる時は、まずテストキーを渡してください。

再送の重複を防ぐ（Idempotency-Key）

POST は Idempotency-Key ヘッダを受け付けます。ネットワークの再試行などで同じ要求を2回送っても、作成は1回にまとまります。要求ごとに一意な値（UUID など）を付けてください。

エラーの形

エラーは常に次の形で返します。分岐は HTTP ステータスでなく type と code で行ってください。

{
  "error": {
    "type": "permission_error",
    "code": "scope_insufficient",
    "message": "（何が足りないかの説明）",
    "param": null,
    "request_id": "req_01JXXXXXXXXXXXXXXXXXXXXXXX"
  }
}
typeHTTP主な場面
invalid_request400・409・422パラメータの不正（param に項目名）・状態の衝突（409）
authentication_error401API キーが無い・無効・失効している
permission_error403スコープの不足・プランの上限・API キーではできない操作
not_found404対象が無い（他のテナントの ID を指した時も同じ）
rate_limit_error429レート制限の超過（Retry-After の秒数の後に再試行する）
api_error5xxサーバー側の失敗（request_id を添えて問い合わせる）

Webhook

登録した送信先（https の URL）へ、イベントの発生を POST で知らせます。送信先は API（Webhook）か管理画面で登録します。送信先の本数にはプランごとの上限があります。

イベント

イベント送る時data の型
lead.captured入力途中の連絡先を取得した時LeadCapturedData
lead.abandoned入力の途中で離脱したと判定した時LeadAbandonedData
delivery.sentSMS・メールの送信を送信事業者が受け付けた時DeliveryEventData
delivery.failed送信の失敗が確定した時DeliveryEventData
conversion.detected成果（コンバージョン）を検知した時ConversionDetectedData
usage.threshold_reachedプランの送信枠の 80%・100% に達した時UsageThresholdReachedData

本文に連絡先（電話番号・メールアドレス）は含みません。必要な時は lead_id でリードを取得してください。

本文の例

{
  "id": "00000000-0000-7000-8000-000000000001",
  "type": "lead.captured",
  "created_at": "2026-01-01T00:00:00Z",
  "tenant_id": "00000000-0000-7000-8000-000000000002",
  "data": {
    "lead_id": "00000000-0000-7000-8000-000000000003",
    "campaign_id": "00000000-0000-7000-8000-000000000004",
    "site_id": "00000000-0000-7000-8000-000000000005",
    "channels": [
      "email",
      "sms"
    ]
  }
}

受け方と署名の検証

Outbound Webhook で送信先へ送る本文（POST・Content-Type: application/json・User-Agent: OKAERI-Webhook/1）。type ごとに data の形が決まる。連絡先（電話・メール）は含まない（必要なら lead_id で取得する）。

受け方

署名の検証（ヘッダ X-OKAERI-Signature: t=<UNIX 秒>,v1=<16進>）

  1. ヘッダを , で分け、t と v1 を取り出す
  2. <t>.<受け取った本文のバイト列> を、送信先の作成時に1回だけ受け取った secret（whsec_…）を鍵にして HMAC-SHA256 で計算し、16進（小文字）にする。本文は JSON として読み直したものでなく、受け取ったバイト列そのままを使う
  3. 計算した値と v1 を定数時間で比較する。一致しなければ破棄する
  4. t と受信時刻の差が許容範囲（推奨 5分）を超えたら破棄する（盗んだ本文の再送の対策）。t は送るたびにその時刻で付け直す（再試行・再送でも古くならない）

検証の例（Python）：

import hashlib
import hmac
import time

TOLERANCE = 300  # 秒（推奨は5分）


def verify(secret: str, header: str, body: bytes) -> bool:
    """X-OKAERI-Signature を検証する。body は受け取ったバイト列そのまま"""
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    t, v1 = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or abs(time.time() - int(t)) > TOLERANCE:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

契約の範囲

クイックスタート

動作の確認はテストキーで行ってください（書き込みは保存されません）。キーは環境変数で渡します。

export OKAERI_API_KEY="okr_test_XXXXXXXXXXXXXXXXXXXXXX"

1. サイトの一覧を取得する

必要なスコープは sites:read。応答の data にサイトが並びます。

curl https://api.okaeri.tech/api/v1/sites \
  -H "Authorization: Bearer $OKAERI_API_KEY"

2. 期間のファネル（段ごとの件数）を取得する

必要なスコープは reports:read。期間は from 以上 to 未満で、日時はオフセット付き（+09:00 など）で指定します。

curl -G https://api.okaeri.tech/api/v1/reports/funnel \
  -H "Authorization: Bearer $OKAERI_API_KEY" \
  --data-urlencode "from=2026-01-01T00:00:00+09:00" \
  --data-urlencode "to=2026-02-01T00:00:00+09:00"

3. 除外リストに登録する（書き込み）

必要なスコープは suppressions:write。登録した宛先には配信しません。テストキーなら応答ヘッダに OKAERI-Dry-Run: true が付き、保存されません。

curl https://api.okaeri.tech/api/v1/suppressions \
  -H "Authorization: Bearer $OKAERI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"value": "[email protected]"}'