Referencia de la API REST de Checkout Guard

A veces quieres bloquear a un cliente sin abrir el administrador de WordPress. Quizás un servicio de puntuación de fraude marque un pedido, o una herramienta de ayuda marque a alguien como abusivo. Checkout Guard incluye una API REST para que tus propios scripts y herramientas puedan leer y gestionar tus entradas bloqueadas, y comprobar si un cliente sería bloqueado.

Todas las rutas viven bajo un único espacio de nombres, cgfw/v1. Este artículo enumera cada ruta para entradas bloqueadas y configuraciones, lo que acepta, lo que devuelve y los errores que puedes encontrar. El espacio de nombres también tiene dos rutas de licencia que utiliza la pantalla de configuración del propio plugin. Este artículo no las cubre.

Esta es una referencia para desarrolladores. Asume que te sientes cómodo realizando solicitudes HTTP con una herramienta como curl. Si solo quieres añadir o eliminar una entrada bloqueada manualmente, ve a WooCommerce → Checkout Guard en tu administrador. Para problemas comunes de bloqueo, consulta la guía de solución de problemas de Checkout Guard.

Prerrequisitos

Requisito	Detalles
Complemento	Checkout Guard 1.0.2 o posterior. Las rutas /check y /entries/batch, y la coincidencia de comodines, forman parte de la versión 1.0.2.
WordPress	5.6 o posterior para usar contraseñas de aplicación. Checkout Guard en sí admite WordPress 5.2 y superior, pero los sitios de 5.2 a 5.5 no pueden usar el método de autenticación a continuación.
Rol de usuario	Un usuario con la capacidad manage_woocommerce, como un Administrador o Gerente de Tienda.
Conexión	HTTPS. WordPress solo habilita las contraseñas de aplicación en sitios HTTPS, o en sitios donde WP_ENVIRONMENT_TYPE está configurado como local.

URL base y formato de solicitud

Cada ruta comienza con la URL base REST de tu sitio seguida del espacio de nombres:

https://your-store.example.com/wp-json/cgfw/v1

En cada ejemplo a continuación, reemplaza your-store.example.com con tu propio dominio.

Si tu sitio usa permalinks simples, /wp-json/ no funcionará. Usa la forma rest_route en su lugar:

https://your-store.example.com/?rest_route=/cgfw/v1/entries

Envía cuerpos de solicitud como JSON y establece la cabecera Content-Type: application/json. Las respuestas también son JSON. Si una URL devuelve un 404, comprueba primero la base REST de tu sitio.

Autenticación

Cada ruta necesita la capacidad manage_woocommerce, por lo que solo los Administradores y Gerentes de Tienda pueden llamar a la API. Para scripts y otros llamadores automatizados, usa una Contraseña de Aplicación de WordPress. Firma cada solicitud como un usuario específico con autenticación HTTP Basic. No necesitas una cookie ni un nonce.

Para crear una Contraseña de Aplicación:

1. Inicia sesión como Administrador o Gerente de Tienda y ve a Usuarios → Perfil.
2. Desplázate hacia abajo hasta la sección Contraseñas de Aplicación.
3. Introduce un nombre, como Checkout Guard automation, en el campo Nombre de Nueva Contraseña de Aplicación.
4. Haz clic en Añadir Contraseña de Aplicación.
5. Copia la contraseña ahora, porque WordPress solo la muestra una vez. Parece xxxx xxxx xxxx xxxx xxxx xxxx. Puedes enviarla con o sin espacios.

Usa el nombre de usuario de ese usuario como nombre de usuario y la Contraseña de Aplicación como contraseña:

curl https://your-store.example.com/wp-json/cgfw/v1/entries \
  --user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx"

La API responde a los problemas de autenticación de dos maneras:

• Sin credenciales: obtienes 401 Unauthorized.
• Credenciales válidas, pero el usuario carece de manage_woocommerce: obtienes 403 Forbidden. Una Contraseña de Aplicación para una cuenta de Cliente o Editor inicia sesión correctamente pero aún así es rechazada.

