カレンダーAPI
概要
RoktカレンダーAPIはRESTに基づいています。当社のAPIは予測可能なリソース指向のURLを持ち、APIエラーを示すためにHTTPレスポンスコードを使用します。HTTP認証やHTTP動詞など、オフシェルフのHTTPクライアントによって理解されるHTTPの組み込み機能を使用しています。JSONは、エラーを含むすべてのAPIレスポンスで返されます。
認証
Roktカレンダーは、アカウントのユーザー名とパスワードを必要とせずに、ウェブサイトやアプリケーションが保護されたカレンダーへのアクセス許可を要求するために、OAuth 2.0プロトコルを使用しています。
API登録
OAuthを使用して認証するには、登録済みのOAuthアプリケーションである必要があります。アプリケーションには、一意のclient_idとclient_secretが発行されます。これらの詳細は、アクセストークンをリクエストする際にアプリケーションが認証するために必要です。
APIはリクエストによって利用できます。アクセスをリクエストするには、アカウントマネージャーに連絡してください。その後、一意のclient_idとclient_secretが提供されます。
次に進む:
OAuthの詳細
- RoktカレンダーOAuthは
client_credentialsグラントタイプをサポートしています。 - OAuthリクエストはHTTPSのみで提供されます。
- アクセストークンは5分後に期限切れになります（本番環境では変更される可能性があります）。最良の結果を得るためには、この値に依存せずに、
expires_inで返される動的な値を使用してください。 - リフレッシュトークンは60分後に期限切れになります（本番環境では変更される可能性があります）。
サンプルリクエスト
認証ヘッダーを使用する場合
curl -vX POST https://api.roktcalendar.com/oauth2/token \
```md
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
-d grant_type=client_credentials'
認証ヘッダーなし
curl -vX POST https://api.roktcalendar.com/oauth2/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
-d 'grant_type=client_credentials&client_id=johnsmithmedia&client_secretpassword'
リクエストフィールド
| キー | In | 説明 | 必須? | 例 |
|---|---|---|---|---|
Authorization | header | client_idとclient_secretは、Basic HTTP認証を通じて認証ヘッダーに含める必要があります。これらはアカウントマネージャーから提供されます。ヘッダーの内容はBasic base64encode(client_id:client_secret)です。 | Yes | Basic base64encocde(12345:abcde) |
Content-Type | header | リクエストのメディアタイプは常にapplication/X-www-form-urlencodedである必要があります。 | Yes | application/X-www-form-urlencoded |
grant_type | body | client_credentialsである必要があります。 | Yes | client_credentials |
client_id | body | クライアントID（認証ヘッダーがない場合は必須） | No | username |
client_secret | body | クライアントシークレット（認証ヘッダーがない場合は必須） | No | password |
サンプルレスポンス
{
"access_token": "eyJraWQiOiJPVUpHT1RjM09FWXROakkzUlMwME5UUkJMVGxCTkRrdFJqWXdOVVV3UkRNNE1FTTJDZz09IiwiYWxnIjoiSFMyNTYifQ.eyJzdWIiOiJkZW1vIiwidG9rZW5fdXNlIjoiYWNjZXNzIiwic2NvcGUiOiJyZXBvcnQtYXBpL3JlYWQtcmVwb3J0LWFwaSIsImF1dGhfdGltZSI6MTU4NTExMDA0MSwiaXNzIjoiaHR0cHM6Ly9jb2duaXRvLWlkcC51cy13ZXN0LTIuYW1hem9uYXdzLmNvbS91cy13ZXN0LTJfZG93Tlp1elRYIiwiZXhwIjoxNTg1MTEzNjQxLCJpYXQiOjE1ODUxMTAwNDEsInZlcnNpb24iOjIsImp0aSI6IkYwNzY5RDVDLTRDNTAtNDVDOC04OTcyLTI4MkUwODlDMkFFOSIsImNsaWVudF9pZCI6ImRlbW8ifQ.NOJIx7qLHFVXqKNZfJKsJlwitOvbHOLdknQ\_D33WjYe8O9ZE08t7LFgs7ANiwBicN5ejmdS7iND0cth5ViUWK5MKZxvLKI6dPG5RljegfpZJtGKqDT\_MFfpayvcOlkkZc5yRw9Bcgz\_fW2ha7q6BGRsUb-e9DZ0Pcb5zL\_HbRLbnvlhYCYi9rPmYOYG6BronvLwB8sg2kVubLQGn\_ASbK\_FW8bKPhqH4BL2\_JunGBzUKJPL9yNvOnFy7VKwlvH1OKUqKlCYbewOtUd1utcMNIb\_AbSGRtzJKslbE5VwQtL5bZ34kOCNH07gSolSGvqqw4dyxU4l0QSVXVmqgVYdKfA",
"refresh_token": "eyJraWQiOiJPVUpHT1RjM09FWXROakkzUlMwME5UUkJMVGxCTkRrdFJqWXdOVVV3UkRNNE1FTTJDZz09IiwiYWxnIjoiSFMyNTYifQ.eyJzdWIiOiJkZW1vIiwidG9rZW5fdXNlIjoiYWNjZXNzIiwic2NvcGUiOiJyZXBvcnQtYXBpL3JlYWQtcmVwb3J0LWFwaSIsImF1dGhfdGltZSI6MTU4NTExMDA0MSwiaXNzIjoiaHR0cHM6Ly9jb2duaXRvLWlkcC51cy13ZXN0LTIuYW1hem9uYXdzLmNvbS91cy13ZXN0LTJfZG93Tlp1elRYIiwiZXhwIjoxNTg1MTEzNjQxLCJpYXQiOjE1ODUxMTAwNDEsInZlcnNpb24iOjIsImp0aSI6IkYwNzY5RDVDLTRDNTAtNDVDOC04OTcyLTI4MkUwODlDMkFFOSIsImNsaWVudF9pZCI6ImRlbW8ifQ.NOJIx7qLHFVXqKNZfJKsJlwitOvbHOLdknQ\_D33WjYe8O9ZE08t7LFgs7ANiwBicN5ejmdS7iND0cth5ViUWK5MKZxvLKI6dPG5RljegfpZJtGKqDT\_MFfpayvcOlkkZc5yRw9Bcgz\_fW2ha7q6BGRsUb-e9DZ0Pcb5zL\_HbRLbnvlhYCYi9rPmYOYG6BronvLwB8sg2kVubLQGn\_ASbK\_FW8bKPhqH4BL2\_JunGBzUKJPL9yNvOnFy7VKwlvH1OKUqKlCYbewOtUd1utcMNIb\_AbSGRtzJKslbE5VwQtL5bZ34kOCNH07gSolSGvqqw4dyxU4l0QSVXVmqgVYdKfA",
"expires_in": 3600,
"token_type": "Bearer"
}
APIエンドポイント
DELETE サブスクリプションの無効化
ユーザー名に関連付けられたカレンダーからすべてのサブスクリプションを無効化し、すべてのイベントを削除します。
説明
「サブスクリプションの無効化」API機能は、将来のイベントを受け取らないようにサブスクリプションを無効化します。サブスクリプションが無効化されると、新しいイベントはカレンダーに表示されません。
個々のサブスクリプションまたはユーザー名に属するすべてのサブスクリプションを指定できます。
このAPI機能はOAuthで保護されており、サブスクリプションを作成する際にアクセストークンを含める必要があります。
#### リクエスト
**パス**
```json
DELETE /v1/subscription/{accountCode}/{calendarCode}
パラメータ
| 名前 | タイプ | In | 説明 | 必須 | 例 |
|---|---|---|---|---|---|
accountCode | String | path | Rokt Calendarの商人アカウントコード、またはRokt CalendarダッシュボードのURLのサブドメインです。 | true | |
calendarCode | String | path | Rokt Calendarアカウント内の特定のカレンダーの一意の識別子です。これは、ドメインの直後に表示されるURLスラッグです。 | true | カレンダーのURLがhttp://youraccount.roktcalendar.com/my-calendarの場合、`calendarCode`は`my-calendar`になります。 |
リクエストボディ
{
"userName": "string",
"id": "string",
"unsubscribeReasonId": null,
"unsubscribeReasonText": "string",
"actionType": "string"
}
レスポンス
202 受け付け済み
エラー
400 不正なリクエスト
401 認証されていません
カレンダーサブスクリプションイベントの削除
このエンドポイントを使用して、プログラムでカレンダーサブスクリプションイベントを削除します。
説明
このAPIエンドポイントは、イベントを削除し、このイベントにサブスクライブしているすべてのカレンダーサブスクリプションを更新します。関連するGoogleサブスクリプションは同期されます。
202 Acceptedのレスポンスは、レスポンスが正常に検証され、処理のために受け入れられたことを示しています。
イベントはバックグラウンドプロセスで削除され、変更がサブスクライバーのカレンダーに伝播するまで数分かかる場合があります。
リクエスト
パス
DELETE /v1/subscriptionevent/{accountCode}/{eventId}
パラメータ
| 名前 | タイプ | In | 説明 | 必須 |
|---|---|---|---|---|
accountCode | String | path | Rokt Calendarの商人アカウントコード、またはRokt CalendarダッシュボードのURLのサブドメインです。 | true |
eventId | String | path | イベントの一意の識別子です。 | true |
レスポンス
202 受け付け済み
エラー
400 不正なリクエスト
500 サーバーエラー
サブスクリプションイベントの削除
APIを使用して、サブスクリプションからサブスクリプションイベントをプログラムで削除します。
説明
このAPI関数は、サブスクリプションからサブスクリプションイベントを削除するために使用されます。
リクエスト
パス
DELETE /v2/subscription/{accountCode}/{subscriptionId}/subscriptionevent/{eventId}
パラメータ
| 名前 | タイプ | In | 説明 | 必須 |
|---|---|---|---|---|
accountCode | String | path | Rokt Calendarの商人アカウントコード、またはRokt CalendarダッシュボードのURLのサブドメインです。 | true |
subscriptionId | String | path | サブスクリプションの一意のIDです。 | true |
eventId | String | path | イベントの一意のIDです。 | true |
レスポンス
202 受け付け済み
エラー
400 不正なリクエスト
カレンダーイベントの取得
APIを使用して利用可能なカレンダーイベントをプログラムで取得します。
リクエスト
パス
GET /v1/{accountCode}/calendars/{calendarId}/events
パラメータ
| 名前 | タイプ | In | 説明 | 必須 |
|---|---|---|---|---|
accountCode | String | path | Rokt Calendarの商人アカウントコード、またはRokt CalendarダッシュボードのURLのサブドメインです。 | true |
calendarId | String | path | Rokt Calendarアカウント内の特定のカレンダーの一意の識別子です。 | true |
pageNumber | integer | query | 受け取りたいデータページの番号（1から始まる）です。 | |
pageSize | integer | query | 受け取りたいデータページの結果の数です。0より大きい必要があります。 |
レスポンス
200 OK
{
"result": {
"data": [
{
"id": "string",
"title": "string",
"description": "string",
"location": "string",
"reminderMinutes": null,
"timezoneBclId": "string",
"timezoneIanaId": "string",
"startDateTimeUtc": "2025-10-04T10:00:00.000Z",
"startDateTimeLocal": "2025-10-04T10:00:00.000Z",
"endDateTimeLocal": "2025-10-04T10:00:00.000Z",
"lastUpdateDateTimeUtc": "2025-10-04T10:00:00.000Z",
"calendarTags": [
{
"id": "string",
"text": "string"
}
],
"calendarTimezones": [
{
"bclId": "string",
"ianaId": "string",
"offsetMinutes": null
}
],
"calendarCustomFields": [
{
"name": "string",
"label": "string",
"url": "string",
"imageUrl": "string"
}
]
}
],
"totalResults": null,
"pageNumber": null,
"pageSize": null,
"totalPages": null
},
"errors": [
{
"type": "string",
"message": "string",
"code": "string"
}
],
"success": true
}
エラー
401 認証されていません
404 見つかりません
サブスクリプションスケジュールの取得
APIを使用して、特定の日付範囲内のイベントをサブスクライバーの主なカレンダーにプログラムで取得します。
リクエスト
パス
GET /v1/schedule/{subscriptionId}
パラメータ
| 名前 | タイプ | In | 説明 | 必須 |
|---|---|---|---|---|
subscriptionId | String | path | これはGUIDであり、特定のサブスクリプションの一意の識別子を表します。 | true |
from | String | query | クエリの日付範囲のUTC開始日 | |
to | String | query | クエリの日付範囲のUTC終了日 |
レスポンス
200 OK
{
"title": "string",
"startUtc": "2025-10-04T10:00:00.000Z",
"endUtc": "2025-10-04T10:00:00.000Z",
"isAllDayEvent": true
}
エラー
401 Unauthorized
404 NotFound
サブスクリプションの詳細を取得する
APIを使用して、プログラムでサブスクリプションの詳細を取得します。
リクエスト
パス
GET /v1/subscription/{subscriptionId}
パラメータ
| 名前 | タイプ | In | 説明 | 必須 | 例 |
|---|---|---|---|---|---|
subscriptionId | String | path | これは、Create New subscription API関数から返されたsubscriptionIdです。 | true |
レスポンス
200 OK
{
"subscriptionId": "string",
"calendar": {
"id": "string",
"code": "string",
"name": "string",
"image": "string"
},
"tags": [
{
"id": "string",
"name": "string"
}
],
"timezoneId": "string",
"subscriptionType": "string",
"subscriberId": "string",
"emailAddress": "string",
"marketingAllowed": true,
"providerName": "string",
"channelFinderLineUpId": "string",
"channelFinderZipCode": "string",
"createdAt": "2025-10-04T10:00:00.000Z",
"isActive": true,
"deactivatedDate": "2025-10-04T10:00:00.000Z",
"events": [
{
"id": "string",
"name": "string",
"externalId": "string",
"isExcluded": true
}
],
"eventsVisibleToSubscription": [
{
"title": "string",
"location": "string",
"description": "string",
"subscriptionEventId": "string",
"calendarEventId": "string",
"timezone": "string",
"timezoneIanaId": "string",
"startDateTime": "2025-10-04T10:00:00.000Z",
"startDateTimeUtc": "2025-10-04T10:00:00.000Z",
"endDateTime": "2025-10-04T10:00:00.000Z",
"allDayEvent": true,
"reminderMinutes": null,
"merchantId": "string",
"accountId": "string",
"eventOccurrenceType": 0,
"isSubscriptionEvent": true,
"recurrenceFrequency": null,
"recurrenceUntilDateTime": "2025-10-04T10:00:00.000Z",
"recurrenceUntilCount": null,
"recurrenceInterval": null,
"recurrenceWeeklyDays": null,
"recurrenceMonthlyDayOfWeek": true
}
],
"eventReminderMinutes": null,
"allowPromotionalContent": true,
"additionalOptIn": true,
"isEventReminderDisabled": true
}
エラー
400 BadRequest
POST Update Subscription Event
エンドポイントを使用して、カレンダーサブスクリプションイベントをプログラムで作成し、1つ以上のカレンダーサブスクリプションに追加します。
説明
このAPIエンドポイントは、イベントの詳細を更新し、このイベントにサブスクライブしているすべてのカレンダーサブスクリプションを更新します。関連するサブスクリプションは同期されます。 202 Acceptedの応答は、応答が正常に検証され、処理のために受け入れられたことを示しています。 イベントはバックグラウンドプロセスで更新されており、変更がサブスクライバーのカレンダーに伝播するまで数分かかる場合があります。
リクエスト
パス
POST /v1/subscriptionevent/{accountCode}/update
パラメータ
| 名前 | タイプ | In | 説明 | 必須 |
|---|---|---|---|---|
accountCode | String | path | Rokt Calendarのマーチャントアカウントコード、またはRokt Calendarダッシュボードのサブドメインです。 | true |
リクエストボディ
{
"eventId": "string",
"title": "string",
"description": "string",
"location": "string",
"timezone": "string",
"timezoneIanaId": "string",
"start": "2025-10-04T10:00:00.000Z",
"end": "2025-10-04T10:00:00.000Z",
"allDayEvent": true,
"notifyBefore": null,
"actionType": "string",
"visibleFromDateTimeUtc": "2025-10-03T10:00:00.000Z" // オプション
}
レスポンス
202 Accepted
エラー
400 BadRequest
500 InternalServerError
POST Create New Subscription Event
エンドポイントを使用して、カレンダーサブスクリプションイベントをプログラムで作成し、1つ以上のカレンダーサブスクリプションに追加します。
説明
このAPIエンドポイントは、イベントを作成し、1つ以上のカレンダーサブスクリプションにアタッチします。 202 Acceptedの応答は、応答が正常に検証され、処理のために受け入れられたことを示しています。 イベントはバックグラウンドプロセスで作成されており、変更がサブスクライバーのカレンダーに伝播するまで数分かかる場合があります。
リクエスト
パス
POST /v1/subscriptionevent/{accountCode}
パラメータ
| 名前 | タイプ | In | 説明 | 必須 | 例 |
|---|---|---|---|---|---|
accountCode | String | path | Rokt Calendarのマーチャントアカウントコード、またはRokt Calendarダッシュボードのサブドメイン | true |
リクエストボディ
{
"event": {
"eventId": "string",
"title": "string",
"description": "string",
"location": "string",
"timezone": "string",
"timezoneIanaId": "string",
"start": "2025-10-04T10:00:00.000Z",
"end": "2025-10-04T10:00:00.000Z",
"allDayEvent": true,
"notifyBefore": null,
"actionType": "string",
"visibleFromDateTimeUtc": "2025-10-03T10:00:00.000Z" // オプション
},
"subscriptionIds": [
"string"
],
"actionType": "string"
}
レスポンス
202 Accepted
エラー
{
"subscriptionMethod": 0,
"events": [
{
"eventId": "string",
"title": "string",
"description": "string",
"location": "string",
"timezone": "string",
"timezoneIanaId": "string",
"start": "2025-10-04T10:00:00.000Z",
"end": "2025-10-04T10:00:00.000Z",
"allDayEvent": true,
"notifyBefore": null,
"actionType": "string"
}
],
"actionType": "string"
}
レスポンス
200 OK
{
"redirectUrl": "string",
"authCode": "string",
"tagId": "string",
"calendarTags": [
{
"internalId": "string",
"externalId": "string"
}
],
"timeZoneId": "string",
"marketingAllowed": true,
"additionalOptIn": true,
"allowPromotionalContent": true,
"eventReminderMinutes": null,
"isEventReminderDisabled": true,
"channelFinderZipCode": "string",
"channelFinderLineUpId": "string",
"sourceId": null,
"networkDevice": "string",
"providerName": "string",
"providerLocation": "string",
"stationNum": null,
"stationName": "string",
"utmSource": "string",
"utmMedium": "string",
"utmCampaign": "string",
"utmContent": "string",
"requestEventIds": [
"string"
],
"externalEventIds": [
"string"
],
"clickId": "string",
"urlReferrer": "string",
"userAgent": "string",
"ipAddress": "string",
"redirectTo": "string",
"userName": "string",
"subscriberId": "string",
"emailAddress": "string",
"trackingId": "string",
"sessionId": "string",
"roktSessionId": "string",
"subscriptionMethod": 0,
"events": [
{
"eventId": "string",
"title": "string",
"description": "string",
"location": "string",
"timezone": "string",
"timezoneIanaId": "string",
"start": "2025-10-04T10:00:00.000Z",
"end": "2025-10-04T10:00:00.000Z",
"allDayEvent": true,
"notifyBefore": null,
"actionType": "string"
}
],
"actionType": "string"
}
レスポンス
200 OK
{
"subscriptionId": "string",
"subscriptionUrl": "string",
"username": "string",
"password": "string",
"isNewSubscription": true,
"subscriberId": "string",
"redirectTo": "string",
"subscriptionType": 0,
"success": true,
"statusCode": 100,
"message": "string",
"errors": [
{
"code": "string",
"reason": "string"
}
]
}
エラー
401 Unauthorized
404 NotFound