🤖 12. Zolteka para desarrolladores

⚠️ Esta página es solo para desarrolladores. No hace falta para usar Zolteka. Explica cómo otro plugin puede aprovechar lo que ya trae Zolteka sin copiarlo.

Requisitos: Zolteka 2.30 o superior, FacturaScripts 2026.65 o superior y PHP 8.1 o superior. Cada apartado indica desde qué versión de Zolteka existe lo que describe; esta página y sus subpáginas recogen hasta la 2.30.

📍 En esta página:

Antes de empezar

  • Comprueba siempre que Zolteka está. Antes de usar una clase o un método de Zolteka, compruébalo con class_exists() (y method_exists() si llamas a un método concreto). Si Zolteka no está activo, tu plugin debe seguir funcionando. Si necesitas saber si Zolteka está activo (por ejemplo, para pintar algo), usa Plugins::isEnabled('Zolteka'): class_exists() solo dice que la carpeta existe.
  • Registra en Init::init(), sin consultas a la base de datos. Los registros viven en memoria durante la petición. Si tu plugin se desactiva, sus registros desaparecen solos.
  • Si repites una clave, gana el último registro. Con una clave no válida, unos registros lanzan InvalidArgumentException y otros devuelven false o descartan con un aviso en el log Zolteka; cada apartado lo indica.
  • No hay garantía de compatibilidad entre versiones. Lo marcado como experimental puede cambiar en la siguiente versión.
  • Las acciones AJAX de Zolteka no son una API HTTP pública. Úsalas solo desde pantallas del propio ERP, con la sesión iniciada y el token CSRF (multireqtoken).
use FacturaScripts\Plugins\Zolteka\Lib\Kanban\KanbanRegistry;

public function init(): void
{
    if (class_exists(KanbanRegistry::class)) {
        KanbanRegistry::register(new MiTableroProvider());
    }
}

💡 Tip Experto: en tus ejemplos y pruebas, importa las clases de FacturaScripts\Plugins\Zolteka\Lib, no las de Dinamic\Lib. Varias clases de Zolteka son final y el envoltorio que genera el núcleo en Dinamic intenta heredar de ellas.

Subpáginas

Cada tema tiene su subpágina. Todas parten de lo explicado en «Antes de empezar» y se rigen por las Condiciones de uso de esta página.

Avisos en la campana y en el móvil

Registra tu propio tipo de aviso con NotificationTypeRegistry::register() y un NotificationTypeInterface. El tipo decide su texto, icono, permiso, si abre ventana emergente y si se envía al móvil. Para crear avisos usa ZoltekaNotificationManager::emit(), que solo sirve con tipos personales y emisibles. Zolteka no los duplica y solo los entrega a usuarios activos con permiso.

Icono del menú

(Desde la 2.28.) En el menú vertical y en el carril, el menú de primer nivel de un plugin toma por defecto el icono de su primera página, así que reordenar el menú (Diseño → Ordenación Menú) lo cambia. Para fijarlo, registra el tuyo en el init() de cada petición:

use FacturaScripts\Plugins\Zolteka\Lib\ZoltekaMenuIconos;

if (class_exists(ZoltekaMenuIconos::class)) {
    ZoltekaMenuIconos::registrar('mi-menu', 'fa-solid fa-paw');
}
  • El menú cumple ^[a-z][a-z0-9_-]{0,49}$ y el icono ^fa-(solid|regular|brands) fa-[a-z0-9-]+$. Si no, lanza InvalidArgumentException. El último registro gana.
  • El registro vive en memoria: hay que hacerlo en cada petición.
  • Los menús del núcleo no se pueden cambiar así, y el menú horizontal no usa este mapa.

Pestañas en las pantallas de ajustes

(Desde la 2.15.) Las pantallas de configuración de Zolteka solo guardan en el grupo de ajustes que tiene declarado cada pestaña, para que nadie pueda escribir en otro grupo ni borrarlo.

  • Si tu plugin añade por extensión una pestaña Settings a ConfigAjustesZolteka, ConfigZolteka o ConfigZoltekaServiciosCalendario, no se guardará hasta que esa pestaña esté declarada con su grupo en el settingsGrupoFijoMapa() de esa pantalla, en Zolteka (por ejemplo, ConfigZcajaPagosEfectivo con el grupo zcaja en ConfigAjustesZolteka). Hay que pedir el cambio en Zolteka.
  • En tu propio PanelController: usa el trait ZoltekaSettingsGrupoFijoTrait (FacturaScripts\Plugins\Zolteka\Lib\Traits), implementa public static function settingsGrupoFijoMapa(): array y, al principio de execPreviousAction($action), comprueba if (false === $this->guardaSettingsGrupoFijo($action)) { return true; }.

El mapa devuelve grupos (pestaña => grupo de ajustes), sinAcciones (pestañas HTML sin acciones nativas) y guardadoPropio (pestañas cuyo guardado lleva el propio controlador). Ejemplo real de ConfigZoltekaServiciosCalendario:

public static function settingsGrupoFijoMapa(): array
{
    return [
        'guardadoPropio' => ['ConfigCalendarioZolteka'],
        'sinAcciones' => ['ZoltekaServiciosCalendario'],
    ];
}

Tema: tokens de contraste

