Module complémentaire REST API Extended

Êtes-vous un développeur cherchant à obtenir un contrôle total sur vos données d'affiliés en utilisant l'API REST d'AffiliateWP ? L'extension REST API Extended permet les opérations de création, lecture, mise à jour et suppression, vous permettant de gérer les affiliés, les références, les créations publicitaires et plus encore via des applications externes.

Dans cet article, nous vous montrerons comment installer et configurer l'extension REST API Extended pour AffiliateWP.

Installation de l'extension REST API Extended

Avant de commencer, assurez-vous d'installer et d'activer AffiliateWP sur votre site WordPress.

Une fois qu'AffiliateWP est installé et que votre licence est vérifiée, vous pourrez rapidement installer et activer l'extension REST API Extended.

Configuration de l'extension REST API Extended

Après avoir activé l'extension REST API Extended, vous devrez configurer ses paramètres. Pour ce faire, accédez à AffiliateWP » Paramètres » REST API dans votre tableau de bord WordPress.

Ici, vous pouvez sélectionner les cases à cocher pour activer les points d'accès que vous souhaitez utiliser, tels que affiliés, références, paiements et créations publicitaires.

Votre site dispose désormais d'une API REST CRUD complète pour interagir avec vos données d'affiliés.

Une fois ces paramètres configurés, votre site sera équipé d'une API REST entièrement fonctionnelle prenant en charge le CRUD, vous permettant de créer, lire, mettre à jour et supprimer des données dans AffiliateWP.

Gestion des affiliés

REST API Extended ajoute trois points d'accès, un pour créer, modifier et supprimer des affiliés, en plus des deux points d'accès en lecture seule déjà disponibles dans le cœur d'AffiliateWP.

Les cinq points d'accès utilisent les mêmes deux modèles de route :

1. Affiliés – Lorsqu'une requête GET est envoyée, une liste d'affiliés est renvoyée et peut être filtrée avec des arguments supplémentaires. Lorsqu'une requête POST ou PUT est envoyée, un nouvel affilié peut être créé.
2. Affiliés/[ID] – Lorsqu'une requête GET, PATCH ou DELETE est envoyée, un affilié unique peut être récupéré, modifié ou supprimé, respectivement.

Les deux routes peuvent également accepter des requêtes OPTIONS génériques, ce qui peut être très utile pour découvrir des informations sur les points d'accès disponibles, les types de requêtes et les arguments acceptés, ainsi que le schéma des éléments.

Que vous prévoyiez de lire, d'écrire, de modifier ou de supprimer des affiliés, cette extension rend cela possible.

Toutes les requêtes doivent être authentifiées à l'aide de clés d'API, qui sont générées et gérées via l'onglet AffiliateWP → Outils → Clés d'API. Consultez l'article REST API – Authentification pour plus d'informations.

Création d'un affilié

Les affiliés peuvent être créés en envoyant une requête POST ou PUT à la route affiliés :

https://alfsflowersandgifts.com/wp-json/affwp/v1/affiliates

Le point de terminaison create accepte tous les arguments suivants de la fonction affwp_add_affiliate():

• user_id – (integer) Chaque affilié partage une relation 1:1 avec un compte utilisateur WordPress existant. Si aucun ID utilisateur approprié n’est disponible, l’argument create_user peut être passé pour tenter de créer un affilié et un compte utilisateur dans la même étape.
• username – (string) Facultatif. Utilisé pour définir le user_login lors de la création d’un nouveau compte utilisateur. S’il n’est pas fourni, le payment_email sera utilisé pour générer le user_login du compte utilisateur WordPress généré.
• create_user – (boolean)  Utilisé pour créer un nouveau compte utilisateur, à la place de user_id. Doit être accompagné d’une valeur unique de payment_email, qui est utilisée lors de l’enregistrement du compte utilisateur.
• rate – (integer) Taux d’affilié à utiliser. S’il n’est pas spécifié, la valeur par défaut globale sera utilisée.
• rate_type – (string) Type de taux. Les types acceptés par défaut sont « percentage » ou « flat ». S’il n’est pas spécifié, la valeur par défaut globale sera utilisée.
• payment_email – (string) Email de paiement de l’affilié. S’il est omis, l’email du compte utilisateur sera utilisé lors de la récupération. Requis lors de l’utilisation de create_user.
• status – (string) Statut de l’affilié. Accepte « active », « inactive », « pending » ou « rejected ». La valeur par défaut est « pending ».
• notes – (string) Notes de l’affilié.

Création d’un affilié avec user_id :

Method: PUT/POST
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/affiliates/?user_id=5&rate=25&rate_type=percentage

