オープンAPI

リクエストヘッダー

署名アルゴリズム

署名対象文字列は 4 行を改行で連結して作ります:1 行目はタイムスタンプ、2 行目は HTTP メソッド(GET)、3 行目はリクエストパス /api/open/v1/appointments、4 行目は query string。query string は実際に送信したものと 1 文字単位で完全一致させ、並べ替えや再エンコードをしないこと(パラメータが無ければ空文字列)。この文字列を API Secret を鍵として HMAC-SHA256 で計算し、小文字 16 進数を X-Signature とします。タイムスタンプは Unix 秒でサーバー時刻の ±300 秒以内でなければ期限切れと見なされます。

クエリパラメータ

レスポンス例

{
  "code": 0,
  "message": "ok",
  "data": {
    "total": 128,
    "items": [
      {
        "id": 1024,
        "scheduled_at": "2026-07-20T10:00:00+09:00",
        "party_size": 2,
        "contact_name": "山田太郎",
        "contact_phone": "+819012345678",
        "subject": "カット予約",
        "note": null,
        "status": "confirmed",
        "outside_slot": false,
        "item_name": "カット",
        "item_external_id": "svc_001",
        "created_at": "2026-07-16T12:34:56+09:00",
        "updated_at": "2026-07-16T12:34:56+09:00"
      }
    ]
  }
}

フィールド説明

プッシュ本文の例

{
  "event": "appointment.created",
  "delivery_id": 8801,
  "timestamp": 1752633600,
  "data": {
    "id": 1024,
    "scheduled_at": "2026-07-20T10:00:00+09:00",
    "party_size": 2,
    "contact_name": "山田太郎",
    "contact_phone": "+819012345678",
    "subject": "カット予約",
    "note": null,
    "status": "pending",
    "outside_slot": false,
    "item_name": "カット",
    "item_external_id": "svc_001",
    "created_at": "2026-07-16T12:34:56+09:00",
    "updated_at": "2026-07-16T12:34:56+09:00"
  }
}

プッシュ署名

プッシュのリクエストヘッダーには X-Timestamp と X-Signature が付きます:署名対象は「タイムスタンプ + 半角ピリオド + 本文の生バイト」で、API Secret を鍵として HMAC-SHA256 で計算します。受信側は署名を再計算して照合し、一致した場合のみ処理してください。2xx を返せば配信成功と見なします。

リトライと冪等性

配信失敗(2xx 以外またはタイムアウト)は自動でリトライされ、間隔は順に 1 分・5 分・30 分・2 時間・6 時間、初回を含め計 6 回試行し、すべて失敗すると終了状態となり以後配信しません。同一予約の複数回の配信は同じ delivery_id を持つため、これで重複排除して冪等性を確保してください。テスト送信を初めて設定する際は、event が webhook.test の検査用イベント(data は空オブジェクト)を先に 1 通送ります。

プル(curl)

# 拉取预约(签名 = HMAC-SHA256(secret, ts + "\n" + "GET" + "\n" + path + "\n" + query))
TS=$(date +%s)
QUERY="page=1&page_size=50"
SIG=$(printf '%s\nGET\n/api/open/v1/appointments\n%s' "$TS" "$QUERY" \
  | openssl dgst -sha256 -hmac "$API_SECRET" -hex | awk '{print $NF}')
curl "https://phone-api.bookmi.ai/api/open/v1/appointments?$QUERY" \
  -H "X-Api-Key: ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

プッシュ検証(Python)

# 推送验签(收到 POST 时)
import hashlib, hmac
def verify(secret: str, timestamp: str, body: bytes, signature: str) -> bool:
    expected = hmac.new(secret.encode(), timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)