La pantalla de administración de Checkout Guard utiliza estas mismas rutas. Se autentica con la cookie de tu sesión iniciada más una cabecera X-WP-Nonce. Solo necesitas ese enfoque si tu propio código se ejecuta dentro del administrador de WordPress.

Resumen de rutas

Las rutas son relativas a /wp-json/cgfw/v1.

Método	Ruta	Propósito
OBTENER	/entradas	Lista las entradas bloqueadas, opcionalmente filtradas.
POST	/entradas	Crea una entrada. Seguro de repetir.
POST	/entradas/lote	Crea y elimina muchas entradas en una sola solicitud.
PUT	/entradas/{id}	Actualiza una entrada.
ELIMINAR	/entradas/{id}	Elimina una entrada.
POST	/comprobar	Averigua si un cliente sería bloqueado.
OBTENER	/ajustes	Lee la configuración del plugin.
POST	/ajustes	Actualiza la configuración del plugin.

Cómo funciona una entrada bloqueada

Cada entrada bloqueada tiene estos campos:

Campo	Tipo	Detalles
id	cadena	Un UUID que Checkout Guard asigna cuando creas la entrada.
nombre	cadena	Opcional. Admite un comodín *, como jo*.
apellidos	cadena	Opcional. Admite un comodín *, como sm*th.
correo_electronico	cadena	Opcional. Admite un comodín *, como *@example.com.
direccion_ip	cadena	Opcional. Una única dirección IPv4 o IPv6, o un comodín IPv4 como 192.168.1.*.
notas	cadena	Opcional. Limitado a 140 bytes, que son 140 caracteres para texto latino plano y menos para otros scripts.
created_by_user_id	entero	El usuario que creó la entrada.
fuente	cadena	api cuando la entrada se creó con una contraseña de aplicación, de lo contrario admin.

Debes enviar al menos uno de first_name, last_name, email o ip_address. Un nombre solo bloquea cuando la entrada tiene nombre y apellidos.

Una entrada bloquea a un cliente cuando se cumple alguna de estas condiciones:

• Tanto su nombre como sus apellidos coinciden con el nombre del cliente.
• Su correo electrónico coincide con el correo electrónico del cliente.
• Su dirección IP coincide con la dirección IP del cliente al finalizar la compra.

La coincidencia de nombre y correo electrónico ignora mayúsculas y minúsculas. La coincidencia de dirección IP es exacta.

Checkout Guard lee la dirección IP del cliente de la misma manera que WooCommerce, por lo que sigue las cabeceras de proxy comunes.

Reglas de comodín

Los valores de nombre y correo electrónico pueden usar * para coincidir con cero o más caracteres. La coincidencia se ancla a todo el valor, por lo que john* coincide con johnny pero no con ajohn. Cualquier otro carácter, incluido ., coincide literalmente.

Las direcciones IP aceptan comodines solo en formato IPv4. Usa exactamente cuatro segmentos, donde cada segmento es o bien solo dígitos o bien exactamente *, y al menos un segmento es un dígito.

Cada segmento de dígitos debe ser de 0 a 255 sin ceros iniciales, por lo que 192.168.01.* y 256.1.1.* se rechazan con 400.

Valor	Resultado
192.168.1.*, 192.168.*.1, 192.*.*.1	Aceptado
*.*.*.*	Rechazado con 400. Sin segmento de dígitos.
19*.168.1.1	Rechazado con 400. Segmento mixto.
1.2.3.*.5	Rechazado con 400. Cinco segmentos.
2001:db8::*	Rechazado con 400. Los comodines IPv6 no son compatibles.

Unos límites más se aplican a cada campo:

• Sin comodines simples. Un valor que coincide con todo, como *, **, *@* o *.*, se rechaza con 400. *@example.com está bien porque tiene texto literal restante.
• Como máximo 5 comodines. Un valor con 6 o más caracteres * se rechaza con 400.
• Las creaciones por lotes omiten valores incorrectos. En una solicitud por lotes, un elemento rechazado no se guarda. Se cuenta en el total skipped, y la propia solicitud sigue devolviendo 200.
• Las búsquedas permanecen literales. Cuando filtras GET /entries o envías una creación repetida, * se trata como un carácter normal. Una regla de comodín y un valor literal con los mismos caracteres son siempre entradas separadas.