Le nouvel affilié serait associé à l’user_id 5 et recevrait un taux de commission de 25 pour cent.

Exemple de réponse :

{
  "affiliate_id": 30,
  "user_id": 5,
  "rate": "25",
  "rate_type": "percentage",
  "payment_email": "",
  "status": "pending",
  "earnings": 0,
  "unpaid_earnings": 0,
  "referrals": 0,
  "visits": 0,
  "date_registered": "2024-01-26 07:27:52",
  "id": 30
}

Création d’un affilié et d’un utilisateur avec create_user :

Method: PUT/POST
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/affiliates/?create_user=1&[email protected]

Le nouvel affilié serait associé au nouvel utilisateur (ID 10) et recevrait un email de paiement de [email protected].

Exemple de réponse :

{
  "affiliate_id": 31,
  "user_id": 10,
  "rate": "",
  "rate_type": "",
  "payment_email": "[email protected]",
  "status": "pending",
  "earnings": 0,
  "unpaid_earnings": 0,
  "referrals": 0,
  "visits": 0,
  "date_registered": "2024-01-26 07:27:52",
  "id": 31
}

Modification d’un affilié existant

Les affiliés individuels peuvent être mis à jour en envoyant une requête POST ou PATCH à la route affiliates/[id] :

https://alfsflowersandgifts.com/wp-json/affwp/v1/affiliates/[id]

Le point de terminaison edit accepte tous les arguments suivants de la fonction affwp_update_affiliate() :

• account_email – (string) Nouvel email de compte pour le compte utilisateur associé.
• payment_email – (string) Nouvel email de paiement.
• rate – (integer) Taux d’affilié à utiliser
• rate_type – (string) Type de taux.
• status – (string) Statut de l’affilié. Accepte « active », « inactive », « pending » ou « rejected ».
• notes – (string) Notes de l’affilié.

Mise à jour d’un affilié

Dans cet exemple, nous allons mettre à jour le statut d’un affilié de pending à active.

Method: POST/PATCH
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/affiliates/31?status=active

Réponse :

{
  "affiliate_id": 31,
  "user_id": 10,
  "rate": "",
  "rate_type": "",
  "payment_email": "[email protected]",
  "status": "active",
  "earnings": 0,
  "unpaid_earnings": 0,
  "referrals": 0,
  "visits": 0,
  "date_registered": "2024-01-26 07:27:52",
  "id": 31
}

Suppression d’un affilié

Un affilié peut être supprimé en envoyant une requête DELETE à la route affiliates/[id] :

https://alfsflowersandgifts.com/wp-json/affwp/v1/affiliates/[id]

Le point de terminaison delete n’accepte aucun argument supplémentaire. Lorsqu’un affilié a été supprimé avec succès, une paire clé/valeur deleted: true sera incluse dans la réponse, ainsi qu’une copie de l’ancienne réponse de l’affilié.

Exemple de requête :

Method: DELETE
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/affiliates/31

Réponse :

{
  "deleted": true,
  "previous": {
    "affiliate_id": 31,
    "user_id": 10,
    "rate": "",
    "rate_type": "",
    "payment_email": "[email protected]",
    "status": "active",
    "earnings": 0,
    "unpaid_earnings": 0,
    "referrals": 0,
    "visits": 0,
    "date_registered": "2024-01-26 07:27:52",
    "id": 31
  }
}

Gestion des créations

REST API Extended ajoute trois points de terminaison, un pour créer, un pour modifier et un pour supprimer des créations, en plus des deux points de terminaison en lecture seule déjà disponibles dans le cœur d'AffiliateWP.

Les cinq points d'accès utilisent les mêmes deux modèles de route :

1. Créations – Lorsqu'une requête GET est envoyée, une liste de créations est renvoyée et peut être filtrée avec des arguments supplémentaires. Lorsqu'une requête POST ou PUT est envoyée, une nouvelle création peut être créée.
2. Créations/[id] – Lorsqu'une requête GET, PATCH ou DELETE est envoyée, une création unique peut être récupérée, modifiée ou supprimée, respectivement.

Les deux routes peuvent également accepter des requêtes OPTIONS génériques, ce qui peut être très utile pour découvrir des informations sur les points d'accès disponibles, les types de requêtes et les arguments acceptés, ainsi que le schéma des éléments.

Que vous prévoyiez de lire, d'écrire, de modifier ou de supprimer des créations, ce module complémentaire le rend possible.

Toutes les requêtes doivent être authentifiées à l'aide de clés d'API, qui sont générées et gérées via l'onglet AffiliateWP → Outils → Clés d'API. Consultez l'article REST API – Authentification pour plus d'informations.

