Aller au contenu principal

API de requête

Aperçu​

L'API de requête Rokt est une API complète et flexible pour interroger les données de compte, les campagnes et les transactions. Consultez notre documentation interactive ici.

Authentification​

L'API de requête Rokt utilise l'approche OAuth 2.0 pour l'intégration client. Voir le flux d'identifiants OAuth 2.0 pour plus de détails. Vous devez utiliser votre Rokt App ID et App Secret pour accéder à l'API de requête.

Génération d'un Rokt App ID et App Secret​

  1. Connectez-vous à One Platform sur my.rokt.com
  2. Accédez à Paramètres du profil sous l'icône de votre compte en bas à gauche
  3. Faites défiler jusqu'à la section Générer des identifiants API personnels
  4. Entrez le nom de votre application et cliquez sur Générer
  5. Stockez l'App ID et l'App Secret de manière sécurisée - vous n'aurez plus accès à l'App Secret

Génération d'un jeton d'accès​

Rokt utilise OAuth 2.0 pour l'authentification sécurisée à nos API publiques. Cela garantit que seuls les utilisateurs autorisés peuvent accéder à leurs données.

Pour générer un jeton d'accès, effectuez la requête POST suivante.

curl -X POST https://api.rokt.com/auth/oauth2/token \
--header "Authorization: Basic $ENCODED_TOKEN" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data "grant_type=client_credentials"

Le jeton d'accès expire après une heure et doit être inclus en tant que jeton Bearer dans toutes les requêtes API.

Exemple étape par étape​

Voici un exemple complet utilisant des commandes shell :

# Étape 1 : Définissez vos variables d'environnement. Ne les stockez pas dans le contrôle de version
export ROKT_APP_ID="your_app_id"
export ROKT_APP_SECRET="your_secret"

# Étape 2 : Encodez vos identifiants pour générer un jeton d'authentification
export ENCODED_TOKEN=$(printf '%s' "${ROKT_APP_ID}:${ROKT_APP_SECRET}" | openssl base64 | tr -d '\n')

