Last updated 24 oct. 2023

API de calendrier

Aperçu

L'API de calendrier Rokt est organisée autour de REST. Notre API utilise des URL prévisibles et orientées ressources, et utilise des codes de réponse HTTP pour indiquer les erreurs de l'API. Nous utilisons des fonctionnalités HTTP intégrées, telles que l'authentification HTTP et les verbes HTTP, qui sont compris par les clients HTTP prêts à l'emploi. Nous prenons en charge le partage de ressources entre origines, ce qui vous permet d'interagir en toute sécurité avec notre API à partir d'une application web côté client (bien que vous ne devriez jamais exposer votre clé d'API secrète dans le code côté client d'un site web public). JSON est renvoyé par toutes les réponses de l'API, y compris les erreurs.

Authentification

Le calendrier Rokt utilise le protocole OAuth 2.0 pour permettre aux sites web ou aux applications de demander une autorisation d'accès aux calendriers protégés sans avoir besoin du nom d'utilisateur et du mot de passe du compte.

Enregistrement de l'API

Pour vous authentifier à l'aide d'OAuth, vous devez être un application OAuth enregistrée. Votre application se verra attribuer un client_id et un client_secret uniques. Ces détails seront nécessaires pour que votre application s'authentifie lors de la demande d'un jeton d'accès.

L'API est disponible sur demande. Veuillez contacter votre gestionnaire de compte pour demander l'accès. Vous recevrez ensuite un client_id et un client_secret uniques.

Accédez à :

Détails OAuth