Créer une création

Les créations peuvent être créées en envoyant une requête POST ou PUT à la route créations :

https://alfsflowersandgifts.com/wp-json/affwp/v1/creatives

Le point de terminaison create accepte tous les arguments suivants de affwp_add_creative() :

• Name – (entier) Nom d'étiquette pour la création.
• Description – (chaîne) Description de la création.
• Url – (chaîne) URL vers laquelle pointer la création.
• Text – (chaîne) Texte à afficher avec la création.
• Image – (chaîne) URL de l'image à associer à la création.
• Status – (chaîne) Statut de la création. Accepte 'active' ou 'inactive'. Par défaut 'active'.

Création d'une création

Method: PUT/POST
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/creatives/?name=New+Creative&text=REST

La nouvelle création, nommée « Nouvelle Création », contiendrait le texte « REST ».

Exemple de réponse :

{
  "creative_id": 20,
  "name": "New Creative",
  "description": "",
  "url": "",
  "text": "REST",
  "image": "",
  "status": "",
  "date": "2024-01-26 09:25:05",
  "id": 20
}

Modification d'une création existante

Les créations uniques peuvent être mises à jour en envoyant une requête POST ou PATCH à la route créations/[id] :

https://alfsflowersandgifts.com/wp-json/affwp/v1/creatives/[id]

Le point de terminaison edit accepte tous les arguments suivants de affwp_update_creative() :

• Name – (entier) Nom d'étiquette pour la création.
• Description – (chaîne) Description de la création.
• Url – (chaîne) URL vers laquelle pointer la création.
• Text – (chaîne) Texte à afficher avec la création.
• Image – (chaîne) URL de l'image à associer à la création.
• Status – (chaîne) Statut de la création. Accepte 'active' ou 'inactive'.

Mise à jour d'une création

Dans cet exemple, nous allons mettre à jour le statut d'une création de actif à inactif.

Method: POST/PATCH
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/creatives/20?status=inactive

Réponse :

{
  "creative_id": 20,
  "name": "Creative",
  "description": "",
  "url": "http://alfsflowersandgifts.com",
  "text": "AffiliateWP Plugin Testing",
  "image": "",
  "status": "inactive",
  "date": "2024-01-26 09:25:05",
  "id": 20
}

Suppression d'une création

Une création peut être supprimée en envoyant une requête DELETE à la route créations/[id] :

https://alfsflowersandgifts.com/wp-json/affwp/v1/creatives/[id]

Le point de terminaison delete n'accepte aucun argument supplémentaire. Lorsqu'une création a été supprimée avec succès, une paire clé/valeur deleted: true sera incluse dans la réponse, ainsi qu'une copie de l'ancienne réponse de la création.

Exemple de requête :

Method: DELETE
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/creatives/20

Réponse :

{
  "deleted": true,
  "previous": {
    "creative_id": 20,
    "name": "Creative",
    "description": "",
    "url": "http://alfsflowersandgifts.com",
    "text": "AffiliateWP Plugin Testing",
    "image": "",
    "status": "inactive",
    "date": "2024-01-26 09:25:05",
    "id": 20
  }
}

Gestion des paiements

REST API Extended ajoute trois points de terminaison, un pour créer, un pour modifier et un pour supprimer des paiements, en plus des deux points de terminaison en lecture seule déjà disponibles dans le cœur d'AffiliateWP.

Les cinq points d'accès utilisent les mêmes deux modèles de route :

1. Paiements – Lorsqu'une requête GET est envoyée, une liste de paiements est renvoyée et peut être filtrée avec des arguments supplémentaires. Lorsqu'une requête POST ou PUT est envoyée, un nouveau paiement peut être créé.
2. Paiements/[id] – Lorsqu'une requête GET, PATCH ou DELETE est envoyée, un paiement unique peut être récupéré, modifié ou supprimé, respectivement.

Les deux routes peuvent également accepter des requêtes OPTIONS génériques, ce qui peut être très utile pour découvrir des informations sur les points de terminaison disponibles, les types de requêtes et les arguments acceptés, ainsi que le schéma des éléments.

Toutes les requêtes doivent être authentifiées à l'aide de clés d'API, qui sont générées et gérées via l'onglet AffiliateWP → Outils → Clés d'API. Consultez l'article REST API – Authentification pour plus d'informations.

Créer un paiement

Les paiements peuvent être créés en envoyant une requête POST ou PUT à la route payouts :

https://alfsflowersandgifts.com/wp-json/affwp/v1/payouts

Le point de terminaison create accepte tous les arguments suivants de affwp_add_payout() :

