HubfiscalCreateDocument

Descripción

Registra un documento fiscal en el Hub Fiscal, una base de datos SQL Server externa que actua como hub central para todas las operaciones fiscales. El nodo consolida pedidos de Shopify (u otras fuentes) junto con los resultados de los proveedores fiscales (Bill.pt, Fiskaly, Sage) en una única base de datos unificada.

Caracteristicas principales:

• MERGE (upsert): Si el pedido ya existe lo actualiza, si no lo crea. Evita duplicados.
• Auto-detección: Extrae el pais de billing_address, detecta el proveedor fiscal por pais (PT=billpt, ES=fiskaly).
• Transacción atomica: Inserta en las tablas documents, fiscal_status y logs en una sola transacción.
• Almacenamiento de tickets: Guarda el ticket HTML y/o el PDF binario devuelto por el proveedor fiscal.

Configuración

Campo	Tipo	Requerido	Descripción
credentials_id	credentials	Si	Credencial Hub Fiscal SQL Server (MSSQL)
entity_id	text	No	ID del pedido (Shopify). Si vacío, usa data.id
entity_source	select	No	Origen: shopify, prestashop, woocommerce, manual, api. Default: shopify
order_number	text	No	Número de pedido visible (ej: PT14684). Si vacío, usa data.name
country_iso	text	No	Código ISO del pais (PT, ES, AO, MZ). Si vacío, extrae de billing_address
doc_type	select	No	Tipo de documento: FT, FR, NC, ORC. Default: FT
fiscal_provider	select	No	Proveedor fiscal: billpt, fiskaly, sage. Auto-detectado por pais si vacío
fiscal_doc_id	text	No	ID del documento devuelto por el proveedor fiscal
fiscal_doc_number	text	No	Número de factura del proveedor fiscal
contact_name	text	No	Nombre del contacto. Si vacío, extrae de billing_address
contact_nif	text	No	NIF del contacto
contact_email	text	No	Email del contacto
total_net	text	No	Total neto (base imponible). Si vacío, usa data.subtotal_price
total_tax	text	No	Total impuestos. Si vacío, usa data.current_total_tax
total_gross	text	No	Total bruto. Si vacío, se calcula como net + tax
currency	text	No	Divisa ISO (default: EUR)
issued_at	text	No	Fecha de emision ISO. Si vacía, usa fecha actual
ticket_html	textarea	No	HTML del ticket de Bill.pt u otro proveedor
ticket_pdf	textarea	No	PDF del ticket en base64. Se almacena como binario en SQL Server
assign_numbering	select	No	No (default): solo guarda portal y zona. Sí: además asigna el número de serie y pasa a completed (portales sin tercero fiscal)
save_payload	select	No	Guardar JSON completo del pedido en payload_json (max 50KB). Default: Si
timeout	text	No	Timeout en milisegundos (default: 30000)

Credenciales

Este modulo requiere una credencial tipo hubfiscalCreateDocument (SQL Server) con:

• host: Hostname o IP del SQL Server
• user: Usuario de base de datos
• password: Contrasena
• database: Nombre de la base de datos Hub Fiscal
• port: Puerto (default: 1433)

El test de credenciales verifica la conexión y comprueba que existan todas las tablas del Hub Fiscal (documents, fiscal_status, logs, countries, reports_cache).

Esquema de Base de Datos

La base de datos Hub Fiscal requiere 5 tablas. El SQL del schema esta incluido en el modulo en modules/hubfiscalCreateDocument/schema.sql.

Tabla	Proposito
documents	Documento fiscal central (pedido + estado + totales + tickets)
fiscal_status	Cada intento de fiscalización (request/response por proveedor)
logs	Eventos y errores del sistema
countries	Paises habilitados para fiscalización
reports_cache	Cache de reportes pre-calculados para dashboard de KPIs

Salida

{
  "success": true,
  "hub_document_id": 42,
  "entity_id": "6702987051221",
  "order_number": "PT14684",
  "country_iso": "PT",
  "type": "FT",
  "status": "completed",
  "fiscal_provider": "billpt",
  "fiscal_doc_id": "789",
  "fiscal_doc_number": "FT 2026/1",
  "total_gross": 19.90,
  "currency": "EUR",
  "message": "Documento registrado en Hub Fiscal (ID: 42)"
}

