agenticSystem/mcp-server/tools/helpers/ACAI_ENDPOINTS.md

# Acai CMS Endpoints Reference

Este documento mapea todos los endpoints de Acai CMS utilizados por las herramientas MCP.

## Endpoints Base

- **CMS Admin**: `https://[website]/admin.php` - Panel administrativo principal
- **Viewer Functions**: `https://[website]/cms/lib/viewer_functions.php` - API de funciones Acai
- **SAAS API**: `https://ws.cocosolution.com/api/schemas/` - API SaaS para esquemas
- **File Upload**: `https://[website]/lib/menus/modals/plupload/multiupload/upload.php` - Subir archivos

## Categoría: Módulos (saveApartados)

### 1. Generar módulo desde HTML
**Endpoint**: `https://acai.cms.cocosolution.com/admin.php?menu=apartados&action=edit&generateModuleFromString=1`
**Método**: POST
**Usado por**: `save_module`
**Headers**: `Content-Type: application/json`, `X-Acai-Token`
**Payload**: moduleData object con html, htmlParsed, vars, etc.

### 2. Obtener esquemas de módulos
**Endpoint**: `/cms/lib/viewer_functions.php`
**Método**: POST via getApiClient
**Usado por**: `save_module`, `saveGeneralSection`, `check_module`, `list_modules`, `get_module`
**Action**: `getModuleSchemas`
**Payload via getCommonParams**:
```javascript
{
  action_ws: "getModuleSchemas",
  ids: [moduleId],    // opcional, para un módulo específico
  full: 1             // opcional, para obtener contenido completo
}
```

### 3. Verificar módulo
**Endpoint**: `https://[website]/cms/lib/viewer_functions.php?action_ws=checkModuleCode`
**Método**: POST
**Usado por**: `check_module`
**Payload**:
```javascript
{
  moduleName: string,
  vars: object       // variables de prueba
}
```

## Categoría: Secciones Generales (saveLexicalData)

### 1. Guardar sección con contenido Twig/HTML
**Endpoint**: `https://[website]/cms/lib/viewer_functions.php`
**Método**: POST
**Usado por**: `saveGeneralSection`
**Action**: `saveLexicalData`
**Payload**:
```javascript
{
  action_ws: 'saveLexicalData',
  token: credentials.token,
  tokenHash: credentials.tokenHash,
  content: string,           // HTML parsed content
  rawDataSended: true,
  endPointFolder: string,    // e.g., 'custom-productos'
  parserType: '2' | '0',     // 2=Twig, 0=Acai
  aditionalFiles: [          // CSS, JS files
    {
      path: string,
      fileName: string,
      content: string
    }
  ]
}
```

## Categoría: Registros (CRUD)

### 1. Crear/Actualizar registro
**Endpoint**: `${CMS_URL}/admin.php`
**Método**: POST
**Usado por**: `create_or_update_record`
**Content-Type**: `application/x-www-form-urlencoded`
**Params**:
```
menu={tableName}
_defaultAction=save
num={recordId}                    // empty para crear
type=
preSaveTempId={timestamp}
action=save
{fieldname}={value}              // campos del registro
{fieldname}:year, :mon, etc      // para campos date
enlace={value}
```

### 2. Listar registros
**Endpoint**: `${CMS_URL}/admin.php?menu={tableName}&json=1&page={n}&keyword={q}`
**Método**: GET
**Usado por**: `list_table_records`
**Headers**: `X-Acai-Token`, `X-Requested-With: XMLHttpRequest`

### 3. Eliminar registros
**Endpoint**: `${CMS_URL}/admin.php`
**Método**: POST
**Usado por**: `delete_table_records`
**Params**:
```
menu={tableName}
_defaultAction=list
page=1
_advancedAction=eraseRecords
_advancedActionSubmit=Ejecutar
selectedRecords[]={id1}
selectedRecords[]={id2}
```

## Categoría: Archivos (saveFileBuilder, removeFileBuilder)

### 1. Escribir archivo
**Endpoint**: `/cms/lib/viewer_functions.php`
**Método**: POST via getApiClient
**Usado por**: `write_file`
**Action**: `saveFileBuilder`
**Payload via getCommonParams**:
```javascript
{
  action_ws: "saveFileBuilder",
  path: string,           // ej: '/modulos/mymodule/'
  fileName: string,       // ej: 'style.css'
  content: string,
  rawDataSended: false,
  rootFolder: false
}
```

### 2. Listar archivos (FTP)
**Endpoint**: `/cms/lib/viewer_functions.php`
**Método**: POST via getApiClient
**Usado por**: `list_files`
**Action**: `getFTPFiles`
**Payload via getCommonParams**:
```javascript
{
  action_ws: "getFTPFiles",
  path: string            // directorio a listar
}
```

### 3. Eliminar archivo
**Endpoint**: `/cms/lib/viewer_functions.php`
**Método**: POST via getApiClient
**Usado por**: `delete_file`
**Action**: `removeFileBuilder`
**Payload via getCommonParams**:
```javascript
{
  action_ws: "removeFileBuilder",
  path: string            // ruta del archivo
}
```

## Categoría: Tablas (Database Schema)

