# API de Blimark Agent Readiness Actualizado: 18-11-2026. Base: `https://agentreadiness.blimark.tech`. Documentación pública; acceso privado mediante credencial suministrada por el propietario. No hay registro público de API keys. Contrato estructurado: [OpenAPI](https://agentreadiness.blimark.tech/documentacion/openapi.json). ## Autenticación y alcance Enviar **una** de estas cabeceras en cada petición privada: ```http X-API-Key: ``` Alternativa: `Authorization: Bearer `. No usar ambas. Nunca enviar la clave en URL, HTML, enlaces compartidos, prompts, logs, capturas o repositorios. Obtenerla de un gestor de secretos y proporcionarla al proceso, sin incluirla en el código ni en archivos publicados. La clave actúa en nombre de la cuenta activa a la que está asociada. Puede operar sobre sus informes, incluidos los creados por esa misma cuenta en la web. No permite administrar usuarios, consultar métricas privadas, listar cuentas ni acceder a informes ajenos. No requiere navegador, cookie, OTP ni Turnstile. La clave es privada, revocable y tiene caducidad: ante `401` detenerse y solicitar revisión al operador. Los permisos y límites efectivos corresponden a la cuenta asociada a la clave. El acceso API se habilita por el operador; actualmente no hay generación de claves por autoservicio. No compartir esta credencial con terceros no autorizados. Usar llamadas servidor a servidor por HTTPS, sin cabecera `Origin`; si se envía, debe coincidir exactamente con el origen de la API, también en GET y OPTIONS; se rechaza un origen ajeno o `null` con `403`. No cargar la clave en JavaScript público. ## Recorrido completo | Paso | Método y ruta | Resultado | | --- | --- | --- | | 1 | `POST /api/v1/audits` | `202`: ID y estado de la auditoría | | 2 | `GET /api/v1/audits/{id}` | `200`: estado y fechas | | 3 | `GET /api/v1/audits/{id}/report` | `200`: JSON con `report` | | 4 | `GET /api/v1/audits/{id}/export-options` | `200`: `{ "pdf": true }` si exportable | | 5 | `POST /api/v1/audits/{id}/pdf` | `200 application/pdf`: guardar bytes tal cual | | 6 | `POST /api/v1/audits/{id}/share` | `200`: `url` y `expiresAt` | Todos esos endpoints requieren autenticación. PDF y share son POST sin cuerpo; no requieren `Idempotency-Key`. Repetir share devuelve el mismo enlace mientras esté vigente. PDF reutiliza la caché de la versión del generador correspondiente. ### Crear una auditoría ```http POST /api/v1/audits Content-Type: application/json X-API-Key: Idempotency-Key: { "url": "https://example.com/", "profile": "full", "device": "mobile", "businessModules": [], "includeLighthouse": false } ``` `url` debe ser HTTP/HTTPS pública. `profile` es obligatorio: `full` es la opción recomendada para todos los controles de Agent Readiness. Lighthouse se solicita por separado. También existen `content` y `application` para alcances parciales; sus informes pueden no tener WPO. Solo se admite `device: "mobile"` (opcional). La API rechaza campos adicionales (`unexpected_field`). `includeCommerce` es booleano, opcional y falso por defecto. Se analiza la URL solicitada, no todo el sitio. El servidor valida destinos, redirecciones y acceso a red; no admite destinos internos. No enviar `captchaToken` con esta clave. La auditoría general usa `profile: "full"`. `businessModules` es opcional y por defecto no selecciona módulos. Acepta `commerce_payments` y `agent_interfaces`, en cualquier combinación; `[]` equivale a omitirlo. `agent_interfaces` requiere `profile: "application"` o `profile: "full"`; con `content` la solicitud se rechaza porque ese alcance no recoge los controles de interfaces de agentes. `includeCommerce` sigue aceptado como alias compatible con clientes anteriores para seleccionar `commerce_payments`. Si se envían ambos campos, deben coincidir o la solicitud se rechaza. `businessModules` queda registrado en el alcance, fingerprint e informe; reutilizar una clave de idempotencia con una selección diferente devuelve `409 idempotency_conflict`. Los módulos no cambian la puntuación Agent Readiness, su cobertura, el índice comparable propio de Blimark ni el nivel de madurez. La selección de Comercio y pagos habilita las comprobaciones públicas de protocolos comerciales en modo de solo lectura. La detección automática de comercio usa únicamente JSON-LD `Product` con oferta y precio en el HTML principal; no interpreta texto de widgets ni contenido de iframes como prueba. Esa señal no demuestra carrito, checkout ni pagos. API o herramientas para agentes se detecta solo con resultados positivos de controles de descubrimiento públicos ya incluidos en la auditoría completa. El informe puede incluir `businessModuleAssessment`: `requested` enumera lo que se seleccionó; cada resultado incluye `selected`, un estado (`detected`, `no_public_evidence` o `unable_to_check`) y `evidenceCheckIds` para abrir las comprobaciones que explican la conclusión. Los módulos detectados sin selección se informan automáticamente. Una selección sin evidencia no se trata como fallo ni como capacidad inexistente; una observación incompleta queda como `unable_to_check`. `businessContext` se conserva para compatibilidad con integraciones antiguas y reportes ya generados. Describe familias y declaraciones de capacidades, y su `contextualAssessment` permanece independiente. No se muestra en el nuevo flujo principal ni se recomienda para nuevas integraciones; usa `businessModules`. `includeLighthouse` es una opción técnica independiente, false por defecto. Enviar `includeLighthouse: true` para incluir rendimiento, accesibilidad, buenas prácticas y SEO con Lighthouse. Si es false u omitido, no se ejecuta Lighthouse ni CrUX; sus secciones se omiten en la web y el PDF. No se muestran puntuaciones vacías ni avisos por módulos u opciones no solicitados. Desde esta actualización, integraciones que deseen WPO deben enviar true explícitamente; los informes anteriores conservan sus resultados. Extracto de respuesta (el contrato OpenAPI enumera todos los campos): ```json { "id": "11111111-1111-4111-8111-111111111111", "status": "queued", "scope": { "url": "https://example.com/", "profile": "full", "includeCommerce": false, "businessModules": [], "includeLighthouse": false, "contextualAssessment": false, "device": "mobile" }, "cache": { "hit": false, "observedAt": null, "expiresAt": null }, "dispatch": "published" } ``` Persistir `Idempotency-Key` **antes** de enviar y guardar el `id` recibido. Si se pierde la conexión, repetir con la misma clave y el mismo cuerpo. Nunca cambiar la clave para reintentar una solicitud incierta. Para una auditoría deliberadamente nueva, usar otra clave. El servidor puede reutilizar mediciones recientes; consultar `cache.hit` y `cache.observedAt`. Una clave nueva no fuerza medición fresca. ### Esperar el resultado Consultar el estado cada 5 segundos, preferiblemente una URL a la vez. `queued` y `running` requieren esperar. `completed` y `partial` permiten leer el informe; en `partial` conservar las limitaciones y controles no verificables. `failed` y `cancelled` son terminales: detenerse, no generar un PDF alternativo. Si solicitaste Lighthouse, espera al estado final del conjunto antes de pedir el PDF: completar Agent Readiness no habilita una exportación anticipada mientras Lighthouse continúa. El control WebMCP puede quedar `unable_to_check` si la política de solo lectura del auditor impide el descubrimiento MCP, si este falla o sigue pendiente al finalizar la observación. Conserva esa limitación: no significa ausencia de herramientas ni aprobación del control. El observador permite únicamente descubrimiento MCP validado (`initialize`, `notifications/initialized`, `tools/list`) en un endpoint HTTPS del mismo origen, sin credenciales de usuario, redirecciones ni ejecución de herramientas. Los endpoints externos o flujos que excedan sus límites pueden seguir sin verificarse. `agents.poppy-discovery` observa el manifiesto público de Personal Agent Protocol como control informativo de peso cero; no cambia puntuación ni niveles. Consulta el [alcance de Poppy y WebMCP](https://agentreadiness.blimark.tech/documentacion/poppy-y-webmcp.md) para interpretar estos resultados y los límites del descubrimiento. Poppy no requiere un parámetro nuevo de la API; no solicita exportaciones ni cambia las opciones independientes `includeCommerce` e `includeLighthouse`. Si se agota el tiempo de espera del cliente, guardar el ID y continuar consultándolo más tarde; no lanzar otra auditoría. El ID no es una URL compartida. ### Descargar y compartir Los pasos de exportación son independientes: puedes obtener solo el JSON, solo el enlace o también el PDF. No se genera PDF al crear o compartir una auditoría. Para un informe previo vigente, utiliza su ID y solicita únicamente los endpoints necesarios; no vuelvas a escanear la URL. El JSON se obtiene del endpoint `/report`. El PDF se descarga de `/pdf` sin reconstruirlo, capturar pantallas ni convertir HTML localmente. Usa exactamente el generador ejecutivo de la aplicación: marca, gráficos, colores, secciones, contacto, numeración y enlace al informe completo. Cambios futuros al generador se aplican también a la API. No sumar AR y WPO ni recalcular puntuaciones. La respuesta de `/share` tiene este formato: ```json { "url": "https://agentreadiness.blimark.tech/r/", "expiresAt": "2026-12-10T12:00:00.000Z" } ``` Usar la URL devuelta; nunca construir ni firmar enlaces por cuenta propia. Quien tenga ese enlace puede ver el informe completo sin iniciar sesión. La URL no contiene la API key. Se conserva el vencimiento original del informe (30 días según la política del sistema); compartir o exportar no lo renueva. Mostrar la fecha `expiresAt`, sin prometer otros 30 días desde el envío. El PDF descargado sigue existiendo después de caducar el informe online. ## Ejemplo Python sin navegador ni dependencias externas Guardar este ejemplo como `auditar.py`. Requiere Python 3.11+ y la variable de entorno `AGENT_READINESS_API_KEY`, inyectada por el entorno autorizado. El ejemplo no depende del PC del propietario ni de archivos locales de secretos. Ejecutar `python auditar.py https://example.com/ ejecucion-example`. Repetir con la misma carpeta reanuda la solicitud; para otra URL usar otra carpeta. Los archivos locales contienen datos del informe y su enlace compartido: tratarlos como información del destinatario, aunque no contengan credenciales. ```python import json, os, pathlib, re, sys, time, uuid import urllib.request, urllib.error BASE = 'https://agentreadiness.blimark.tech' key = os.environ.get('AGENT_READINESS_API_KEY', '') if not re.fullmatch(r'ar_api_[0-9a-f]{64}', key): raise SystemExit('Falta una AGENT_READINESS_API_KEY válida; no la imprimas.') if len(sys.argv) != 3: raise SystemExit('Uso: python auditar.py https://example.com/ carpeta-ejecucion') folder = pathlib.Path(sys.argv[2]); folder.mkdir(parents=True, exist_ok=True) statefile = folder / 'estado.json' body = {'url': sys.argv[1], 'profile': 'full', 'device': 'mobile', 'includeCommerce': False, 'includeLighthouse': False} state = json.loads(statefile.read_text()) if statefile.exists() else {'request': body, 'key': str(uuid.uuid4())} if state['request'] != body: raise SystemExit('Esta carpeta pertenece a otra solicitud. Usa una carpeta distinta.') def save(): temp = statefile.with_suffix('.tmp') temp.write_text(json.dumps(state, indent=2), encoding='utf-8'); temp.replace(statefile) save() # La key guardada aquí es de idempotencia, nunca la credencial. class NoRedirect(urllib.request.HTTPRedirectHandler): def redirect_request(self, *args, **kwargs): return None # No reenviar la credencial a otro destino. opener = urllib.request.build_opener(NoRedirect()) def api(path, method='GET', data=None, idem=None): headers = {'X-API-Key': key} if data is not None: headers['Content-Type'] = 'application/json' if idem: headers['Idempotency-Key'] = idem for attempt in range(4): req = urllib.request.Request(BASE + path, method=method, headers=headers, data=json.dumps(data).encode() if data is not None else None) try: with opener.open(req, timeout=90) as response: return response.read(), response.headers.get_content_type() except urllib.error.HTTPError as error: code = error.code delay = error.headers.get('Retry-After', '') error.close() if code in (429, 502, 503, 504) and attempt < 3: time.sleep(min(120, max(5, int(delay))) if delay.isdigit() else 30) continue raise SystemExit(f'API HTTP {code}; conserva estado.json para reanudar.') from None except (urllib.error.URLError, TimeoutError): if attempt < 3: time.sleep(5 * (attempt + 1)); continue raise SystemExit('Conexión interrumpida; reanuda con la misma carpeta.') from None def getjson(path, method='GET', data=None, idem=None): raw, mime = api(path, method, data, idem) if mime != 'application/json': raise SystemExit('Respuesta JSON inesperada.') return json.loads(raw) if 'id' not in state: state['id'] = getjson('/api/v1/audits', 'POST', body, state['key'])['id']; save() audit_id = state['id'] if not re.fullmatch(r'[a-f0-9-]{36}', audit_id): raise SystemExit('ID inesperado.') path = '/api/v1/audits/' + audit_id deadline = time.monotonic() + 1800 while True: status = getjson(path)['status'] if status in ('completed', 'partial'): break if status in ('failed', 'cancelled'): raise SystemExit('Auditoría ' + status) if time.monotonic() >= deadline: raise SystemExit('Sigue pendiente. Reanuda con la misma carpeta.') time.sleep(5) report = getjson(path + '/report') (folder / 'informe.json').write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding='utf-8') if not getjson(path + '/export-options').get('pdf'): raise SystemExit('PDF no disponible.') pdf, mime = api(path + '/pdf', 'POST') if mime != 'application/pdf' or not pdf.startswith(b'%PDF'): raise SystemExit('PDF inesperado.') (folder / 'informe-ejecutivo.pdf').write_bytes(pdf) share = getjson(path + '/share', 'POST') (folder / 'enlace.json').write_text(json.dumps(share, indent=2), encoding='utf-8') print('Auditoría:', audit_id, '| Estado:', status) print('PDF guardado. Enlace y caducidad guardados en enlace.json.') ``` ## Errores y límites | HTTP | Acción | | --- | --- | | 400 | Revisar cuerpo, URL, perfil o `Idempotency-Key` (no vacía, máximo 128 caracteres). | | 401 | Clave inválida/caducada o cuenta asociada inactiva; detenerse. | | 403 | Operación fuera de alcance, origen inválido o permiso insuficiente. | | 404 | Informe inexistente o ajeno. No intentar otros IDs. | | 409 | Informe aún no listo; consultar estado y esperar. En `POST /audits`, `idempotency_conflict` indica que la clave ya se usó con otro alcance/contexto. | | 410 | Informe caducado/no disponible; no se puede renovar el enlace. | | 422 | Informe demasiado grande para exportar PDF. | | 429 | Límite alcanzado; respetar Retry-After si existe y no insistir en bucle. | | 503 | Cola ocupada o exportación en curso; respetar Retry-After y reintentar de forma acotada. | | 5xx/red | Guardar estado y reintentar con el mismo ID/clave de idempotencia. | Una cuenta exenta de cuota personal sigue sujeta a los límites de capacidad. El motor y la exportación tienen límites de concurrencia. No lanzar lotes masivos ni hacer polling continuo. Generar el PDF y compartir reutiliza resultados; no ejecuta otro escaneo. La API no envía emails al destinatario. ## Flujo recomendado de secretos 1. Guardar `AGENT_READINESS_API_KEY` en el gestor autorizado de la organización. 2. Conceder a la identidad del proceso solo lectura del secreto necesario. 3. El despliegue/runner obtiene el secreto y lo inyecta como variable de entorno, o el cliente lo recupera mediante el SDK del gestor en tiempo de ejecución. 4. Enviar el valor exclusivamente en X-API-Key o Authorization sobre HTTPS. 5. Rotar/revocar de forma coordinada con el operador de esta API. Cambiar solo el valor del cliente no registra una nueva clave en el servidor. La API es independiente del proveedor. Doppler puede suministrarlo al proceso; GitHub Secrets al job autorizado de GitHub Actions; Azure App Service a su aplicación mediante configuración protegida o referencia a Key Vault. Un cliente que use directamente Azure Key Vault necesita una identidad con permiso para leer el secreto. No debe añadir otra credencial fija al código para conseguirlo. No todos los gestores funcionan como almacenes directamente consultables por cualquier cliente: la integración corresponde al entorno de ejecución. ## Frecuencia de PDF y enlaces Máximo **10 solicitudes PDF y 30 solicitudes share por minuto y cuenta**. Son ventanas fijas UTC de 60 segundos, compartidas entre sesiones y la API de esa cuenta, incluso tras rotar la clave. Incluyen descargas de PDF en caché. Las peticiones autenticadas consumen su cupo de operación aunque el informe no esté disponible. Las excedidas reciben 429 `report_rate_limited` y `Retry-After` en segundos. El bloqueo global de generación PDF permanece; una generación concurrente puede responder 503 `export_busy`. GET de consulta no utiliza este cupo de exportación: mantener polling cada 5 segundos. Los límites de admisión/infraestructura siguen siendo adicionales. La ausencia de Origin no demuestra por sí sola que el cliente sea servidor: el control de acceso real es la clave válida, su alcance y la propiedad del recurso. La documentación es pública para facilitar integraciones. El secreto y los datos privados permanecen protegidos. No incluir secretos ni cabeceras de autenticación al pedir ayuda. ## Admisión y presupuesto operativo Web y API comparten identidad y límites: una auditoría en cola/ejecución por cuenta y 10 intentos nuevos de admisión por minuto UTC. Repetir una solicitud ya aceptada con la misma Idempotency-Key no crea ni consume otra auditoría. El servicio admite hasta 3 auditorías activas globales, ejecutadas una a una. Las demás solicitudes reciben 429 account_busy o 503 queue_busy con Retry-After; no se guardan en una cola ilimitada. La generación de claves para otras cuentas sigue sin estar disponible por autoservicio. Las cuentas exentas de cuota comercial tienen un presupuesto operativo de 100 auditorías aceptadas/día y 1.000/mes UTC, incluidos fallos/cancelaciones. Además, se conservan como máximo 500 auditorías por cuenta antes de admitir otra. No se borran informes vigentes para liberar este límite. Errores: audit_rate_limited, operational_budget_exceeded y retention_budget_exceeded responden 429; respetar Retry-After. Cambiar IP, navegador o clave no reinicia el contador de la cuenta. Varias cuentas distintas comparten los límites globales. El PDF se genera bajo demanda y se almacena en caché privada hasta 24 horas, sin superar el vencimiento del informe. El cron elimina físicamente las cachés caducadas; si hace falta se regeneran desde el informe vigente, sin nuevo escaneo. El PDF tiene límite de salida de 2 MiB. El informe y enlace mantienen sus 30 días originales. El cliente debe guardar la descarga donde la necesite. Los enlaces directos del tipo `/example.com` ejecutan solo Agent Readiness, sin Ecommerce ni Lighthouse. El PDF contiene dos páginas ejecutivas sin WPO o tres si se solicitó Lighthouse; conserva membrete, numeración y enlace completo. ### Concurrencia y Lighthouse Cada cuenta puede tener una auditoría aceptada en cola o en ejecución, compartida entre web y API. Una segunda solicitud diferente recibe `429 account_busy`; reintentar la misma clave de idempotencia devuelve el trabajo ya aceptado. Agent Readiness sin Lighthouse y las auditorías que incluyen Lighthouse usan workers separados. El sistema mantiene un puesto de ejecución por tipo y hasta tres auditorías admitidas en conjunto. Esto no amplía la cuota de la cuenta. Solicitar Lighthouse sigue generando un único informe con el mismo identificador; puede tardar más de un minuto. La API autenticada no requiere cookies ni CAPTCHA. La creación puede rechazarse con `403 network_not_supported` si la conexión se identifica como salida Tor. La autenticación con clave no elimina las cuotas ni los controles de red. La API no proporciona una garantía de detección de VPN.