• affiliate_id – (entier) ID de l'affilié auquel associer le paiement. Ce champ est requis.
• referrals – (tableau|chaîne) Tableau ou liste séparée par des virgules d'ID de parrainages à inclure dans le paiement.
• amount – (flottant) Montant du paiement (généralement dérivé des montants des parrainages).
• payout_method – (chaîne) Méthode de paiement.
• status – (chaîne) Accepte 'paid' ou 'failed'. Par défaut 'paid'.

Exemple de requête :

Method: PUT/POST
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/payouts/?affilite_id=30&referrals=10,15,20

Le nouveau paiement, avec l'ID de paiement 15, couvrirait les parrainages 10, 15 et 20 pour l'ID d'affilié 30.

Réponse :

{
  "payout_id": 15,
  "affiliate_id": 30,
  "referrals": "10,15,20",
  "amount": 27.87,
  "payout_method": "manual",
  "status": "paid",
  "date": "2024-01-26 12:55:13",
  "owner": 1,
  "id": 15
}

Modifier un paiement existant

Les paiements uniques peuvent être mis à jour en envoyant une requête POST ou PATCH à la route payouts/[id] :

https://alfsflowersandgifts.com/wp-json/affwp/v1/payouts/[id]

Le point de terminaison edit accepte tous les arguments suivants :

• affiliate_id – (entier) ID de l'affilié auquel associer le paiement. Ce champ est requis.
• referrals – (tableau|chaîne) Tableau ou liste séparée par des virgules d'ID de parrainages à inclure dans le paiement.
• amount – (flottant) Montant du paiement (généralement dérivé des montants des parrainages).
• payout_method – (chaîne) Méthode de paiement.
• status – (chaîne) Accepte 'paid' ou 'failed'. Par défaut 'paid'.

Mise à jour d'un paiement

Dans cet exemple, nous allons mettre à jour le statut d'un paiement de failed à paid.

Method: POST/PATCH
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/payouts/15?status=paid

Réponse :

{
  "payout_id": 15,
  "affiliate_id": 30,
  "referrals": "10,15,20",
  "amount": 30,
  "payout_method": "manual",
  "status": "paid",
  "date": "2024-01-26 12:55:13",
  "owner": 1,
  "id": 15
}

Supprimer un paiement

Un paiement peut être supprimé en envoyant une requête DELETE à la route payouts/[id] :

https://alfsflowersandgifts.com/wp-json/affwp/v1/payouts/[id]

Le point de terminaison delete n'accepte aucun argument supplémentaire. Lorsqu'un paiement a été supprimé avec succès, une paire clé/valeur deleted: true sera incluse dans la réponse, ainsi qu'une copie de l'ancienne réponse du paiement.

Exemple de requête :

Method: DELETE
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/payouts/15

Réponse :

{
  "deleted": true,
  "previous": {
    "payout_id": 6751,
    "affiliate_id": 5454,
    "referrals": "35878,35877,35876",
    "amount": 30,
    "payout_method": "manual",
    "status": "paid",
    "date": "2024-01-26 12:55:13",
    "owner": 1,
    "id": 6751
  }
}

Gestion des parrainages

REST API Extended ajoute trois points de terminaison, un pour créer, modifier et supprimer des parrainages, en plus des deux points de terminaison en lecture seule déjà disponibles dans le cœur d'AffiliateWP.

Les cinq points d'accès utilisent les mêmes deux modèles de route :

1. referrals – Lorsqu'une requête GET est envoyée, une liste de parrainages est renvoyée et peut être filtrée avec des arguments supplémentaires. Lorsqu'une requête POST ou PUT est envoyée, un nouveau parrainage peut être créé.
2. referrals/[id] – Lorsqu'une requête GET, PATCH ou DELETE est envoyée, un parrainage unique peut être récupéré, modifié ou supprimé, respectivement.

Les deux routes peuvent également accepter des requêtes OPTIONS génériques, ce qui peut être très utile pour découvrir des informations sur les points de terminaison disponibles, les types de requêtes et les arguments acceptés, ainsi que le schéma des éléments.

Toutes les requêtes doivent être authentifiées à l'aide de clés d'API, qui sont générées et gérées via l'onglet AffiliateWP → Outils → Clés d'API. Consultez l'article REST API – Authentification pour plus d'informations.

Créer un parrainage

Les parrainages peuvent être créés en envoyant une requête POST ou PUT à la route referrals :

https://alfsflowersandgifts.com/wp-json/affwp/v1/referrals

Le point de terminaison create accepte tous les arguments suivants de affwp_add_referral() :

