{ "openapi": "3.0.0", "info": { "title": "AR Sistema ERP - Multi-Tenant API Documentation", "description": "Documentación oficial de la API de AR Sistema ERP. Incluye endpoints de autenticación, administración del ERP y la API REST M2M para integraciones CRM externas.", "contact": { "name": "Soporte Técnico AR Sistema", "email": "soporte@arsistema.com" }, "version": "1.0.0" }, "servers": [ { "url": "http://arsistema.localhost:8000/api", "description": "Entorno Local de Desarrollo (Multi-tenant Tenant Subdomain / Key)" }, { "url": "http://localhost:8000/api", "description": "Servidor de desarrollo genérico" } ], "paths": { "/api-keys": { "get": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Listar API Keys del Tenant", "description": "Obtiene todas las llaves de API activas y revocadas asociadas a la empresa/tenant.", "operationId": "getApiKeys", "responses": { "200": { "description": "Listado de API Keys" }, "401": { "description": "No autenticado" }, "403": { "description": "Sin permisos suficientes" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] }, "post": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Generar nueva API Key M2M", "description": "Genera una nueva llave secreta para integración externa con CRM. El secreto completo sólo se muestra en la respuesta de este endpoint.", "operationId": "storeApiKey", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Integración CRM HubSpot" }, "scopes": { "type": "array", "items": { "type": "string" }, "example": [ "students:read", "enrollments:write" ] }, "allowed_ips": { "type": "array", "items": { "type": "string" }, "example": [ "192.168.1.1" ] }, "expires_in_days": { "type": "integer", "example": 90 } }, "type": "object" } } } }, "responses": { "201": { "description": "API Key creada exitosamente" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/api-keys/{id}": { "delete": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Revocar API Key", "description": "Revoca inmediatamente el acceso a una API Key existente.", "operationId": "destroyApiKey", "parameters": [ { "name": "id", "in": "path", "description": "ID de la API Key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "API Key revocada" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/register": { "post": { "tags": [ "1. Públicas & Autenticación" ], "summary": "Registro de usuario bajo el tenant actual", "description": "Registra un usuario asociado a la academia/tenant activa identificada por header o subdominio.", "operationId": "authRegister", "parameters": [ { "name": "X-Tenant-Key", "in": "header", "description": "Subdominio o Key del tenant", "required": false, "schema": { "type": "string", "example": "arsistema" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "last_name", "email", "password" ], "properties": { "name": { "type": "string", "example": "Juan" }, "last_name": { "type": "string", "example": "Pérez" }, "email": { "type": "string", "format": "email", "example": "juan@ejemplo.com" }, "password": { "type": "string", "format": "password", "example": "password123" }, "cedula": { "type": "string", "example": "V-12345678" } }, "type": "object" } } } }, "responses": { "201": { "description": "Usuario registrado e inicio de sesión establecido" }, "422": { "description": "Error de validación" } } } }, "/login": { "post": { "tags": [ "1. Públicas & Autenticación" ], "summary": "Inicio de sesión de usuario ERP", "description": "Autentica las credenciales del usuario para el tenant activo y establece la cookie de sesión Sanctum.", "operationId": "authLogin", "parameters": [ { "name": "X-Tenant-Key", "in": "header", "description": "Subdominio o Key del tenant", "required": false, "schema": { "type": "string", "example": "arsistema" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "example": "admin@arsistema.com" }, "password": { "type": "string", "format": "password", "example": "password123" } }, "type": "object" } } } }, "responses": { "200": { "description": "Autenticación exitosa" }, "401": { "description": "Credenciales inválidas" } } } }, "/logout": { "post": { "tags": [ "1. Públicas & Autenticación" ], "summary": "Cerrar sesión de usuario", "description": "Destruye la sesión activa del usuario.", "operationId": "authLogout", "responses": { "200": { "description": "Sesión cerrada correctamente" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/me": { "get": { "tags": [ "1. Públicas & Autenticación" ], "summary": "Obtener detalles del usuario autenticado", "description": "Devuelve la información del usuario autenticado, roles, permisos y tenant activo.", "operationId": "authMe", "responses": { "200": { "description": "Detalles del usuario autenticado" }, "401": { "description": "No autenticado" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/bank-accounts": { "get": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Listar Cuentas Bancarias ERP", "description": "Obtiene las cuentas bancarias configuradas para la recepción de pagos del tenant.", "operationId": "getBankAccounts", "responses": { "200": { "description": "Listado de cuentas bancarias" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] }, "post": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Registrar Cuenta Bancaria", "description": "Registra una nueva cuenta bancaria para recaudación.", "operationId": "storeBankAccount", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "bank_name", "account_number", "account_type", "holder_name", "holder_id" ], "properties": { "bank_name": { "type": "string", "example": "Banesco Banco Universal" }, "account_number": { "type": "string", "example": "01340123456789012345" }, "account_type": { "type": "string", "example": "Corriente", "enum": [ "Corriente", "Ahorro" ] }, "holder_name": { "type": "string", "example": "AR Sistema C.A." }, "holder_id": { "type": "string", "example": "J-12345678-9" }, "phone_number": { "type": "string", "example": "04121234567" }, "email": { "type": "string", "format": "email", "example": "pagos@arsistema.com" } }, "type": "object" } } } }, "responses": { "201": { "description": "Cuenta bancaria registrada" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/bank-accounts/{bank_account}": { "get": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Detalles de Cuenta Bancaria", "description": "Obtiene información detallada de una cuenta bancaria.", "operationId": "getBankAccountShow", "parameters": [ { "name": "bank_account", "in": "path", "description": "ID de la Cuenta Bancaria", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Detalles de la cuenta" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] }, "put": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Actualizar Cuenta Bancaria", "description": "Actualiza datos de una cuenta bancaria.", "operationId": "updateBankAccount", "parameters": [ { "name": "bank_account", "in": "path", "description": "ID de la Cuenta Bancaria", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "enum": [ "active", "inactive" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Cuenta bancaria actualizada" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] }, "delete": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Eliminar Cuenta Bancaria", "description": "Elimina una cuenta bancaria de la configuración.", "operationId": "deleteBankAccount", "parameters": [ { "name": "bank_account", "in": "path", "description": "ID de la Cuenta Bancaria", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Cuenta bancaria eliminada" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/courses": { "get": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Listar Cursos del ERP (Paginado)", "description": "Obtiene el catálogo paginado de cursos de la academia/tenant activa.", "operationId": "getCourses", "parameters": [ { "name": "per_page", "in": "query", "description": "Cantidad por página", "required": false, "schema": { "type": "integer", "default": 10 } } ], "responses": { "200": { "description": "Listado paginado de cursos" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] }, "post": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Crear Nuevo Curso ERP", "description": "Crea un nuevo curso en la oferta académica.", "operationId": "createCourse", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "start_date", "end_date", "days", "start_time", "end_time", "duration_months", "price_usd" ], "properties": { "code": { "type": "string", "example": "PROG-101" }, "name": { "type": "string", "example": "Programación Web Fullstack" }, "description": { "type": "string", "example": "Curso intensivo de desarrollo web" }, "teacher_id": { "type": "integer", "example": 1 }, "start_date": { "type": "string", "format": "date", "example": "2026-09-01" }, "end_date": { "type": "string", "format": "date", "example": "2026-12-01" }, "days": { "type": "array", "items": { "type": "string" }, "example": [ "Lunes", "Miércoles" ] }, "start_time": { "type": "string", "example": "14:00" }, "end_time": { "type": "string", "example": "16:00" }, "duration_months": { "type": "string", "example": "3 meses" }, "price_usd": { "type": "number", "format": "float", "example": 150 } }, "type": "object" } } } }, "responses": { "201": { "description": "Curso creado exitosamente" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/v1/crm/courses": { "get": { "tags": [ "3. CRM M2M API (X-API-Key)" ], "summary": "Catálogo de Cursos para CRM (M2M)", "description": "Consulta del catálogo de cursos para integraciones externas vía API Key (Scope: `courses:read`).", "operationId": "crmGetCourses", "parameters": [ { "name": "per_page", "in": "query", "description": "Cantidad por página", "required": false, "schema": { "type": "integer", "default": 10 } } ], "responses": { "200": { "description": "Listado paginado de cursos" } }, "security": [ { "ApiKeyAuth": [], "TenantKey": [] } ] } }, "/courses/{course}": { "get": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Detalles del Curso ERP", "description": "Obtiene los datos detallados del curso incluyendo profesor y alumnos inscritos.", "operationId": "getCourseShow", "parameters": [ { "name": "course", "in": "path", "description": "ID del Curso", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Detalles del curso" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] }, "put": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Actualizar Curso ERP", "description": "Actualiza la información, horarios o profesor asignado a un curso.", "operationId": "updateCourse", "parameters": [ { "name": "course", "in": "path", "description": "ID del Curso", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "price_usd": { "type": "number", "format": "float" }, "status": { "type": "string", "enum": [ "active", "inactive" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Curso actualizado" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] }, "delete": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Eliminar Curso ERP", "description": "Elimina un curso de la base de datos.", "operationId": "deleteCourse", "parameters": [ { "name": "course", "in": "path", "description": "ID del Curso", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Curso eliminado" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/dashboard-menu": { "get": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Obtener Árbol de Menú Dinámico del Dashboard", "description": "Retorna la estructura jerárquica del menú lateral filtrada automáticamente según los permisos Spatie del usuario autenticado.", "operationId": "getDashboardMenu", "responses": { "200": { "description": "Estructura de menú filtrada por permisos" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/enrollments": { "post": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Inscribir Alumno en Curso (ERP)", "description": "Inscribe a un estudiante en un curso verificando choque de horarios y generando sus cuotas de mensualidad automáticamente.", "operationId": "enrollStudentERP", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "student_id", "course_id" ], "properties": { "student_id": { "type": "integer", "example": 1 }, "course_id": { "type": "integer", "example": 2 } }, "type": "object" } } } }, "responses": { "201": { "description": "Inscripción realizada exitosamente" }, "422": { "description": "Solapamiento de horarios o cuotas pendientes" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/v1/crm/enrollments": { "post": { "tags": [ "3. CRM M2M API (X-API-Key)" ], "summary": "Inscripción Automatizada desde CRM (M2M)", "description": "Inscribe automáticamente un alumno desde CRM externo mediante API Key (Scope: `enrollments:write`).", "operationId": "crmEnrollStudent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "student_id", "course_id" ], "properties": { "student_id": { "type": "integer", "example": 1 }, "course_id": { "type": "integer", "example": 2 } }, "type": "object" } } } }, "responses": { "201": { "description": "Inscripción automatizada exitosa" } }, "security": [ { "ApiKeyAuth": [], "TenantKey": [] } ] } }, "/exchange-rates": { "get": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Listar Tasas de Cambio BCV", "description": "Obtiene el historial registrado de tasas oficiales del Banco Central de Venezuela (USD / EUR).", "operationId": "getExchangeRates", "responses": { "200": { "description": "Historial de tasas de cambio" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] }, "post": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Registrar Tasa BCV Manual", "description": "Registra manualmente la tasa oficial BCV del día.", "operationId": "storeExchangeRate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "rate_bcv_usd", "rate_bcv_eur", "rate_date" ], "properties": { "rate_bcv_usd": { "type": "number", "format": "float", "example": 36.5 }, "rate_bcv_eur": { "type": "number", "format": "float", "example": 39.8 }, "rate_date": { "type": "string", "format": "date", "example": "2026-07-28" } }, "type": "object" } } } }, "responses": { "201": { "description": "Tasa creada exitosamente" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/exchange-rates/sync": { "post": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Sincronizar Tasas de Cambio BCV", "description": "Sincroniza automáticamente la tasa del BCV del día raspando el BCV o consultando el servicio DolarApi de respaldo.", "operationId": "syncExchangeRates", "responses": { "200": { "description": "Tasa BCV del día registrada/actualizada exitosamente" }, "500": { "description": "Fallo en la comunicación con BCV / servicio de respaldo" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/exchange-rates/{exchange_rate}": { "get": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Detalles de Tasa BCV", "description": "Obtiene los datos de un registro de tasa específico.", "operationId": "getExchangeRateShow", "parameters": [ { "name": "exchange_rate", "in": "path", "description": "ID de la Tasa", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Detalles de la tasa" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] }, "put": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Actualizar Tasa BCV", "description": "Actualiza una tasa de cambio existente.", "operationId": "updateExchangeRate", "parameters": [ { "name": "exchange_rate", "in": "path", "description": "ID de la Tasa", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "rate_bcv_usd": { "type": "number", "format": "float" }, "rate_bcv_eur": { "type": "number", "format": "float" } }, "type": "object" } } } }, "responses": { "200": { "description": "Tasa actualizada" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] }, "delete": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Eliminar Tasa BCV", "description": "Elimina un registro de tasa de cambio.", "operationId": "deleteExchangeRate", "parameters": [ { "name": "exchange_rate", "in": "path", "description": "ID de la Tasa", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Tasa eliminada" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/installments": { "get": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Listar Mensualidades / Cuotas del ERP", "description": "Obtiene las mensualidades filtradas opcionalmente por estudiante o estado (pending, paid, late, processing).", "operationId": "getInstallments", "parameters": [ { "name": "student_id", "in": "query", "description": "ID del Alumno", "required": false, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "description": "Estado de la cuota", "required": false, "schema": { "type": "string", "enum": [ "pending", "paid", "late", "processing" ] } } ], "responses": { "200": { "description": "Listado de cuotas de mensualidad" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/installments/{installment}/pay": { "post": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Registrar Pago de Mensualidad", "description": "Registra un reporte de pago para una cuota académica y genera el registro en la cola de conciliación.", "operationId": "payInstallment", "parameters": [ { "name": "installment", "in": "path", "description": "ID de la mensualidad", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "payment_method" ], "properties": { "payment_method": { "type": "string", "example": "Pago Móvil" }, "reference": { "type": "string", "example": "REF-987654" }, "notes": { "type": "string", "example": "Transferencia desde Mercantil" }, "bank_account_id": { "type": "integer", "example": 1 }, "attachment": { "description": "Comprobante digital del pago", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Reporte de pago registrado en proceso de validación" }, "422": { "description": "Mensualidad ya pagada o datos requeridos faltantes" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/payments": { "get": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Listar Registros de Pago para Conciliación", "description": "Obtiene los pagos registrados por los estudiantes pendientes por conciliar o filtrados por estado.", "operationId": "getPayments", "parameters": [ { "name": "student_id", "in": "query", "description": "ID del Estudiante", "required": false, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "description": "Estado del pago", "required": false, "schema": { "type": "string", "enum": [ "pending_validation", "approved", "declined", "under_review", "insufficient_funds", "incorrect_reference" ] } }, { "name": "start_date", "in": "query", "description": "Fecha de inicio (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "description": "Fecha fin (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "search", "in": "query", "description": "Búsqueda por referencia o nombre de alumno", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Listado de pagos" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/payments/{payment}/reconcile": { "post": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Conciliar / Validar Pago", "description": "Aprueba o declina un pago reportado (o establece un estado intermedio). Al aprobar, marca la mensualidad como pagada y verifica reactivación de alumno suspendido.", "operationId": "reconcilePayment", "parameters": [ { "name": "payment", "in": "path", "description": "ID del Pago", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "action" ], "properties": { "action": { "type": "string", "example": "approve", "enum": [ "approve", "decline", "under_review", "insufficient_funds", "incorrect_reference" ] }, "decline_reason": { "type": "string", "example": "El número de transferencia no coincide con la cuenta receptora." } }, "type": "object" } } } }, "responses": { "200": { "description": "Pago verificado y actualizado con éxito" }, "422": { "description": "Falta motivo de rechazo o acción no válida" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/payments/report": { "get": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Reporte General y Estadísticas de Pagos", "description": "Retorna el resumen financiero de ingresos recaudados en USD, desglosado por métodos de pago y totales pendientes/declinados.", "operationId": "getPaymentsReport", "parameters": [ { "name": "start_date", "in": "query", "description": "Desde fecha", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "description": "Hasta fecha", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Métricas y desglose de reportes de pago" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/public/register-tenant": { "post": { "tags": [ "1. Públicas & Autenticación" ], "summary": "Registro público de un nuevo Tenant / Academia", "description": "Crea un nuevo tenant/sucursal en el sistema, configura sus permisos por defecto, su menú dinámico y el usuario administrador inicial.", "operationId": "registerTenantPublic", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "company_name", "subdomain", "rif", "admin_name", "admin_last_name", "email", "password" ], "properties": { "company_name": { "type": "string", "example": "Academia Digital" }, "subdomain": { "type": "string", "example": "academiadigital" }, "rif": { "type": "string", "example": "J-12345678-9" }, "phone": { "type": "string", "example": "+584121234567" }, "address": { "type": "string", "example": "Caracas, Venezuela" }, "brand_name": { "type": "string", "example": "Academia Digital Marca" }, "course_code_prefix": { "type": "string", "example": "ACAD" }, "admin_name": { "type": "string", "example": "Carlos" }, "admin_last_name": { "type": "string", "example": "Pérez" }, "email": { "type": "string", "format": "email", "example": "admin@academiadigital.com" }, "password": { "type": "string", "format": "password", "example": "Secret123!" } }, "type": "object" } } } }, "responses": { "201": { "description": "Tenant registrado exitosamente", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Sucursal / Tenant registrado con éxito." }, "redirect_subdomain": { "type": "string", "example": "academiadigital" }, "token": { "type": "string", "example": "1|AbCdEfGhIj..." } }, "type": "object" } } } }, "422": { "description": "Error de validación (subdomain o email duplicado, datos faltantes)" } } } }, "/reports/hub": { "get": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Hub Central de Reportes y KPIs (ERP)", "description": "Obtiene el resumen consolidado de métricas clave (ingresos, estudiantes activos/suspendidos, cursos, docentes, marketing y riesgo).", "operationId": "getReportHub", "responses": { "200": { "description": "Resumen de KPIs centralizados" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/v1/crm/reports/hub": { "get": { "tags": [ "3. CRM M2M API (X-API-Key)" ], "summary": "Hub KPIs Centralizados para CRM (M2M)", "description": "Consulta del resumen general de KPIs para CRM externo vía API Key (Scope: `reports:read`).", "operationId": "crmGetReportHub", "responses": { "200": { "description": "Resumen de KPIs centralizados" } }, "security": [ { "ApiKeyAuth": [], "TenantKey": [] } ] } }, "/reports/students": { "get": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Reporte Detallado de Alumnos y Solvencia", "description": "Reporte ejecutivo del listado de alumnos, estado de solvencia y deuda acumulada.", "operationId": "getStudentsReport", "parameters": [ { "name": "status", "in": "query", "description": "Filtro estado (active, suspended)", "required": false, "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Búsqueda por cédula o nombre", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Reporte de estudiantes y solvencia" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/reports/courses": { "get": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Reporte de Ocupación e Ingresos por Curso", "description": "Muestra el número de matriculados e ingresos recaudados y pendientes por cada curso ofertado.", "operationId": "getCoursesReport", "responses": { "200": { "description": "Reporte de cursos" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/reports/teachers": { "get": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Reporte de Carga Docente y Asignaciones", "description": "Presenta la distribución de cursos y total de alumnos atendidos por cada profesor.", "operationId": "getTeachersReport", "responses": { "200": { "description": "Reporte de docentes" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/reports/financial": { "get": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Reporte de Tendencia Financiera Mensual", "description": "Retorna la curva mensual de ingresos recaudados en USD y su equivalente en Bolívares según la tasa BCV.", "operationId": "getFinancialReport", "parameters": [ { "name": "year", "in": "query", "description": "Año a consultar", "required": false, "schema": { "type": "integer", "default": 2026 } } ], "responses": { "200": { "description": "Tendencia mensual de recaudación" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/reports/marketing": { "get": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Reporte de Captación y Conversión de Alumnos", "description": "Ofrece estadísticas sobre el embudo de conversión de registros e inscritos por mes.", "operationId": "getMarketingReport", "parameters": [ { "name": "year", "in": "query", "description": "Año a consultar", "required": false, "schema": { "type": "integer", "default": 2026 } } ], "responses": { "200": { "description": "Métricas de captación" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/reports/at-risk": { "get": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Radar de Alumnos en Riesgo y Alerta Temprana (ERP)", "description": "Evalúa el puntaje de riesgo financiero y académico (0-100) para cada alumno y genera recomendaciones automatizadas.", "operationId": "getAtRiskReport", "parameters": [ { "name": "min_score", "in": "query", "description": "Puntaje mínimo de riesgo (0 a 100)", "required": false, "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Evaluación de riesgo y alertas tempranas" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/v1/crm/reports/at-risk": { "get": { "tags": [ "3. CRM M2M API (X-API-Key)" ], "summary": "Alerta Temprana de Alumnos en Riesgo para CRM (M2M)", "description": "Consulta del radar de alumnos en mora o riesgo para CRM externo vía API Key (Scope: `reports:read`).", "operationId": "crmGetAtRiskReport", "parameters": [ { "name": "min_score", "in": "query", "description": "Puntaje mínimo de riesgo (0 a 100)", "required": false, "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Evaluación de riesgo de alumnos" } }, "security": [ { "ApiKeyAuth": [], "TenantKey": [] } ] } }, "/students": { "get": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Listar Alumnos del ERP", "description": "Obtiene el listado completo de alumnos pertenecientes a la academia/tenant activa.", "operationId": "getStudents", "responses": { "200": { "description": "Listado de estudiantes" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] }, "post": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Crear Alumno en ERP", "description": "Registra un nuevo estudiante en el ERP.", "operationId": "createStudent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "cedula", "phone", "age", "first_name", "paternal_last_name", "maternal_last_name", "address" ], "properties": { "cedula": { "type": "string", "example": "V-12345678" }, "phone": { "type": "string", "example": "+584121234567" }, "age": { "type": "integer", "example": 20 }, "first_name": { "type": "string", "example": "María" }, "middle_name": { "type": "string", "example": "Elena" }, "paternal_last_name": { "type": "string", "example": "Gómez" }, "maternal_last_name": { "type": "string", "example": "López" }, "address": { "type": "string", "example": "Caracas, Venezuela" } }, "type": "object" } } } }, "responses": { "201": { "description": "Estudiante creado exitosamente" }, "422": { "description": "Cédula duplicada o campos requeridos faltantes" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/v1/crm/students": { "get": { "tags": [ "3. CRM M2M API (X-API-Key)" ], "summary": "Listar Alumnos para CRM Externe (M2M)", "description": "Consulta de alumnos para integraciones externas mediante API Key (Scope: `students:read`).", "operationId": "crmGetStudents", "responses": { "200": { "description": "Listado de estudiantes" } }, "security": [ { "ApiKeyAuth": [], "TenantKey": [] } ] }, "post": { "tags": [ "3. CRM M2M API (X-API-Key)" ], "summary": "Crear Alumno vía CRM External API (M2M)", "description": "Endpoint M2M para ingresar prospectos / alumnos desde CRM externo (Scope: `students:write`).", "operationId": "crmCreateStudent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "cedula", "phone", "age", "first_name", "paternal_last_name", "maternal_last_name", "address" ], "properties": { "cedula": { "type": "string", "example": "V-87654321" }, "phone": { "type": "string", "example": "+584141234567" }, "age": { "type": "integer", "example": 22 }, "first_name": { "type": "string", "example": "Pedro" }, "paternal_last_name": { "type": "string", "example": "Ramírez" }, "maternal_last_name": { "type": "string", "example": "Díaz" }, "address": { "type": "string", "example": "Valencia, Venezuela" } }, "type": "object" } } } }, "responses": { "201": { "description": "Estudiante creado desde CRM" } }, "security": [ { "ApiKeyAuth": [], "TenantKey": [] } ] } }, "/students/{student}": { "get": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Detalles del Alumno ERP", "description": "Obtiene los datos detallados de un estudiante.", "operationId": "getStudentShow", "parameters": [ { "name": "student", "in": "path", "description": "ID del Estudiante", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Detalles del alumno" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] }, "put": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Actualizar Alumno ERP", "description": "Actualiza la información personal o estado académico de un alumno.", "operationId": "updateStudent", "parameters": [ { "name": "student", "in": "path", "description": "ID del Estudiante", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "phone": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "graduated", "inactive", "suspended" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Estudiante actualizado" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] }, "delete": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Eliminar Alumno ERP", "description": "Elimina un registro de alumno.", "operationId": "deleteStudent", "parameters": [ { "name": "student", "in": "path", "description": "ID del Estudiante", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Estudiante eliminado" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/v1/crm/students/{student}": { "get": { "tags": [ "3. CRM M2M API (X-API-Key)" ], "summary": "Detalles de Alumno CRM (M2M)", "description": "Consulta detallada de un alumno para CRM externo (Scope: `students:read`).", "operationId": "crmGetStudentShow", "parameters": [ { "name": "student", "in": "path", "description": "ID del Estudiante", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Detalles del alumno" } }, "security": [ { "ApiKeyAuth": [], "TenantKey": [] } ] } }, "/v1/crm/students/{student}/progress": { "get": { "tags": [ "3. CRM M2M API (X-API-Key)" ], "summary": "Progreso Académico y Financiero del Alumno CRM (M2M)", "description": "Obtiene avance de cursos e historial financiero/solvencia para integraciones externas (Scope: `students:read`).", "operationId": "crmGetStudentProgress", "parameters": [ { "name": "student", "in": "path", "description": "ID del Estudiante", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Reporte de progreso académico y financiero del estudiante" } }, "security": [ { "ApiKeyAuth": [], "TenantKey": [] } ] } }, "/teachers": { "get": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Listar Profesores del ERP", "description": "Obtiene el listado completo de profesores de la academia/tenant.", "operationId": "getTeachers", "responses": { "200": { "description": "Listado de profesores" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] }, "post": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Crear Profesor ERP", "description": "Registra un nuevo profesor en el sistema.", "operationId": "createTeacher", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "cedula", "phone", "profession", "age", "first_name", "paternal_last_name", "maternal_last_name", "address" ], "properties": { "cedula": { "type": "string", "example": "V-99999999" }, "phone": { "type": "string", "example": "+584129998877" }, "profession": { "type": "string", "example": "Lic. en Educación / Programador" }, "age": { "type": "integer", "example": 35 }, "first_name": { "type": "string", "example": "Roberto" }, "paternal_last_name": { "type": "string", "example": "Silva" }, "maternal_last_name": { "type": "string", "example": "Rojas" }, "address": { "type": "string", "example": "Caracas, Venezuela" } }, "type": "object" } } } }, "responses": { "201": { "description": "Profesor creado exitosamente" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/v1/crm/teachers": { "get": { "tags": [ "3. CRM M2M API (X-API-Key)" ], "summary": "Listar Profesores para CRM (M2M)", "description": "Consulta del equipo docente para integraciones CRM externas vía API Key (Scope: `teachers:read`).", "operationId": "crmGetTeachers", "responses": { "200": { "description": "Listado de profesores" } }, "security": [ { "ApiKeyAuth": [], "TenantKey": [] } ] } }, "/teachers/{teacher}": { "get": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Detalles del Profesor ERP", "description": "Obtiene los datos detallados de un profesor.", "operationId": "getTeacherShow", "parameters": [ { "name": "teacher", "in": "path", "description": "ID del Profesor", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Detalles del profesor" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] }, "put": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Actualizar Profesor ERP", "description": "Actualiza la información de un profesor.", "operationId": "updateTeacher", "parameters": [ { "name": "teacher", "in": "path", "description": "ID del Profesor", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "phone": { "type": "string" }, "profession": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Profesor actualizado" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] }, "delete": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Eliminar Profesor ERP", "description": "Elimina un profesor.", "operationId": "deleteTeacher", "parameters": [ { "name": "teacher", "in": "path", "description": "ID del Profesor", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Profesor eliminado" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/tenant/settings": { "get": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Obtener Configuración del Tenant", "description": "Obtiene los datos del perfil corporativo de la academia (logo, RIF, teléfono, prefijo de cursos, etc.).", "operationId": "getTenantSettings", "responses": { "200": { "description": "Configuración del tenant" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] }, "post": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Actualizar Configuración del Tenant", "description": "Actualiza la información institucional y/o el logotipo oficial del tenant.", "operationId": "updateTenantSettings", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "name": { "type": "string", "example": "Academia AR Sistema" }, "rif": { "type": "string", "example": "J-50012345-6" }, "phone": { "type": "string", "example": "+582129990000" }, "email": { "type": "string", "format": "email", "example": "contacto@arsistema.com" }, "address": { "type": "string", "example": "Caracas, Venezuela" }, "brand_name": { "type": "string", "example": "AR Sistema ERP" }, "course_code_prefix": { "type": "string", "example": "ARS" }, "logo": { "description": "Imagen del logotipo", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Configuración de la academia actualizada" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/users": { "get": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Listar Usuarios del Tenant", "description": "Obtiene todos los usuarios registrados bajo la organización/tenant activa.", "operationId": "getUsers", "parameters": [ { "name": "search", "in": "query", "description": "Búsqueda por nombre o correo", "required": false, "schema": { "type": "string" } }, { "name": "role", "in": "query", "description": "Filtro por rol de usuario", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Listado de usuarios" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] }, "post": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Crear Usuario ERP", "description": "Crea un nuevo usuario administrativo o personal de la academia asignando su rol inicial.", "operationId": "storeUser", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email", "password", "role" ], "properties": { "name": { "type": "string", "example": "Ana" }, "last_name": { "type": "string", "example": "Martínez" }, "email": { "type": "string", "format": "email", "example": "ana@arsistema.com" }, "password": { "type": "string", "format": "password", "example": "Secret123" }, "role": { "type": "string", "example": "admin", "enum": [ "root", "gerente", "admin", "asistente", "profesor", "estudiante" ] } }, "type": "object" } } } }, "responses": { "201": { "description": "Usuario creado exitosamente" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/users/roles": { "get": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Listar Roles del Sistema", "description": "Obtiene los roles disponibles para asignar a los usuarios.", "operationId": "getUserRolesList", "responses": { "200": { "description": "Lista de roles y etiquetas" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } }, "/users/{user}": { "get": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Detalles del Usuario ERP", "description": "Obtiene información detallada de un usuario.", "operationId": "getUserShow", "parameters": [ { "name": "user", "in": "path", "description": "ID del Usuario", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Detalles del usuario" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] }, "put": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Actualizar Usuario ERP", "description": "Actualiza datos de un usuario o su rol.", "operationId": "updateUser", "parameters": [ { "name": "user", "in": "path", "description": "ID del Usuario", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "role": { "type": "string", "enum": [ "root", "gerente", "admin", "asistente", "profesor", "estudiante" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Usuario actualizado" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] }, "delete": { "tags": [ "2. ERP API Protegidas (Sanctum / Sesión)" ], "summary": "Eliminar Usuario ERP", "description": "Elimina la cuenta de usuario especificada.", "operationId": "deleteUser", "parameters": [ { "name": "user", "in": "path", "description": "ID del Usuario", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Usuario eliminado" } }, "security": [ { "SanctumAuth": [], "TenantKey": [] } ] } } }, "components": { "securitySchemes": { "TenantKey": { "type": "apiKey", "description": "Header requerido para identificar la academia / tenant (ej: arsistema)", "name": "X-Tenant-Key", "in": "header" }, "SanctumAuth": { "type": "http", "description": "Token de autenticación de usuario Sanctum Bearer o Cookie de Sesión SPA (`laravel_session`)", "bearerFormat": "JWT", "scheme": "bearer" }, "ApiKeyAuth": { "type": "apiKey", "description": "Llave de API M2M secreta de integración CRM externa (ej: `ark_live_...`)", "name": "X-API-Key", "in": "header" } } }, "tags": [ { "name": "1. Públicas & Autenticación", "description": "Endpoints públicos para registro de tenants, inicio y cierre de sesión de usuarios ERP" }, { "name": "2. ERP API Protegidas (Sanctum / Sesión)", "description": "API de gestión interna del ERP protegidas por sesión de usuario y rol (Cursos, Alumnos, Profesores, Mensualidades, Pagos, etc.)" }, { "name": "3. CRM M2M API (X-API-Key)", "description": "API REST v1 externa para integraciones M2M/CRM protegidas por X-API-Key y Tenant" } ] }