# Step 3: Demander un token OAuth2/Bearer en utilisant Basic Auth avec le token encodé
BEARER_TOKEN=$(curl -s -X POST https://api.rokt.com/auth/oauth2/token \
    -H "Authorization: Basic $ENCODED_TOKEN" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=client_credentials" | jq -r '.access_token')

# Étape 4 : Utiliser le token Bearer dans les requêtes de l'API Query
curl -X GET "https://api.rokt.com/v1/query/accounts" \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $BEARER_TOKEN"

Notes Importantes​

  • Utilisez toujours des variables d'environnement pour les identifiants afin d'éviter de les exposer dans les scripts ou le contrôle de version
  • La commande printf avec openssl base64 assure un encodage correct sans caractères de nouvelle ligne
  • Stockez le token d'accès de manière sécurisée car il fournit un accès complet à l'API jusqu'à expiration

Limitation de Taux​

Les requêtes API sont soumises à une limitation de taux pour garantir une utilisation équitable et la stabilité du système.

Gestion des Erreurs​

L'API renvoie des réponses d'erreur standardisées avec des codes d'état HTTP appropriés.

APIs de Compte​

Obtenir les Comptes Utilisateur​

Récupérer tous les comptes associés à l'utilisateur authentifié.

Description​

Ce point de terminaison (endpoint) retourne une liste de tous les comptes auxquels l'utilisateur authentifié a accès. La réponse inclut les détails du compte tels que l'ID du compte, le nom, le pays, la devise, et les informations de fuseau horaire.

Requête​

Chemin​
GET /v1/query/accounts
Authentification​

Nécessite un jeton Bearer valide à partir d'un JWT Rokt de l'utilisateur ou un jeton OAuth2 encodé. Pour plus d'informations sur l'authentification avec notre API, consultez la documentation d'Authentification.

Réponse​

Retourne une liste d'objets de compte avec la structure suivante :

  • accountId: Identifiant unique pour le compte
  • accountName: Nom d'affichage du compte
  • countryCode: Code pays ISO pour le compte
  • accountOwner: Adresse e-mail du propriétaire du compte (optionnel)
  • accountCurrencyCode: Code de la devise pour le compte
  • accountTimezone: Nom du fuseau horaire pour le compte
  • accountTimezoneOffset: Décalage du fuseau horaire en minutes
Réponses d'erreur​
  • 401 Unauthorized: Échec de l'authentification. Jeton invalide.
  • 404 Not Found: L'utilisateur n'a aucun compte
  • 500 Internal Server Error: Erreur du serveur lors de la récupération des comptes
Exemple de réponse​
[
    {
        "accountId": "acc_123456789",
        "accountName": "Example Account 1",
        "countryCode": "US",
        "accountOwner": "user@example.com",
        "accountCurrencyCode": "USD",
        "accountTimezone": "America/New_York",
        "accountTimezoneOffset": -300
    },
    {
        "accountId": "acc_123456790",
        "accountName": "Example Account 2",
        "countryCode": "AU",
        "accountOwner": "user@example.com",
        "accountCurrencyCode": "AUD",
        "accountTimezone": "Australia/Sydney",
        "accountTimezoneOffset": 600
    }
]

Obtenir un compte​

Récupérer des informations détaillées pour un compte spécifique.

Description​

Ce point de terminaison (endpoint) renvoie des informations détaillées sur un compte spécifique identifié par le paramètre account_id. L'utilisateur doit avoir des autorisations d'accès au compte spécifié.

Requête​

Chemin​
GET /v1/query/accounts/{account_id}
Paramètres​
  • accountId (chemin) : L'identifiant unique du compte à récupérer
Authentification​

Nécessite un jeton Bearer valide provenant d'un JWT Rokt de l'utilisateur ou d'un jeton OAuth2 encodé. Pour plus d'informations sur l'authentification avec notre API, consultez la documentation sur l'authentification. L'utilisateur doit avoir des permissions d'accès aux données du compte et de la campagne spécifiés.

Réponse​

Renvoie un objet compte unique avec la structure suivante :

  • accountId : Identifiant unique pour le compte
  • accountName : Nom d'affichage du compte
  • countryCode : Code pays ISO pour le compte
  • accountOwner : Adresse e-mail du propriétaire du compte (optionnel)
  • accountCurrencyCode : Code de devise pour le compte
  • accountTimezone : Nom du fuseau horaire pour le compte
  • accountTimezoneOffset : Décalage du fuseau horaire en minutes
Réponses d'erreur​
  • 401 Unauthorized: Échec de l'authentification. Jeton invalide.
  • 403 Forbidden: L'utilisateur n'a pas accès au compte spécifié
  • 404 Not Found: Le compte avec l'ID spécifié n'existe pas
  • 500 Internal Server Error: Erreur du serveur lors de la récupération du compte
Exemple de réponse​
{
    "accountId": "1234567891011",
    "accountName": "Example Account 1",
    "countryCode": "US",
    "accountOwner": "user@example.com",
    "accountCurrencyCode": "USD",
    "accountTimezone": "America/New_York",
    "accountTimezoneOffset": -300
}

APIs d'annonceur​

Obtenir le rapport de l'annonceur​

Générez un rapport de campagne complet pour le compte spécifié.

Description​

Ce point de terminaison vous permet d'interroger les données de performance des campagnes avec un filtrage flexible, une sélection de métriques et une spécification de plage de dates. La réponse inclut des données de campagne agrégées basées sur vos critères spécifiés.

Requête​

Chemin​
POST /v1/query/accounts/{account_id}/campaigns/
Paramètres​
  • account_id (chemin) : L'identifiant unique du compte pour lequel générer le rapport
Corps de la requête​

Le corps de la requête doit contenir un objet ReportingRequestExternal avec les champs suivants :

ParamètreTypeRequisDescriptionDéfaut
timezoneVariationstringoptionnelFuseau horaire pour les données du rapport"America/New_York"
currencyCodestringoptionnelCode de devise pour les données du rapport"USD"
intervalstringoptionnelIntervalle de temps pour les données du rapport. Options : "day", "week", "month", "year"
startDatestringrequisDate de début pour la période du rapport au format ISO (inclus). Accepte YYYY-MM-DD ou YYYY-MM-DD HH:MM:SS
endDatestringrequisDate de fin pour la période du rapport au format ISO (exclus). Accepte YYYY-MM-DD ou YYYY-MM-DD HH:MM:SS
dimensionFiltersobjectoptionnelFiltres à appliquer à des dimensions spécifiques
metricsarrayrequisListe des métriques à inclure dans le rapport. Utilisez les slugs du point de terminaison get_help
dimensionsarrayoptionnelDimensions pour regrouper les données. Utilisez les slugs du point de terminaison get_help
orderBysarrayoptionnelCritères de tri pour les résultats. Accepte les clés "column" et "direction"
limitintegeroptionnelNombre maximum de résultats à retourner
Exemple de Requête​
{
    "timezoneVariation": "America/New_York",
    "currencyCode": "USD",
    "interval": "day",
    "startDate": "2025-03-04",
    "endDate": "2025-03-05",
    "dimensionFilters": {
        "campaign_id": ["3427232771076128951"]
    },
    "metrics": ["impressions", "referrals", "gross_cost"],
    "dimensions": ["campaign_id", "creative_id", "age_group"],
    "orderBys": [
        {
            "column": "referrals",
            "direction": "desc"
        }
    ]
}
Authentification​

Nécessite soit un jeton JWT Bearer valide, soit un jeton Cognito dans les en-têtes de la requête. Pour plus d'informations sur l'authentification avec notre API, consultez la documentation sur l'authentification. L'utilisateur doit avoir des autorisations d'accès aux données du compte et de la campagne spécifiés.

Réponse​

Renvoie un objet ReportingResponseExternal contenant :

  • data : Tableau des métriques et dimensions de campagne demandées. Si un intervalle est fourni, chaque objet contiendra un champ datetime indiquant le début de l'intervalle fourni.
  • accountId : L'ID du compte pour lequel le rapport a été généré
  • queryTimeMs : Temps d'exécution de la requête en millisecondes
Réponses d'erreur​
  • 400 Bad Request: Paramètres ou filtres de requête invalides
  • 401 Unauthorized: Échec de l'authentification. Jeton invalide.
  • 403 Forbidden: L'utilisateur n'a pas accès au compte spécifié
  • 404 Not Found: La ressource demandée est introuvable. Veuillez vérifier que votre requête est correcte et réessayez.
  • 500 Internal Server Error: Erreur du serveur lors de la génération du rapport
Exemple de réponse​
{
    "data": [
        {
            "datetime": "2025-03-04T00:00:00Z",
            "impressions": 1501.0,
            "referrals": 205.0,
            "gross_cost": 410.05,
            "campaign_id": "3427232771076128951",
            "creative_id": "3427232968644886703",
            "age_group": "26-35"
        },
        {
            "datetime": "2025-03-04T00:00:00Z",
            "impressions": 1220.0,
            "referrals": 180.0,
            "gross_cost": 300.00,
            "campaign_id": "3401676908203081730",
            "creative_id": "3404563830614458492",
            "age_group": "36-45"
        }
    ],
    "accountId": "3286272607917027328",
    "queryTimeMs": 206
    }

Obtenir de l'aide​

Récupérer les métriques et dimensions disponibles pour le reporting de campagne.

Description​

Ce point de terminaison (endpoint) renvoie des métadonnées sur les options de reporting disponibles, y compris quelles métriques et dimensions peuvent être utilisées ensemble, leurs noms d'affichage, et toutes les options de configuration supplémentaires.

Requête​

Chemin​
GET /v1/query/accounts/{account_id}/campaigns/help
Paramètres​
  • account_id (chemin) : L'identifiant unique du compte (utilisé pour la validation d'accès)