• affiliate_id – (entier) ID de l'affilié auquel associer le parrainage. Ce champ est requis. Voir user_id et user_name.
• user_id – (entier) ID utilisateur utilisé pour récupérer l'ID d'affilié associé si affiliate_id n'est pas envoyé.
• user_name – (chaîne) Nom d'utilisateur utilisé pour récupérer l'ID d'affilié associé si affiliate_id n'est pas envoyé.
• amount – (flottant) Montant final calculé du parrainage, pas le montant de la transaction ou de la vente.
• currency – (chaîne) Devise du montant du parrainage.
• description – (chaîne) Description du parrainage.
• référence – (string) Référence de parrainage. Contient généralement des informations sur le produit telles que les identifiants de produit.
• contexte – (string) Contexte dans lequel le parrainage a été créé. Il s'agit généralement du slug d'intégration.
• statut – (string) Accepte « payé », « non payé », « en attente » ou « rejeté ». Par défaut « en attente ».

Créer un parrainage

Method: PUT/POST
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/referrals/?affilite_id=30&amount=15

Ce qui précède créerait un nouveau parrainage associé à l'ID d'affilié 30 pour un montant de 15 $ avec le statut « en attente ».

Exemple de réponse :

{
  "referral_id": 450,
  "affiliate_id": 30,
  "visit_id": 0,
  "description": "",
  "status": "pending",
  "amount": "15.00",
  "currency": "USD",
  "custom": "",
  "context": "",
  "campaign": "",
  "reference": "",
  "products": "",
  "date": "2024-01-26 22:28:54",
  "payout_id": "0",
  "id": 450
}

Modifier un parrainage existant

Les parrainages individuels peuvent être mis à jour en envoyant une requête POST ou PATCH à la route referrals/[id] :

https://alfsflowersandgifts.com/wp-json/affwp/v1/referrals/[id]

Le point de terminaison edit accepte l'un des arguments affwp_process_update_referral() suivants :

• affiliate_id – (integer) ID de l'affilié auquel associer le parrainage.
• visit_id – (integer) ID de la visite à associer au parrainage.
• amount – (float) Montant du parrainage mis à jour.
• currency – (string) Devise du montant du parrainage mis à jour.
• description – (string) Description du parrainage mise à jour.
• référence – (string) Référence de parrainage. Contient généralement des informations sur le produit telles que les identifiants de produit.
• contexte – (string) Contexte dans lequel le parrainage a été créé. Il s'agit généralement du slug d'intégration.
• status – (string) Accepte « payé », « non payé », « en attente » ou « rejeté ».

Mise à jour d'un parrainage

Dans cet exemple, nous allons mettre à jour le statut d'un parrainage de en attente à payé.

Method: POST/PATCH
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/referrals/450?status=paid

Réponse :

{
  "referral_id": 450,
  "affiliate_id": 30,
  "visit_id": 0,
  "description": "",
  "status": "paid",
  "amount": "",
  "currency": "",
  "custom": "",
  "context": "",
  "campaign": "",
  "reference": "",
  "products": "",
  "date": "2024-01-26 22:28:54",
  "payout_id": "0",
  "id": 450
}

Supprimer un parrainage

Un parrainage peut être supprimé en envoyant une requête DELETE à la route referrals/[id] :

https://alfsflowersandgifts.com/wp-json/affwp/v1/referrals/[id]

Le point de terminaison delete n'accepte aucun argument supplémentaire. Lorsqu'un parrainage a été supprimé avec succès, une paire clé/valeur deleted: true sera incluse dans la réponse, ainsi qu'une copie de l'ancienne réponse du parrainage.

Exemple de requête :

Method: DELETE
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/referrals/450

Réponse :

{
  "deleted": true,
  "previous": {
    "referral_id": 35879,
    "affiliate_id": 5454,
    "visit_id": 0,
    "description": "",
    "status": "paid",
    "amount": "",
    "currency": "",
    "custom": "",
    "context": "",
    "campaign": "",
    "reference": "",
    "products": "",
    "date": "2024-01-26 22:28:54",
    "payout_id": "0",
    "id": 35879
  }
}

Gestion des visites

REST API Extended ajoute trois points de terminaison, un pour créer, modifier et supprimer des visites, en plus des deux points de terminaison en lecture seule déjà disponibles dans le cœur d'AffiliateWP.

Les cinq points d'accès utilisent les mêmes deux modèles de route :

1. visits – Lorsqu'une requête GET est envoyée, une liste de visites est renvoyée et peut être filtrée avec des arguments supplémentaires. Lorsqu'une requête POST ou PUT est envoyée, un nouveau parrainage peut être créé.
2. visits/[id] – Lorsqu'une requête GET, PATCH ou DELETE est envoyée, une visite unique peut être récupérée, modifiée ou supprimée, respectivement.

