Documentación

Primeros Pasos

Bienvenido a Igniral

Igniral simplifica el desarrollo backend permitiéndole diseñar, desplegar y gestionar APIs REST listas para producción de forma visual. Ya sea que esté construyendo un prototipo o un microservicio escalable, Igniral maneja la infraestructura para que pueda enfocarse en los datos y la lógica.

Cómo Funciona

El flujo de trabajo está diseñado para ser intuitivo:

1. Definir: Cree una Aplicación para agrupar sus recursos.
2. Diseñar: Use el Constructor de Schemas para modelar sus datos (ej., Usuarios, Productos).
3. Desplegar: Sus endpoints están instantáneamente activos y listos para usar.
4. Asegurar: Controle quién puede acceder a sus datos con Control de Acceso.

Aplicaciones

¿Qué es una Aplicación?

Una Aplicación sirve como un espacio de nombres o contenedor para sus APIs. Agrupa schemas y endpoints relacionados. Por ejemplo, podría tener aplicaciones separadas para "Tienda E-commerce", "Gestión de Inventario" y "Autenticación de Usuarios".

Opciones de Configuración

• Nombre: El identificador único de su aplicación. Será parte de la URL de su API.
• Versión: Le ayuda a gestionar el ciclo de vida de la API (ej., v1, v2). Cambiar esto le permite publicar actualizaciones sin afectar a los clientes existentes.
• Modo Privado:
  • No (Pública): Los endpoints están abiertos al mundo. Ideal para datos públicos o pruebas.
  • Sí (Privada): Requiere un token JWT Bearer válido para acceder.
• Estado: Las aplicaciones "Deshabilitadas" rechazarán todas las solicitudes entrantes inmediatamente.

Exportación y Migración de Datos

Puede exportar los datos completos de cualquier aplicación como un archivo JSON descargable directamente desde la tabla de Aplicaciones en su panel de control. Haga clic en el botón de descarga en la columna de Acciones.

Qué incluye

• Metadatos de la aplicación: Nombre, versión, subdominio, configuración de privacidad, estado y contexto generado por IA.
• Definiciones de endpoints: Rutas, schemas JSON, políticas de seguridad, métodos HTTP permitidos y documentación.
• Todos los registros de datos: Cada registro almacenado en todos los endpoints JSON, transmitidos progresivamente para evitar problemas de memoria.
• Metadatos de endpoints de archivos: Nombres de archivos, tipos de contenido y tamaños (los archivos binarios no se incluyen en la exportación).
• Resumen de exportación: Total de endpoints, conteos de registros (JSON vs Archivos) y estadísticas de uso compartido.

Garantías de seguridad

• Solo una exportación a la vez por cuenta de usuario — previene sobrecarga del sistema y DoS.
• Todas las operaciones de escritura (POST, PUT, DELETE) se pausan temporalmente durante la exportación para garantizar una instantánea consistente.
• El bloqueo de exportación se libera automáticamente después de 10 minutos si la descarga se interrumpe.
• Estricto aislamiento de inquilinos — solo puede exportar aplicaciones que le pertenecen.

Constructor de Schemas

Diseñando Sus Datos

El Constructor de Schemas es donde define la estructura de sus objetos de base de datos. Igniral utiliza esta definición para validar los datos entrantes y generar documentación HTML.

Inferencia Inteligente de Tipos

Al agregar atributos, Igniral sugiere automáticamente el tipo de dato apropiado basándose en el nombre:

• email → string (formato: email)
• created_at, dob → string (formato: date-time)
• is_active, has_access → boolean
• price, rating → number
• count, age → integer

Configuración Avanzada

Para cada atributo, puede configurar:

• Obligatorio: Marca el campo como requerido. Las solicitudes que no incluyan este campo fallarán con un error 400.
• Único: Asegura que no haya dos registros con el mismo valor (ej., para Nombres de usuario o SKUs).
• Array/Objeto: Cree estructuras complejas anidadas seleccionando estos tipos.

Carga de Archivos

Propósito

La sección de Carga de Archivos le permite gestionar los archivos que han sido subidos a los endpoints de archivos de su aplicación. Puede ver, descargar y eliminar archivos almacenados en su API.

