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.

#Directamente desde allverto (vía principal)

Si tu JTL-Wawi funciona en un servidor alquilado y el servidor REST es accesible desde internet, allverto se conecta a él por sí mismo. Entonces no necesitas ningún programa en tu servidor.

Funciona si:

• el servidor REST es accesible con una dirección IP pública o un nombre público, no con localhost, una dirección de la red de la empresa o un nombre de equipo.
• el puerto es 80, 443 o 1024 o superior.

Cómo hacerlo:

1. Abre Configuración → Migración de datos → Migración desde JTL-Wawi, paso Conectar origen, y elige API de JTL-Wawi.
2. En Datos de conexión, introduce la Dirección de la API de Wawi, p. ej. https://217.160.19.64:5885/api/eazybusiness, y haz clic en Guardar.
3. Haz clic en Probar conexión. allverto consulta …/v2/info. Sin clave API, el resultado es «servidor REST accesible ✓; el inicio de sesión se hace con el registro». Es normal que la propia dirección (…/api/eazybusiness) muestre «404» en el navegador.
4. Si tu servidor REST solo responde por HTTPS, allverto propone la dirección con https://. Haz clic en Cambiar la dirección a https://.
5. Si tu servidor REST usa un certificado creado por ti, allverto muestra la huella (SHA-256), el emisor y la validez. Compara la huella con el certificado de tu servidor y haz clic en Confiar en este certificado.
6. Registra allverto en JTL-Wawi, en este orden:
   1. En JTL-Wawi abre „Anwendungsregistrierungen“ → „Anwendung registrieren“ y avanza hasta «Registrierung beginnen». La Wawi espera entonces una solicitud.
   2. En allverto haz clic en Enviar registro desde allverto. allverto reenvía la solicitud cada 5 segundos durante un máximo de 10 minutos. El estado aparece justo debajo, p. ej. «Esperando a la Wawi» o «Aceptada». Con Cancelar detienes el proceso.
   3. En la Wawi revisa «Anwendungsinformationen», elige un usuario de Wawi en «Benutzer», confirma los permisos (solo lectura, opcionalmente imprimir facturas) en «Zugriffsverwaltung» y haz clic en «Einrichtung abschließen». allverto muestra entonces «Clave API guardada.» y la guarda cifrada.
7. Haz clic en Obtener datos directamente ahora. allverto obtiene los datos en segundo plano. Las cantidades aparecen después en Datos encontrados.

Si introduces localhost o una dirección de la red de tu empresa, el campo muestra: «Esta dirección solo es accesible en tu servidor. Introduce la IP pública de tu servidor o usa jtl-bridge más abajo.» Si tu servidor REST no es accesible desde internet, usa la vía con jtl-bridge (pasos 2 y 3 más abajo).

#¿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 funciona en el ordenador en el que funciona tu JTL-Wawi (normalmente un servidor Windows).
• En ese ordenador se accede a él mediante una dirección como http://localhost:5883/api/eazybusiness. localhost significa «este ordenador», 5883 es un ejemplo de puerto: es el puerto que configuraste en Wawi para el servidor REST (a menudo 5883, pero también p. ej. 5885). eazybusiness es el nombre de tu base de datos de Wawi.
• Cada programa debe registrarse una vez como aplicación. Tú inicias el registro en Wawi, el programa envía su solicitud y tú completas la configuración; después, el programa recibe su clave API.
• allverto se registra como la aplicación «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: p. ej., abre en el navegador del servidor de Wawi la dirección http://localhost:<port>/api/eazybusiness. Si llega cualquier respuesta (incluso un mensaje de error en el navegador), está en marcha.

#2. Con jtl-bridge: elegir el origen en allverto

Esta vía solo la necesitas si tu servidor REST no es accesible desde internet.

1. Abre Configuración → Migración de datos → Migración desde JTL-Wawi, paso Conectar origen.
2. Elige API de JTL-Wawi. No tienes que introducir nada: jtl-bridge transfiere por sí mismo la dirección y la clave API.
3. Opcional: define una fecha de cambio.

En Datos de conexión también están Clave API (solo si ya tienes una), ID de empresa (opcional) (solo si tu Wawi lo exige), Obtener los PDF de facturas por la API y el interruptor Completar los datos que faltan desde la base de datos (opcional) (ver más abajo).

#3. Con jtl-bridge: iniciar el programa y registrar la aplicación en Wawi

Despliega abajo el cuadro ¿El servidor no es accesible desde internet? Transferir datos con jtl-bridge. Te guía por los pasos (en detalle: El programa auxiliar jtl-bridge):