Authentification​

Nécessite un jeton Bearer valide provenant d'un JWT Rokt de l'utilisateur ou un jeton OAuth2 encodé. Pour plus d'informations sur l'authentification avec notre API, consultez la documentation Authentification. L'utilisateur doit avoir des permissions d'accès aux données du compte et de la campagne spécifiés.

Réponse​

Renvoie un objet ReportingMetadataExternal contenant :

  • dimensions : Liste des dimensions avec leurs slugs et descriptions
  • metrics : Liste des métriques avec leurs slugs et descriptions
Réponses d'erreur​
  • 401 Unauthorized: Échec de l'authentification. Jeton invalide.
  • 403 Forbidden: L'utilisateur n'a pas accès au compte spécifié
  • 404 Not Found: La ressource demandée est introuvable. Veuillez vérifier que votre demande est correcte et réessayer.
  • 500 Internal Server Error: Erreur du serveur lors de la récupération des métadonnées
Exemple de réponse​
{
  "dimensions": [
      {
          "slug": "age_range",
          "description": "La tranche d'âge de l'utilisateur"
      },
      {
          "slug": "campaign_id",
          "description": "L'ID de la campagne"
      },
      {
          "slug": "creative_id",
          "description": "L'ID de la création"
      },
      {
          "slug": "device",
          "description": "L'appareil de l'utilisateur"
      },
  ],
  "metrics": [
      {
          "slug": "impressions",
          "description": "Le nombre d'impressions publicitaires"
      },
      {
          "slug": "referrals",
          "description": "Le nombre d'engagements positifs avec la publicité"
      },
      {
          "slug": "clickthru_acquisitions",
          "description": "Le nombre d'acquisitions par clic pour la publicité. Une acquisition représente la première conversion suivant un événement d'engagement."
      },
      {
          "slug": "cpa",
          "description": "Le Coût par Acquisition pour la publicité"
      },
      {
          "slug": "gross_cost",
          "description": "Le coût brut (dépense) pour la publicité"
      },
  ]
}

