Endpoints del API Gateway

Endpoints Principales

Health Check

GET /health

Verifica el estado de salud del API Gateway y los servicios conectados.

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "services": {
    "image_processor": "healthy",
    "ml_embeddings": "healthy", 
    "ml_classifier": "healthy",
    "ocr_extractor": "healthy"
  },
  "uptime": 3600,
  "memory": {
    "used": "45.2 MB",
    "total": "512 MB"
  }
}

Procesamiento de Imágenes

POST /process

Procesa una imagen a través del pipeline completo de 6 fases.

Request

curl -X POST http://localhost:8000/process \
  -H "Content-Type: multipart/form-data" \
  -H "Authorization: Bearer <jwt-token>" \
  -F "file=@imagen.jpg" \
  -F "config={\"ficha_type\":\"auto\",\"language\":\"es\"}"

Response

{
  "success": true,
  "processing_id": "proc_123456789",
  "phases": {
    "phase_1": {
      "status": "completed",
      "processing_time": 1.23,
      "output": {
        "corrected_image": "base64...",
        "confidence": 0.95
      }
    },
    "phase_2": {
      "status": "completed", 
      "processing_time": 2.45,
      "output": {
        "embeddings": [...],
        "cluster_id": 1
      }
    },
    "phase_3": {
      "status": "completed",
      "processing_time": 0.87,
      "output": {
        "predicted_class": "ficha_residencia",
        "confidence": 0.89
      }
    },
    "phase_4": {
      "status": "completed",
      "processing_time": 3.12,
      "output": {
        "text": "Extracted text...",
        "confidence": 0.92
      }
    },
    "phase_5": {
      "status": "completed",
      "processing_time": 0.56,
      "output": {
        "structured_data": {...}
      }
    }
  },
  "total_processing_time": 8.23,
  "final_result": {
    "document_type": "ficha_residencia",
    "extracted_data": {...},
    "confidence_scores": {...}
  }
}

Procesamiento por Fases

Fase 1: Preprocesamiento

POST /phase1/process

{
  "file": "imagen_base64",
  "options": {
    "enhance": true,
    "unwarp": true
  }
}

Fase 2: Embeddings y Clustering

POST /phase2/embed

{
  "image": "imagen_procesada_base64"
}

POST /phase2/cluster

{
  "embeddings": [[...], [...], [...]],
  "max_k": 10
}

Fase 3-4: Clasificación

POST /phase3/classify

{
  "image": "imagen_base64",
  "model": "efficientnet_b0"
}

POST /phase3/train

{
  "dataset_path": "/path/to/training/data",
  "model_config": {
    "epochs": 50,
    "batch_size": 32
  }
}

Fase 5-6: Extracción (IDP) con OCR

POST /phase4/ocr

{
  "image": "imagen_base64",
  "ficha_type": "residencia",
  "language": "es"
}

POST /phase4/extract

{
  "text": "texto_extraido",
  "document_type": "ficha_residencia"
}

Endpoints de Administración

Gestión de Modelos

GET /admin/models

Lista todos los modelos disponibles.

POST /admin/models/reload

Recarga los modelos en memoria.

DELETE /admin/models/{model_id}

Elimina un modelo específico.

Estadísticas

GET /admin/stats

{
  "total_requests": 1523,
  "successful_requests": 1498,
  "failed_requests": 25,
  "average_processing_time": 5.67,
  "requests_by_phase": {
    "phase_1": 1523,
    "phase_2": 1498,
    "phase_3": 1498,
    "phase_4": 1498
  },
  "most_processed_types": [
    {"type": "ficha_residencia", "count": 856},
    {"type": "documento_identidad", "count": 642}
  ]
}

Configuración

GET /admin/config

Obtiene la configuración actual.

PUT /admin/config

Actualiza la configuración del sistema.

{
  "services": {
    "image_processor": {
      "timeout": 30000,
      "max_retries": 3
    }
  },
  "cache": {
    "enabled": true,
    "ttl": 3600
  },
  "rate_limiting": {
    "enabled": true,
    "max_requests": 100,
    "window_ms": 900000
  }
}

Códigos de Estado HTTP

Código	Descripción	Uso
200	OK	Operación exitosa
201	Created	Recurso creado exitosamente
400	Bad Request	Request malformado
401	Unauthorized	Token de autenticación requerido
403	Forbidden	Permisos insuficientes
404	Not Found	Recurso no encontrado
429	Too Many Requests	Rate limit excedido
500	Internal Server Error	Error interno del servidor
502	Bad Gateway	Servicio backend no disponible
503	Service Unavailable	Servicio temporalmente no disponible

Headers Requeridos

Autenticación

Authorization: Bearer <jwt-token>

Content-Type

Content-Type: application/json
Content-Type: multipart/form-data

Request ID

X-Request-ID: unique-request-identifier

Parámetros de Query Comunes

Parámetro	Tipo	Descripción	Ejemplo
limit	integer	Número máximo de resultados	?limit=50
offset	integer	Número de resultados a saltar	?offset=100
format	string	Formato de respuesta	?format=json
fields	string	Campos específicos a incluir	?fields=id,name,status
sort	string	Campo por el cual ordenar	?sort=created_at
order	string	Dirección del ordenamiento	?order=desc

Ejemplos de Uso

Procesamiento Completo

# 1. Subir y procesar imagen
curl -X POST http://localhost:8000/process \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -F "file=@documento.jpg" \
  -F "config={\"ficha_type\":\"auto\"}"

# 2. Verificar estado del procesamiento
curl -X GET http://localhost:8000/process/proc_123456789 \
  -H "Authorization: Bearer $JWT_TOKEN"

# 3. Obtener resultados
curl -X GET http://localhost:8000/results/proc_123456789 \
  -H "Authorization: Bearer $JWT_TOKEN"

Procesamiento por Fases

# Solo clasificación
curl -X POST http://localhost:8000/phase3/classify \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
    "model": "efficientnet_b0"
  }'

# Solo extracción de texto (OCR)
curl -X POST http://localhost:8000/phase4/ocr \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
    "ficha_type": "residencia",
    "language": "es"
  }'