Les deux routes peuvent également accepter des requêtes OPTIONS génériques, ce qui peut être très utile pour découvrir des informations sur les points de terminaison disponibles, les types de requêtes et les arguments acceptés, ainsi que le schéma des éléments.

Toutes les requêtes doivent être authentifiées à l'aide de clés d'API, qui sont générées et gérées via l'onglet AffiliateWP → Outils → Clés d'API. Consultez l'article REST API – Authentification pour plus d'informations.

Créer une visite

Les visites peuvent être créées en envoyant une requête POST ou PUT à la route visits :

https://alfsflowersandgifts.com/wp-json/affwp/v1/visits

Le point de terminaison create accepte l'un des arguments suivants :

• affiliate_id – (integer) ID de l'affilié à associer à la visite. Ce champ est obligatoire.
• referral_id – (integer) ID du parrainage à associer à la visite.
• url – (string) URL de la visite.
• referrer – (string) URL de référence
• campaign – (string) Campagne associée.
• ip – (string) Adresse IP du visiteur.

Exemple de requête :

Method: PUT/POST
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/visits/?affilite_id=30&url=https%3A%2F%2Faffiliatewp.com

Ce qui précède créerait une nouvelle visite associée à l'ID d'affilié 30 qui a une URL stockée de https://affiliatewp.com.

Réponse :

{
  "visit_id": 541,
  "affiliate_id": 30,
  "referral_id": 0,
  "url": "https://affiliatewp.com",
  "referrer": "",
  "campaign": "",
  "ip": "",
  "date": "2024-01-26 23:05:21",
  "id": 541
}

Modification d'une visite existante

Les visites uniques peuvent être mises à jour en envoyant une requête POST ou PATCH à la route visits/[id] :

https://alfsflowersandgifts.com/wp-json/affwp/v1/visits/[id]

Le point de terminaison edit accepte tous les arguments suivants :

• visit_id – (integer) ID de la visite. Ce champ est requis.
• referral_id – (integer) ID du parrainage à associer à la visite.
• affiliate_id – (integer) ID de l'affilié à associer à la visite.
• url – (string) URL de la visite.
• referrer – (string) URL de référence
• campaign – (string) Campagne associée.
• ip – (string) Adresse IP du visiteur.

Mise à jour d'une visite

Dans cet exemple, nous allons mettre à jour la campagne associée d'une visite :

Method: POST/PATCH
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/visits/541?campaign=spring-sale

Réponse :

{
  "visit_id": 541,
  "affiliate_id": 30,
  "referral_id": 0,
  "url": "https://affiliatewp.com",
  "referrer": "",
  "campaign": "spring-sale",
  "ip": "",
  "date": "2024-01-26 23:05:21",
  "id": 541
}

Suppression d'une visite

Une visite peut être supprimée en envoyant une requête DELETE à la route visits/[id] :

https://alfsflowersandgifts.com/wp-json/affwp/v1/visits/[id]

Le point de terminaison delete n'accepte aucun argument supplémentaire. Lorsqu'une visite a été supprimée avec succès, une paire clé/valeur deleted: true sera incluse dans la réponse, ainsi qu'une copie de l'ancienne réponse de visite.

Exemple de requête :

Method: DELETE
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/visits/541

Réponse :

{
  "deleted": true,
  "previous": {
    "visit_id": 541,
    "affiliate_id": 30,
    "referral_id": 0,
    "url": "https://affiliatewp.com",
    "referrer": "",
    "campaign": "spring-sale",
    "ip": "",
    "date": "2024-01-26 23:05:21",
    "id": 541
  }
}

Exemple : Intégration de l'API REST entre deux sites WordPress

L'un des cas d'utilisation les plus courants du module complémentaire REST API Extended est de permettre à un site WordPress d'interagir avec un autre site exécutant AffiliateWP.

Par exemple, vous pourriez créer un affilié sur un site WordPress (Site A) et l'enregistrer comme affilié sur un site distinct propulsé par WordPress (Site B) en utilisant l'API. Cette intégration permet une communication transparente entre les deux sites.

Les exemples suivants supposent que vous avez des connaissances de base sur la façon dont WordPress gère l'envoi de requêtes distantes et la récupération de réponses.

Si vous n'êtes pas familier avec l'API HTTP ou l'API REST, nous vous recommandons de consulter l'article API HTTP dans le manuel officiel des développeurs de plugins ainsi que le manuel de l'API REST.

Découverte d'informations

