Comprobaciones del sitio
Cuando un objetivo ejecuta una comprobación de bots antes de llegar a la página solicitada, FourA te avisa. Cada request que encuentra uno devuelve un campo que indica el sistema, si la comprobación se superó y, en caso afirmativo, la autorización que puedes reutilizar para que la siguiente llamada la omita.
Esta página es la referencia de esos campos. Para conocer la estrategia, consulta Sitios protegidos.
Dónde se ubica el campo
| Endpoint | Campo | Presente cuando |
|---|---|---|
POST /api/single/ |
defense (object) |
Se reconoció una comprobación de bots en el response |
POST /api/proxy/ |
defense (object) |
Lo mismo, reportado por el intento que respondió |
POST /api/browser/ |
defenseSolved (boolean) y defenses (object) |
Siempre, en una página cargada. defenseSolved es false y defenses está vacío cuando no se reconoció nada. |
POST /api/auto/ |
meta.solved (boolean) |
En cada respuesta una vez que la secuencia ha comenzado. true cuando se superó una comprobación en algún punto de la secuencia. Un body que falla la validación o un host que no se resuelve se responde antes de la secuencia, sin meta. |
Su ausencia significa que no se reconoció nada. No interpretes la falta de defense como un error.
En Single y Proxy, el reporte requiere unblocker, que está activado por defecto. Con unblocker: false pediste la página exactamente como llegó, por lo que Single devuelve el desafío sin modificar y Browser lo renderiza sin resolverlo.
defense en Single y Proxy
{
"status": 200,
"data": "<!doctype html>...",
"total_time": 3.61,
"defense": {
"vendor": "sgcaptcha",
"solved": true,
"present": ["sgcaptcha"],
"ms": 3412,
"hashes": 1048576,
"complexity": 20,
"cookie": "_I_=<clearance>"
}
}
| Campo | Tipo | Descripción |
|---|---|---|
vendor |
string | El sistema al que corresponde este registro: el que se superó o el principal encontrado. Consulta la lista de proveedores a continuación. |
solved |
boolean | true significa que la verificación se superó y data es la página real. false significa que data puede ser la página de desafío. |
present |
string[] | Cada sistema reconocido en esta response. Puede contener más nombres que vendor y puede incluir nombres que nadie supera todavía. |
ms |
number | Milisegundos empleados en superar la verificación. Solo cuando se supera. |
hashes |
number | Cuánto trabajo computacional requirió el desafío. Solo cuando se supera. |
complexity |
number | La dificultad que declaró el desafío. Solo cuando se supera y únicamente donde el desafío reporta una. |
answers |
number | Cuántas respuestas aceptadas se suministraron, para desafíos que requieren varias en lugar de una. Solo cuando se supera. |
retry |
string | Presente cuando el body provino de un reintento en lugar de una resolución exitosa: refusal-cookies, amazon-continue, reddit-js-check o verify-challenge. Consulta más abajo. |
cookie |
string | El jar para reproducir: la autorización que obtuvo una resolución exitosa o la sesión que entregó un rechazo. |
solved: false es el caso por el que vale la pena crear bifurcaciones lógicas. FourA nunca presenta una página de desafío como contenido, por lo que el flag es tu señal de que el body necesita escalación en lugar de parseo.
retry: "refusal-cookies"
Algunos sitios no ejecutan un puzzle. Rechazan la primera request, configuran cookies en el rechazo y entregan la página real a cualquiera que devuelva esas cookies. Las páginas de artículos de eBay son el caso de referencia.
Cuando eso sucede, FourA las devuelve por ti y te entrega la página. La response incluye entonces retry: "refusal-cookies":
{
"status": 200,
"data": "<!doctype html>...",
"defense": {
"vendor": "akamai",
"solved": false,
"present": ["akamai"],
"retry": "refusal-cookies",
"cookie": "bm_sv=...; dp1=..."
}
}
Léelo de esta manera:
solvedse mantiene enfalse. Responder a un handshake no equivale a superar un challenge y nunca modifica el coste de la llamada. Se te factura por la request que realizaste.dataes contenido real, no una página de challenge. Este es el único caso dondesolved: falseno significa que el body requiera escalación, motivo por el cual existe este campo.cookiees la sesión entregada por el sitio. Repítela igual que repetirías una autorización y las páginas posteriores omitirán el rechazo.- Un retry y un clear pueden ocurrir en la misma request. Si la respuesta del retry resultó ser un challenge que FourA puede resolver, obtendrás
solved: truecon los campos propios del proveedor yretry: "refusal-cookies"junto a ellos.
vendor muestra unknown cuando un retry generó el contenido y no se reconoció ningún sistema durante el proceso. present es entonces un array vacío.
retry: "amazon-continue"
Amazon a veces responde con una verificación de robot de un solo botón: una página pequeña que te pide hacer clic para continuar comprando, con la respuesta ya completada. Con unblocker activado (el valor predeterminado), Single y Proxy presionan ese botón en la misma salida, dentro de tu timeout_ms, y vuelven a solicitar tu página con las cookies que estableció. Cuando eso abre la página, la response incluye retry: "amazon-continue":
{
"status": 200,
"data": "<!doctype html>...",
"defense": {
"vendor": "akamai",
"solved": false,
"present": ["akamai", "amazon"],
"retry": "amazon-continue",
"cookie": "ak_bmsc=...; ..."
}
}
Léelo como un reintento de refusal-cookies. solved se mantiene en false, data es la página real, se te factura la request que hiciste y cookie es el jar que debes reproducir en las páginas siguientes. Busca amazon en present en lugar de en vendor: la página de comprobación a menudo establece una cookie que FourA también reconoce, y vendor nombra al primer sistema de la lista.
La versión con imagen de la misma comprobación, donde una persona tiene que leer la respuesta, se reporta y se deja tal como vino. Lo mismo ocurre con una acción que solo vuelve a mostrar la comprobación. En cualquiera de los dos casos esa página no se factura (consulta Qué cuesta).
retry: "reddit-js-check"
Reddit a veces responde con una comprobación de página ligera: una página pequeña con un formulario oculto y un script que rellena dicho formulario. Con unblocker activado (el valor predeterminado), Single y Proxy envían ese formulario en la misma salida, dentro de tu timeout_ms, y solicitan tu página de nuevo con las cookies que estableció. Cuando eso abre la página, la response incluye retry: "reddit-js-check":
{
"status": 200,
"data": "<!doctype html>...",
"defense": {
"vendor": "reddit",
"solved": false,
"present": ["reddit"],
"retry": "reddit-js-check",
"cookie": "edgebucket=...; ..."
}
}
Interprétalo como un reintento amazon-continue. solved se mantiene en false, data es la página real, se te factura por la request que hiciste y cookie es el jar que debes reutilizar en las páginas siguientes. Cuando la comprobación sigue apareciendo, FourA deja la página tal como llegó y esa página no se factura.
retry: "verify-challenge"
Algunos sitios abren con una breve página de comprobación propia: un indicador de carga y un script que te redirige a la página una vez completada la comprobación. Con unblocker activado (el valor predeterminado), Single y Proxy completan esa comprobación en la misma salida, dentro de tu timeout_ms, y solicitan tu página de nuevo con la cookie que se configuró. Cuando eso abre la página, la response incluye retry: "verify-challenge":
{
"status": 200,
"data": "<!doctype html>...",
"defense": {
"vendor": "verify-challenge",
"solved": false,
"present": ["verify-challenge"],
"retry": "verify-challenge",
"cookie": "token=..."
}
}
Léelo como un reintento de reddit-js-check. solved se mantiene como false, data es la página real, se te factura por la request que realizaste y cookie es el jar para reproducir en páginas posteriores. Cuando la página de verificación vuelve sin respuesta, no se factura.
defenses en Browser
{
"status": 200,
"body": "<!doctype html>...",
"userAgent": "Mozilla/5.0...",
"defenseSolved": true,
"defenses": {
"present": ["cloudflare"],
"cleared": ["cloudflare"]
}
}
| Campo | Tipo | Descripción |
|---|---|---|
defenseSolved |
boolean | true cuando se encontró un sistema durante la carga y su autorización se mantiene en la página final. Este es el flag que determina si la llamada cuesta 5 o 10 créditos. |
defenses.present |
string[] | Cada sistema reconocido en cualquier momento durante la carga de la página, no solo en la respuesta final. Una verificación es algo que ocurrió, y para cuando llega la página real, la respuesta del challenge ya desapareció hace tiempo. |
defenses.cleared |
string[] | Los sistemas cuya autorización mantiene la página final. |
Un nombre en present que nunca llega a cleared es un sistema que FourA reconoció sin obtener una autorización para él: uno que todavía no puede completar, o uno de los pocos que Browser maneja de otra manera (consulta Qué se autoriza hoy). Esos nunca aumentan el precio de una llamada.
Proveedores
Valor de vendor |
El sistema |
|---|---|
cloudflare |
Desafíos y gestión de bots de Cloudflare |
sgcaptcha |
Verificación de sitio de SiteGround |
datadome |
DataDome |
perimeterx |
PerimeterX |
akamai |
Akamai Bot Manager |
incapsula |
Imperva Incapsula |
awswaf |
Desafío de AWS WAF |
ebay-splashui |
Desafío propio de eBay |
reddit |
Páginas propias de verificación y rechazo de Reddit |
verify-challenge |
Página de verificación propia de un sitio que te redirige una vez completada su comprobación |
amazon |
Verificación de robots de Amazon |
hcaptcha |
hCaptcha |
recaptcha |
reCAPTCHA |
unknown |
No se reconoció ningún sistema. Solo aparece junto a retry, donde el registro existe para informar el reintento en lugar de un proveedor. |
Qué se autoriza hoy
| Endpoint | Autorizaciones |
|---|---|
| Single, Proxy | sgcaptcha, ebay-splashui. Ambos son computacionales en lugar de visuales, por lo que no interviene ningún navegador. |
| Browser | cloudflare, sgcaptcha |
Algunos más se manejan sin una autorización. Single y Proxy presionan la verificación de robots de un solo botón de Amazon y la reportan como retry: "amazon-continue", envían la verificación ligera de página de Reddit y la reportan como retry: "reddit-js-check", y completan la página de verificación propia de un sitio reportándola como retry: "verify-challenge". Browser espera hasta 10 segundos a que esa misma página de verificación lo redirija. Browser presiona el botón de Amazon y espera mientras la página de sensor de Akamai, la página de desafío de AWS WAF, la verificación de dispositivo de DataDome o la página de desafío propia de eBay cargan la siguiente página por sí mismas, y luego devuelve esa página. Si esa página nunca llega, Browser devuelve la que tenía retenida, dentro de tu timeout_ms. En Browser esos nombres se muestran en defenses.present, nunca en cleared, y la llamada cuesta 5.
Todo lo demás en la lista se reconoce y se reporta, y nada más. Esa división cambia a medida que FourA aprende a resolver más de ellos, así que lee solved en lugar de asumir a partir de esta tabla.
Dos notas sobre casos límite:
hcaptchayrecaptchatambién son widgets de formulario comunes. Solo se reportan cuando la respuesta realmente te bloqueó (403, 429 o 503), por lo que una página de pago con un widget de verificación en un formulario no reporta una defensa.- Estar detrás de Cloudflare no es una defensa.
cloudflareaparece cuando hay un desafío real o un artefacto de gestión de bots en la respuesta, no porque un sitio use Cloudflare.
Reutilizar un clearance
defense.cookie es el propósito principal del campo. Un clearance está vinculado a la salida que lo obtuvo y al User-Agent que lo obtuvo, por lo que si lo reutilizas con el mismo par, la verificación no se ejecuta de nuevo.
import requests
API = "https://eu.api.foura.ai"
H = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}
# 1) First call pays for the clear.
first = requests.post(f"{API}/api/proxy/", headers=H, json={
"maxTries": 5,
"request": {"method": "GET", "url": "https://example.com/catalog"},
}).json()
defense = first.get("defense", {})
if defense.get("solved"):
clearance = defense["cookie"]
exit_id = first["proxy"]
# 2) Follow-up pages skip the check: same exit, same clearance.
for page in range(2, 6):
r = requests.post(f"{API}/api/single/", headers=H, json={
"method": "GET",
"url": f"https://example.com/catalog?page={page}",
"proxy": exit_id,
"headers": [["Cookie", clearance]],
}).json()
print(page, r["status"])
La primera llamada asume el costo de la resolución. Cada repetición es una request ordinaria al precio habitual.
Tres factores invalidan una repetición:
- Una salida distinta. Fija el ID de proxy devuelto en la response de resolución. Consulta Reutilizar un proxy entre requests.
- Un User-Agent distinto. Las responses de Browser devuelven el
userAgentque utilizaron. Envíalo de vuelta junto con la cookie. - Caducidad. Las autorizaciones tienen sus propios tiempos de vida, definidos por el destino. La de SiteGround dura alrededor de 30 días para todo el sitio; una autorización de Cloudflare suele ser mucho más corta. Trata una autorización como una caché: cuando las repeticiones comiencen a devolver desafíos de nuevo, ejecuta una llamada limpia y obtén la nueva.
Cuánto cuesta
Una verificación resuelta modifica el precio únicamente en Browser:
| Motor | Base | Defensa resuelta |
|---|---|---|
| Single | 1 (2 con unblocker) |
Sin cambios |
| Proxy | 2 (4 con unblocker) |
Sin cambios |
| Browser | 5 | 10 |
Browser cobra 10 solo cuando el solver estuvo activo y se superó realmente un sistema de defensa. Un sistema reconocido pero no resuelto cuesta 5, lo mismo que una página sin ningún tipo de verificación.
Una página de verificación o de rechazo reconocida por FourA que se entregue con HTTP 200 (por ejemplo, el robot check de Amazon, la página de verificación de Reddit o la página de challenge de eBay) no se factura en ningún endpoint. Las responses de Single, Proxy y Browser la identifican en X-FourA-Check-Page.
Combínalo con validate
defense te indica que se encontró una verificación. validate le indica a FourA cómo es la página real, lo que permite que una request falle en lugar de entregarte un intersticial que casualmente devuelva HTTP 200.
{
"method": "GET",
"url": "https://example.com/product/42",
"validate": {
"data": {"accept": ["Add to cart"], "fail": ["Just a moment"]}
}
}
En POST /api/auto/, validate es lo que evita que la secuencia acepte una página de desafío y la dé por completada.
Relacionado
- Sitios protegidos: Qué motor utilizar en cada nivel de protección
- Endpoints de la API: Referencia de request y response para los cuatro endpoints
- Reutilizar un proxy entre requests: Fija la salida a la que está vinculada una autorización
- Smart Fetch (Auto): Cómo encaja
meta.solveden la secuencia - Headers de respuesta: Dónde se muestra el costo en créditos de una llamada