Especificaciones Técnicas de Marca Blanca

Este documento define los estándares de configuración de la infraestructura NoPaperManuals™ en modo Marca Blanca (Whitelabel).

[!NOTE] Ofrecemos 3 niveles de integración progresivos según tus necesidades técnicas:

Nivel 1: Delegación DNS (Personalización sencilla mediante colores y logotipos).

Nivel 2: Smart Embedded (Integración fluida mediante iframe en tu sitio existente).

Nivel 3: Reverse Proxy (Remote Fetching para inyectar tu HTML nativo completo).

🔗 Niveles de Integración y Personalización

Según tus necesidades de branding y recursos técnicos, hay tres niveles de integración disponibles.

🎨 NIVEL 1: Delegación DNS (Personalización del Branding)

Para el Nivel 1 (Delegación DNS), la personalización está diseñada para ser sencilla y rápida, y será configurada por nuestro equipo técnico.

1. Configuración del Nombre de Dominio (CNAME)

Primero debes elegir un subdominio dedicado para tus manuales (por ejemplo, manuales.tu-marca.com). Luego, en la interfaz de gestión DNS de tu dominio, deberás crear un registro CNAME que apunte a nuestra infraestructura: fallback.nopapermanuals.com.

2. Qué podemos personalizar para ti:

• Identidad Visual: Subida de tu logotipo en alta resolución y un favicon personalizado.

• Paleta de Colores: Definición de tu "Color de Acento" que se aplicará a los botones y elementos activos.

• Navegación (Cabecera): Configuración de menús simples (nombre del enlace, URL) para recrear el acceso a tus páginas principales.

• Pie de página (Footer): Integración de enlaces a tus redes sociales y páginas de aviso legal.

🧩 NIVEL 2: Smart Embedded (Integración Iframe)

El enfoque "Smart Embedded" es ideal para integrar los manuales directamente en tu sitio E-commerce (Shopify, PrestaShop) o tu CMS de Soporte existente.

Este método te permite prescindir del diseño de la Cabecera o del Pie de página de NoPaperManuals, garantizando al mismo tiempo que los escaneos físicos de códigos QR redirijan a tus clientes hacia tu propio entorno.

1. Configuración de la URL de Alojamiento (Host URL)

