Configuration et utilisation de l’API REST v1

Andrew Munro

Écrit par Andrew Munro
Mis à jour le

Comment configurer et utiliser l’API REST v1

AffiliateWP dispose d’une série de points d’accès REST en lecture seule qui s’appuient sur l’infrastructure incluse avec WordPress 4.4 et versions ultérieures.

Dans cet article, nous vous montrerons comment configurer et utiliser l’API REST v1 pour accéder aux données AffiliateWP.

API REST – Authentification

Afin d’exploiter les points d’accès REST principaux, tous les consommateurs d’API doivent s’authentifier à l’aide de clés d’API générées à partir d’un nouvel onglet Clés d’API situé dans Affiliés → Outils → Clés d’API.

L’API REST utilise l’authentification de base avec une combinaison d’une clé publique et d’un jeton.

Avant de pouvoir authentifier une requête d’API, vous avez besoin d’un ensemble de clés d’API. Celles-ci sont spécifiques à l’utilisateur et peuvent être créées dans Affiliés → Outils → Clés d’API :

Pour générer un nouvel ensemble de clés d’API, saisissez le nom d’utilisateur auquel les clés doivent appartenir et cliquez sur Générer de nouvelles clés d’API.

Remarque : Le compte utilisateur auquel les clés d’API sont associées doit avoir les autorisations appropriées pour que l’API fonctionne. Généralement, cela signifie que l’utilisateur doit avoir le rôle d’Administrateur. Consultez notre documentation sur les rôles et autorisations pour plus d’informations.

Une fois les clés d’API créées, vous pouvez vous authentifier auprès de l’API REST en incluant les clés dans l’en-tête d’authentification. La clé publique doit être transmise en tant qu’utilisateur et le jeton en tant que mot de passe.

Par exemple, en utilisant Postman, notre requête authentifiée ressemblerait à ceci :

Si vous utilisez curl, une requête authentifiée ressemblerait à ceci :

curl -u 229c1d4292800a4fdaa1099a4c646c9a:c7fd218923e058e1637698e5257855de http://local.wp/woo/wp-json/affwp/v1/affiliates

L’en-tête d’autorisation doit être inclus avec chaque requête d’API afin de s’authentifier correctement auprès de l’API. Si l’authentification de base n’est pas fournie ou si les informations d’identification sont incorrectes, un message d’erreur sera renvoyé : 

{
  "code": "rest_forbidden",
  "message": "Sorry, you are not allowed to do that.",
  "data": {
    "status": 403
  }
}

Routes et points d’accès

AffiliateWP propose cinq routes et plusieurs points d’accès sous-jacents. Ces cinq routes sont :

  1. Affiliés
  2. Créations
  3. Paiements
  4. Parrainages
  5. Visites

Cliquez sur les noms des routes ci-dessus pour en savoir plus sur leurs points d’accès respectifs, voir des exemples de requêtes, et plus encore.

Remarque : les opérations complètes de création, lecture, mise à jour et suppression (CRUD) peuvent être activées via le module complémentaire REST API Extended. Consultez la documentation REST API Extended pour plus d’informations sur les opérations de création, de mise à jour et de suppression.

1. Points d’accès des affiliés

Le cœur d’AffiliateWP 1.9+ propose deux points d’accès REST en lecture seule pour les affiliés :

  1. affiliates – Récupère les objets de réponse pour tous les affiliés sur le site actuel
  2. affiliates/{ID} – Récupère un objet de réponse pour un affilié avec l’ID d’affilié donné

Les points d’accès des affiliés peuvent être accédés via des requêtes GET aux emplacements suivants :

http://example.com/wp-json/affwp/v1/affiliates
http://example.com/wp-json/affwp/v1/affiliates/ID

Tous les points d’accès des affiliés et leurs différentes options sont également découvrables en visitant directement l’espace de noms REST AffiliateWP :

http://example.com/wp-json/affwp/v1/
Points d’accès

