Open API

Request headers

Signature algorithm

The string to sign is four lines joined by newlines: line 1 is the timestamp, line 2 the HTTP method (GET), line 3 the request path /api/open/v1/appointments, line 4 the query string. The query string must match what you actually send byte for byte — no reordering, no re-encoding (empty string when there are no parameters). Compute HMAC-SHA256 over this string using the API Secret as the key and use the lowercase hex as X-Signature. The timestamp must be Unix seconds within ±300 seconds of server time, otherwise it is treated as expired.

Query parameters

Response example

{
  "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"
      }
    ]
  }
}

Field reference

Push body example

{
  "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"
  }
}

Push signature

Push requests carry X-Timestamp and X-Signature headers: the string to sign is timestamp + a period + the raw request body bytes, computed with HMAC-SHA256 using the API Secret as the key. Your service should recompute and compare the signature, processing only on a match. Return 2xx to mark the delivery as successful.

Retry and idempotency

A failed delivery (non-2xx or timeout) is retried automatically at intervals of 1 minute, 5 minutes, 30 minutes, 2 hours, and 6 hours — 6 attempts including the first — after which it becomes a terminal state and is no longer delivered. Repeated deliveries for the same appointment carry the same delivery_id; use it to deduplicate and stay idempotent. When you first configure a test push, a probe event with event webhook.test (empty data object) is sent first.

Pull (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"

Push verification (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)