Rokt Calendar OAuth prend en charge le type de subvention client_credentials.
Les demandes OAuth ne sont servies que via HTTPS.
Les jetons d'accès expirent après cinq minutes (sous réserve de modifications dans l'environnement de production). Pour de meilleurs résultats, ne vous fiez pas à cette durée. Utilisez plutôt la valeur dynamique renvoyée dans expires_in.
Les jetons de rafraîchissement expirent après 60 minutes (sous réserve de modifications dans l'environnement de production).

Exemple de demande

Avec en-tête d'autorisation

curl -vX POST https://api.roktcalendar.com/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Accept: application/json' \
  --header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
  -d grant_type=client_credentials'

Sans en-tête d'autorisation

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'

Champs de la requête

Clé	Emplacement	Description	Obligatoire?	Exemple
`Authorization`	en-tête	`client_id` et `client_secret` doivent être inclus dans l'en-tête d'autorisation via l'autorisation HTTP de base et seront fournis par votre gestionnaire de compte ; le contenu de l'en-tête est `Basic base64encode(client_id:client_secret)`	Oui	Basic base64encocde(12345:abcde)
`Content-Type`	en-tête	Le type de média de la requête doit toujours être `application/X-www-form-urlencoded`	Oui	application/X-www-form-urlencoded
`grant_type`	corps	Doit être `client_credentials`	Oui	client_credentials
`client_id`	corps	Votre ID client (obligatoire si aucun en-tête d'autorisation)	Non	username
`client_secret`	corps	Votre secret client (obligatoire si aucun en-tête d'autorisation)	Non	password

Exemple de réponse

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

Points de terminaison de l'API

DELETE Désactiver les abonnements

Désactive tous les abonnements et supprime tous les événements des calendriers associés à un nom d'utilisateur.

Description

La fonction API "Désactiver l'abonnement" désactive un abonnement pour qu'il ne reçoive aucun événement à l'avenir. Une fois qu'un abonnement a été désactivé, les nouveaux événements publiés n'apparaîtront pas dans leur calendrier.

Vous pouvez spécifier soit un abonnement individuel, soit tous les abonnements appartenant à un nom d'utilisateur pour un calendrier.

Cette fonction API est protégée par OAuth et doit inclure un jeton d'accès de la même manière qu'il est nécessaire de créer un abonnement.

Demande

Chemin

DELETE /v1/subscription/{accountCode}/{calendarCode}

Paramètres

Nom	Type	Emplacement	Description	Requis	Exemple
`accountCode`	String	chemin	Le code du compte marchand Rokt Calendar, ou le sous-domaine de votre URL du tableau de bord Rokt Calendar.	true
`calendarCode`	String	chemin	Il s'agit d'un identifiant unique d'un calendrier spécifique dans votre compte Rokt Calendar. Il s'agit de l'URL slug qui apparaît directement après le domaine.	true	si votre URL de calendrier est https://youraccount.roktcalendar.com/my-calendar, alors le `calendarCode` sera `my-calendar`.

Corps de la demande

{
  "userName": "string",
  "id": "string",
  "unsubscribeReasonId": null,
  "unsubscribeReasonText": "string",
  "actionType": "string"
}

Réponse

202 Accepté

Erreur

400 Mauvaise requête

401 Non autorisé

SUPPRIMER un événement d'abonnement au calendrier

Utilisez ce point de terminaison pour supprimer programmation un événement d'abonnement au calendrier.

Description

Ce point de terminaison de l'API supprimera un événement et mettra à jour tous les abonnements au calendrier qui sont abonnés à cet événement. Les abonnements Google associés seront synchronisés. La réponse 202 Accepté indique que la réponse a été validée avec succès et a été acceptée pour traitement. Les événements sont supprimés dans un processus en arrière-plan et il peut prendre quelques minutes pour que les modifications se propagent aux calendriers des abonnés.

Demande

Chemin

DELETE /v1/subscriptionevent/{accountCode}/{eventId}

Paramètres

Nom	Type	Dans	Description	Requis
`accountCode`	String	chemin	Le code du compte marchand Rokt Calendar, ou le sous-domaine de votre URL du tableau de bord Rokt Calendar.	true
`eventId`	String	chemin	Un identifiant unique pour l'événement.	true

Réponse

202 Accepté

Erreur

400 Mauvaise requête

500 Erreur interne du serveur

SUPPRIMER un événement d'abonnement

Utilisez l'API pour supprimer de manière programmée un événement d'abonnement d'un abonnement.

Description

Cette fonctionnalité de l'API est utilisée pour supprimer un événement d'abonnement d'un abonnement.

Requête

Chemin

SUPPRIMER /v2/subscription/{accountCode}/{subscriptionId}/subscriptionevent/{eventId}

Paramètres

Nom	Type	Emplacement	Description	Requis
`accountCode`	String	chemin	Le code de compte marchand Rokt Calendar, ou le sous-domaine de l'URL du tableau de bord Rokt Calendar.	vrai
`subscriptionId`	String	chemin	L'ID unique de l'abonnement.	vrai
`eventId`	String	chemin	L'ID unique de l'événement.	vrai

Réponse

202 Accepté

Erreur

400 Mauvaise requête

GET Événements du calendrier

Utilisez l'API pour récupérer de manière programmatique les événements du calendrier disponibles

Requête

Chemin

GET /v1/{accountCode}/calendars/{calendarId}/events

Paramètres

Nom	Type	Emplacement	Description	Obligatoire
`accountCode`	String	chemin	Le code du compte marchand Rokt Calendar, ou le sous-domaine de l'URL de votre tableau de bord Rokt Calendar.	vrai
`calendarId`	String	chemin	Il s'agit d'un identifiant unique d'un calendrier spécifique dans votre compte Rokt Calendar.	vrai
`pageNumber`	integer	requête	Le numéro de la page de données que vous souhaitez recevoir, en commençant par 1.
`pageSize`	integer	requête	Nombre de résultats dans une page de données que vous souhaitez recevoir. Doit être supérieur à 0.

Réponse

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
}

Erreur

401 Non autorisé

404 Introuvable

GET Planification de l'abonnement

Utilisez l'API pour obtenir de manière programmée les événements pour une plage de dates spécifique qui se trouvent dans le calendrier principal de l'abonné.

Requête

Chemin

GET /v1/planification/{subscriptionId}

Paramètres

Nom	Type	Emplacement	Description	Requis
`subscriptionId`	String	chemin	Il s'agit d'un GUID et représente l'identifiant unique d'un abonnement spécifique.	vrai
`from`	String	requête	La date de début UTC de la plage de dates de la requête
`to`	String	requête	La date de fin UTC de la plage de dates de la requête

Réponse

200 OK

{
  "title": "string",
  "startUtc": "2025-10-04T10:00:00.000Z",
  "endUtc": "2025-10-04T10:00:00.000Z",
  "isAllDayEvent": true
}

Erreur

401 Non autorisé

404 Non trouvé

Obtenir les détails de l'abonnement

Utilisez l'API pour obtenir les détails de l'abonnement de manière programmée.

Requête

Chemin

GET /v1/subscription/{subscriptionId}

Paramètres

Nom	Type	Dans	Description	Requis	Exemple
`subscriptionId`	String	chemin	Il s'agit de l'ID d'abonnement renvoyé par la fonction API Create New subscription.	true

Réponse

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
}

Erreur

400 BadRequest

POST Mettre à jour l'événement d'abonnement

Utilisez ce point de terminaison pour créer de manière programmée un événement d'abonnement au calendrier et l'ajouter à un ou plusieurs abonnements au calendrier.

Description

Ce point de terminaison API mettra à jour les détails de l'événement et mettra à jour tous les abonnements au calendrier qui sont abonnés à cet événement. Les abonnements associés seront synchronisés. La réponse 202 Accepted indique que la réponse a été validée avec succès et a été acceptée pour traitement. Les événements sont mis à jour dans un processus en arrière-plan, il peut prendre quelques minutes pour que les modifications se propagent aux calendriers des abonnés.

Demande

Chemin

POST /v1/subscriptionevent/{accountCode}/update

Paramètres

Nom	Type	Dans	Description	Requis
`accountCode`	String	chemin	Le code du compte marchand Rokt Calendar, ou le sous-domaine de l'URL de votre tableau de bord Rokt Calendar.	vrai

Corps de la demande

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

Réponse

202 Accepté

Erreur

400 Mauvaise requête

500 Erreur interne du serveur

POST Créer un nouvel événement d'abonnement

Utilisez ce point de terminaison pour créer de manière programmée un événement d'abonnement au calendrier et l'ajouter à un ou plusieurs abonnements au calendrier.

Description

Ce point de terminaison de l'API créera un événement et le liera à un ou plusieurs abonnements au calendrier. La réponse 202 Accepté indique que la réponse a été validée avec succès et a été acceptée pour traitement. Les événements sont créés dans un processus en arrière-plan, il peut prendre quelques minutes pour que les modifications se propagent aux calendriers des abonnés.

Demande

Chemin

POST /v1/subscriptionevent/{accountCode}

Paramètres

Nom	Type	Dans	Description	Requis	Exemple
`accountCode`	String	path	Le code du compte marchand Rokt Calendar, ou le sous-domaine de l'URL de votre tableau de bord Rokt Calendar	true

Corps de la demande

{
  "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" // facultatif
  },
  "subscriptionIds": [
    "string"
  ],
  "actionType": "string"
}