Le point de terminaison affiliates accepte tous les arguments valides de get_affiliates():

  • number – Le nombre de résultats à récupérer (si disponible)
  • offset – Le nombre de résultats à décaler dans la requête. La valeur par défaut est 0 (aucun décalage)
  • affiliate_id – L’ID d’affilié ou un tableau d’ID à interroger.
  • user_id – L’ID utilisateur ou un tableau d’ID pour interroger les paiements.
  • exclude – L’ID d’affilié ou un tableau d’ID à exclure de la requête.
  • search – Termes de recherche pour les affiliés. Accepte un ID d’affilié ou une chaîne de caractères.
  • status – Le statut de l’affilié. Accepte ‘active’, ‘inactive’, ‘pending’, ou ‘rejected’.
  • order – Comment trier les résultats. Accepte ‘ASC’ (ascendant) ou ‘DESC’ (descendant).
  • orderby – Le champ selon lequel trier les résultats de la réponse. La valeur par défaut est ‘date’
  • fields – Champs spécifiques à retourner pour chaque affilié dans la réponse. La valeur par défaut est ‘*’ (tous). Accepte ‘ids’ ou toute colonne valide

Arguments supplémentaires :

  • user – Si user est passé comme true, des objets utilisateur personnalisés seront récupérés à la volée pour chaque affilié dans la réponse. Il faut être prudent lors de l’utilisation de cette option en raison de l’augmentation 1:1 des requêtes de base de données associées à chaque affilié
  • meta – Si passé comme true, un tableau de métadonnées d’affilié sera récupéré à la volée pour chaque affilié dans la réponse. Tout comme avec user, il faut être prudent en raison de l’impact réduit sur les performances.

Tous les arguments valides peuvent également être obtenus en envoyant une requête OPTIONS à l’un ou l’autre des points de terminaison.

Le point de terminaison affiliates/{ID} accepte tout ID d’affilié valide. De plus, si user et/ou meta sont passés comme true, un objet utilisateur personnalisé et/ou un tableau de métadonnées d’affilié seront respectivement récupérés à la volée pour être inclus dans la réponse.

Visibilité

Tous les points de terminaison nécessitent la clé API et le jeton, à l’exception du point de terminaison principal affwp/v1.

Réponse

Les réponses sont retournées au format JSON.

Exemple de réponse affiliates :

[
  {
    "affiliate_id": 2736,
    "user_id": 1336,
    "rate": "",
    "rate_type": "",
    "payment_email": "",
    "status": "active",
    "earnings": 6,
    "unpaid_earnings": 0,
    "referrals": 6,
    "visits": 0,
    "date_registered": "2016-08-17 19:46:25",
    "id": 2736
  },
  {
    "affiliate_id": 2737,
    "user_id": 1337,
    "rate": "",
    "rate_type": "",
    "payment_email": "",
    "status": "inactive",
    "earnings": 1,
    "unpaid_earnings": 3145.59,
    "referrals": 1,
    "visits": 0,
    "date_registered": "2016-08-17 19:46:25",
    "id": 2737
  }
]

Exemple de réponse affiliates/{ID} :

{
  "affiliate_id": 2737,
  "user_id": 1337,
  "rate": "",
  "rate_type": "",
  "payment_email": "",
  "status": "inactive",
  "earnings": 1,
  "unpaid_earnings": 3145.59,
  "referrals": 1,
  "visits": 0,
  "date_registered": "2016-08-17 19:46:25"
}

Exemple de réponse affiliates{ID}?user=1 :

{
  "affiliate_id": 2737,
  "user_id": 1337,
  "rate": "",
  "rate_type": "",
  "payment_email": "",
  "status": "inactive",
  "earnings": 1,
  "unpaid_earnings": 3145.59,
  "referrals": 1,
  "visits": 0,
  "date_registered": "2016-08-17 19:46:25",
  "user": {
    "ID": "1337",
    "user_login": "user_1_11",
    "user_nicename": "user_1_11",
    "user_url": "",
    "user_registered": "2016-08-17 19:46:25",
    "user_status": "0",
    "display_name": "User 11",
    "spam": "0",
    "deleted": "0",
    "first_name": "",
    "last_name": ""
  }
}

Exemple de réponse affiliates{ID}?meta=1 :

{
  "affiliate_id": 2737,
  "user_id": 1337,
  "rate": "",
  "rate_type": "",
  "payment_email": "[email protected]",
  "status": "active",
  "earnings": 32039.07,
  "unpaid_earnings": 3145.59,
  "referrals": 3192,
  "visits": 0,
  "date_registered": "2016-08-17 19:46:25",
  "meta": {
    "some_key": [
      "some_value"
    ]
  },
  "id": 2737
}<br>

.

2. Points de terminaison des créations

