Checkout Guard ahora tiene una API de lista de bloqueo de WooCommerce documentada. Su herramienta antifraude, mesa de ayuda o script de sincronización puede agregar, eliminar y buscar reglas de bloqueo sin una sesión de navegador. Un cliente puede ser bloqueado en el momento en que algo más en su pila decida que debería serlo.
La API de la lista de bloqueo de WooCommerce se documenta por primera vez en Checkout Guard 1.0.2, que también agrega los endpoints /check y batch, bajo el namespace cgfw/v1. Es el mismo conjunto de rutas que utiliza la propia pantalla de administración del plugin, lo que importa más de lo que parece. No hay una segunda implementación que se desvíe de lo que realmente sucede en el checkout.
Tabla de Contenidos
- Para qué sirve la API de la lista de bloqueo de WooCommerce
- Autenticación con una contraseña de aplicación
- Los Endpoints
- Qué puede contener una regla
- Creación de reglas sin crear duplicados
- Sincronización de una lista completa en una solicitud
- Preguntar si un cliente sería bloqueado
- Búsqueda de reglas y saber de dónde provienen
- Qué rechazará la API
- Conclusión
- Preguntas Frecuentes
Para qué sirve la API de la lista de bloqueo de WooCommerce
La mayoría de las listas de bloqueo comienzan manualmente. Alguien realiza un pedido que no querías, abres la administración y lo agregas.
Eso funciona mientras el volumen es bajo y las decisiones son tuyas. Deja de funcionar cuando la señal vive en otro lugar. Un servicio de puntuación de fraude marca un pedido. Tu agente de soporte cierra un ticket sobre un cliente abusivo. Una contracargo llega a tu proveedor de pagos. En cada caso, algo ya sabe que la persona debe ser bloqueada, y la única pieza que falta es una forma de decirlo sin que un humano abra WordPress.
Esa es la brecha que esto cierra. La API de lista de bloqueo de WooCommerce está diseñada para llamadores automáticos: sin cookie, sin nonce, sin pantalla de administración.
Autenticación con una contraseña de aplicación
Los llamadores automáticos se autentican con una Contraseña de Aplicación de WordPress a través de HTTP Basic Auth. No hay una clave separada de Checkout Guard para crear.
Según la documentación de WordPress sobre contraseñas de aplicación, creas una en Usuarios → Perfil → Contraseñas de aplicación, le das un nombre como automatización de Checkout Guard. Copia el valor generado. Se muestra una vez, en el formato xxxx xxxx xxxx xxxx xxxx xxxx, y los espacios forman parte de él. Usa el nombre de usuario de la cuenta como nombre de usuario de Basic Auth y esa contraseña como contraseña de Basic Auth.
Un requisito es fácil de pasar por alto. Cada ruta en la API de lista de bloqueo de WooCommerce verifica la capacidad manage_woocommerce, por lo que la cuenta detrás de la Contraseña de Aplicación debe ser un Administrador o un Gerente de Tienda. Una contraseña que pertenezca a cualquier otro usuario se autentica perfectamente bien y luego se rechaza con un 403. Las credenciales faltantes te dan un 401 en su lugar, lo cual es una forma útil de distinguir los dos fallos.
Las Contraseñas de Aplicación requieren WordPress 5.6 o más reciente y un sitio servido a través de HTTPS. Checkout Guard en sí mismo soporta WordPress 5.2, por lo que en un sitio 5.2 a 5.5 esta ruta de autenticación no existe.
Los Endpoints
Ocho rutas componen la API de lista de bloqueo de WooCommerce, cubriendo la lista de bloqueo y su configuración.
| Método | Ruta | Propósito |
|---|---|---|
| GET | /entries | Listar entradas, opcionalmente filtradas |
| POST | /entries | Crear una entrada, idempotente |
| POST | /entries/batch | Crear y eliminar en lote |
| PUT | /entries/{id} | Actualizar una entrada por id |
| DELETE | /entries/{id} | Eliminar una entrada por id |
| POST | /check | ¿Se bloquearía a este cliente? |
| GET | /settings | Leer configuración |
| POST | /settings | Actualizar configuración |
La URL base es https://tu-tienda.ejemplo.com/wp-json/cgfw/v1. Si esas URLs devuelven un 404, comprueba el prefijo REST de tu sitio, ya que /wp-json/ es el predeterminado en lugar de una garantía. Un sitio con permalinks simples usa la forma ?rest_route= en su lugar.
Listar el espacio de nombres muestra dos rutas más, /license y /license/activate. Esas pertenecen a la pantalla de activación de licencia del propio plugin en lugar de a la lista de bloqueo, y no forman parte de la API descrita aquí.
Qué puede contener una regla
Una entrada bloqueada lleva un id, un nombre y apellidos opcionales, un correo electrónico opcional, una dirección IP opcional y notas opcionales de hasta 140 caracteres. También registra el id del usuario que la creó y un campo de procedencia. Al menos uno de los campos de nombre, correo electrónico o IP debe estar rellenado.
Una entrada bloquea a un cliente cuando cualquiera de sus campos rellenados coincide. Coinciden ambos nombres, o coincide el correo electrónico, o coincide la dirección IP. Los nombres y correos electrónicos se comparan sin distinguir mayúsculas y minúsculas. La IP del cliente al finalizar la compra se resuelve a través del ayudante de geolocalización de WooCommerce, de modo que un proxy o una CDN delante de tu tienda no rompa la comparación.
Los valores de nombre, correo electrónico e IP aceptan cada uno un comodín de *, por lo que una regla puede cubrir un dominio de correo electrónico completo o un rango IPv4. Los comodines de IP son más restrictivos que los otros: solo en formato de segmento IPv4, por lo que 192.168.1.* funciona y 2001:db8::* no.
El campo notes merece una nota propia. Es un campo de la API. Aparece como una columna en la tabla de Entradas Bloqueadas, y es de donde esa columna obtiene su contenido, pero no hay una entrada de notas en el diálogo de añadir entrada. Si quieres que tus reglas se expliquen solas más adelante, la API es el camino para configurarlo.
Creación de reglas sin crear duplicados
POST /entries es idempotente, que es la propiedad que hace que sea seguro llamarlo desde algo que no controlas por completo.
Si ya existe una entrada con el mismo correo electrónico, se actualiza con los campos no vacíos que envíes y se te devuelve. Sin correo electrónico, el mismo nombre y apellido identifican la entrada. Sin ninguno de los dos, lo hace la misma dirección IP. Llamarlo dos veces con el mismo correo electrónico te da exactamente una entrada, no dos.
curl -X POST https://your-store.example.com/wp-json/cgfw/v1/entries \
--user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx" \
-H "Content-Type: application/json" \
-d '{"email":"[email protected]","notes":"chargeback fraud"}'El bloqueo puramente por conexión funciona de la misma manera.
curl -X POST https://your-store.example.com/wp-json/cgfw/v1/entries \
--user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx" \
-H "Content-Type: application/json" \
-d '{"ip_address":"203.0.113.42","notes":"repeat spammer"}'Lo que hemos visto: las integraciones que causan problemas son las que asumen que una creación es una creación. Un reintento después de un tiempo de espera de red, una webhook entregada dos veces, un trabajo nocturno que reenvía las filas de ayer, y de repente una lista de bloqueo tiene cuatro copias de la misma persona y nadie puede decir cuál es la actual. La idempotencia en el correo electrónico, el nombre y la IP es lo que detiene eso, así que envía el campo identificador cada vez en lugar de solo en la primera llamada.
Sincronización de una lista completa en una solicitud
POST /entries/batch toma un array create y un array delete, que es la forma que deseas cuando otro sistema posee la lista y WordPress es el seguidor.
{
"create": [
{ "email": "[email protected]", "notes": "ring leader" },
{ "first_name": "Jane", "last_name": "Doe" }
],
"delete": [ "11112222-3333-4444-5555-666677778888" ]
}Las creaciones se ejecutan primero, cada una a través de la misma ruta idempotente que una creación individual, luego las eliminaciones por id. Al menos uno de los dos arrays tiene que no estar vacío. La respuesta te dice lo que sucedió en lugar de hacerte comparar la lista tú mismo:
{
"created": [ { "id": "…", "email": "[email protected]" } ],
"deleted": [ "11112222-3333-4444-5555-666677778888" ],
"not_found": [],
"skipped": 0
}not_found recopila los ids de eliminación que no coincidieron con nada. skipped cuenta las cargas de creación que se ignoraron porque no llevaban nombre, correo electrónico o IP, o porque su IP no estaba vacía y era inválida. Un lote que contiene filas incorrectas todavía devuelve 200, así que lee skipped en lugar de confiar solo en el código de estado.
Preguntar si un cliente sería bloqueado
POST /check responde la pregunta directamente, y ejecuta el mismo código de coincidencia que el guardia de pago en vivo. La respuesta no puede desviarse de lo que experimenta un comprador real, que es el propósito de su existencia en lugar de que tú reimplementes la lógica.
curl -X POST https://your-store.example.com/wp-json/cgfw/v1/check \
--user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx" \
-H "Content-Type: application/json" \
-d '{"email":"[email protected]"}'La respuesta es { "blocked": true, "matched_entry": { … } }, con matched_entry establecido en null cuando no coincide nada. Saber qué regla ha bloqueado a alguien suele ser más útil que saber que algo lo ha hecho.
Este endpoint es deliberadamente más estricto que los otros. Un candidato es un valor de cliente real, nunca un patrón, por lo que un * en cualquier campo se rechaza con un 400. Las búsquedas de reglas van en la otra dirección: GET /entries?email=*@example.com encuentra esa regla almacenada exacta, porque las búsquedas comparan literalmente y nunca expanden un comodín.
Búsqueda de reglas y saber de dónde provienen
GET /entries sin parámetros devuelve todo. Añade email, first_name, last_name o ip_address para filtrar, combinado con AND cuando envíes más de uno, y comparado sin distinguir mayúsculas y minúsculas.
Cada entrada también lleva un campo source que registra de dónde provino: api cuando se creó a través de una Contraseña de Aplicación, y admin en caso contrario. Cuando una lista de bloqueo es mantenida tanto por personas como por máquinas, esa distinción es lo que te permite auditar una sin perturbar la otra.
Los endpoints de configuración completan las opciones, aunque solo hay una configuración para leer o escribir. checkout_denial_message es el mensaje que ve un comprador bloqueado, y no puede estar vacío.
Qué rechazará la API
Cuatro rechazos merecen ser conocidos antes de conectar nada, porque cada uno es deliberado.
- Una dirección IP mal formada se rechaza con un
400en la creación y actualización, y se omite y cuenta en un lote. - Los comodines desnudos son rechazados en todas partes. Al eliminar los asteriscos, espacios en blanco y separadores de
*,*@*o*.*no queda nada, y una regla que coincida con todos los clientes es una interrupción en lugar de un bloqueo. - Más de cinco comodines en un solo valor falla por la misma razón.
- Se rechaza una entrada sin nombre, sin correo electrónico y sin IP, ya que no habría nada con lo que coincidir.
Conclusión
La API de lista de bloqueo de WooCommerce convierte tus reglas de algo que mantienes a algo que tu pila mantiene por ti. Mismas reglas, mismo matching, mismo comportamiento en el checkout, accesible desde cualquier cosa que ya sepa que un cliente es un problema.
Si eres nuevo en el plugin, nuestra introducción a Checkout Guard cubre lo que hace la lista de bloqueo. Para una visión más amplia, nuestra guía sobre flujos de trabajo de automatización de datos de WooCommerce y nuestro tutorial sobre exportar datos de WooCommerce a Zapier cubren los otros lugares donde la automatización vale la pena.
Una última cosa que vale la pena decir claramente. Las entradas bloqueadas son datos personales, y una dirección IP es un identificador en línea bajo el RGPD, que el Considerando 30 nombra directamente. Una API facilita la acumulación de muchos de ellos rápidamente, así que decide cuánto tiempo los conservas antes de abrir el grifo.
La API de lista de bloqueo de WooCommerce está disponible en Checkout Guard 1.0.2.
Preguntas Frecuentes
¿Cómo me autentico con la API de la lista de bloqueo de WooCommerce?
Usa una Contraseña de Aplicación de WordPress sobre autenticación HTTP básica. Crea una en Usuarios → Perfil → Contraseñas de Aplicación, luego envía el nombre de inicio de sesión de la cuenta como nombre de usuario y la contraseña generada como contraseña. No se necesitan cookies ni nonces.
¿Por qué obtengo un 403 si mis credenciales son correctas?
Cada ruta requiere la capacidad manage_woocommerce. Una Contraseña de Aplicación perteneciente a un usuario sin ella se autentica correctamente y luego es rechazada. Usa una cuenta de Administrador o Gerente de Tienda. Un 401 significa que no llegaron credenciales.
¿Llamar al endpoint create dos veces agregará un duplicado?
No. POST /entries es idempotente. Una entrada con el mismo correo electrónico se actualiza y se devuelve en lugar de duplicarse. Lo mismo se aplica a un nombre y apellido coincidentes cuando no se proporciona correo electrónico, o a una dirección IP coincidente cuando no se proporciona ninguna.
¿Puedo sincronizar toda mi lista de bloqueo desde otro sistema?
Sí. POST /entries/batch acepta una matriz create y una matriz delete en una sola solicitud y devuelve un resumen de lo que se creó, eliminó, no se encontró y se omitió. Las creaciones se ejecutan antes que las eliminaciones.
¿La API de la lista de bloqueo de WooCommerce utiliza la misma lógica de bloqueo que el checkout?
Sí. POST /check reutiliza el mismo código coincidente que el guardia de pago en vivo, por lo que su respuesta no puede diferir de lo que experimenta un cliente real. Devuelve si el cliente está bloqueado y qué entrada coincidió.
¿Puedo usar comodines a través de la API?
Sí, en los valores de las reglas. Los campos de nombre, correo electrónico e IP aceptan un comodín * en la creación y actualización. El punto final /check es la excepción y rechaza los comodines, porque un candidato de verificación es un valor de cliente real en lugar de un patrón.
