API y MCP de Fojaria

1. Un owner o admin crea una clave en Configuración → API y conectores. La clave (fjr_live_…) se muestra una sola vez; guárdala como secreto.

2. Envíala en cada petición como encabezado Bearer:

curl https://fojaria.vicentediaz.dev/api/v1/yo \
  -H "Authorization: Bearer $FOJARIA_API_KEY"

Cada clave pertenece a una organización y solo ve sus datos. Si quien la creó deja la organización o pierde el rol de owner/admin, la clave deja de funcionar.

1. Elige plantilla: GET /plantillas (o instala una de /galeria).
2. Sube los datos: POST /datos con filas JSON o un archivo .xlsx/.csv.
3. Crea el lote: POST /lotes (mapeo automático variable → columna).
4. Valida: POST /lotes/{id}/validar. Corrige y repite si hay filas con error.
5. Pide generar: POST /lotes/{id}/solicitar-generacion. Responde con url_aprobacion: una persona de la organización aprueba o rechaza en la página del lote.
6. Sigue el estado en GET /lotes/{id} y descarga con GET /lotes/{id}/zip (enlace firmado de 10 minutos).

curl -X POST https://fojaria.vicentediaz.dev/api/v1/lotes/$LOTE/solicitar-generacion \
  -H "Authorization: Bearer $FOJARIA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"solo_filas_validas": false}'

Una clave nunca puede encolar la generación ni aprobar solicitudes: lo impide la base de datos, no solo la aplicación. Todo lo que hace una clave queda en el historial de auditoría con su prefijo.

Con el permiso contratos:leer puedes buscar los contratos de la organización (generados en Fojaria e importados ya confirmados por una persona) y sus vencimientos. El estado se calcula con la fecha de hoy en Chile: vigente, por_vencer (30 días), vencido, terminado o anulado.

curl "https://fojaria.vicentediaz.dev/api/v1/contratos?vence_antes_de=2026-12-31&estado=por_vencer" \
  -H "Authorization: Bearer $FOJARIA_API_KEY"

Cerrar, renovar o importar contratos lo hace una persona en Fojaria. Los contratos importados no tienen código de verificación: Fojaria no los emitió. Los avisos de plazo fijo del detalle son información general, revisa con tu asesor.

POST /api/v1/buscar busca en contratos, cláusulas aprobadas, plantillas y lotes con una pregunta en español. La consulta va en el cuerpo (nunca en la URL). Interpreta filtros de una lista cerrada (tipo, estado, fechas, cargo, plantilla, faena, firma, origen, sueldo, RUT, estado y aprobación de lotes), busca en el texto completo y por significado, y devuelve cada resultado con su cita (fragmento y ubicación). Con "modo": "preguntar" agrega un conteo calculado por la base de datos y una frase marcada como resumen automático.

curl -X POST "https://fojaria.vicentediaz.dev/api/v1/buscar" \
  -H "Authorization: Bearer $FOJARIA_API_KEY" -H "Content-Type: application/json" \
  -d '{"consulta": "¿cuántos contratos a plazo fijo vencen este mes?", "modo": "preguntar"}'

Cada grupo exige su permiso de lectura: contratos con contratos:leer, cláusulas y plantillas con plantillas:leer, lotes y documentos con lotes:leer. Puedes enviar filtros ya corregidos para saltarte la interpretación.

Servidor remoto (Streamable HTTP) en https://fojaria.vicentediaz.dev/api/mcp, con la misma clave en el encabezado Authorization. Ejemplo para Claude Code:

claude mcp add --transport http fojaria https://fojaria.vicentediaz.dev/api/mcp \
  --header "Authorization: Bearer $FOJARIA_API_KEY"

• plantillas:leer — Ver plantillas y la galería de contratos
• plantillas:escribir — Subir plantillas e instalarlas desde la galería
• datos:escribir — Subir archivos de datos o filas en JSON
• lotes:leer — Ver lotes, su estado y su reporte de validación
• lotes:escribir — Crear borradores de lotes y validarlos
• lotes:solicitar_generacion — Pedir la generación de un lote (siempre la aprueba una persona)
• lotes:generar — Generar documentos directamente, sin aprobación previa (solo para integraciones de confianza)
• documentos:descargar — Descargar el ZIP y los documentos generados
• contratos:leer — Buscar contratos del repositorio y sus vencimientos (solo lectura)

Los errores tienen siempre la misma forma y mensajes en español:

{ "error": { "codigo": "sin_permiso", "mensaje": "…", "detalles": { … } } }

Límite: 120 peticiones por minuto por clave (encabezados RateLimit-* y Retry-After en el 429). En los POST, Idempotency-Key repetida con el mismo cuerpo durante 24 h devuelve la misma respuesta. Las listas se paginan con pagina y por_pagina (máx. 100).

Parámetros, cuerpos, respuestas y ejemplos en cURL, JavaScript y Python para cada endpoint, con un probador integrado. Base: https://fojaria.vicentediaz.dev/api/v1.