GoHighLevelの空き枠は日付キーにslotsが入る。31日を超えると400で止まる

予約の空き枠をClaude Codeに読ませて、「来週の空きを一覧にして」と頼みたくなる場面は多いはずです。GoHighLevelのカレンダーには、空き枠を返す口があります。

ところが、この口は素直に書くと落ちます。私たちは自社のカレンダーで試して、4か所でつまずきました。この記事は、その記録です。

まず、Versionヘッダが別になる

GoHighLevelのAPIは、リクエストにVersionというヘッダを付けます。コンタクトやオポチュニティの口では 2021-07-28 を使います。ところが、カレンダー系の口は 2021-04-15 を指定します。

コンタクトの口で動いていたスクリプトを、そのままカレンダーへ流用すると、ヘッダの値が合わずに弾かれます。カレンダーの口に入るときは、ヘッダを持ち替えます。

返りのトップは日付キーで、混ざりものがある

空き枠の口は、開始と終了をエポックミリ秒で受け取り、タイムゾーンに Asia/Tokyo を渡すと、日本時間に換算した枠を返します。返りのトップには、2026-08-28 のような日付のキーが並び、その中の slots に、日本時間のオフセット付きの時刻の配列が入ります。

罠は、同じ階層に日付ではないキーが混ざることです。たとえば traceId という、追跡用のIDを入れたキーがあります。「トップの値を全部回して、slots を取り出す」と書くと、日付ではないキーにぶつかったところで落ちます。

直し方は簡単です。キーが日付の形かどうかで、先に濾します。濾したあとで slots を読みます。

空き枠が0件のときは、計器の生存も疑う

空き枠も予約の件数も、壊れた計器が0を返すことがあります。0件の結果を「空きなし」と書く前に、期間を広げて、0以外が出ることを確かめます。広げて何も出ないなら、本当に0件です。

時刻は、日本のタイムゾーンで受け取る

開始と終了は、秒ではなくミリ秒の数値です。桁を取り違えると、1970年代の空き枠を読みにいくことになり、結果は0件になります。ここでも「0件は計器の故障かもしれない」が効きます。

タイムゾーンを Asia/Tokyo で渡すと、返る枠は日本時間のオフセット付きです。UTCで受け取って自分で9時間足す書き方もできますが、換算の誤りが入り込みます。口に任せたほうが、間違いが少なくなります。

窓は31日まで

期間を長く取りたくなりますが、開始から終了までの幅が31日を超えると、400が返ります。メッセージは「日付の範囲が31日を超えてはいけない」という内容です。長い期間を見たいときは、月ごとに割って、順に取ります。

認証なしで読める公開の口もある

自社の予約ページを埋め込んだ公開のページには、予約ウィジェットが入っています。このウィジェットが裏で読んでいる空き枠の口は、認証のヘッダもVersionヘッダも付けずに、読み取りだけで200を返します。ホストは backend.leadconnectorhq.com で、パスは /calendars/ から始まります。

ここにも罠があります。

• api.leadconnectorhq.com の同じパスは、404になる
• backend の同じホストでも、空き枠を付けないカレンダー本体のパスは、401になる

つまり、素通しで読めるのは空き枠の口だけです。「認証なしでは読めない」と早合点して、別の経路を探し始めると遠回りになります。

読み取りだけなので、他社が公開しているイベントの開催日時の裏取りにも使えます。ランディングページの表記より、主催者のシステムの中身のほうが、一次の証拠として強いからです。イベントが1回だけのカレンダーなら、枠はちょうど1つ返り、それが本番の日時です。

実測の数字

2026年8月28日に、自社の拠点のカレンダーを一覧したところ、9本が見つかり、全部が有効でした。9本すべてで空き枠の取得が200を返しました。窓を31日を超えて渡すと、同じ口が400を返すことも、同じ日に確かめています。

予約の実数を読む口は、カレンダーのIDと、開始と終了のエポックミリ秒を受け取ります。こちらも同じVersionヘッダで読めました。空き枠と予約の実数を並べて読むと、「枠はあるのに予約がない」のか、「枠そのものがない」のかを分けて見られます。

Claude Codeに頼むときの最初の一文

私たちは、Claude Codeに空き枠を頼むときに、最初の指示へ次の3つを書いておきます。

• Versionヘッダはカレンダー用の値を使うこと
• 返りの日付キーだけを濾して読むこと
• 窓は31日以内に割って取ること

この3つを先に書いておけば、上で書いた3つのつまずきは、最初の1回から避けられます。

次に読む

空き枠が読めたら、次は予約ウィジェットの表示です。日本語にできない理由と、自前の画面で描く方法は、予約ウィジェットの記事にまとめました。