Al configurar tu cuenta de Marca Blanca con nuestro equipo, debes proporcionar la URL exacta donde se alojará el Iframe (por ejemplo: https://soporte.tu-marca.com/manuales).

2. Integración del JS Snippet

Nuestro equipo técnico te proporcionará un Snippet de Javascript preconfigurado para tu marca. Este código lee la URL cuando un usuario escanea un código QR (?npm_shortcode=XYZ) y crea dinámicamente la URL de nuestro Iframe (https://nopapermanuals.com/s/XYZ?embedded=true).

<!-- Objetivo del Iframe en tu página -->
<iframe id="npm-iframe" style="width:100%; height:100vh; border:none;"></iframe>

<script>
  // 1. Leer el parámetro 'npm_shortcode' de la URL
  const params = new URLSearchParams(window.location.search);
  const shortcode = params.get('npm_shortcode');
  
  // 2. Definir la URL final del iframe (Modo minimalista sin menús iniciales)
  const iframeUrl = shortcode 
    ? `https://nopapermanuals.com/s/${shortcode}?embedded=true` 
    : `https://nopapermanuals.com/tenant/tu-identificador?embedded=true`;

  // 3. Cargar el contenido de forma transparente
  document.getElementById('npm-iframe').src = iframeUrl;
</script>

3. Recorrido del Usuario durante el escaneo

• Paso 1: El usuario escanea el código QR en tu producto (qrmanual.app/ABC).
• Paso 2: Nuestro servidor detecta el modo Smart Embedded para este producto.
• Paso 3: El usuario es redirigido instantáneamente a tu página: https://soporte.tu-marca.com/manuales?npm_shortcode=ABC.
• Paso 4: El snippet lee "ABC", carga el manual desde NoPaperManuals, y lo inyecta en la página. Tus usuarios permanecen en tu nombre de dominio.

🚀 NIVEL 3: Reverse Proxy (Modo Shell)

El modo Proxy (Reverse Proxy) es la integración más avanzada. Permite fusionar NoPaperManuals en el corazón de tu propia infraestructura web.

El contenido se sirve directamente desde tu nombre de dominio, lo que optimiza el posicionamiento en buscadores (SEO) y ofrece la experiencia más transparente.

Personalización por "Remote Fetching" (Dinámica)

En lugar de recrear manualmente tus menús, NoPaperManuals recupera en tiempo real los fragmentos de tu Cabecera y Pie de página a través de URLs específicas.

• Ventaja clave: Sincronización 100% automática. Cualquier modificación en tu sitio principal se refleja instantáneamente en la sección "Manuales".
• Requisito técnico: Debes proporcionar endpoints HTML que devuelvan únicamente la estructura de tu cabecera y pie de página (sin las etiquetas globales <body> o <html>).

🔒 Seguridad de la comunicación

La comunicación "Server-to-Server" entre tu infraestructura y NoPaperManuals debe estar estrictamente autenticada mediante cabeceras (headers) específicas, para evitar cualquier suplantación:

| Cabecera HTTP (Header) | Valor esperado | | :--- | :--- | | X-NPM-Custom-Host | Tu nombre de dominio oficial (ej: manuales.tu-marca.com) | | X-NPM-Proxy-Secret | Tu clave secreta criptográfica (compartida con nuestro equipo técnico) |

[!WARNING] Protección crítica Activa Si la cabecera X-NPM-Proxy-Secret falta, es incorrecta o está comprometida, el cortafuegos de NoPaperManuals se negará a servir tu contenido para proteger la integridad de tu marca.

⚙️ Arquitectura Requerida: Subdominio Exclusivo

Para las Aplicaciones de Página Única (SPA), el Reverse Proxy debe obligatoriamente apuntar a un subdominio dedicado (ej: manuales.tu-marca.com) e interceptar el tráfico en la raíz /.

[!WARNING] La configuración en una subcarpeta (ej: tu-marca.com/manuales/) está fuertemente desaconsejada. Requiere validación técnica para evitar cualquier conflicto con nuestros activos (/_next/, /api/, etc.). En el 95% de los casos, el subdominio es la solución recomendada.

🛠️ Ejemplo de Configuración Nginx

Plantilla estándar de un bloque server Nginx a utilizar:

server {
    listen 443 ssl http2;
    server_name manuales.tu-marca.com;
    
    # 1. Certificados SSL válidos (A mantener por ti)
    ssl_certificate /path/to/cert/fullchain.pem;
    ssl_certificate_key /path/to/cert/privkey.pem;
    
    location / {
        # 2. Proxy hacia la raíz de NoPaperManuals
        proxy_pass https://nopapermanuals.com/;
        
        # 3. Cabeceras de Seguridad obligatorias
        proxy_set_header X-NPM-Custom-Host "tu-marca.com";
        proxy_set_header X-NPM-Proxy-Secret "TU_SECRETO_CRIPTOGRAFICO";
        
        # 4. Cabeceras de transferencia estándar
        proxy_ssl_server_name on;
        proxy_set_header Host nopapermanuals.com;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

🛠️ Validación y Despliegue

• Validación Visual: Para validar el aspecto de sus colores, logotipos y opciones de marca antes de pasar a producción, se puede configurar un entorno de prueba dedicado. Por favor, contáctenos para proceder con su activación.

• Pruebas de Seguridad: (Solo Nivel 3) Asegúrate de que tus cabeceras de seguridad estén configuradas y propagadas correctamente.

[!NOTE] Cualquier actualización de su branding realizada por nuestro soporte técnico se aplica en tiempo real en su dominio Marca Blanca.