Documentación de la API

Entiscore expone su análisis como un endpoint HTTP simple que cualquier desarrollador puede consumir directamente, sin necesidad de usar la interfaz web. Es útil para integrarlo en scripts propios, pipelines de integración continua, o herramientas internas de un equipo.

POST /api/audit

Analiza una URL y devuelve un reporte completo de entidad digital con puntaje, hallazgos por eje y plan de acción.

Request

json

POST /api/audit
Content-Type: application/json

{
  "url": "https://tu-sitio.com"
}

Response (200)

Reporte completo con la estructura AuditResponse:

json

{
  "url": "https://example.com",
  "timestamp": "2026-07-25T16:00:00.000Z",
  "overallScore": 42,
  "maturityLevel": "medio",
  "executiveSummary": "El sitio tiene una base técnica aceptable...",
  "axes": {
    "structuredData": {
      "score": 0,
      "status": "evaluated",
      "findings": [
        {
          "type": "critical",
          "title": "No se encontró schema markup en el sitio",
          "description": "..."
        }
      ]
    },
    "identityConsistency": { "score": 50, "status": "evaluated", "findings": [...] },
    "authoritySignals": { "score": 30, "status": "evaluated", "findings": [...] },
    "technicalAccessibility": { "score": 60, "status": "evaluated", "findings": [...] }
  },
  "actionPlan": [
    {
      "priority": 1,
      "title": "Agregar schema markup de tipo Person",
      "reason": "...",
      "effort": "medio",
      "axis": "structuredData",
      "codeSnippet": "<script type=\"application/ld+json\">...</script>",
      "codeLanguage": "html"
    }
  ],
  "code": "bold-key-742",
  "siteName": "Example Domain",
  "faviconUrl": "https://example.com/favicon.ico"
}

Campos principales

overallScore: Puntaje general de 0 a 100.

maturityLevel: bajo, medio, alto o excelente.

axes: Resultado por cada eje (score, status, findings).

actionPlan: Recomendaciones priorizadas con código de solución opcional.

code: Código único para acceder al reporte via /r/[codigo].

executiveSummary: Resumen narrativo generado por IA (opcional).

Errores

400 INVALID_URL: La URL tiene formato inválido o no usa protocolo http/https.

403 FORBIDDEN_URL: La URL apunta a localhost, una IP privada o un rango reservado.

504 TIMEOUT: El análisis superó el tiempo máximo de 55 segundos.

500 INTERNAL_ERROR: Error inesperado del servidor.

json

{
  "error": "La URL proporcionada no es válida",
  "code": "INVALID_URL",
  "details": "url: Invalid URL"
}

Ejemplo con curl

bash

curl -X POST https://entiscore.vercel.app/api/audit \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Ejemplo con fetch (JavaScript)

javascript

const response = await fetch("https://entiscore.vercel.app/api/audit", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://example.com" }),
});

const report = await response.json();
console.log(report.overallScore);
console.log(report.maturityLevel);
console.log(report.actionPlan);

Autenticación y seguridad

El endpoint no requiere autenticación ni API key en esta versión. Está pensado como una herramienta abierta para la comunidad de desarrolladores. Las mismas protecciones de seguridad que aplican desde la interfaz web, como el bloqueo de URLs privadas y localhost, se aplican también a las llamadas directas al endpoint.