Onboarding
🚀 Manual xPOS-Core - Onboarding
🧭 Onboarding
El proceso de Onboarding es clave para la correcta configuración y operación del xPOS. En dicho proceso, se solicitará identificar al xPOS y este obtendrá su configuración para operar según se haya identificado.
xPOS operará solo en 1 ambiente a la vez, es decir, si el Onboarding es realizado en ambiente Sandbox operará en ese ambiente, si el Onboarding es realizado en ambiente Producción, xPOS se comunicará en ese ambiente con la Entidad Tributaria.
Se debe considerar que el proceso de onboarding se realiza únicamente por dispositivo xPOS.
A partir de xPOS-Core 2.6.0 un mismo dispositivo puede tener varios onboardings: varias empresas (tax-ids) facturando desde el mismo equipo, cada una con su propio certificado digital, sus credenciales ante la entidad tributaria y sus rangos de folios, completamente separados.
El proceso descrito en esta página es el mismo para el primero y para los siguientes. Para agregar un emisor adicional a un equipo ya instalado, usa Nuevo onboarding (+ TaxID) en el Dashboard.
Esto tiene una consecuencia para el integrador: con dos o más emisores instalados, el POS debe enviar el parámetro origin en cada emisión. Ver Multiroot.
🧭 Onboarding por interfaz gráfica
Abrir el navegador en el equipo local y acceder a:
También, podemos realizar el proceso Onboarding de manera remota (ver sección Acceso remoto a xPOS-Core).
Por medidas de seguridad, el xPOS cuenta con una pantalla de acceso a la aplicación, se solicitará ingresar un usuario y contraseña para acceder al Dashboard. Por el momento, solo se puede acceder con el siguiente usuario:
Las credenciales mostradas son de ejemplo: las reales de tu instalación se entregan durante el onboarding con el equipo de Gosocket.
Una vez realizada esta acción, permitirá entrar al proceso de Onboarding o acceder al Dashboard principal de xPOS-Core.
Inicio
Para el ejemplo se utilizará una empresa de Chile.
En la pantalla de inicio se deberá realizar lo siguiente:
- Seleccionar ambiente Sandbox / Producción
- Ingresar el UUID xPOS entregado o administrado desde el gadget de xPOS en el portal de Inbox Gosocket.
- Seguir el proceso haciendo clic en Continuar.
Si el UUID xPOS existe en los registros de Gosocket, se presentarán los datos de la organización para su revisión. Caso contrario, se debe notificar al equipo de Gosocket para su revisión.
A continuación, xPOS-Core descargará de forma obligatoria los archivos de configuración (XSLT de transformación y XSD de validación) desde el backend de Gosocket.
Si su organización tiene habilitado el gestor de folios 3.0 (numeración de documentos), el sistema descargará automáticamente los folios correspondientes al UUID de xPOS seleccionado. Si esta función está deshabilitada, este paso no es requerido y no se mostrará en la interfaz.
🩺 Verificación de la instalación
A partir de xPOS-Core 2.6.0, el onboarding incorpora un paso de verificación obligatorio antes de finalizar. El equipo no completa la instalación hasta pasarlo.
Antes, un problema de configuración —una plantilla corrupta, la mensajería sin conectar, la zona horaria del equipo mal configurada— se descubría en producción, con la tienda ya vendiendo. Este paso lo detecta durante la instalación.
Se ejecutan seis verificaciones automáticas:
| Verificación | Qué comprueba |
|---|---|
| XSLT | Que las plantillas de transformación estén presentes y sean utilizables. |
| XSD | Que los esquemas de validación del país estén presentes. |
| Conexión de mensajería | Que el equipo pueda conectarse al canal de mensajería de la nube. |
| Almacenamiento de mensajería | Que el equipo pueda leer y escribir en el almacenamiento asociado. |
| Telemetría | Que el equipo pueda reportar al servicio central de logs. |
| Zona horaria | Que el reloj del equipo esté en una zona horaria compatible con el país. |
El progreso se muestra en vivo en pantalla: quien instala ve cada verificación pasar o fallar en el momento. Cada una informa además su latencia, que sirve como indicador de la calidad del enlace en la tienda.
Con las seis verificaciones en verde, el botón Continuar finaliza el onboarding.
La verificación de zona horaria
Es la que previene el error de mayor impacto: el rechazo de documentos por la entidad tributaria.
Los documentos se firman con la hora local del equipo proyectada a la zona horaria del país. Si el equipo está configurado en una zona con un desplazamiento UTC distinto al del país, los sellos de tiempo de la firma salen corridos y la autoridad puede rechazar los documentos.
La comparación tiene tres resultados posibles:
| Resultado | Cuándo ocurre |
|---|---|
| ✅ Pasa | La zona horaria del equipo está en la lista de zonas válidas del país. |
| ⚠️ Pasa con advertencia | El nombre de la zona no coincide, pero el desplazamiento UTC actual sí. Quedan registradas en el detalle. |
| ❌ Falla | El desplazamiento difiere. El mensaje indica qué zona se detectó, cuál se esperaba y el desplazamiento de cada una. |
Que hoy dos zonas tengan el mismo desplazamiento no significa que lo mantengan: pueden divergir cuando entre el horario de verano. Es especialmente relevante en Chile y Paraguay. Ante una advertencia, conviene corregir la zona horaria igualmente.
Esta verificación no valida la exactitud del reloj: un equipo con la zona correcta pero la hora desviada sigue pasando.
Si una verificación falla
El fallo es bloqueante. Hay tres salidas:
| Acción | Qué hace |
|---|---|
| Reintentar | Vuelve a ejecutar las seis verificaciones. |
| Re-descargar | Vuelve a bajar los archivos de configuración desde el portal y los repone en orden. Es la salida para archivos faltantes o corruptos. |
| Retroceder (rollback) | Deshace el onboarding, incluidos los folios asociados. En un equipo con varios emisores, retroceder uno deja operativos a los demás. |
Desvío controlado de la verificación de zona horaria
Existe un mecanismo de desvío para el caso legítimo en que la instalación deba continuar con la verificación de zona horaria en rojo. Se solicita desde la misma pantalla y los datos los completa quien instala.
Funciona con cuatro candados:
- Requiere un aprobador identificado: nombre, correo electrónico y motivo. No es un botón de "continuar igual".
- Re-ejecuta las verificaciones al aprobar, de modo que el registro refleja el estado real en ese momento. Si al re-ejecutar ya pasa todo, no se registra ningún desvío.
- Solo la zona horaria es desviable. Si falla cualquier otra verificación, el desvío se rechaza: una plantilla de transformación rota o la mensajería caída dejan el xPOS inoperante, y no hay riesgo razonable que un aprobador pueda asumir.
- Queda registrado el riesgo operativo concreto de cada verificación fallida, junto con el aprobador y el motivo, tanto en el equipo como en el servicio central de telemetría.
La corrección permitida es configurar la zona horaria correcta del país. Cambiar la fecha y hora del equipo dejando la zona incorrecta corrompe el UTC de los sellos de tiempo aunque la hora local "se vea bien", y los documentos siguen expuestos a rechazo.
El registro permite auditar después por qué una tienda quedó operativa con verificaciones en rojo, quién lo autorizó y con qué justificación.
Fin del proceso
Superada la verificación, el proceso de Onboarding finaliza y se debe hacer clic en Continuar.
La pantalla final de confirmación se eliminó: el botón Continuar del último paso finaliza el onboarding y lleva directamente al Dashboard.
El UUID xPOS se encuentra operativo en el ambiente seleccionado para comenzar a procesar documentos.
El POS podrá iniciar la comunicación con xPOS-Core según lo definido en el documento de País - Comunicación con xPOS.
🧭 Onboarding por Consola
Para sistemas operativos que no cuenten con acceso a una interfaz gráfica, xPOS-Core cuenta con una consola para realizar el proceso de Onboarding.
Esta consola debe ser solicitada al equipo de Gosocket o descargada desde el gadget de xPOS en el portal de Inbox.
En caso de Unix, se requiere otorgar permisos de ejecución a la consola:
chmod +x console-linux
Luego, ejecutar la consola:
./console-linux
./console-win
Seleccionar la opción 1. Nuevo onboarding.
Ingresar el UUID xPOS y seleccionar el país a configurar.
Seleccionar el ambiente a configurar.
Se presentarán los datos de la organización.
Si cancelamos, no se realizará Onboarding.
Si confirmamos, ejecutará el proceso Onboarding.
🌐 Acceso remoto a xPOS-Core
Es posible realizar el onboarding y acceder al dashboard de manera remota, conectándose directamente al dispositivo donde está instalado xPOS-Core; si se cumplen los siguientes requisitos:
- Los dispositivos deben estar conectados a través de la red interna (ej.: VPN).
- xPOS-Core debe estar instalado en el dispositivo host.
- El puerto
3200debe estar habilitado para la comunicación entre ambos equipos.
Desde el equipo remoto, se debe abrir el navegador y reemplazar localhost por la IP del dispositivo con xPOS-Core: