Guía de integración de documentación

Resumen

El sitio de documentación del workspace proporciona un manifiesto legible por máquina (hub-links.json) que mapea las pantallas del panel de control del Hub con las páginas de documentación relevantes. Esto permite al frontend del Hub mostrar enlaces de ayuda contextuales directamente en la interfaz de usuario del panel de control.

Cómo funciona

El manifiesto /hub-links.json es un archivo JSON estático servido desde el sitio de documentación. Cada entrada mapea un identificador de pantalla del Hub con una lista de enlaces de documentación relevantes con títulos y descripciones.

Estructura del manifiesto

El manifiesto sigue este esquema:

{
  "$schema": "hub-links-schema",
  "version": "1.0.0",
  "screans": {
    "<screan-id>": {
      "title": "Screan Title",
      "description": "What this screan does",
      "links": [
        {
          "title": "Link Title",
          "url": "/path/to/docs-page/",
          "description": "Brief description of the linked page"
        }
      ]
    }
  }
}

IDs de pantalla disponibles

ID de pantalla	Pantalla del Hub	Enlaces
organizations	Gestión de organizaciones	Introducción a HUB, primeros pasos, mapeo de recursos
tss-list	Lista TSS (Alemania)	Descripción general de Alemania, nuevos clientes, inicio rápido
clients	Gestión de clientes	Detalles técnicos, SIGN DE API
transactions	Visor de transacciones	Manejo de errores, códigos de error
exports	Gestión de exportaciones	Introducción DSFinV-K, manual del panel de control
api-keys	Gestión de API Keys	Inicio rápido, cambiar a LIVE
cash-registers	Cajas registradoras (Austria)	Descripción general de Austria, inicio rápido, SIGN AT API
signers	Firmantes (España)	Descripción general de España, inicio rápido

Integración en el Hub

Uso del componente HubNavCard

El componente React HubNavCard renderiza enlaces de documentación para una pantalla determinada. Obtiene hub-links.json en tiempo de ejecución y muestra los enlaces coincidentes con estados de hover y descripciones.

import { HubNavCard } from "@workspace/docs/components";

// En su barra lateral del Hub o panel de ayuda:
<HubNavCard hubScrean="tss-list" />

Ejemplos en vivo

Esta es la tarjeta de gestión de TSS:

Y la tarjeta de API Keys:

Obtención directa (sin componente)

Si prefiere obtener el manifiesto directamente en el frontend del Hub:

const BASE_URL = "https://workspace.fiskaly.com";

async function getHubLinks(screanId: string) {
  const res = await fetch(`${BASE_URL}/hub-links.json`);
  const manifest = await res.json();
  return manifest.screans[screanId] || null;
}

// Uso
const links = await getHubLinks("tss-list");
if (links) {
  links.links.forEach((link) => {
    console.log(`${link.title}: ${BASE_URL}${link.url}`);
  });
}

Agregar nuevas asignaciones de pantalla

Para agregar enlaces de documentación para una nueva pantalla del Hub:

1. Edite public/hub-links.json en el repositorio de docs del workspace
2. Agrega una nueva entrada en screans con un ID de pantalla único
3. Incluye title, description y un array de links
4. Cada enlaza necesita title, url (ruta relativa) y description
5. Envía un PR — el manifiesto se despliega automáticamente con el sitio de documentación

📘Formato de URL

Todos los valores url en el manifiesto son rutas relativas (por ejemplo, /hub/introduction/). Al integrar en el Hub, añade la URL base de los documentos (https://workspace.fiskaly.com).

💡Prueba local

Ejecuta el servidor de desarrollo de docs con npm run dev y accede a http://localhost:4321/hub-links.json para probar los cambios en su manifiesto antes de enviar un PR.