Endpoints

Listar entradas

GET /entries devuelve una matriz de entradas. Añade cualquiera de los parámetros de consulta email, first_name, last_name o ip_address para filtrar la lista. Los filtros de nombre y correo electrónico son coincidencias exactas, sin distinción entre mayúsculas y minúsculas. El filtro ip_address es una coincidencia exacta. Varios filtros se combinan con AND. Un email o ip_address no válido devuelve 400.

Cada entrada en la lista también incluye created_by_display_name y created_by_edit_url cuando el usuario creador todavía existe.

curl https://your-store.example.com/wp-json/cgfw/v1/entries \
  --user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx"

# Look up one email
curl "https://your-store.example.com/wp-json/cgfw/v1/[email protected]" \
  --user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx"

Respuesta:

[
  {
    "id": "11112222-3333-4444-5555-666677778888",
    "first_name": "",
    "last_name": "",
    "email": "[email protected]",
    "ip_address": "",
    "notes": "chargeback fraud",
    "created_by_user_id": 2,
    "source": "api",
    "created_by_display_name": "Shop Manager",
    "created_by_edit_url": "https://your-store.example.com/wp-admin/user-edit.php?user_id=2"
  }
]

Crear una entrada

POST /entries crea una entrada y la devuelve. Repetir la misma solicitud no crea un duplicado. Si ya existe una entrada con el mismo email, Checkout Guard la actualiza con cualquier campo no vacío que envíes y la devuelve. Cuando no envías un email, coincide con el mismo nombre y apellido. Cuando no envías ninguno, coincide con la misma ip_address.

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

Respuesta:

{
  "id": "11112222-3333-4444-5555-666677778888",
  "first_name": "",
  "last_name": "",
  "email": "[email protected]",
  "ip_address": "",
  "notes": "chargeback fraud",
  "created_by_user_id": 2,
  "source": "api"
}

Para bloquear solo por dirección IP, envía {"ip_address":"203.0.113.42","notes":"repeat spammer"}. Una ip_address no vacía que no sea válida devuelve 400.

Crear y eliminar en bloque

POST /entries/batch te permite sincronizar una lista completa en una sola solicitud. Envía un array create, un array delete de IDs de entrada, o ambos. Checkout Guard procesa primero las creaciones, cada una a través de la misma ruta segura contra repeticiones que una creación individual. Luego procesa las eliminaciones. Al menos uno de los dos arrays debe contener algo, o recibirás 400.

curl -X POST https://your-store.example.com/wp-json/cgfw/v1/entries/batch \
  --user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "create": [
      { "email": "[email protected]", "notes": "ring leader" },
      { "first_name": "Jane", "last_name": "Doe" }
    ],
    "delete": [ "99998888-7777-6666-5555-444433332222" ]
  }'

Respuesta:

{
  "created": [
    {
      "id": "aaaa1111-2222-3333-4444-555566667777",
      "first_name": "",
      "last_name": "",
      "email": "[email protected]",
      "ip_address": "",
      "notes": "ring leader",
      "created_by_user_id": 2,
      "source": "api"
    }
  ],
  "deleted": [ "99998888-7777-6666-5555-444433332222" ],
  "not_found": [],
  "skipped": 0
}

Campo de respuesta	Significado
creado	Las entradas que fueron creadas o actualizadas.
eliminado	Los IDs que fueron eliminados.
no_encontrado	Elimina IDs que no coincidieron con ninguna entrada.
omitido	Cuántos elementos de creación fueron ignorados. Se omite un elemento cuando no tiene nombre, email o dirección IP, o cuando tiene una dirección IP o comodín no válidos.

Actualizar o eliminar una entrada