AffiliateWP core 1.9+ offre deux points de terminaison REST en lecture seule pour les créations :

  1. creatives – Récupère les objets de réponse pour toutes les créations sur le site actuel
  2. creatives/{ID} – Récupère un objet de réponse pour une création avec l’ID de création donné

Les points de terminaison des créations sont accessibles via des requêtes GET aux emplacements suivants :

http://example.com/wp-json/affwp/v1/creatives
http://example.com/wp-json/affwp/v1/creatives/ID

Tous les points de terminaison créatifs et leurs diverses options sont également découvrables en visitant directement l'espace de noms REST AffiliateWP :

http://example.com/wp-json/affwp/v1/
Points d’accès

Le point de terminaison creatives accepte tous les arguments valides de get_creatives() :

  • number – Le nombre de résultats à récupérer (si disponible)
  • offset – Le nombre de résultats à décaler dans la requête. La valeur par défaut est 0 (aucun décalage)
  • creative_id – L'ID du créatif ou le tableau d'ID à interroger.
  • status – Le statut du créatif. Accepte 'active' ou 'inactive'.
  • order – Comment trier les résultats. Accepte ‘ASC’ (ascendant) ou ‘DESC’ (descendant).
  • orderby – Colonne de la table des créatifs par laquelle trier.
  • fields – Champs spécifiques à retourner pour chaque créatif dans la réponse. Par défaut '*' (tous). Accepte 'ids' ou toute colonne valide.

Tous les arguments valides peuvent également être obtenus en envoyant une requête OPTIONS à l’un ou l’autre des points de terminaison.

Le point de terminaison creatives/{ID} accepte tout ID de créatif valide.

Visibilité

Tous les points de terminaison nécessitent la clé API et le jeton, à l'exception du point de terminaison principal affwp/v1.

Réponse

Les réponses sont retournées au format JSON.

Exemple de réponse creatives :

  {
    "creative_id": 2,
    "name": "My Other Creative",
    "description": "",
    "url": "http://affiliate.dev",
    "text": "AffiliateWP Plugin Testing",
    "image": "",
    "status": "inactive",
    "date": "2016-05-11 23:35:58",
    "id": 2
  },
  {
    "creative_id": 3,
    "name": "Special Case",
    "description": "",
    "url": "http://affiliate.dev",
    "text": "AffiliateWP Plugin Testing",
    "image": "https://affwp.dev/wp-content/images/brand-assets/affiliatewp-1v.png",
    "status": "active",
    "date": "2016-05-11 23:43:02",
    "id": 3
  },

Exemple de réponse creatives/{ID} :

{
  "creative_id": 2,
  "name": "My Other Creative",
  "description": "",
  "url": "http://affiliate.dev",
  "text": "AffiliateWP Plugin Testing",
  "image": "",
  "status": "inactive",
  "date": "2016-05-11 23:35:58",
  "id": 2
}

.

3. Points de terminaison des paiements

AffiliateWP core 1.9+ offre deux points de terminaison REST en lecture seule pour les paiements :

  1. payouts – Récupère les objets de réponse pour tous les paiements sur le site actuel
  2. payouts/{ID} – Récupère un objet de réponse pour un paiement avec l'ID de paiement donné

Les points de terminaison de paiement sont accessibles via des requêtes GET aux emplacements suivants :

http://example.com/wp-json/affwp/v1/payouts
http://example.com/wp-json/affwp/v1/payouts/ID

Tous les points de terminaison de paiement et leurs diverses options sont également découvrables en visitant directement l'espace de noms REST AffiliateWP :

http://example.com/wp-json/affwp/v1/
Points d’accès

Le point de terminaison payouts accepte tous les arguments valides de get_payouts() :

  • number – Le nombre de résultats à récupérer (si disponible)
  • offset – Le nombre de résultats à décaler dans la requête. La valeur par défaut est 0 (aucun décalage)
  • payout_id – L'ID du paiement ou le tableau d'ID à interroger.
  • affiliate_id – L'ID de l'affilié ou le tableau d'ID pour interroger les paiements.
  • referrals – L'ID de référence ou le tableau d'ID de référence pour récupérer les paiements.
  • amount – Le montant du paiement (float) ou la plage min/max (tableau) pour récupérer les paiements.
  • amount_compare – Opérateur de comparaison utilisé avec amount. Accepte '>', '<', '>=', '<=', '=', ou '!='.
  • status – Le statut du paiement. Accepte 'paid' ou 'failed'.
  • date – Le tableau ou la chaîne de date pour interroger les paiements dans un intervalle.
  • order – Comment trier les résultats. Accepte ‘ASC’ (ascendant) ou ‘DESC’ (descendant).
  • orderby – Le champ selon lequel trier les résultats de la réponse. La valeur par défaut est ‘date’
  • fields – Champs spécifiques à retourner pour chaque paiement dans la réponse. Par défaut '*' (tous). Accepte 'ids' ou toute colonne valide.