APIs Partenaires​

Obtenir le Rapport Partenaire​

Générez un rapport de transaction complet pour le compte spécifié.

Description​

Ce point de terminaison vous permet d'interroger les données de transaction avec un filtrage flexible, une sélection de métriques et une spécification de plage de dates. La réponse inclut des données de transaction agrégées basées sur vos critères spécifiés.

Requête​

Chemin​
POST /v1/query/accounts/{account_id}/transactions
Paramètres​
  • account_id (chemin) : L'identifiant unique du compte pour lequel générer le rapport
Corps de la Requête​

Le corps de la requête doit contenir un objet ReportingRequestExternal avec les champs suivants :

ParamètreTypeRequisDescriptionDéfaut
timezoneVariationstringoptionnelFuseau horaire pour les données du rapport"America/New_York"
currencyCodestringoptionnelCode de devise pour les données du rapport"USD"
intervalstringoptionnelIntervalle de temps pour les données du rapport. Options : "day", "week", "month", "year"
startDatestringrequisDate de début pour la période du rapport au format ISO (inclusif). Accepte YYYY-MM-DD ou YYYY-MM-DD HH:MM:SS
endDatestringrequisDate de fin pour la période du rapport au format ISO (exclusif). Accepte YYYY-MM-DD ou YYYY-MM-DD HH:MM:SS
dimensionFiltersobjectoptionnelFiltres à appliquer à des dimensions spécifiques
metricsarrayrequisListe des métriques à inclure dans le rapport. Utilisez les slugs du point de terminaison get_help
dimensionsarrayoptionnelDimensions pour regrouper les données. Utilisez les slugs du point de terminaison get_help
orderBysarrayoptionnelCritères de tri pour les résultats. Accepte les clés "column" et "direction"
limitintegerfacultatifNombre maximum de résultats à retourner
Exemple de Requête​
{
    "timezoneVariation": "America/New_York",
    "currencyCode": "USD",
    "interval": "day",
    "startDate": "2025-03-04",
    "endDate": "2025-03-05",
    "dimensionFilters": {
        "page_type": ["confirmation"]
    },
    "metrics": ["impressions", "referrals", "total_page_transactions"],
    "dimensions": ["display_type", "page_type", "age_range"],
    "orderBys": [
        {
            "column": "referrals",
            "direction": "desc"
        }
    ]
}
Authentification​

Nécessite soit un jeton JWT Bearer valide, soit un jeton Cognito dans les en-têtes de la requête. Pour plus d'informations sur l'authentification avec notre API, consultez la Authentification documentation. L'utilisateur doit avoir les autorisations d'accès au compte et aux données de transaction spécifiés.

Réponse​