Réponse

202 Accepté

Erreur

400 Mauvaise requête

500 Erreur interne du serveur

POST Créer une nouvelle souscription

Utilisez l'API pour créer de manière programmatique une souscription à un calendrier pour Webcal et Google.

Requête

Chemin

POST /v2/subscribe/{accountCode}/{calendarCode}

Paramètres

Nom	Type	Emplacement	Description	Requis
`accountCode`	String	chemin	Le code du compte marchand Rokt Calendar, ou le sous-domaine de votre URL de tableau de bord Rokt Calendar.	vrai
`calendarCode`	String	chemin	Il s'agit d'un identifiant unique d'un calendrier spécifique dans votre compte Rokt Calendar.	vrai

Corps de la requête

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

Réponse

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

Erreur

401 Non autorisé

404 Non trouvé

Aperçu​

Authentification​

Enregistrement de l'API​

Détails OAuth​

Exemple de demande​

Avec en-tête d'autorisation​

Sans en-tête d'autorisation​

Champs de la requête​

Exemple de réponse​

Points de terminaison de l'API​

DELETE Désactiver les abonnements​

Description​

Demande​

Réponse​

Erreur​

SUPPRIMER un événement d'abonnement au calendrier​

Description​

Demande​

Réponse​

Erreur​

SUPPRIMER un événement d'abonnement​

Description​

Requête​

Réponse​

Erreur​

GET Événements du calendrier​

Requête​

Réponse​

Erreur​

GET Planification de l'abonnement​

Requête​

Réponse​

Erreur​

Obtenir les détails de l'abonnement​

Requête​

Réponse​

Erreur​

POST Mettre à jour l'événement d'abonnement​

Description​

Demande​

Réponse​

Erreur​

POST Créer un nouvel événement d'abonnement​

Description​

Demande​

Réponse​

Erreur​

POST Créer une nouvelle souscription​

Requête​

Réponse​

Erreur​

Aperçu

Authentification

Enregistrement de l'API

Détails OAuth

Exemple de demande

Avec en-tête d'autorisation

Sans en-tête d'autorisation

Champs de la requête

Exemple de réponse

Points de terminaison de l'API

DELETE Désactiver les abonnements

Description

Demande

Réponse

Erreur

SUPPRIMER un événement d'abonnement au calendrier

Description

Demande

Réponse

Erreur

SUPPRIMER un événement d'abonnement

Description

Requête

Réponse

Erreur

GET Événements du calendrier

Requête

Réponse

Erreur

GET Planification de l'abonnement

Requête

Réponse

Erreur

Obtenir les détails de l'abonnement

Requête

Réponse

Erreur

POST Mettre à jour l'événement d'abonnement

Description

Demande

Réponse

Erreur

POST Créer un nouvel événement d'abonnement

Description

Demande

Réponse

Erreur

POST Créer une nouvelle souscription

Requête

Réponse

Erreur