Pre-revisión documental en tu plataforma
Envía un PDF de hasta 200 MB y recibe observaciones y una recomendación para revisión técnica, con los criterios de tu colegio. La respuesta indica la cobertura del análisis. Tu equipo revisa los hallazgos y decide; la integración conserva vuestro flujo de trabajo.
Cómo funciona, de un vistazo
La regla de oro
La API key es un secreto de servidor. Nunca la uses desde el navegador: si la pones en el JavaScript de tu web queda expuesta y con ella se puede consumir tu cuota. La key va solo en tu servidor.
Primeros pasos de integración
Consigue la URL base y la key
El administrador de tu colegio las obtiene en su panel (Administración → API): genera la key —se muestra una sola vez— y ve la URL base de vuestra instancia. La key tiene el aspecto avk_live_XXXX…
Guárdala como secreto
En tu servidor, como variable de entorno, p. ej. AIVISADO_API_KEY. Nunca en el código del navegador.
Comprueba la conexión
Con el endpoint de salud (no gasta análisis). Debe responder ok: true.
curl https://TU-BASE/api/v1/health \
-H "Authorization: Bearer $AIVISADO_API_KEY"Analizar un documento
https://TU-BASE/api/v1/analisisAutenticación por cabecera Authorization: Bearer avk_live_… (o x-api-key). Cuerpo multipart/form-data, un PDF por petición.
archivorequeridofichero (PDF)El PDF a analizar. Máx. 200 MB. La respuesta indica si la cobertura es parcial. Debe tener texto (los escaneos sin OCR se rechazan con 422).
tipoopcionaltextoTipo de documento, p. ej. «Proyecto de ejecución». Afina el análisis.
tituloopcionaltextoTítulo del proyecto o expediente.
descripcionopcionaltextoContexto breve del proyecto.
tipo_trabajoopcionaltextoTipo de trabajo declarado (obra nueva, reforma, legalización…). Orienta el análisis.
uso_caracteristicoopcionaltextoUso característico del edificio (residencial, comercial…).
usos_subsidiariosopcionaltexto / listaUsos secundarios del edificio. Acepta un texto o una lista.
El informe
{
"contrato_version": 1,
"analisis_id": "an_9f3k2a8b1c4d5e6f",
"estado": "completado",
"texto_truncado": false,
"modelo": "claude-haiku-4-5-20251001",
"informe": {
"puntuacion": 68,
"recomendacion": "CORRECCION",
"resumen": "Memoria coherente; faltan dos justificaciones…",
"deficiencias": [
{ "deficiencia": "Falta el certificado energético del edificio terminado",
"solucion": "1) Adjuntar el CEE… 2) …",
"norma": "CTE DB-HE", "gravedad": "moderada" }
],
"criterios_evaluados": [ /* … */ ],
"aspectos_conformes": [ /* … */ ],
"justificacion": "…"
}
}puntuaciongarantizadoEntero 0–100.
recomendaciongarantizadoAPROBAR · CORRECCION · RECHAZAR. Se re-deriva con reglas deterministas: la IA no decide.
resumenResumen en lenguaje natural del dictamen.
criterios_evaluados[]Cada criterio con su norma, estado (cumple/no_cumple/no_consta/no_aplica), cita textual y comentario.
aspectos_conformes[]Aspectos correctos, con su norma y cita.
deficiencias[]Cada deficiencia con solucion (pasos), norma, gravedad (leve/moderada/grave) y cita.
justificacionJustificación global de la recomendación.
analisis_paso_a_paso). Solo puntuacion y recomendacion tienen garantía de tipo cerrada. El campo modelo indica el modelo de IA que ejecutó el análisis —según la configuración de tu colegio, puede ser un modelo europeo (ver IA europea)—. El contrato formal es el OpenAPI v1 del servicio.Cierre por fase
https://TU-BASE/api/v1/faseVarios PDFs de una misma fase → un único informe consolidado. Campo documentos (de 1 a 20 PDFs) y fase obligatorio; admite además tipologia, titulo, descripcion y los mismos campos de contexto que /analisis. La respuesta añade fase y documentos_analizados[] (con el nº de páginas de cada uno).
/analisis, admite ?modo=async.Documentos extensos, con límites explícitos
Los documentos extensos se procesan por fragmentos y se consolidan en un informe. Se aplican límites de extracción, fragmentos y tiempo, además del máximo de 200 MB por PDF en /analisis. Una petición aceptada no garantiza la lectura de todas las páginas. Para no mantener la conexión abierta durante el análisis, usa el modo asíncrono.
texto_truncado: true señala que el análisis es parcial. Puede deberse a límites del procesamiento o a documentos sin texto extraíble dentro de una fase. El técnico debe revisar lo que quedó fuera antes de resolver.Consola de análisis
Una demostración —sin backend real— de cómo se ve una petición y su informe. Lanza el análisis de una memoria de ejemplo y observa el resultado.
Memoria coherente y bien estructurada; faltan dos justificaciones normativas antes de poder aprobar el visado.
El dictamen es asesor y no sustituye la revisión del técnico. Datos de ejemplo con fines ilustrativos.
Modo asíncrono
Si tu cliente no puede mantener la conexión abierta durante el análisis, añade ?modo=async: la API responde al instante con un identificador y recoges el resultado después (se conserva 48 horas).
# 1) Lanzas el análisis y te devuelve un identificador al instante
POST https://TU-BASE/api/v1/analisis?modo=async
→ 202 { "analisis_id": "an_…", "estado": "analizando" } (+ cabecera Location)
# 2) Consultas el resultado (se conserva 48 h)
GET https://TU-BASE/api/v1/analisis/an_…
→ "analizando" (sigue en curso; respeta Retry-After ~15 s)
→ "completado" (el mismo envoltorio con el informe)
→ "error" (con code/error; si es "interrumpido", reenvía la petición)Copia y pega
curl -X POST https://TU-BASE/api/v1/analisis \
-H "Authorization: Bearer $AIVISADO_API_KEY" \
-F "archivo=@memoria.pdf" \
-F "tipo=Proyecto de ejecución" \
--max-time 180// En TU backend (nunca en el navegador): recibe el PDF del navegador y lo reenvía.
app.post("/analizar", subida.single("pdf"), async (req, res) => {
const fd = new FormData();
fd.append("archivo", new Blob([req.file.buffer], { type: "application/pdf" }), "memoria.pdf");
fd.append("tipo", "Proyecto de ejecución");
const r = await fetch("https://TU-BASE/api/v1/analisis", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.AIVISADO_API_KEY}` },
body: fd,
signal: AbortSignal.timeout(180000), // >= 120 s
});
const data = await r.json();
if (!r.ok) return res.status(r.status).json(data); // 401/413/415/429/503…
res.json(data); // Conserva texto_truncado y el resto del envoltorio.
});import os, requests
def analizar(ruta_pdf):
with open(ruta_pdf, "rb") as f:
r = requests.post(
"https://TU-BASE/api/v1/analisis",
headers={"Authorization": f"Bearer {os.environ['AIVISADO_API_KEY']}"},
files={"archivo": ("memoria.pdf", f, "application/pdf")},
data={"tipo": "Proyecto de ejecución"},
timeout=180, # >= 120 s
)
r.raise_for_status()
return r.json() # Conserva la cobertura además del informe.Códigos y qué hacer
Devuelven { "error": "…", "code": "…" }; algunos incluyen retriable: true o la cabecera Retry-After. Reintenta solo 429/503/504 (con espera); no reintentes 4xx de petición.
Falta el PDF o está corrupto. Revisa el envío multipart. No reintentar.
Key ausente, inválida, revocada o caducada. Revísala con el colegio. No reintentar.
El módulo API no está activo para tu colegio, o el análisis async no existe / caducó (48 h).
Falta la longitud del cuerpo (solo en cierre por fase). Añade la cabecera Content-Length.
El PDF supera el máximo, o la fase lleva más de 20 documentos. Reduce o divide.
El fichero no es un PDF. Envía un PDF real.
El PDF no tiene texto (escaneo sin OCR). Usa un PDF con capa de texto.
Límite alcanzado. Respeta Retry-After; el de peticiones/hora trae cabeceras RateLimit-*.
Temporal. Reintenta más tarde (retriable: true).
El análisis tardó demasiado. Reintenta la petición.
Uso responsable
- Un PDF por petición a /analisis. Para varios de una misma fase, utiliza /fase y respeta sus límites.
- Límite por hora, cuota diaria y concurrencia por key: espacia o encola en tu lado.
- Presupuesto mensual por colegio: al alcanzarlo, 429 hasta el mes siguiente.
- Guarda la key como secreto; si se filtra, pide al colegio que la revoque y rote.
- Timeout del cliente ≥120 s, o usa el modo asíncrono.
El documento no se almacena
El PDF se procesa en memoria y no se guarda; su texto tampoco. En modo síncrono el informe se devuelve y se descarta; en modo asíncrono se conserva 48 horas para su recogida y se elimina automáticamente. Se conservan metadatos de uso y coste. Si el colegio habilita el aprendizaje opcional, también se guardan resultados categóricos, puntuaciones y referencias seudonimizadas; esa opción no guarda el PDF ni su texto reconstruible.
El dictamen es asesor: no sustituye la revisión del técnico. El análisis usa un proveedor de IA como encargado del tratamiento, declarado en las condiciones que firma el colegio.
Opción de IA europea
La integración admite Mistral como opción de IA europea y otros proveedores, como Anthropic, según la configuración del colegio. Antes de activar el servicio se deben concretar proveedor, región de procesamiento y condiciones de tratamiento. Elegir un modelo europeo no acredita por sí solo la ubicación de toda la infraestructura. El campo modelo identifica el modelo que ejecutó cada análisis.
Cómo se factura
Se factura por análisis (no por tokens), con la API key de tu colegio. Cada análisis queda medido: el colegio ve su uso y su coste en su propio panel. El precio se ajusta a vuestro volumen.
Pagas por análisis realizado. Para empezar o para volumen bajo, sin cuota fija.
Cuota con análisis incluidos y mejor precio por análisis cuanto mayor es el volumen.
El acceso lo contrata el colegio (IVA aparte). Te preparamos una propuesta con el precio para vuestro volumen.