Documentation AffiliateWP

Documentation, matériel de référence et didacticiels pour AffiliateWP

Configuration et utilisation de l'API REST v1

Comment configurer et utiliser l'API REST v1

AffiliateWP dispose d'un grand nombre de points d'accès REST en lecture seule qui s'appuient sur l'infrastructure incluse dans WordPress 4.4 et les versions ultérieures.

Dans cet article, nous allons vous montrer comment configurer et utiliser l'API REST v1 pour accéder aux données d'AffiliateWP.

API REST - Authentification

Afin d'exploiter les principaux points d'extrémité REST, 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 une authentification de base combinant une clé publique et un jeton.

Avant de pouvoir authentifier une demande d'API, vous avez besoin d'un ensemble de clés d'API. Celles-ci sont propres à chaque utilisateur et peuvent être créées dans Affiliés → Outils → Clés API :

Pour générer un nouveau jeu de clés API, entrez le nom d'utilisateur de l'utilisateur auquel les clés doivent appartenir et cliquez sur Générer de nouvelles clés API.

Remarque: le compte d'utilisateur auquel les clés API sont associées doit avoir les capacités appropriées pour que l'API fonctionne. En règle générale, cela signifie que l'utilisateur doit avoir le rôle d'administrateur. Consultez notre documentation sur les rôles et les capacités pour plus d'informations.

Une fois les clés API créées, vous pouvez vous authentifier avec 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 demande authentifiée ressemblerait à ceci :

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

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

L'en-tête d'autorisation doit être inclus dans chaque demande 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'arrivée

AffiliateWP propose cinq itinéraires et plusieurs points d'accès sous-jacents. Ces cinq itinéraires sont les suivants :

  1. Affiliés
  2. Créatifs
  3. Paiements
  4. Renvois
  5. Visites

Cliquez sur les noms des itinéraires ci-dessus pour en savoir plus sur leurs points d'arrivée respectifs, voir des exemples de demandes, etc.

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

1. Points finaux de l'affiliation

AffiliateWP core 1.9+ offre deux points d'accès REST en lecture seule pour les affiliés :

  1. affiliés - Récupère les objets de réponse de tous les affiliés du 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 sont accessibles via des requêtes GET aux endroits suivants :

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

Tous les points de terminaison des affiliés et leurs différentes options peuvent également être découverts en visitant directement l'espace de noms REST d'AffiliateWP :

http://example.com/wp-json/affwp/v1/
Points finaux

Les affiliates accepte tous les arguments valides de la fonction get_affiliates() :

  • number - Le nombre de résultats à extraire (si disponible)
  • offset - Le nombre de résultats à décaler dans la requête. La valeur par défaut est 0 (pas de décalage)
  • affiliate_id - L'identifiant de l'affilié ou un tableau d'identifiants à rechercher.
  • user_id - L'identifiant de l'utilisateur ou un tableau d'identifiants à interroger sur les paiements.
  • exclude - ID de l'affilié ou tableau d'ID à exclure de la demande.
  • search - Termes permettant de rechercher des affiliés. Accepte un identifiant d'affilié ou une chaîne de caractères.
  • status - Le statut de l'affilié. Accepte "actif", "inactif", "en attente" ou "rejeté".
  • order - Comment ordonner les résultats. Accepte 'ASC' (croissant) ou 'DESC' (décroissant).
  • orderby - Le champ par lequel les résultats de la réponse doivent être classés. La valeur par défaut est "date
  • fields - Champs spécifiques à renvoyer pour chaque affilié dans la réponse. Défaut '*' (tous). Accepte 'ids' ou toute autre colonne valide.

Arguments supplémentaires :

  • user - Si user est passé à true, des objets utilisateurs personnalisés seront récupérés à la volée pour chaque affilié dans la réponse. Il convient d'être prudent lors de l'utilisation de cette option en raison de l'augmentation de 1:1 des requêtes de base de données associées à chaque affilié.
  • meta - S'il est passé à true, un tableau de méta d'affilié sera récupéré à la volée pour chaque affilié dans la réponse. Comme pour l'utilisateur, il convient d'être prudent en raison de la baisse des performances.

Tous les arguments valides peuvent également être obtenus en envoyant une requête OPTIONS à l'un ou l'autre des points d'extrémité.

