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 :
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 :
- affiliates – Récupère les objets de réponse pour tous les affiliés sur le site actuel
- 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 :
- creatives – Récupère les objets de réponse pour toutes les créations sur le site actuel
- 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 :
- payouts – Récupère les objets de réponse pour tous les paiements sur le site actuel
- 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 :
- referrals – Récupère les objets de réponse pour tous les parrainages sur le site actuel
- 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 :
- visits – Récupère les objets de réponse pour toutes les visites sur le site actuel
- 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
}
.