Configurar la API REST de JTL-Wawi

JTL-Wawi tiene su propia interfaz de programación: la API de JTL-Wawi, a menudo llamada también «API REST» o «servidor REST de Wawi». A través de ella, otro programa (en este caso, allverto) puede leer artículos, clientes y documentos de tu Wawi sin acceder directamente a la base de datos. Esta página explica qué tienes que configurar en Wawi para ello.

#¿Qué es la API REST, en palabras sencillas?

Imagina el servidor REST como la ventanilla de recepción de tu Wawi. Los programas que quieren datos los piden en la ventanilla («dame todas las facturas»). La ventanilla comprueba si el programa tiene una identificación válida (la clave API) y entonces entrega exactamente los datos autorizados.

• El servidor REST es un programa de JTL que se ejecuta en la red de tu empresa, normalmente en el mismo equipo que Wawi o su SQL Server.
• Se accede a él mediante una dirección como http://wawi-server:5883/api/eazybusiness. wawi-server es el nombre o la IP de tu equipo, 5883 el puerto (en tu caso puede ser otro) y eazybusiness el nombre de tu base de datos de Wawi.
• Cada programa debe registrarse una vez como app. Tú confirmas el registro en Wawi y, después, el programa recibe su clave API.
• allverto se registra como la app «allverto – Umzug von JTL-Wawi» (allverto: migración desde JTL-Wawi) y solo solicita acceso de lectura (y, opcionalmente, la impresión de PDF de facturas). allverto no cambia nada en tu Wawi.

#¿A partir de qué versión de Wawi?

allverto utiliza la API en la versión que JTL ha publicado para Wawi 2.1 y 2.2 (rutas con /v2/…). La vía de la API está desarrollada y probada con estas versiones.

#Paso a paso

#1. Activar el servidor REST en Wawi

1. Inicia sesión en JTL-Wawi como usuario con permisos de administración.
2. Configura el servidor REST tal como lo describe JTL para tu versión e inícialo. Anota el puerto en el que escucha.
3. Comprueba que el servidor funciona: un equipo de la red de la empresa debe poder acceder a la dirección http://<wawi-server>:<port>/api/eazybusiness (abre ese puerto en el cortafuegos del equipo de Wawi para la red interna).

#2. Registrar allverto como app

El registro se inicia con el programa auxiliar jtl-bridge en un equipo de la red de la empresa:

jtl-bridge register --api-url http://wawi-server:5883/api/eazybusiness

1. jtl-bridge envía la solicitud de registro a tu servidor REST e indica: «Registrierung gesendet … Bitte jetzt in der JTL-Wawi unter Admin → App-Registrierung bestätigen» (registro enviado; confírmalo ahora en JTL-Wawi en Admin → App-Registrierung).
2. En Wawi, abre el registro de apps (App-Registrierung). Según nuestra documentación, en Wawi 2.2 la opción se llama Admin → App-Registrierung. Allí aparece la solicitud de allverto – Umzug von JTL-Wawi con los permisos solicitados.
3. Revisa los permisos (solo lectura y, opcionalmente, imprimir facturas) y confirma la solicitud.
4. jtl-bridge consulta cada 5 segundos. Tras la confirmación, muestra la clave API, solo esta única vez. Cópiala inmediatamente.
5. Si no confirmas en 10 minutos, jtl-bridge se interrumpe; en ese caso, simplemente vuelve a iniciar el registro.

#3. Introducirlo en allverto

1. Abre Configuración → Migración de datos → Migración desde JTL-Wawi, paso Conectar origen.
2. Elige API de JTL-Wawi.
3. En Dirección de la API de Wawi, introduce la dirección del paso 1, p. ej., http://wawi-server:5883/api/eazybusiness.
4. Pega la Clave API. allverto la guarda cifrada; la próxima vez que abras la página aparecerá «Guardada: déjala vacía para conservarla».
5. ID de empresa (opcional): rellénalo solo si tu Wawi lo exige. En una Wawi instalada en tu propia empresa, el campo normalmente se queda vacío.
6. Deja activado Obtener los PDF de facturas por la API si quieres que tus facturas se traspasen como PDF (Wawi los genera de nuevo para ello).
7. Opcional: introduce el SQL Server; así jtl-bridge completa lo que la API no entrega (ver más abajo).
8. Haz clic en Guardar origen.

#4. Subir los datos

Como el servidor REST solo es accesible en la red de la empresa (y así debe seguir siendo), jtl-bridge sube los datos: Generar token de importación y, a continuación, ejecutar en la red de la empresa el comando mostrado, p. ej.:

jtl-bridge upload --url https://erp.allverto.cloud --token avjtl_… --fill-from-db

En el asistente se continúa con Datos encontrados y Asignaciones; consulta Migración desde JTL-Wawi: cómo funciona.

#¿Qué entrega la API y qué no?

#Cómo cubre jtl-bridge los huecos

Si inicias jtl-bridge con --fill-from-db y además has configurado el SQL Server en allverto, lee directamente de la base de datos todo lo que la API no entrega o entrega solo en parte: suscripciones, facturas de proveedor, líneas de facturas rectificativas, listas de materiales, nombres de atributos y mandatos SEPA. Para ello basta con un usuario de base de datos solo con permiso de lectura. Sin base de datos faltan estos datos; todo lo demás se migra igualmente.

#Seguridad y red

• El servidor REST se queda en la red de la empresa. No abras el puerto a internet. jtl-bridge se ejecuta dentro, lee el servidor REST y sube los datos hacia fuera; no hacen falta conexiones entrantes.
• jtl-bridge solo sube datos por HTTPS. Además, los datos van cifrados con una clave derivada del token de importación.
• La clave API y el token de importación son como contraseñas: no los envíes por correo electrónico ni los copies en tickets. El token de importación es válido hasta que se completa la migración; después deja de ser válido.
• Obtener datos directamente solo funciona si la API de Wawi es accesible desde internet. Solo lo recomendamos con un acceso protegido (p. ej., HTTPS a través de un proxy inverso con restricción de acceso). Normalmente, usa jtl-bridge.
• Tras la migración puedes eliminar de nuevo en Wawi el registro de la app de allverto.

#Solución de problemas

Más casos: Solución de problemas en la migración desde JTL.