Tous les arguments valides peuvent également être obtenus en envoyant une requête OPTIONS à l’un ou l’autre des points de terminaison.

Le point de terminaison payouts/{ID} accepte tout ID de paiement valide.

Visibilité

Tous les points de terminaison nécessitent la clé API et le jeton, à l'exception du point de terminaison principal affwp/v1.

Réponse

Les réponses sont retournées au format JSON.

Exemple de réponse payouts :

[
  {
    "payout_id": 1,
    "affiliate_id": 22,
    "referrals": "2,3",
    "amount": 1,
    "payout_method": "manual",
    "status": "paid",
    "date": "2016-08-04 16:54:21",
    "owner": 0,
    "id": 1
  },
  {
    "payout_id": 2,
    "affiliate_id": 22,
    "referrals": "2,3",
    "amount": 1,
    "payout_method": "manual",
    "status": "paid",
    "date": "2016-08-04 16:54:24",
    "owner": 0,
    "id": 2
  },

Exemple de réponse payouts/{ID} :

{
  "payout_id": 2,
  "affiliate_id": 22,
  "referrals": "2,3",
  "amount": 1,
  "payout_method": "manual",
  "status": "paid",
  "date": "2016-08-04 16:54:24",
  "owner": 0,
  "id": 2
}<br>

.

4. Points de terminaison des références

AffiliateWP core 1.9+ offre deux points de terminaison REST en lecture seule pour les références :

  1. referrals – Récupère les objets de réponse pour tous les parrainages sur le site actuel
  2. referrals/{ID} – Récupère un objet de réponse pour un parrainage avec l'ID de parrainage donné

Les points de terminaison de parrainage sont accessibles via des requêtes GET aux emplacements suivants :

http://example.com/wp-json/affwp/v1/referrals
http://example.com/wp-json/affwp/v1/referrals/ID

Tous les points de terminaison de parrainage et leurs diverses options sont également découvrables en visitant directement l'espace de noms REST AffiliateWP :

http://example.com/wp-json/affwp/v1/
Points d’accès

Le point de terminaison referrals accepte tous les arguments valides de get_referrals() :

  • number – Le nombre de résultats à récupérer (si disponible)
  • offset – Le nombre de résultats à décaler dans la requête. La valeur par défaut est 0 (aucun décalage)
  • referral_id – L'ID de parrainage ou le tableau d'ID à interroger.
  • affiliate_id – L’ID d’affilié ou un tableau d’ID à interroger.
  • reference – Informations de référence (ID du produit) pour le parrainage.
  • ref_context – Le contexte dans lequel le parrainage a été créé (intégration).
  • campaign – La campagne associée.
  • status – Le statut du parrainage ou le tableau de statuts. Accepte « paid », « unpaid », « pending » ou « rejected ».
  • order – Comment trier les résultats. Accepte ‘ASC’ (ascendant) ou ‘DESC’ (descendant).
  • orderby – Le champ selon lequel trier les résultats de la réponse. La valeur par défaut est ‘date’
  • search – Un ID de parrainage ou la chaîne de recherche pour interroger les parrainages.
  • date – Le tableau ou la chaîne de dates pour interroger les parrainages.
  • fields – Champs spécifiques à retourner pour chaque parrainage dans la réponse. Par défaut « * » (tous). Accepte « ids » ou toute colonne valide

Tous les arguments valides peuvent également être obtenus en envoyant une requête OPTIONS à l’un ou l’autre des points de terminaison.

Le point de terminaison referrals/{ID} accepte tout ID de parrainage valide.

Visibilité

Tous les points de terminaison nécessitent la clé API et le jeton, à l'exception du point de terminaison principal affwp/v1.

Réponse

Les réponses sont retournées au format JSON.

Exemple de réponse referrals  :

  {
    "referral_id": 21,
    "affiliate_id": 0,
    "visit_id": 0,
    "description": "",
    "status": "",
    "amount": "",
    "currency": "",
    "custom": "",
    "context": "",
    "campaign": "",
    "reference": "",
    "products": "",
    "date": "2016-08-17 19:57:30",
    "payout_id": "102",
    "id": 21
  },
  {
    "referral_id": 22,
    "affiliate_id": 2736,
    "visit_id": 0,
    "description": "",
    "status": "paid",
    "amount": "1.00",
    "currency": "USD",
    "custom": "",
    "context": "",
    "campaign": "",
    "reference": "",
    "products": "",
    "date": "2016-08-17 19:57:43",
    "payout_id": "81",
    "id": 22
  },

Exemple de réponse referrals/{ID} :

{
  "referral_id": 21,
  "affiliate_id": 0,
  "visit_id": 0,
  "description": "",
  "status": "",
  "amount": "",
  "currency": "",
  "custom": "",
  "context": "",
  "campaign": "",
  "reference": "",
  "products": "",
  "date": "2016-08-17 19:57:30",
  "payout_id": "102",
  "id": 21
}

.

5. Points de terminaison des visites

AffiliateWP core 1.9+ offre deux points de terminaison REST en lecture seule pour les visites :

  1. visits – Récupère les objets de réponse pour toutes les visites sur le site actuel
  2. visits/{ID} – Récupère un objet de réponse pour une visite avec l'ID de visite donné

Les points de terminaison de visite sont accessibles via des requêtes GET aux emplacements suivants :

http://example.com/wp-json/affwp/v1/visits
http://example.com/wp-json/affwp/v1/visits/ID

Tous les points de terminaison de visite et leurs diverses options sont également découvrables en visitant directement l'espace de noms REST AffiliateWP :

http://example.com/wp-json/affwp/v1/
Points d’accès

Le point de terminaison visits accepte tous les arguments valides de get_visits() :

  • number – Le nombre de résultats à récupérer (si disponible)
  • offset – Le nombre de résultats à décaler dans la requête. La valeur par défaut est 0 (aucun décalage)
  • visit_id – L'ID de visite ou le tableau d'ID pour interroger les visites.
  • affiliate_id – L'ID d'affilié ou le tableau d'ID pour interroger les visites.
  • referral_id – L'ID de parrainage ou le tableau d'ID pour interroger les visites.
  • referral_status – Le statut du parrainage ou le tableau de statuts pour récupérer les visites.
  • campaign – La campagne associée.
  • order – Comment trier la visite dans la réponse. Par défaut est « ASC » (ascendant)
  • orderby – Le champ selon lequel trier les résultats de la réponse. La valeur par défaut est ‘date’
  • fields – Champs spécifiques à retourner pour chaque visite dans la réponse. Par défaut « * » (tous). Accepte « ids » ou toute colonne valide

Tous les arguments valides peuvent également être obtenus en envoyant une requête OPTIONS à l’un ou l’autre des points de terminaison.

Le point de terminaison visits/{ID} accepte tout ID de visite valide.

Visibilité

Tous les points de terminaison nécessitent la clé API et le jeton, à l'exception du point de terminaison principal affwp/v1.

Réponse

Les réponses sont retournées au format JSON.

Exemple de réponse visites :

  {
    "visit_id": 1,
    "affiliate_id": 5464,
    "referral_id": 0,
    "url": "http://google.com",
    "referrer": "https://affiliatewp.com",
    "campaign": "test",
    "ip": "",
    "date": "2016-09-20 21:58:09",
    "id": 1
  },
  {
    "visit_id": 2,
    "affiliate_id": 5464,
    "referral_id": 0,
    "url": "http://google.com",
    "referrer": "https://affiliatewp.com",
    "campaign": "test",
    "ip": "",
    "date": "2016-09-18 21:58:11",
    "id": 2
  },

Exemple de réponse visites/{ID} :

{
  "visit_id": 2,
  "affiliate_id": 5464,
  "referral_id": 0,
  "url": "http://google.com",
  "referrer": "https://affiliatewp.com",
  "campaign": "test",
  "ip": "",
  "date": "2016-09-18 21:58:11",
  "id": 2
}

.

Toujours bloqué ? Soumettre un ticket et l'équipe qui l'a conçu vous aidera.

Commencez à obtenir plus de ventes dès aujourd'hui avec AffiliateWP

Lancez votre programme d'affiliation dès aujourd'hui et débloquez un nouveau canal de revenus pour développer votre entreprise plus rapidement.

Obtenir AffiliateWP maintenant