### 1. Listar tablas (SaaS)
**Endpoint**: `${SAAS_URL}`
**Método**: POST
**Usado por**: `list_tables`
**Payload**:
```javascript
{
  action: 'getSchemaTables',
  type: 'acai'
}
```
**Headers**: `Authorization: Bearer {token}`, `Content-Type: application/json`

### 2. Obtener esquema tabla (SaaS)
**Endpoint**: `${SAAS_URL}`
**Método**: POST
**Usado por**: `get_table_schema`
**Payload**:
```javascript
{
  action: 'getSchemaTables',
  type: 'acai'
}
```

### 3. Actualizar esquema tabla (SaaS + CMS)
**Endpoint SaaS**: `${SAAS_URL}` (PUT)
**Método**: PUT
**Usado por**: `update_table_schema`
**Payload**:
```javascript
{
  action: "saveSchema",
  type: "acai",
  schema: object,         // esquema completo o parcial
  dir: "",
  id: tableName
}
```

**Luego sincronizar en CMS**:
**Endpoint CMS**: `/cms/lib/viewer_functions.php`
**Método**: POST via getApiClient
**Action**: `updateAllSchemas`
**Payload via getCommonParams**:
```javascript
{
  action_ws: "updateAllSchemas",
  tokenHash: credentials.tokenHash
}
```

### 4. Crear tabla
**Endpoint**: `${CMS_URL}/admin.php`
**Método**: POST
**Usado por**: `create_table`
**Params**:
```
menu=database
_defaultAction=addTable_save
type={multi|single|category|separador}
preset=
enlace={on|''}
seo_metas={on|''}
menuName={name}
menuOrder={order}
tableName={name}
```

### 5. Eliminar tabla
**Endpoint**: `${CMS_URL}/admin.php`
**Método**: POST
**Usado por**: `delete_table`
**Params**:
```
menu=database
action=editTable
dropTable=1
tableName={name}
```

### 6. Editar campos tabla
**Endpoint**: `${CMS_URL}/admin.php`
**Método**: POST
**Usado por**: `edit_table_field`
**Params**:
```
menu=database
_defaultAction=editTable
editField=1
tableName=cms_{tableName}
save=1
multipleFields={JSON.stringify(fieldArray)}
```

### 7. Eliminar campo tabla
**Endpoint**: `${CMS_URL}/admin.php`
**Método**: POST
**Usado por**: `delete_table_field`
**Params**:
```
menu=database
action=editTable
editField=1
tableName=cms_{tableName}
fieldname={fieldname}
deleteField=1
```

### 8. Obtener templates tabla (general section)
**Endpoint**: `/cms/lib/viewer_functions.php`
**Método**: POST via getApiClient
**Usado por**: `get_table_templates`
**Action**: `getTableData`
**Payload via getCommonParams**:
```javascript
{
  action_ws: "getTableData",
  menu: tableName
}
```

## Categoría: Media (Upload)

### 1. Subir imagen a campo
**Endpoint**: `${CMS_URL}/lib/menus/modals/plupload/multiupload/upload.php?menu={table}&fieldName={field}&num={recordId}&preSaveTempId=`
**Método**: POST (FormData)
**Usado por**: `upload_record_image`
**Form Fields**:
```
file={File buffer}    // File object
```

### 2. Listar uploads campo
**Endpoint**: `${CMS_URL}/admin.php?menu={table}&action=uploadList&fieldName={field}&num={recordId}&preSaveTempId=&json=1`
**Método**: GET
**Usado por**: `list_record_uploads`
**Headers**: `X-Acai-Token`

### 3. Reemplazar upload
**Endpoint**: `${CMS_URL}/admin.php`
**Método**: POST (FormData)
**Usado por**: `replace_record_image`
**Form Fields**:
```
_defaultAction=uploadModify
menu={tableName}
fieldName={fieldName}
num={recordId}
preSaveTempId=
save=1
uploadNums[]={uploadId}
{uploadId}_file={File buffer}
{uploadId}_name={originalFilePath}
{uploadId}_alt={altText}
action=uploadModify
```

### 4. Eliminar upload
**Endpoint**: `${CMS_URL}/admin.php?menu={table}&action=uploadErase&fieldName={field}&uploadNum={id}&num={recordId}&preSaveTempId=`
**Método**: GET
**Usado por**: `delete_record_upload`
**Headers**: `X-Acai-Token`, `X-Requested-With: XMLHttpRequest`

## Patrones Comunes

### getApiClient Calls
```javascript
const client = getApiClient(extra.sessionId);
const response = await client.post("/cms/lib/viewer_functions.php", getCommonParams(extra.sessionId, {
  action_ws: "actionName",
  // ... otros params
}));
```

### getCommonParams
Agrega automáticamente:
- token
- tokenHash
- website
- session info

### Headers Recurrentes
```javascript
{
  "X-Acai-Token": credentials.token,
  "Content-Type": "application/json" | "application/x-www-form-urlencoded"
}
```

## Notas Importantes

1. **Construcción de URLs**: Algunos endpoints usan la URL base dinámicamente (`https://{website}/...`) mientras otros usan `CMS_URL` configurado.
2. **Parámetros de formulario**: Algunos endpoints esperan URLSearchParams, otros JSON.
3. **Token Auth**: Algunos usan `X-Acai-Token`, otros pasan token en payload.
4. **Respuestas**: Varían entre `{success: true}`, `{result: true}`, o respuestas direc tas.