Primeros Pasos

Para gestionar archivos, siga estos pasos:

• Seleccionar Aplicación: Elija la aplicación que contiene los archivos que desea gestionar.
• Seleccionar Endpoint: Elija un endpoint de archivos para ver sus archivos subidos.

Subir Archivos

Una vez seleccionada una aplicación y endpoint, haga clic en el botón Subir Archivo. Puede:

• Arrastrar y soltar archivos directamente en la zona de carga.
• Hacer clic para buscar y seleccionar archivos desde su computadora.

Gestionar Archivos

Para cada archivo subido, puede:

• Ver: Haga clic en el nombre del archivo para abrirlo en una nueva pestaña.
• Descargar: Haga clic en el botón de descarga para guardar el archivo localmente.
• Eliminar: Haga clic en el ícono de papelera para eliminar permanentemente el archivo.

Métricas de API

Monitoreo de Rendimiento

Mantenga seguimiento de la salud y los patrones de uso de su API. Las métricas se agregan en tiempo real.

Indicadores Clave

• Latencia Promedio: El tiempo que tarda el servidor en procesar una solicitud. Una latencia consistentemente alta (>500ms) puede indicar consultas ineficientes o carga excesiva.
• Tasa de Errores (4xx/5xx):
  • 4xx (Error del Cliente): Generalmente significa datos inválidos enviados por el usuario (ej., campos faltantes).
  • 5xx (Error del Servidor): Indica un problema en la plataforma de Igniral o en la conectividad de la base de datos.

Tendencias de Uso

Use el gráfico "Solicitudes en el Tiempo" para identificar las horas pico de uso. La lista "Endpoints Principales" le ayuda a optimizar las partes más críticas de su aplicación.

Control de Acceso

Asegurando Sus Aplicaciones Privadas

Cuando una aplicación está configurada como Privada, solo los usuarios autenticados con los permisos correctos pueden acceder a ella. Control de Acceso es donde gestiona estas entidades.

Gestión de Usuarios

Cree cuentas para los consumidores reales de su API (ej., usuarios de aplicaciones móviles, clientes frontend). Puede suspender usuarios instantáneamente para revocar su acceso sin eliminar sus datos.

Control de Acceso Basado en Roles (RBAC)

Los roles son colecciones de permisos que se pueden asignar a los usuarios. Esto permite políticas de seguridad flexibles:

• Rol Admin: Podría tener GET, POST, PUT, DELETE en todos los recursos.
• Rol Visor: Podría tener solo permisos de GET.
• Rol Editor: Podría tener GET y PUT, pero no DELETE.

Los usuarios obtienen un token de acceso iniciando sesión a través del endpoint /auth/login de su aplicación. Este token debe enviarse en el encabezado Authorization: Bearer <token> de las solicitudes subsiguientes.

Cifrado de Datos

Descripción General

Igniral proporciona cifrado en reposo integrado para proteger los datos sensibles almacenados en sus endpoints. El cifrado se aplica automáticamente — no se necesitan cambios de código de su parte. Sus datos se cifran antes de guardarse y se descifran de forma transparente cuando los lee a través de la API.

Cómo Funciona

Igniral aplica cifrado a nivel de campo para proteger los valores sensibles dentro de sus registros JSON mediante AES-256-GCM, un algoritmo de cifrado autenticado de grado militar. Usted elige qué campos son sensibles (ej., ssn, historial_medico, tarjeta_credito) marcándolos en el schema, e Igniral cifra solo esos campos — los campos no sensibles permanecen en texto plano para que puedan consultarse y filtrarse normalmente.

Para campos que necesitan ser buscables aun estando cifrados, Igniral genera automáticamente índices ciegos (HMAC-SHA256). Esto permite buscar por valor exacto sin exponer jamás el texto plano.

Almacenamiento de Archivos

Los archivos subidos pasan primero por un bucket de cuarentena donde un escáner ClamAV los analiza. Solo los archivos limpios se mueven al bucket de producción y quedan disponibles para descarga. El cifrado en reposo de los objetos almacenados es gestionado de forma estándar por el proveedor cloud.