1. Descargar jtl-bridge.
2. Copiar el archivo al servidor en el que funciona tu JTL-Wawi, p. ej. por Escritorio remoto al escritorio.
3. En el servidor, iniciar el archivo con doble clic.
4. Hacer clic aquí en «Generar código de configuración», copiar el código, pegarlo en la ventana con clic derecho y pulsar Enter.
5. Responder a las preguntas de la ventana: normalmente basta con pulsar Enter. El programa busca el servidor REST en este ordenador (puertos 5883 a 5890) y propone la dirección encontrada, p. ej. «Encontrado: http://localhost:5885/api/eazybusiness – pulsa Enter para usarlo.».
6. En JTL-Wawi, registrar la aplicación (ver más abajo).
7. Esperar hasta que aparezca «Listo»; allverto marcará entonces el paso.

Sobre el paso 6: el orden es importante, porque Wawi solo acepta una solicitud mientras su asistente está esperando:

1. En JTL-Wawi, abre Anwendungsregistrierungen (registros de aplicaciones) → Anwendung registrieren (registrar aplicación). El asistente tiene los pasos Einführung, Registrierung beginnen, Anwendungsinformationen, Benutzer, Zugriffsverwaltung y Einrichtung abschließen.
2. Avanza hasta Registrierung beginnen. Allí aparece «Eine Sitzung zur Entgegennahme von Registrierungsanfragen wurde gestartet …» y «Es wird auf die Übermittlung einer Registrierungsanfrage durch die zu registrierende Anwendung gewartet …» (se ha iniciado una sesión para recibir solicitudes de registro; esperando una solicitud de registro).
3. Ahora pulsa Enter en la ventana de jtl-bridge. El programa envía la solicitud allverto – Umzug von JTL-Wawi. Si Wawi todavía no la acepta, el programa lo vuelve a intentar cada 5 segundos durante 10 minutos.
4. En Wawi, revisa Anwendungsinformationen, elige un usuario de Wawi en Benutzer y confirma en Zugriffsverwaltung los permisos solicitados (solo lectura y, opcionalmente, imprimir facturas).
5. Haz clic en Einrichtung abschließen. Después, jtl-bridge entrega la clave API cifrada a allverto: no la ves ni tienes que copiar nada. allverto la guarda cifrada y solo la usa para esta migración.

Si no completas la configuración en 10 minutos, jtl-bridge se interrumpe; en ese caso, simplemente vuelve a iniciarlo.

#¿De dónde sale la clave API?

JTL-Wawi no muestra ninguna clave API ni la genera con solo pulsar un botón. Solo la entrega a una aplicación que la solicita en ese momento, mientras su asistente espera en Registrierung beginnen. Esa solicitud la envía allverto por sí mismo (Enviar registro desde allverto). Si tu servidor REST no es accesible desde internet, la envía jtl-bridge.

Después, allverto obtiene los datos o jtl-bridge los sube. 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 en el asistente, en Datos, activas el interruptor Completar los datos que faltan desde la base de datos (opcional) e introduces el acceso al SQL Server, jtl-bridge 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. En Usuario (sa) va el usuario de SQL Server (normalmente sa), no tu usuario de JTL-Wawi; también basta con un usuario propio solo con permiso de lectura. Sin base de datos faltan estos datos; todo lo demás se migra igualmente.

#Seguridad y red

• Directamente desde allverto, el servidor REST tiene que ser accesible desde internet. Abre el puerto en el cortafuegos solo para los servidores de allverto: 2.31.70.120, 2.31.74.112, 2.31.72.228, nunca para todos.
• Usa https://. Con http://, la clave API y los datos viajan sin cifrar por internet. Un certificado creado por ti lo confirmas una vez con Confiar en este certificado. Después, allverto solo se conecta con exactamente ese certificado.
• Con jtl-bridge no tiene que ser accesible nada desde internet. jtl-bridge funciona en el servidor de Wawi y sube los datos solo por HTTPS. Además, los datos van cifrados con una clave del token de importación.
• La clave API y el código de configuración son como contraseñas: no los envíes por correo ni los copies en tickets. allverto guarda la clave API cifrada y nunca la muestra. El código de configuración vale 30 días cada vez (ampliable), como máximo hasta cerrar la migración.
• Con Probar conexión, allverto solo comprueba una dirección por sí mismo si es accesible desde internet. Con localhost o una dirección de la red de la empresa, la prueba la hace jtl-bridge y comunica el resultado.
• Tras la migración puedes eliminar la aplicación «allverto – Umzug von JTL-Wawi» en la Wawi, en „Anwendungsregistrierungen“.

#Solución de problemas

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