Ejemplo de Uso

Flujo tipico: Webhook Shopify → Decision (pais) → Bill.pt (crear factura) → HubfiscalCreateDocument

{
  "credentials_id": "10",
  "entity_id": "{{id}}",
  "order_number": "{{name}}",
  "country_iso": "{{billing_address.country_code}}",
  "doc_type": "FT",
  "contact_name": "{{billing_address.name}}",
  "contact_email": "{{email}}",
  "total_net": "{{subtotal_price}}",
  "total_tax": "{{current_total_tax}}",
  "total_gross": "{{total_price}}"
}

La mayoria de campos se auto-detectan de los datos del nodo anterior, así que una configuración minima funciona:

{
  "credentials_id": "10",
  "save_payload": "true"
}

Notas

• La tabla documents tiene un constraint único en (entity_id, entity_source, type) para prevenir duplicados
• Si el nodo anterior retorno error, el documento se guarda con status: "failed" y el mensaje de error se almacena
• Si el nodo anterior retorno success: true, el documento se guarda con status: "completed"
• El campo ticket_html almacena contenido HTML como NVARCHAR(MAX) (hasta 2GB, consultable)
• El campo ticket_pdf almacena PDF binario como VARBINARY(MAX) (acepta input en base64, se convierte a Buffer)
• El payload del pedido original se trunca a 50KB para evitar almacenamiento excesivo
• Auto-detección de proveedor: PT → billpt, ES → fiskaly, AO → billpt, MZ → billpt

Portal y numeración (agregación diaria a Sage X3)

Además de guardar el documento, el nodo determina el portal de venta (equivalenza.com, .it, .fr o .pt) a partir del pedido y la zona (Canarias, si el código postal de envío empieza por 35 o 38), y los guarda en el documento. Esto lo usa HubfiscalAggregateSales para agrupar las ventas del día.

Con la opción Numerar y completar en Sí, en los portales sin tercero fiscal (equivalenza.com, .it y .fr) el nodo además:

• asigna el siguiente número correlativo de la serie, sin ceros a la izquierda y sin reinicio anual (FESH1, FESH2…), y
• pasa el documento a completed.

Portal	Factura	Abono
equivalenza.com	FESH	AESH
equivalenza.com (Canarias)	FCAH	ACAH
equivalenza.it	FITH	AITH
equivalenza.fr	FFRH	AFRH

• Sin huecos ni duplicados, aunque entren pedidos a la vez: el contador de cada serie se bloquea al asignar, y un error no consume el número.
• Idempotente: reenviar el mismo pedido no lo renumera.
• equivalenza.pt no se numera aquí: lo hace Bill.pt (FHPT / AHPT).
• Un tipo distinto de factura o abono (por ejemplo ORC) o un portal sin regla no se numera.
• Por defecto está desactivado (No): solo se guardan portal y zona. Actívalo cuando decidas desde qué día se numera, porque la numeración consume números de serie reales.

Requiere aplicar en la base de datos de Hub Fiscal las columnas portal y zone y las tablas document_sequences y portal_providers. Si no están aplicadas, el nodo sigue funcionando como antes y no numera.

Salida adicional del nodo con estos datos: portal, zone, fiscal_doc_number y numbering (el resultado: numerado, ya_numerado, numeracion_desactivada, delegado_en_billpt, esquema_no_aplicado…).

Nodos Relacionados

• HubfiscalAggregateSales - Agrupa las ventas del día por portal y las prepara para Sage X3
• HubfiscalUpdateDocument - Actualizar documento existente
• HubfiscalExportPdf - Exportar tickets PDF/HTML
• HubfiscalGetDocuments - Consultar y filtrar documentos
• BillptCreateDocument - Crear documento en Bill.pt
• SageCreateDocument - Crear documento en Sage X3
• FiskalyCreateInvoice - Crear factura en Fiskaly