Renvoie un objet ReportingResponseExternal contenant :

  • data : Tableau des métriques et dimensions de transaction demandées. Si un intervalle est fourni, chaque objet contiendra un champ datetime indiquant le début de l'intervalle fourni.
  • accountId : L'ID du compte pour lequel le rapport a été généré
  • queryTimeMs : Temps d'exécution de la requête en millisecondes
Réponses d'erreur​
  • 400 Bad Request : Paramètres de requête ou filtres invalides
  • 401 Unauthorized : Échec de l'authentification. Jeton invalide.
  • 403 Forbidden : L'utilisateur n'a pas accès au compte spécifié
  • 404 Not Found : La ressource demandée n'a pas été trouvée. Veuillez valider que votre requête est correcte et réessayez.
  • 500 Internal Server Error : Erreur du serveur lors de la génération du rapport
Exemple de réponse​
{
    "data": [
        {
            "datetime": "2025-03-04T00:00:00Z",
            "impressions": 1501.0,
            "referrals": 205.0,
            "total_page_transactions": 1600.0,
            "display_type": "desktop",
            "page_type": "confirmation",
            "age_range": "26-35"
        },
        {
            "datetime": "2025-03-04T00:00:00Z",
            "impressions": 1220.0,
            "referrals": 180.0,
            "total_page_transactions": 1400.0,
            "display_type": "mobile",
            "page_type": "confirmation",
            "age_range": "36-45"
        }
    ],
    "accountId": "3286272607917027328",
    "queryTimeMs": 206
    }

Obtenir de l'aide​

Récupérer les métriques et dimensions disponibles pour le reporting des transactions.

Description​

Ce point de terminaison (endpoint) renvoie des métadonnées sur les options de reporting disponibles, y compris quelles métriques et dimensions peuvent être utilisées ensemble, leurs noms d'affichage, et toutes options de configuration supplémentaires.

Requête​

Chemin​
GET /v1/query/accounts/{account_id}/transactions/help
Paramètres​
  • account_id (chemin) : L'identifiant unique du compte (utilisé pour la validation d'accès)
Authentification​

Nécessite un jeton Bearer valide à partir d'un JWT Rokt d'un utilisateur ou d'un jeton OAuth2 encodé. Pour plus d'informations sur l'authentification avec notre API, voir la documentation Authentification. L'utilisateur doit avoir des permissions d'accès au compte spécifié et aux données de transaction.

Réponse​

Renvoie un objet ReportingMetadataExternal contenant :

  • dimensions : Liste des dimensions avec leurs slugs et définitions
  • metrics : Liste des métriques avec leurs slugs et définitions
Réponses d'erreur​
  • 401 Unauthorized: Échec de l'authentification. Jeton invalide.
  • 403 Forbidden: L'utilisateur n'a pas accès au compte spécifié
  • 404 Not Found: La ressource demandée est introuvable. Veuillez vérifier que votre demande est correcte et réessayez.
  • 500 Internal Server Error: Erreur du serveur lors de la récupération des métadonnées
Exemple de réponse​
{
    "dimensions": [
        {
            "slug": "age_range",
            "description": "La tranche d'âge de l'utilisateur"
        },
        {
            "slug": "display_type",
            "description": "Le type d'affichage sur lequel l'annonce a été montrée"
        },
        {
            "slug": "page_type",
            "description": "Le type de page sur laquelle l'utilisateur se trouvait"
        },
        {
            "slug": "device",
            "description": "L'appareil de l'utilisateur"
        },
    ],
    "metrics": [
        {
            "slug": "transactions",
            "description": "Nombre total de transactions"
        },
        {
            "slug": "rokt_transactions_per_transaction",
            "description": "Nombre total de transactions traitées par Rokt par transaction"
        },
        {
            "slug": "impressions",
            "description": "Nombre total d'impressions publicitaires"
        },
        {
            "slug": "page_transactions",
            "description": "Nombre total de transactions traitées par page"
        },
        {
            "slug": "layout_impressions",
            "description": "Nombre total d'impressions publicitaires traitées par mise en page"
        },
    ]
}
Cet article vous a-t-il été utile ?
Last updated Oct 29, 2025