¿Eres un desarrollador que busca obtener control total sobre tus datos de afiliados utilizando la REST API de AffiliateWP? El addon REST API Extended permite operaciones de Creación, Lectura, Actualización y Eliminación, lo que te permite administrar afiliados, referencias, creatividades y más a través de aplicaciones externas.
En este artículo, te mostraremos cómo instalar y configurar el add-on REST API Extended para AffiliateWP.
Necesitarás una licencia Pro para acceder al addon REST API Extended.
Instalación del addon REST API Extended
Antes de empezar, asegúrese de instalar y activar AffiliateWP en su sitio de WordPress.
Una vez que tengas AffiliateWP instalado y tu licencia verificada, podrás instalar y activar rápidamente el addon REST API Extended.
Configuración del addon REST API Extended
Después de activar el add-on REST API Extended, deberás configurar sus ajustes. Para ello, navega a AffiliateWP » Ajustes » REST API en tu panel de WordPress.
Aquí, puedes seleccionar las casillas para habilitar los endpoints que deseas utilizar, como afiliados, referencias, pagos y creatividades.
Tu sitio ahora tiene una REST API CRUD completa para interactuar con tus datos de afiliados.
Una vez configurados estos ajustes, tu sitio estará equipado con una REST API totalmente funcional con capacidad CRUD, lo que te permitirá crear, leer, actualizar y eliminar datos en AffiliateWP.
Si no estás familiarizado con la REST API básica de AffiliateWP o necesitas ayuda con la autenticación, consulta la Descripción general de la REST API en la documentación principal para obtener orientación adicional sobre los métodos de uso y autenticación.
Gestión de Afiliados
REST API Extended añade tres endpoints, uno para crear, editar y eliminar afiliados, además de los dos endpoints de solo lectura ya disponibles en el núcleo de AffiliateWP.
Los cinco endpoints utilizan los mismos dos patrones de ruta:
- Afiliados – Cuando se envía una solicitud GET, se devuelve una lista de afiliados que se puede filtrar con argumentos adicionales. Cuando se envía una solicitud POST o PUT, se puede crear un nuevo afiliado.
- Afiliados/[ID] – Cuando se envía una solicitud GET, PATCH o DELETE, se puede recuperar, editar o eliminar un afiliado individual, respectivamente.
Ambas rutas también pueden aceptar solicitudes OPTIONS genéricas, que pueden ser muy útiles para descubrir información sobre los endpoints disponibles, los tipos de solicitud y argumentos aceptados, y el esquema de los elementos.
Ya sea que planees leer, escribir, editar o eliminar afiliados, este add-on lo hace posible.
Todas las solicitudes deben autenticarse utilizando claves API, que se generan y gestionan a través de la pestaña AffiliateWP → Herramientas → Claves API. Consulta el artículo REST API – Autenticación para obtener más información.
Creación de un Afiliado
Los afiliados se pueden crear enviando una solicitud POST o PUT a la ruta afiliados:
https://alfsflowersandgifts.com/wp-json/affwp/v1/affiliates
El endpoint create acepta cualquiera de los siguientes argumentos de affwp_add_affiliate():
- user_id – (integer) Cada afiliado comparte una relación 1:1 con una cuenta de usuario de WordPress existente. Si no hay un ID de usuario adecuado disponible, el argumento create_user puede pasarse para intentar crear un afiliado y una cuenta de usuario en el mismo paso.
- username – (string) Opcional. Se utiliza para establecer el user_login al crear una nueva cuenta de usuario. Si no se proporciona, el payment_email se utilizará para generar el user_login de la cuenta de usuario de WordPress generada.
- create_user – (boolean) Se utiliza para crear una nueva cuenta de usuario, en lugar de user_id. Debe ir acompañado de un valor único de payment_email, que se utiliza al registrar la cuenta de usuario.
- rate – (integer) Tarifa de afiliado a utilizar. Si no se especifica, se utilizará la predeterminada global.
- rate_type – (string) Tipo de tarifa. Los tipos aceptados por defecto son 'percentage' o 'flat'. Si no se especifica, se utilizará la predeterminada global.
- payment_email – (string) Correo electrónico de pago del afiliado. Si se omite, se utilizará el correo electrónico de la cuenta de usuario al recuperarlo. Requerido cuando se utiliza create_user.
- status – (string) Estado del afiliado. Acepta 'active', 'inactive', 'pending' o 'rejected'. El valor predeterminado es 'pending'.
- notes – (string) Notas del afiliado.
Creación de un afiliado con user_id:
Method: PUT/POST
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/affiliates/?user_id=5&rate=25&rate_type=percentage
El nuevo afiliado se asociaría con el user_id 5 y se le daría una tasa de comisión del 25 por ciento.
Respuesta de ejemplo:
{
"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
}
Creación de un afiliado y un usuario con create_user:
Method: PUT/POST
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/affiliates/?create_user=1&[email protected]
El nuevo afiliado se asociaría con el nuevo usuario (ID 10) y se le daría una dirección de correo electrónico de pago de [email protected].
Respuesta de ejemplo:
{
"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
}
Edición de un Afiliado Existente
Los afiliados individuales se pueden actualizar enviando una solicitud POST o PATCH a la ruta affiliates/[id]:
https://alfsflowersandgifts.com/wp-json/affwp/v1/affiliates/[id]
El endpoint edit acepta cualquiera de los siguientes argumentos de affwp_update_affiliate():
- account_email – (string) Nuevo correo electrónico de cuenta para la cuenta de usuario asociada.
- payment_email – (string) Nuevo correo electrónico de pago.
- rate – (integer) Tarifa de afiliado a utilizar
- rate_type – (string) Tipo de tarifa.
- status – (string) Estado del afiliado. Acepta 'active', 'inactive', 'pending' o 'rejected'.
- notes – (string) Notas del afiliado.
Actualización de un Afiliado
En este ejemplo, actualizaremos el estado de un afiliado de pending a active.
Method: POST/PATCH
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/affiliates/31?status=active
Respuesta:
{
"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
}
Eliminación de un Afiliado
Un afiliado puede eliminarse enviando una solicitud DELETE a la ruta affiliates/[id]:
https://alfsflowersandgifts.com/wp-json/affwp/v1/affiliates/[id]
El endpoint delete no acepta argumentos adicionales. Cuando un afiliado se ha eliminado correctamente, se incluirá un par clave/valor de deleted: true en la respuesta, junto con una copia de la respuesta del afiliado anterior.
Solicitud de ejemplo:
Method: DELETE
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/affiliates/31
Respuesta:
{
"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
}
}
Gestión de Creatividades
REST API Extended añade tres endpoints, uno para crear, otro para editar y otro para eliminar creatividades, además de los dos endpoints de solo lectura ya disponibles en el núcleo de AffiliateWP.
Los cinco endpoints utilizan los mismos dos patrones de ruta:
- Creatividades – Al recibir una solicitud GET, se devuelve una lista de creatividades que pueden filtrarse con argumentos adicionales. Al recibir una solicitud POST o PUT, se puede crear una nueva creatividad.
- Creatividades/[id] – Al recibir una solicitud GET, PATCH o DELETE, se puede recuperar, editar o eliminar una creatividad individual, respectivamente.
Ambas rutas también pueden aceptar solicitudes OPTIONS genéricas, que pueden ser muy útiles para descubrir información sobre los endpoints disponibles, los tipos de solicitud y argumentos aceptados, y el esquema de los elementos.
Ya sea que planees leer, escribir, editar o eliminar creatividades, este complemento lo hace posible.
Todas las solicitudes deben autenticarse utilizando claves API, que se generan y gestionan a través de la pestaña AffiliateWP → Herramientas → Claves API. Consulta el artículo REST API – Autenticación para obtener más información.
Crear una Creatividad
Las creatividades se pueden crear enviando una solicitud POST o PUT a la ruta creatives:
https://alfsflowersandgifts.com/wp-json/affwp/v1/creatives
El endpoint create acepta cualquiera de los siguientes argumentos de affwp_add_creative():
- Name – (integer) Etiqueta de nombre para la creatividad.
- Description – (string) Descripción de la creatividad.
- Url – (string) URL a la que apuntará la creatividad.
- Text – (string) Texto a mostrar con la creatividad.
- Image – (string) URL de la imagen a asociar con la creatividad.
- Status – (string) Estado de la creatividad. Acepta 'active' o 'inactive'. Por defecto 'active'.
Creando una creatividad
Method: PUT/POST
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/creatives/?name=New+Creative&text=REST
La nueva creatividad, llamada "New Creative", contendría el texto "REST".
Respuesta de ejemplo:
{
"creative_id": 20,
"name": "New Creative",
"description": "",
"url": "",
"text": "REST",
"image": "",
"status": "",
"date": "2024-01-26 09:25:05",
"id": 20
}
Editar una Creatividad Existente
Las creatividades individuales se pueden actualizar enviando una solicitud POST o PATCH a la ruta creatives/[id]:
https://alfsflowersandgifts.com/wp-json/affwp/v1/creatives/[id]
El endpoint edit acepta cualquiera de los siguientes argumentos de affwp_update_creative():
- Name – (integer) Etiqueta de nombre para la creatividad.
- Description – (string) Descripción de la creatividad.
- Url – (string) URL a la que apuntará la creatividad.
- Text – (string) Texto a mostrar con la creatividad.
- Image – (string) URL de la imagen a asociar con la creatividad.
- Status – (string) Estado de la creatividad. Acepta 'active' o 'inactive'.
Actualizando una Creatividad
En este ejemplo, actualizaremos el estado de una creatividad de activa a inactiva.
Method: POST/PATCH
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/creatives/20?status=inactive
Respuesta:
{
"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
}
Eliminar una Creatividad
Se puede eliminar enviando una solicitud DELETE a la ruta creatives/[id]:
https://alfsflowersandgifts.com/wp-json/affwp/v1/creatives/[id]
El endpoint delete no acepta argumentos adicionales. Cuando una creatividad se ha eliminado correctamente, se incluirá un par clave/valor de deleted: true en la respuesta, junto con una copia de la respuesta de la creatividad anterior.
Solicitud de ejemplo:
Method: DELETE
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/creatives/20
Respuesta:
{
"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
}
}
Gestión de Pagos
REST API Extended añade tres endpoints, uno para crear, otro para editar y otro para eliminar pagos, además de los dos endpoints de solo lectura ya disponibles en el núcleo de AffiliateWP.
Los cinco endpoints utilizan los mismos dos patrones de ruta:
- Pagos – Al recibir una solicitud GET, se devuelve una lista de pagos que pueden filtrarse con argumentos adicionales. Al recibir una solicitud POST o PUT, se puede crear un nuevo pago.
- Pagos/[id] – Al recibir una solicitud GET, PATCH o DELETE, se puede recuperar, editar o eliminar un pago individual, respectivamente.
Ambas rutas también pueden aceptar solicitudes genéricas OPTIONS, que pueden ser muy útiles para descubrir información sobre los endpoints disponibles, los tipos de solicitud y argumentos aceptados, y el esquema de los elementos.
Todas las solicitudes deben autenticarse utilizando claves API, que se generan y gestionan a través de la pestaña AffiliateWP → Herramientas → Claves API. Consulta el artículo REST API – Autenticación para obtener más información.
Creación de un pago
Los pagos se pueden crear enviando una solicitud POST o PUT a la ruta payouts:
https://alfsflowersandgifts.com/wp-json/affwp/v1/payouts
El endpoint create acepta cualquiera de los siguientes argumentos de affwp_add_payout():
- affiliate_id – (integer) ID del afiliado con el que asociar el pago. Este campo es obligatorio.
- referrals – (array|string) Matriz o lista separada por comas de IDs de referencia a incluir en el pago.
- amount – (float) Importe del pago (normalmente derivado de los importes de referencia).
- payout_method – (string) Método de pago.
- status – (string) Acepta ‘paid’ o ‘failed’. Por defecto ‘paid’.
Solicitud de ejemplo:
Method: PUT/POST
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/payouts/?affilite_id=30&referrals=10,15,20
El nuevo pago, con payout_id 15, cubriría las referencias 10, 15 y 20 para el affiliate_id 30.
Respuesta:
{
"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
}
Edición de un pago existente
Los pagos individuales se pueden actualizar enviando una solicitud POST o PATCH a la ruta payouts/[id]:
https://alfsflowersandgifts.com/wp-json/affwp/v1/payouts/[id]
El endpoint edit acepta cualquiera de los siguientes argumentos:
- affiliate_id – (integer) ID del afiliado con el que asociar el pago. Este campo es obligatorio.
- referrals – (array|string) Matriz o lista separada por comas de IDs de referencia a incluir en el pago.
- amount – (float) Importe del pago (normalmente derivado de los importes de referencia).
- payout_method – (string) Método de pago.
- status – (string) Acepta ‘paid’ o ‘failed’. Por defecto ‘paid’.
Actualización de un pago
En este ejemplo, actualizaremos el estado de un pago de failed a paid.
Method: POST/PATCH
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/payouts/15?status=paid
Respuesta:
{
"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
}
Eliminación de un pago
Un pago se puede eliminar enviando una solicitud DELETE a la ruta payouts/[id]:
https://alfsflowersandgifts.com/wp-json/affwp/v1/payouts/[id]
El endpoint delete no acepta argumentos adicionales. Cuando un pago se ha eliminado correctamente, se incluirá un par clave/valor de deleted: true en la respuesta, junto con una copia de la respuesta del pago anterior.
Solicitud de ejemplo:
Method: DELETE
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/payouts/15
Respuesta:
{
"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
}
}
Gestión de referencias
REST API Extended añade tres endpoints, uno para crear, editar y eliminar referencias, además de los dos endpoints de solo lectura ya disponibles en el núcleo de AffiliateWP.
Los cinco endpoints utilizan los mismos dos patrones de ruta:
- referrals – Cuando se envía una solicitud GET, se devuelve una lista de referencias y se pueden filtrar con argumentos adicionales. Cuando se envía una solicitud POST o PUT, se puede crear una nueva referencia.
- referrals/[id] – Cuando se envía una solicitud GET, PATCH o DELETE, se puede recuperar, editar o eliminar una referencia individual, respectivamente.
Ambas rutas también pueden aceptar solicitudes genéricas OPTIONS, que pueden ser muy útiles para descubrir información sobre los endpoints disponibles, los tipos de solicitud y argumentos aceptados, y el esquema de los elementos.
Todas las solicitudes deben autenticarse utilizando claves API, que se generan y gestionan a través de la pestaña AffiliateWP → Herramientas → Claves API. Consulta el artículo REST API – Autenticación para obtener más información.
Creación de una referencia
Las referencias se pueden crear enviando una solicitud POST o PUT a la ruta referrals:
https://alfsflowersandgifts.com/wp-json/affwp/v1/referrals
El endpoint create acepta cualquiera de los siguientes argumentos de affwp_add_referral():
- affiliate_id – (integer) ID del afiliado con el que asociar la referencia. Este campo es obligatorio. Ver user_id y user_name.
- user_id – (integer) ID de usuario utilizado para recuperar el ID de afiliado asociado si no se envía affiliate_id.
- user_name – (string) Nombre de usuario utilizado para recuperar el ID de afiliado asociado si no se envía affiliate_id.
- amount – (float) Importe final calculado de la referencia, no el importe de la transacción o la venta.
- currency – (string) Moneda del importe de la referencia.
- description – (string) Descripción de la referencia.
- referencia – (string) Referencia de referencia. Normalmente contiene información del producto, como los ID de producto.
- contexto – (string) Contexto en el que se creó la referencia. Normalmente es el slug de la integración.
- estado – (string) Acepta ‘pagado’, ‘no pagado’, ‘pendiente’ o ‘rechazado’. Por defecto ‘pendiente’.
Crear una referencia
Method: PUT/POST
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/referrals/?affilite_id=30&amount=15
Lo anterior crearía una nueva referencia asociada con el ID de afiliado 30 por un importe de 15 $ con el estado ‘pendiente’.
Respuesta de ejemplo:
{
"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
}
Editar una referencia existente
Las referencias individuales se pueden actualizar enviando una solicitud POST o PATCH a la ruta referrals/[id]:
https://alfsflowersandgifts.com/wp-json/affwp/v1/referrals/[id]
El punto final edit acepta cualquiera de los siguientes argumentos de affwp_process_update_referral():
- affiliate_id – (integer) ID del afiliado con el que asociar la referencia.
- visit_id – (integer) ID de la visita con la que asociar la referencia.
- amount – (float) Importe de referencia actualizado.
- currency – (string) Moneda del importe de referencia actualizado.
- description – (string) Descripción de referencia actualizada.
- referencia – (string) Referencia de referencia. Normalmente contiene información del producto, como los ID de producto.
- contexto – (string) Contexto en el que se creó la referencia. Normalmente es el slug de la integración.
- status – (string) Acepta ‘pagado’, ‘no pagado’, ‘pendiente’ o ‘rechazado’.
Actualizar una referencia
En este ejemplo, actualizaremos el estado de una referencia de pendiente a pagado.
Method: POST/PATCH
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/referrals/450?status=paid
Respuesta:
{
"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
}
Eliminar una referencia
Una referencia se puede eliminar enviando una solicitud DELETE a la ruta referrals/[id]:
https://alfsflowersandgifts.com/wp-json/affwp/v1/referrals/[id]
El punto final delete no acepta argumentos adicionales. Cuando una referencia se ha eliminado correctamente, se incluirá un par clave/valor de deleted: true en la respuesta, junto con una copia de la respuesta de la referencia anterior.
Solicitud de ejemplo:
Method: DELETE
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/referrals/450
Respuesta:
{
"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
}
}
Gestionar visitas
REST API Extended añade tres puntos finales, uno para crear, editar y eliminar visitas, además de los dos puntos finales de solo lectura ya disponibles en el núcleo de AffiliateWP.
Los cinco endpoints utilizan los mismos dos patrones de ruta:
- visits – Cuando se envía una solicitud GET, se devuelve una lista de visitas que se pueden filtrar con argumentos adicionales. Cuando se envía una solicitud POST o PUT, se puede crear una nueva referencia.
- visits/[id] – Cuando se envía una solicitud GET, PATCH o DELETE, se puede recuperar, editar o eliminar una visita individual, respectivamente.
Ambas rutas también pueden aceptar solicitudes genéricas OPTIONS, que pueden ser muy útiles para descubrir información sobre los endpoints disponibles, los tipos de solicitud y argumentos aceptados, y el esquema de los elementos.
Todas las solicitudes deben autenticarse utilizando claves API, que se generan y gestionan a través de la pestaña AffiliateWP → Herramientas → Claves API. Consulta el artículo REST API – Autenticación para obtener más información.
Crear una visita
Las visitas se pueden crear enviando una solicitud POST o PUT a la ruta de visitas:
https://alfsflowersandgifts.com/wp-json/affwp/v1/visits
El punto final create acepta cualquiera de los siguientes argumentos:
- affiliate_id – (integer) ID del afiliado con el que asociar la visita. Este campo es obligatorio.
- referral_id – (integer) ID de la referencia con la que asociar la visita.
- url – (string) URL de la visita.
- referrer – (string) URL de referencia
- campaign – (string) Campaña asociada.
- ip – (string) Dirección IP del visitante.
Solicitud de ejemplo:
Method: PUT/POST
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/visits/?affilite_id=30&url=https%3A%2F%2Faffiliatewp.com
Lo anterior crearía una nueva visita asociada con el ID de afiliado 30 que tiene una URL almacenada de https://affiliatewp.com.
Respuesta:
{
"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
}
Edición de una visita existente
Las visitas individuales se pueden actualizar enviando una solicitud POST o PATCH a la ruta visits/[id]:
https://alfsflowersandgifts.com/wp-json/affwp/v1/visits/[id]
El endpoint edit acepta cualquiera de los siguientes argumentos:
- visit_id – (integer) ID de la visita. Este campo es obligatorio.
- referral_id – (integer) ID de la referencia con la que asociar la visita.
- affiliate_id – (integer) ID del afiliado a asociar con la visita.
- url – (string) URL de la visita.
- referrer – (string) URL de referencia
- campaign – (string) Campaña asociada.
- ip – (string) Dirección IP del visitante.
Actualización de una visita
En este ejemplo, actualizaremos la campaña asociada de una visita:
Method: POST/PATCH
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/visits/541?campaign=spring-sale
Respuesta:
{
"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
}
Eliminación de una visita
Una visita se puede eliminar enviando una solicitud DELETE a la ruta visits/[id]:
https://alfsflowersandgifts.com/wp-json/affwp/v1/visits/[id]
El endpoint delete no acepta argumentos adicionales. Cuando una visita se ha eliminado correctamente, se incluirá un par clave/valor de deleted: true en la respuesta, junto con una copia de la respuesta de la visita anterior.
Solicitud de ejemplo:
Method: DELETE
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/visits/541
Respuesta:
{
"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
}
}
Ejemplo: Integración de la API REST entre dos sitios de WordPress
Uno de los casos de uso más comunes para el complemento REST API Extended es permitir que un sitio de WordPress interactúe con otro sitio que ejecuta AffiliateWP.
Por ejemplo, podría crear un afiliado en un sitio de WordPress (Sitio A) y registrarlo como afiliado en un sitio separado con tecnología de WordPress (Sitio B) utilizando la API. Esta integración permite una comunicación fluida entre los dos sitios.
Los siguientes ejemplos asumen que tiene un conocimiento básico sobre cómo WordPress maneja el envío de solicitudes remotas y la obtención de respuestas.
Si no está familiarizado con la API HTTP o la API REST, le recomendamos que consulte el artículo de la API HTTP en el manual oficial para desarrolladores de complementos, así como el manual de la API REST.
Descubrimiento de información
Como se describe en las secciones de Gestión de afiliados, creatividades, pagos, referencias y visitas, el complemento REST API Extended aporta capacidades completas de CRUD (Crear, Leer, Actualizar y Eliminar) al interactuar con AffiliateWP de forma remota.
En su mayor parte, las respuestas remotas se estructuran de manera consistente en todos los tipos de objetos. Dicho esto, dependiendo del endpoint utilizado, ciertos campos específicos de los tipos de objeto dados serán necesarios en diversas circunstancias.
La forma más fácil de determinar qué campos son obligatorios o qué parámetros se aceptan es enviar una solicitud OPTIONS al endpoint; la respuesta de la solicitud OPTIONS debería decirle todo lo que necesita saber.
Por ejemplo, la siguiente es una sección de la respuesta de una solicitud OPTIONS enviada al endpoint /v1/creatives/ con REST API Extended activado:
{
"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"
}
}
}
],
Puede ver que los métodos de solicitud disponibles para este endpoint están claramente listados y los argumentos disponibles para cada uno están definidos y listados dentro de la jerarquía a continuación. Otra información útil devuelta en una solicitud OPTIONS incluye información del esquema, que define los campos que estarán presentes en un solo objeto, y más.
Creación de solicitudes
Ahora que tienes una buena base sobre lo que necesitas saber y cómo obtener más información, vamos a crear algunas solicitudes de ejemplo.
Autenticación
Si recuerdas del artículo Descripción general de la API REST v1, todas las solicitudes enviadas deben incluir una cabecera de autorización creada utilizando el esquema de autenticación básica. La cabecera de autenticación básica en AffiliateWP se logra utilizando los valores de la clave pública y el token. El siguiente es un ejemplo de una cabecera de autenticación básica:
Authorization : Basic N2Q4NTM1OWM4NzlkYWNjOWE2ZmMxZjgxYjQ2ZDYyZDE6YmE3YjUwZGUyMjZkOGI2YzRkNjQyMjA1YjcwNDUwMjY=
“Authorization” es la clave y “Basic N2Q4NTM…” es el valor. El valor se crea codificando la combinación de los valores de la clave pública y el token, separados por dos puntos, y anteponiendo “Basic ”. Por ejemplo:
"Basic " . base64_encode( "{$public_key}:{$token}" );
Al utilizar las funciones de la API HTTP de WordPress, la cabecera Authorization debe enviarse de la siguiente manera:
wp_remote_*( 'request_url', array(<br> 'headers' => array(<br> 'Authorization' => 'Basic hash_value'<br> )<br>) );
Para obtener más información sobre cómo se autentica la API REST de AffiliateWP, consulta el artículo API REST – Autenticación.
Solicitud de ejemplo: Crear un afiliado
Como se indica en la sección Gestión de afiliados, se requiere un user_id al crear un afiliado. Alternativamente, el argumento create_user se puede enviar junto con un valor payment_email para crear un usuario y un afiliado en el mismo paso.
El siguiente es el código de WordPress necesario para crear remotamente un afiliado cuando ya tienes un user_id válido:
$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'
)
) );
En el fragmento anterior, ten en cuenta que el valor user_id se pasa a través de $request_url en lugar de a través del argumento 'body', lo cual es compatible con las solicitudes POST. Esto se hace por coherencia con los ejemplos de otros puntos finales, concretamente aquellos que utilizan los métodos PUT o PATCH, que no admiten el envío de parámetros a través del cuerpo de la solicitud.
Solicitud de ejemplo: Crear un pago
De manera similar a la creación de afiliados, los nuevos pagos también requieren ciertos campos, específicamente los valores affiliate_id y referrals.
El siguiente es el código necesario para crear remotamente un nuevo pago, dado un affiliate_id válido y una lista de IDs de referencia:
$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'
)
) );
Ten en cuenta que el valor payout_method no es necesariamente necesario, solo es útil para proporcionar contexto de que el pago se generó a través de REST.
Solicitud de ejemplo: Actualizar una referencia
Al actualizar un objeto a través de REST, vale la pena señalar que, dado que el ID del objeto que estás modificando forma parte del punto final, el valor de esa clave principal no necesita enviarse también con la solicitud.
El siguiente es un ejemplo de cómo actualizar el estado de una referencia de no pagada a pagada:
$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'
)
) );
Ten en cuenta que en lugar de wp_remote_post() como antes, esta solicitud utiliza wp_remote_request() con el argumento 'method' => 'PATCH' pasado. Esto le dice a la API REST que estás enviando específicamente una solicitud PATCH.
Además, ten en cuenta que el ID de referencia 3 se pasa como parte del punto final en lugar de en el estado similar a una URL.
Analizar respuestas
Además de elaborar solicitudes, es importante tener un buen dominio de cómo se estructuran las respuestas y estar familiarizado con cómo validar que una solicitud se realizó correctamente dentro del ámbito de WordPress.
En los dos primeros ejemplos bajo “Building Requests” hablamos sobre cómo elaborar solicitudes para crear nuevos afiliados y pagos.
Al examinar una respuesta, una de las formas más sencillas de confirmar que ha sido exitosa es observar el código de respuesta:
$response_code = wp_remote_retrieve_response_code( $response );
if ( 201 === $response_code ) {
// success
}
En el caso de los endpoints de creación y actualización de AffiliateWP, las solicitudes exitosas enviarán respuestas con el código de estado 201. Para las solicitudes de eliminación exitosas, los códigos de respuesta serán el valor predeterminado 200.
Las respuestas enviadas para solicitudes de eliminación exitosas también incluirán un par clave:valor de deleted: true, junto con una copia del objeto anterior:
{
"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
}
}
Ahora que hemos cubierto cómo elaborar solicitudes y analizar respuestas, veamos cómo elaborar una solicitud de crear afiliado, luego examinar y proceder a analizar la información recuperada en caso de éxito:
$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
}
Preguntas frecuentes
¿Qué es el complemento REST API Extended para AffiliateWP?
El complemento REST API Extended para AffiliateWP proporciona a los desarrolladores capacidades completas de CRUD (Crear, Leer, Actualizar, Eliminar) para administrar datos de afiliados a través de solicitudes de API. Este complemento extiende la API REST principal de AffiliateWP agregando endpoints que permiten a las aplicaciones externas crear, modificar y eliminar afiliados, referencias, pagos, creatividades y visitas.
¿Cómo autentico las solicitudes de API utilizando la API REST de AffiliateWP?
Para autenticar las solicitudes de API, necesitará generar claves de API desde AffiliateWP » Herramientas » Claves de API en su panel de WordPress. La autenticación se maneja mediante Autenticación Básica, donde la clave pública y el token se codifican y se pasan en las cabeceras de la solicitud.
¿Qué puedo hacer con el complemento REST API Extended?
Con este complemento, puede realizar una variedad de acciones, que incluyen crear nuevos afiliados, actualizar información de afiliados, administrar referencias, pagos y visitas, y eliminar datos de afiliados. Le da control total sobre la administración de afiliados a través de la API.
¿Qué sucede si elimino un afiliado, referencia o pago a través de la API?
Cuando elimina un afiliado, referencia o pago a través de la API, se devolverá una respuesta con el valor deleted: true, junto con una copia del objeto eliminado. Esto asegura que la acción se completó con éxito y le permite verificar los detalles del elemento eliminado.
¡Eso es todo! El complemento REST API Extended para AffiliateWP brinda a los desarrolladores una herramienta poderosa para administrar afiliados, referencias, pagos, creatividades y visitas de forma programática. Al habilitar operaciones CRUD completas, este complemento abre una gama de posibilidades para integrar AffiliateWP con sistemas externos, automatizar procesos y personalizar la administración de afiliados para satisfacer necesidades específicas.