Comme indiqué dans les sections Gestion des affiliés, des créations, des paiements, des références et des visites, le module complémentaire REST API Extended apporte des capacités CRUD (Create, Read, Update, and Delete) complètes lors de l'interaction avec AffiliateWP à distance.

Dans la plupart des cas, les réponses distantes sont structurées de manière cohérente entre les types d'objets. Cela dit, en fonction du point de terminaison utilisé, certains champs spécifiques aux types d'objets donnés seront requis dans diverses circonstances.

La meilleure façon de déterminer quels champs sont requis ou quels paramètres sont acceptés est d'envoyer une requête OPTIONS au point de terminaison ; la réponse de la requête OPTIONS devrait vous dire tout ce que vous devez savoir.

Par exemple, voici une section de la réponse d'une requête OPTIONS envoyée au point de terminaison /v1/creatives/ avec REST API Extended activé :

{
  "namespace": "affwp/v1",
  "methods": [
    "GET",
    "POST",
    "PUT",
    "PATCH"
  ],
  "endpoints": [
    {
      "methods": [
        "POST",
        "PUT",
        "PATCH"
      ],
      "args": {
        "name": {
          "required": false,
          "description": "Name of the creative.",
          "type": "string"
        },
        "description": {
          "required": false,
          "description": "Description for the creative.",
          "type": "string"
        },
        "url": {
          "required": false,
          "description": "URL the creative points to.",
          "type": "string"
        },
        "text": {
          "required": false,
          "description": "Text for the creative.",
          "type": "string"
        },
        "image": {
          "required": false,
          "description": "ID of the media library image associated with the creative",
          "type": "integer"
        },
        "status": {
          "required": false,
          "description": "The creative status.",
          "type": "string"
        },
        "date": {
          "required": false,
          "description": "The date the creative was created.",
          "type": "string"
        }
      }
    }
  ],

Vous pouvez voir que les méthodes de requête disponibles pour ce point de terminaison sont clairement répertoriées et que les arguments disponibles pour chacune sont définis et répertoriés dans la hiérarchie ci-dessous. D'autres informations utiles renvoyées dans une requête OPTIONS incluent des informations de schéma – définissant les champs qui seront présents dans un seul objet, et plus encore.

Construction des requêtes

Maintenant que vous avez une bonne base sur ce que vous devez savoir et comment trouver plus d'informations, construisons quelques exemples de requêtes.

Authentification

Si vous vous souvenez de l'article Présentation de l'API REST v1, toutes les requêtes envoyées doivent inclure un en-tête Authorization construit à l'aide du schéma Basic Auth. L'en-tête Basic Auth dans AffiliateWP est obtenu en utilisant les valeurs de clé publique et de jeton. Voici un exemple d'en-tête Basic Auth :

Authorization : Basic N2Q4NTM1OWM4NzlkYWNjOWE2ZmMxZjgxYjQ2ZDYyZDE6YmE3YjUwZGUyMjZkOGI2YzRkNjQyMjA1YjcwNDUwMjY=

« Authorization » est la clé, et « Basic N2Q4NTM… » est la valeur. La valeur est construite en encodant la combinaison des valeurs de clé publique et de jeton, séparées par un deux-points, et en ajoutant « Basic » au début. Par exemple :

"Basic " . base64_encode( "{$public_key}:{$token}" );

Lors de l'utilisation des fonctions de l'API HTTP de WordPress, l'en-tête Authorization doit être envoyé comme suit :

wp_remote_*( 'request_url', array(<br>    'headers' => array(<br>        'Authorization' => 'Basic hash_value'<br>    )<br>) );

Pour plus d'informations sur la façon dont l'API REST AffiliateWP s'authentifie, consultez l'article API REST – Authentification.

Exemple de requête : Créer un affilié

Comme indiqué dans la section Gestion des affiliés, un user_id est requis lors de la création d'un affilié. Alternativement, l'argument create_user peut être envoyé avec une valeur payment_email pour créer un utilisateur et un affilié dans la même étape.

Voici le code WordPress nécessaire pour créer un affilié à distance lorsque vous avez déjà un user_id valide :

$request_url = add_query_arg( array( 
    'user_id' => 5 
), 

'https://alfsflowersandgifts.com/wp-json/affwp/v1/affiliates' );

$response = wp_remote_post( $request_url, array(
    'headers' => array(
        'Authorization' => 'Basic hash_value'
    )
) );

Dans l'extrait ci-dessus, notez que la valeur user_id est passée via $request_url plutôt que via l'argument « body », ce qui est pris en charge pour les requêtes POST. Ceci est fait pour la cohérence avec les exemples d'autres points de terminaison, notamment ceux qui utilisent les méthodes PUT ou PATCH, qui ne prennent pas en charge l'envoi de paramètres via le corps de la requête.

Exemple de requête : Créer un paiement

Similairement à la création d'affiliés, les nouveaux paiements nécessitent également certains champs, spécifiquement les valeurs affiliate_id et referrals.

Voici le code nécessaire pour créer à distance un nouveau paiement, étant donné un affiliate_id valide et une liste d'ID de référence :

$request_url = add_query_arg( array(
    'affiliate_id'  => 2,
    'referrals'     => '2,3,4',
    'payout_method' => 'REST',
), 

'https://alfsflowersandgifts.com/wp-json/affwp/v1/payouts' );

$response = wp_remote_post( $request_url, array(
    'headers' => array(
        'Authorization' => 'Basic hash_value'
    )
) );

Notez que la valeur payout_method n'est pas nécessairement nécessaire, mais elle est utile pour fournir le contexte que le paiement a été généré via REST.

Exemple de requête : Mise à jour d'une référence

Lors de la mise à jour d'un objet via REST, il est intéressant de noter que comme l'ID de l'objet que vous modifiez fait en fait partie du point de terminaison, la valeur de cette clé primaire n'a pas besoin d'être envoyée avec la requête.

Voici un exemple de la façon de mettre à jour le statut d'une référence de non payé à payé :

$request_url = add_query_arg( array( 
'status' => 'paid', 

'https://alfsflowersandgifts.com/wp-json/affwp/v1/referrals/3' );

$response = wp_remote_request( $request_url, array(
    'method'  => 'PATCH',
    'headers' => array(
        'Authorization' => 'Basic hash_value'
    )
) );

Notez qu'au lieu de wp_remote_post() comme précédemment, cette requête utilise wp_remote_request() avec l'argument « method » => « PATCH ». Cela indique à l'API REST que vous envoyez spécifiquement une requête PATCH.

Notez également que l'ID de référence 3 est passé dans le cadre du point de terminaison plutôt que dans le statut de type URL.

Analyse des réponses

En plus de la création de requêtes, il est important d'avoir une bonne compréhension de la structure des réponses et de savoir comment valider qu'une requête a réussi dans l'écosystème WordPress.

Dans les deux premiers exemples sous « Création de requêtes », nous avons expliqué comment formuler des requêtes pour créer de nouveaux affiliés et paiements.

Lors de l’examen d’une réponse, l’une des façons les plus simples de confirmer qu’elle a réussi est de regarder le code de réponse :

$response_code = wp_remote_retrieve_response_code( $response );

if ( 201 === $response_code ) {
    // success
}

Dans le cas des points de terminaison de création et de mise à jour d’AffiliateWP, les requêtes réussies renverront des réponses avec le code d’état 201. Pour les requêtes de suppression réussies, les codes de réponse seront le 200 par défaut.

Les réponses renvoyées pour les requêtes de suppression réussies incluront également une paire clé:valeur « supprimé: vrai », ainsi qu’une copie de l’ancien objet :

{
  "deleted": true,
  "previous": {
    "affiliate_id": 35,
    "user_id": 11,
    "rate": "",
    "rate_type": "",
    "payment_email": "[email protected]",
    "status": "active",
    "earnings": 0,
    "unpaid_earnings": 0,
    "referrals": 0,
    "visits": 0,
    "date_registered": "2024-01-31 07:31:05",
    "id": 35
  }
}

Maintenant que nous avons vu comment formuler des requêtes et analyser les réponses, examinons comment formuler une requête de création d’affilié, puis comment examiner et procéder au traitement des informations récupérées en cas de succès :

$request_url = add_query_arg( array( 
   'user_id' => 5 ), 

'https://alfsflowersandgifts.com/wp-json/affwp/v1/affiliates' );

// Send the request, storing the return in $response.
$response = wp_remote_post( $request_url, array(
    'headers' => array(
        'Authorization' => 'Basic hash_value'
    )
) );

// Check for the requisite response code. If 201, retrieve the response body and continue.
if ( 201 === wp_remote_retrieve_response_code( $response ) ) {
    $body = wp_remote_retrieve_body( $response );
    // do something successful
} else {
    // maybe display an error message
}

Questions fréquemment posées

---

C’est tout ! Le module complémentaire REST API Extended pour AffiliateWP donne aux développeurs un outil puissant pour gérer les affiliés, les références, les paiements, les créations et les visites par programme. En permettant des opérations CRUD complètes, ce module complémentaire ouvre un éventail de possibilités pour intégrer AffiliateWP avec des systèmes externes, automatiser des processus et personnaliser la gestion des affiliés pour répondre à des besoins spécifiques.