Aislamiento y Derivación de Claves

Igniral deriva una clave de cifrado única para cada inquilino de forma interna a partir de una clave maestra utilizando HKDF (Función de Derivación de Claves basada en HMAC). Las claves nunca se exponen a los usuarios finales. Esto garantiza:

• Aislamiento de inquilinos: La clave de cada inquilino es matemáticamente independiente de la de cualquier otro.
• Sin almacenamiento de claves en texto plano: Las claves de cifrado se derivan al vuelo y se almacenan en caché solo en memoria — nunca se guardan en la base de datos.

Rotación Automática de Claves

Igniral soporta rotación de claves sin interrupciones y sin tiempo de inactividad. Un job de Cloud Scheduler dispara el proceso automáticamente cada 180 días:

1. Se activa una nueva versión de clave.
2. Todos los datos cifrados existentes se re-cifran registro a registro con la nueva clave.
3. Las versiones anteriores de claves se retienen temporalmente para compatibilidad durante la transición.
4. Un registro de auditoría documenta cada evento de rotación para cumplimiento normativo.

Inicio de Sesión con Google

Descripción General

Permita que los usuarios finales de su aplicación inicien sesión con su cuenta de Google. Igniral actúa como un intermediario seguro — todo el intercambio OAuth ocurre del lado del servidor. No necesita un Google Client ID ni credenciales OAuth.

Configuración