(Desde la 2.27.) Cada tema de Zolteka cumple WCAG 2.1 AA en el texto (4,5:1 el texto normal y 3:1 el grande, los iconos y el foco). Si tu plugin pinta con colores propios, usa estos tokens de zolteka.css en lugar de --v-primary sobre blanco:

  • --v-primary: color corporativo. Solo relleno (botones, píldoras, insignias). Nunca como texto sobre blanco.
  • --zolteka-primary-relleno y --zolteka-primary-relleno-hover: relleno de los botones primarios y su estado al pasar el ratón.
  • --zolteka-primary-contraste: el texto sobre ese relleno (blanco o #0F172A, el que más contraste da).
  • --zolteka-acento-texto: el primario como texto sobre blanco o sobre un tinte claro (contraste de al menos 4,6:1).
  • --zolteka-acento-contraste: el texto sobre --v-accent.
  • --zolteka-texto-contenido: el texto del contenido.
  • --zolteka-menu-texto y --zolteka-menu-acento: el texto y el acento sobre el fondo del menú.

Correcto: color: var(--zolteka-acento-texto) para un enlace o un icono sobre blanco, y background: var(--zolteka-primary-relleno); color: var(--zolteka-primary-contraste) para un botón. Incorrecto: color: var(--v-primary) sobre blanco, o texto blanco fijo sobre un relleno de color. Si añades un tema nuevo, declara todos los tokens en su bloque body.zolteka-theme-*, no solo --v-primary.

Condiciones de uso

Esta página y sus subpáginas explican cómo puedes usar desde tu propio plugin las clases, extensiones, eventos, widgets e integraciones de Zolteka. Desarrolla el punto 1.c del Contrato de licencia freeware de Zolteka y no lo sustituye. Si hay alguna diferencia, manda el contrato.

1. Lo que puedes hacer

  • Crear plugins complementarios, gratuitos o de pago, que se conecten a Zolteka: llamar a sus clases, extenderlas o heredar de ellas, usar sus extensiones, eventos y widgets, leer sus datos e integrarte con el calendario y el resto de funciones documentadas en esta página. Hacerlo desde tu plugin no modifica el código de Zolteka y está permitido (punto 1.c).
  • Instalar Zolteka y tus plugins complementarios a tus clientes y cobrar por tus servicios, pero no por Zolteka. Descárgalo siempre de los canales oficiales (puntos 1.b y 4).
  • Cambiar el código de Zolteka solo para uso interno en tu propia instalación. Esos cambios no pueden instalarse en instalaciones de terceros, incluidos tus clientes, ni distribuirse. Si encuentras una corrección que afecte a otros, comunícasela al autor (punto 1.d).

2. Lo que no puedes hacer

  • Copiar, reutilizar o adaptar todo o una parte sustancial del código, la estructura o las vistas de Zolteka dentro de tu plugin. Tu plugin se conecta a Zolteka, no lo incluye (punto 2.c).
  • Vender, alquilar, sublicenciar o redistribuir Zolteka, ni publicarlo, ni una copia modificada, con otro nombre o autoría (puntos 2.a, 2.b y 2.c).
  • Eliminar, ocultar, alterar o redirigir desde tu plugin los avisos, los logotipos, los nombres «Zolteka» o «Carlos Moreno Gil» o los enlaces a zolteka.com. La única excepción son las herramientas oficiales del autor que lo permiten expresamente, como zMarcaBlanca, en sus condiciones. Los avisos de autoría y copyright se mantienen siempre (puntos 2.d y 3).

Nada de esto limita lo que la ley permite en todo caso, como la interoperabilidad (art. 100 de la Ley de Propiedad Intelectual).

3. Uso del nombre «Zolteka»

Puedes indicar que tu plugin es «compatible con Zolteka» o que «requiere Zolteka». No puedes usar el nombre ni el logotipo como parte del nombre de tu plugin o de tu marca, ni dar a entender que Zolteka o su autor lo respaldan, lo revisan o lo mantienen.

4. Estabilidad de la API y sin garantía

  • Esta API se ofrece «tal cual», como el resto del plugin (punto 8). Intentamos mantenerla estable, pero puede cambiar entre versiones de Zolteka. Los cambios incompatibles se anunciarán en el CHANGELOG y, cuando sea posible, con una versión de margen antes de retirar algo.
  • Usa solo lo que se documenta en esta página y en sus subpáginas. Cualquier otra clase, método o tabla es interna y puede cambiar sin aviso.
  • No ofrecemos soporte a plugins de terceros. Cada desarrollador responde de su plugin ante sus clientes.
  • El autor no responde de los daños causados por plugins de terceros ni por cambios en la API, salvo dolo o culpa grave y en lo que la ley no permita excluir (punto 8).

5. Ejemplos de código de esta página

Puedes copiar, adaptar y distribuir los ejemplos de código de esta página y de sus subpáginas dentro de tus plugins, gratuitos o de pago, sin pedir permiso ni citar la fuente. Se ofrecen «tal cual», sin garantía. Este permiso solo cubre los ejemplos de esta página y de sus subpáginas: el código de Zolteka sigue sujeto a su contrato de licencia freeware.


Titular: Carlos Moreno Gil, bajo el nombre comercial Zolteka · carlos.moreno@zolteka.com · https://zolteka.com

Cookies
Usamos cookies necesarias para el funcionamiento del sitio y cookies opcionales para recordar tus preferencias y mejorar tu experiencia. Puedes aceptarlas todas, rechazarlas o configurar tus preferencias

Soporte