HubfiscalCreateDocument

Descripcion

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 unica base de datos unificada.

Caracteristicas principales:

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

Configuracion

Campo	Tipo	Requerido	Descripcion
credentials_id	credentials	Si	Credencial Hub Fiscal SQL Server (MSSQL)
entity_id	text	No	ID del pedido (Shopify). Si vacio, usa data.id
entity_source	select	No	Origen: shopify, prestashop, woocommerce, manual, api. Default: shopify
order_number	text	No	Numero de pedido visible (ej: PT14684). Si vacio, usa data.name
country_iso	text	No	Codigo ISO del pais (PT, ES, AO, MZ). Si vacio, 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 vacio
fiscal_doc_id	text	No	ID del documento devuelto por el proveedor fiscal
fiscal_doc_number	text	No	Numero de factura del proveedor fiscal
contact_name	text	No	Nombre del contacto. Si vacio, 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 vacio, usa data.subtotal_price
total_tax	text	No	Total impuestos. Si vacio, usa data.current_total_tax
total_gross	text	No	Total bruto. Si vacio, se calcula como net + tax
currency	text	No	Divisa ISO (default: EUR)
issued_at	text	No	Fecha de emision ISO. Si vacia, 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
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 conexion 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 fiscalizacion (request/response por proveedor)
logs	Eventos y errores del sistema
countries	Paises habilitados para fiscalizacion
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, asi que una configuracion minima funciona:

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

Notas

• La tabla documents tiene un constraint unico 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-deteccion de proveedor: PT → billpt, ES → fiskaly, AO → billpt, MZ → billpt

Nodos Relacionados

• 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