1. Vaya a Aplicaciones en el Panel de Control y edite su aplicación.
2. Active Inicio de Sesión con Google.
3. Seleccione un Rol Predeterminado para los nuevos usuarios de inicio de sesión social.
4. Ingrese su URI de Redirección — la URL donde los usuarios llegan después de la autenticación (ej., https://miapp.com/auth/callback).
5. Haga clic en Guardar.

Integración

En su frontend, agregue un enlace o botón que redirija a los usuarios a la URL de autorización (mostrada en el Panel de Control después de guardar). Esta URL debe abrirse en un navegador — es un flujo OAuth basado en redirección, no una API REST.

<a href="https://auth.igniral.io/api/oauth/google/authorize?applicationId=YOUR_APP_ID">
  Iniciar sesión con Google
</a>

Después de la autenticación, el usuario es redirigido a su URI de Redirección con parámetros de consulta:

https://miapp.com/callback?token=eyJhbG...&refresh_token=AMf-vB...&email=user@example.com

Usando el Token

Use el valor del token como token Bearer para todas las solicitudes de API:

curl https://{your-subdomain}.igniral.io/api/products \
  -H "Authorization: Bearer eyJhbG..."

Autenticación de Dos Factores (2FA)

Descripción General

Agregue autenticación de dos factores basada en TOTP a las cuentas de usuario de su aplicación. Cuando 2FA está habilitado, los usuarios deben proporcionar un código de 6 dígitos desde una aplicación autenticadora (Google Authenticator, Authy, Microsoft Authenticator, etc.) durante el inicio de sesión.

Configuración de Autoservicio (API)

Los usuarios gestionan su propio 2FA a través de estos endpoints:

Flujo de Inicio de Sesión con 2FA

Cuando un usuario con 2FA habilitado llama a /api/oauth/login, el inicio de sesión retorna un desafío en lugar de tokens:

// Paso 1: Login → retorna challengeId
POST /api/oauth/login
{ "email": "user@example.com", "password": "..." }

→ { "twoFactorRequired": true, "challengeId": "a1b2c3d4-..." }

// Paso 2: Verificar 2FA → retorna tokens
POST /api/oauth/verify-2fa
{ "challengeId": "a1b2c3d4-...", "totpCode": "123456" }

→ { "accessToken": "eyJhbG...", "refreshToken": "AMf-vB...", "expiresIn": "3600" }

Configuración de Cuenta

Mejores Prácticas de Seguridad

Política de Contraseñas: La contraseña de su panel de control protege todas sus aplicaciones. Aplicamos una política de contraseñas fuerte (mínimo 12 caracteres, mayúsculas y minúsculas, números, símbolos) para prevenir acceso no autorizado.

Autenticación de Dos Factores (2FA): Recomendamos encarecidamente habilitar 2FA. Esto agrega un segundo paso al proceso de inicio de sesión, requiriendo un código temporal de una aplicación como Google Authenticator o Authy. Incluso si su contraseña se ve comprometida, su cuenta permanece segura. Importante: Guarde sus códigos de recuperación en un lugar seguro al habilitar 2FA; son la única forma de recuperar el acceso si pierde su teléfono.

Gestión de Datos

Suscripciones

Planes y Precios

Igniral ofrece planes flexibles diseñados para crecer con sus necesidades. Puede actualizar o reducir su plan en cualquier momento desde el panel de control.

Facturación y Gestión

• Ciclo de Facturación: Las suscripciones se facturan mensualmente en la fecha en que se registró.
• Actualización: Los cambios toman efecto inmediatamente. Se le cobrará la diferencia prorrateada del mes actual.
• Reducción: Los cambios toman efecto al inicio del siguiente ciclo de facturación. Conserva las funciones de su plan actual hasta entonces.
• Cancelación: Puede cancelar su suscripción en cualquier momento. Su acceso continúa hasta el final del período de facturación.

Referencia de API

Documentación OpenAPI / Swagger

Cada aplicación que crea en Igniral genera automáticamente una especificación OpenAPI (Swagger) completa. Esta documentación siempre está sincronizada con sus definiciones de schemas.

Acceder a Su Documentación de API

Puede acceder a la interfaz Swagger de su aplicación desde el panel de control:

1. Navegue a su Aplicación en el panel de control
2. Haga clic en el botón API Docs en la tarjeta de la aplicación
3. Explore endpoints, pruebe solicitudes y descargue la especificación OpenAPI

Características

• Pruebas Interactivas: Pruebe llamadas a la API directamente desde la documentación
• Ejemplos de Solicitud/Respuesta: Vea payloads de ejemplo para cada endpoint
• Definiciones de Schemas: Vea el modelo de datos completo de sus recursos
• Autenticación: Configure tokens Bearer para endpoints privados

Agente IA (MCP)

Construyendo con IA

Igniral proporciona un servidor Model Context Protocol (MCP) que conecta agentes de IA (Claude, Cursor, Antigravity, etc.) con su plataforma backend. Describa su API en lenguaje natural, y el agente genera automáticamente el schema, endpoints CRUD y control de acceso.

Requisitos Previos

1. Genere Claves de API de Agente desde el Panel de Control → Claves de API de Agente
2. Tener Node.js ≥ 18 instalado en su máquina

Configuración Rápida

Agregue la siguiente configuración a su IDE de IA. Reemplace agent-xxxxxxxxxxxx y your-client-secret con sus credenciales de Clave de API de Agente.

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "igniral": {
      "command": "npx",
      "args": ["-y", "igniral-mcp-server"],
      "env": {
        "IGNIRAL_CLIENT_ID": "agent-xxxxxxxxxxxx",
        "IGNIRAL_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "igniral": {
      "command": "npx",
      "args": ["-y", "igniral-mcp-server"],
      "env": {
        "IGNIRAL_CLIENT_ID": "agent-xxxxxxxxxxxx",
        "IGNIRAL_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Antigravity (~/.gemini/antigravity/mcp_config.json)

{
  "mcpServers": {
    "igniral": {
      "command": "npx",
      "args": ["-y", "igniral-mcp-server"],
      "env": {
        "IGNIRAL_CLIENT_ID": "agent-xxxxxxxxxxxx",
        "IGNIRAL_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Nota: Antigravity puede no heredar el PATH de su shell. Use la ruta absoluta a npx o node (ej., /opt/homebrew/bin/npx) si obtiene errores de "ejecutable no encontrado".

Herramientas de Agente Disponibles

• igniral_generate_schema_from_prompt: Genere automáticamente una aplicación completa a partir de una descripción en lenguaje natural.
• igniral_create_application: Cree una aplicación vacía.
• igniral_create_dynamic_endpoint: Agregue endpoints de API a una aplicación existente.
• igniral_list_applications: Liste sus aplicaciones existentes.

Preguntas Frecuentes