Le point de terminaison affiliates/{ID} accepte tout identifiant 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éta d'affilié seront respectivement récupérés à la volée pour être inclus dans la réponse.

Visibilité

Tous les points d'accès requièrent la clé et le jeton de l'API, à l'exception du point d'accès principal affwp/v1 principal.

Réponse

Les réponses sont renvoyées sous forme JSON.

Exemple affiliés réponse :

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

Example affiliates/{ID} response:

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

Example affiliates{ID}?user=1 response:

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

Example affiliates{ID}?meta=1 response:

{
  "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 finaux créatifs

AffiliateWP core 1.9+ propose deux points d'accès REST en lecture seule pour les créatifs :

  1. créatifs - 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 dont l'identifiant est donné.

Les points d'accès créatifs sont accessibles via des requêtes GET aux endroits 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 accessibles en visitant directement l'espace de noms REST d'AffiliateWP :

http://example.com/wp-json/affwp/v1/
Points finaux

Les creatives accepte tous les arguments valides de la fonction get_creatives() :

  • number - Le nombre de résultats à extraire (si disponible)
  • offset - Le nombre de résultats à décaler dans la requête. La valeur par défaut est 0 (pas de décalage)
  • creative_id - L'identifiant du créateur ou un tableau d'identifiants à rechercher.
  • status - Le statut de la création. Accepte "actif" ou "inactif".
  • order - Comment ordonner les résultats. Accepte 'ASC' (croissant) ou 'DESC' (décroissant).
  • orderby - Crée une colonne de tableau pour ordonner par.
  • fields - Champs spécifiques à renvoyer pour chaque créatif dans la réponse. Valeur par défaut "*" (tous). Accepte 'ids' ou toute autre colonne valide.

Tous les arguments valides peuvent également être obtenus en envoyant une requête OPTIONS à l'un ou l'autre des points d'extrémité.

Les creatives/{ID} accepte tout identifiant créatif valide.

Visibilité

Tous les points d'accès requièrent la clé et le jeton de l'API, à l'exception du point d'accès principal affwp/v1 principal.

Réponse

Les réponses sont renvoyées sous forme JSON.

Exemple creatives sresponse:

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

Example creatives/{ID} response:

{
  "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 d'arrivée des paiements

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

  1. paiements - 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 des paiements sont accessibles via des requêtes GET aux endroits suivants :

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

Tous les points de paiement et leurs différentes options sont également accessibles en visitant directement l'espace de noms REST d'AffiliateWP :

http://example.com/wp-json/affwp/v1/
Points finaux

Les payouts accepte tous les arguments valides de la fonction get_payouts() :

  • number - Le nombre de résultats à extraire (si disponible)
  • offset - Le nombre de résultats à décaler dans la requête. La valeur par défaut est 0 (pas de décalage)
  • payout_id - L'identifiant du paiement ou un tableau d'identifiants à rechercher.
  • affiliate_id - L'identifiant de l'affilié ou un tableau d'identifiants pour lesquels les paiements doivent être demandés.
  • referrals - ID de référence ou tableau d'ID de référence pour récupérer les paiements.
  • amount - Montant du paiement (float) ou plage min/max (array) pour lequel les paiements doivent être récupérés.
  • amount_compare – Comparison operator used with amount. Accepts ‘>’, ‘<‘, ‘>=’, ‘<=’, ‘=’, or ‘!=’.
  • status - Le statut du paiement. Accepte "paid" ou "failed
  • date - Le tableau ou la chaîne de dates dans lequel les paiements doivent être recherchés.
  • order - Comment ordonner les résultats. Accepte 'ASC' (croissant) ou 'DESC' (décroissant).
  • orderby - Le champ par lequel les résultats de la réponse doivent être classés. La valeur par défaut est "date
  • fields - Champs spécifiques à retourner pour chaque paiement dans la réponse. Défaut '*' (tous). Accepte 'ids' ou toute autre colonne valide.

Tous les arguments valides peuvent également être obtenus en envoyant une requête OPTIONS à l'un ou l'autre des points d'extrémité.

Les payouts/{ID} accepte n'importe quel identifiant de paiement valide.

Visibilité

Tous les points d'accès requièrent la clé et le jeton de l'API, à l'exception du point d'accès principal affwp/v1 principal.

Réponse

Les réponses sont renvoyées sous forme JSON.

Exemple paiements réponse :

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

Example payouts/{ID} response:

{
  "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. Critères d'évaluation des renvois

AffiliateWP core 1.9+ offre deux points d'accès REST en lecture seule pour les références :

  1. références - Récupère les objets de réponse pour toutes les références sur le site actuel.
  2. referrals/{ID} - Récupère un objet de réponse pour un renvoi avec l'ID de renvoi donné.

Les points de référence sont accessibles via des requêtes GET aux endroits suivants :

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

Tous les points de référence et leurs différentes options peuvent également être découverts en visitant directement l'espace de noms REST d'AffiliateWP :

http://example.com/wp-json/affwp/v1/
Points finaux

Les références accepte tous les arguments valides de la fonction get_referrals() :

  • number - Le nombre de résultats à extraire (si disponible)
  • offset - Le nombre de résultats à décaler dans la requête. La valeur par défaut est 0 (pas de décalage)
  • referral_id - L'identifiant du référent ou un tableau d'identifiants à rechercher.
  • affiliate_id - L'identifiant de l'affilié ou un tableau d'identifiants à rechercher.
  • référence - Informations de référence (ID de produit) pour le renvoi.
  • ref_context - Le contexte dans lequel le renvoi a été créé (intégration).
  • campagne - La campagne associée.
  • status - Le statut de la recommandation ou un tableau de statuts. Accepte "paid", "unpaid", "pending" ou "rejected".
  • order - Comment ordonner les résultats. Accepte 'ASC' (croissant) ou 'DESC' (décroissant).
  • orderby - Le champ par lequel les résultats de la réponse doivent être classés. La valeur par défaut est "date
  • search - Un identifiant de référence ou la chaîne de recherche à utiliser pour rechercher des références.
  • date - Le tableau ou la chaîne de dates dans lequel les références doivent être recherchées.
  • fields - Champs spécifiques à renvoyer pour chaque référence dans la réponse. Valeur par défaut "*" (tous). Accepte 'ids' ou toute autre colonne valide.

Tous les arguments valides peuvent également être obtenus en envoyant une requête OPTIONS à l'un ou l'autre des points d'extrémité.

Les referrals/{ID} accepte n'importe quel identifiant de référence valide.

Visibilité

Tous les points d'accès requièrent la clé et le jeton de l'API, à l'exception du point d'accès principal affwp/v1 principal.

Réponse

Les réponses sont renvoyées sous forme JSON.

Exemple références réponse :

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

Example referrals/{ID} response:

{
  "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. Critères d'évaluation des visites

AffiliateWP core 1.9+ offre deux points d'accès REST en lecture seule pour les visites :

  1. visites - 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'identifiant de visite donné.

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

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

Tous les points de visite et leurs différentes options peuvent également être découverts en visitant directement l'espace de noms REST d'AffiliateWP :

http://example.com/wp-json/affwp/v1/
Points finaux

Les visites accepte tous les arguments valides de la fonction get_visits() :

  • number - Le nombre de résultats à extraire (si disponible)
  • offset - Le nombre de résultats à décaler dans la requête. La valeur par défaut est 0 (pas de décalage)
  • visit_id - L'identifiant de la visite ou un tableau d'identifiants pour interroger les visites.
  • affiliate_id - L'identifiant de l'affilié ou un tableau d'identifiants à interroger sur les visites.
  • referral_id - L'identifiant du référent ou un tableau d'identifiants pour interroger les visites.
  • referral_status - Le statut de la référence ou un tableau de statuts pour lesquels les visites doivent être récupérées.
  • campagne - La campagne associée.
  • order - Comment ordonner la visite dans la réponse. La valeur par défaut est "ASC" (croissant).
  • orderby - Le champ par lequel les résultats de la réponse doivent être classés. La valeur par défaut est "date
  • fields - Champs spécifiques à renvoyer pour chaque visite dans la réponse. Défaut '*' (tous). Accepte "ids" ou toute autre colonne valide.

Tous les arguments valides peuvent également être obtenus en envoyant une requête OPTIONS à l'un ou l'autre des points d'extrémité.

Les visits/{ID} accepte tout identifiant de visite valide.

Visibilité

Tous les points d'accès requièrent la clé et le jeton de l'API, à l'exception du point d'accès principal affwp/v1 principal.

Réponse

Les réponses sont renvoyées sous forme JSON.

Exemple visites réponse :

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

Example visits/{ID} response:

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

.