PUT /entries/{id} cambia una entrada. Envía solo los campos que deseas cambiar. La respuesta es la entrada completa actualizada. No puedes borrar todos los campos identificativos. La entrada debe conservar al menos uno de los campos de nombre, email o IP, o recibirás 400.

DELETE /entries/{id} elimina una entrada y devuelve { "success": true }. Si el ID no coincide con una entrada, ambas rutas devuelven 404.

curl -X PUT https://your-store.example.com/wp-json/cgfw/v1/entries/11112222-3333-4444-5555-666677778888 \
  --user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -H "Content-Type: application/json" \
  -d '{"notes":"confirmed fraud"}'

curl -X DELETE https://your-store.example.com/wp-json/cgfw/v1/entries/11112222-3333-4444-5555-666677778888 \
  --user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx"

Comprobar un cliente

POST /check te dice si un cliente sería bloqueado al finalizar la compra. Ejecuta la misma lógica de coincidencia que el proceso de pago real, por lo que la respuesta coincide con lo que obtendría un pedido real. Envía al menos uno de email, first_name, last_name o ip_address, o recibirás 400.

Esta ruta es estricta con los comodines. Los valores que envías son los detalles de un cliente real, no un patrón. Un * en cualquier campo devuelve 400.

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]"}'

Respuesta:

{
  "blocked": true,
  "matched_entry": {
    "id": "11112222-3333-4444-5555-666677778888",
    "first_name": "",
    "last_name": "",
    "email": "[email protected]",
    "ip_address": "",
    "notes": "chargeback fraud",
    "created_by_user_id": 2,
    "source": "api"
  }
}

Cuando no coincide ninguna entrada, blocked es false y matched_entry es null.

Leer y actualizar configuración

GET /settings devuelve la configuración del plugin. La única configuración es checkout_denial_message, que es el mensaje que un cliente bloqueado ve al finalizar la compra. POST /settings la cambia y devuelve la configuración guardada. El mensaje no puede estar vacío, o recibirás 400.

curl https://your-store.example.com/wp-json/cgfw/v1/settings \
  --user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx"

curl -X POST https://your-store.example.com/wp-json/cgfw/v1/settings \
  --user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -H "Content-Type: application/json" \
  -d '{"checkout_denial_message":"Sorry, you cannot place an order right now."}'

Respuesta:

{ "checkout_denial_message": "Sorry, you cannot place an order right now." }

Respuestas de error

Los errores utilizan el formato estándar de WordPress, con un code, un message y un estado HTTP.

Estado	Código	Cuándo ocurre
400	entrada_inválida	Una creación o actualización no tiene nombre, correo electrónico o dirección IP.
400	verificación_inválida	Una solicitud /check no tiene email, first_name, last_name o ip_address.
400	lote_inválido	Una solicitud de lote tiene matrices create y delete vacías.
400	dirección_ip_inválida	Una dirección IP o comodín de IP no es válida.
400	valor_comodín_inválido	Un valor comodín es un comodín simple o tiene más de 5 caracteres *.
400	configuración_inválida	El mensaje de configuración está vacío.
400	rest_parametro_invalido	Un parámetro de consulta o de /check no es válido, como un correo electrónico no válido o un * en un campo de /check.
401	rest_prohibido	La solicitud no tiene credenciales.
403	rest_prohibido	El usuario no tiene la capacidad manage_woocommerce.
404	entrada_no_encontrada	Ninguna entrada coincide con el ID en la URL.

Un 404 sin código significa que la URL base REST de tu sitio es diferente de la que usaste.

Privacidad

Las entradas bloqueadas son datos personales. Si almacenas correos electrónicos, nombres o direcciones IP de clientes, eres responsable de gestionarlos de acuerdo con tus obligaciones de privacidad, como el RGPD.

Solución de problemas

Preguntas frecuentes

¿Necesita ayuda?

Checkout Guard es un plugin con licencia. Si sigues atascado, abre un ticket de soporte e incluye la ruta, la solicitud que enviaste y la respuesta que recibiste. Esto ayuda a nuestro equipo a comprobar tu configuración directamente.