HubfiscalAggregateSales

Descripción

Toma los documentos de Hub Fiscal en estado completed de un día que todavía no se han contabilizado, los agrupa por portal y por tipo (factura o abono) y deja preparado un asiento por grupo para enviarlo a Sage X3. En un día normal salen de 3 a 5 asientos, nunca un asiento por documento.

Es la primera pieza del proceso de contabilización diaria Hub Fiscal → Sage X3: este nodo calcula y deja los lotes, el nodo SageX3Soap los envía y HubfiscalLogSageBatch guarda el resultado.

Características principales:

• Un documento, un asiento: cada documento se contabiliza una sola vez. La base de datos lo garantiza aunque el proceso se lance varias veces o a la vez.
• Importe neto, sin IVA, sumado en céntimos (sin errores de redondeo). Sage aplica el IVA con el código del grupo.
• Primer y último número de factura de cada grupo (TCKINI / TCKFIN), ordenados por el correlativo numérico (FESH10 va después de FESH9).
• Modo simulación: calcula y muestra los asientos sin escribir nada. Es el valor por defecto.
• Reenvío automático: los lotes del día que no llegaron bien a Sage se devuelven otra vez para reenviarlos.

Configuración

Campo	Tipo	Requerido	Descripción
credentials_id	credentials	Sí	Credencial Hub Fiscal MySQL/MariaDB (tipo sqlQuery)
date	text	No	Fecha a contabilizar, AAAA-MM-DD. Admite variables {{...}}. Si está vacía, usa ayer (hora de Madrid)
simular	select	No	Sí (por defecto): solo calcula y muestra. No: crea los lotes y enlaza los documentos
timeout	text	No	Timeout de conexión en ms. Default: 30000

No hay fecha de corte fija: la fecha es un parámetro y da el control exacto de qué se contabiliza.

Qué documentos entran

Solo los que cumplen las tres condiciones:

1. Estado completed.
2. Sin asiento todavía.
3. Emitidos en la fecha indicada.

Cómo se agrupan

La clave es el portal de venta, no el país de destino: un pedido de equivalenza.it enviado a Suiza se contabiliza con Italia. Dentro de equivalenza.com, Canarias se separa cuando el código postal de la dirección de envío empieza por 35 o 38.

Grupo	Factura	Abono	Serie factura / abono
equivalenza.com	ES_FAC	ES_ABO	FESH / AESH
equivalenza.com + Canarias	CA_FAC	CA_ABO	FCAH / ACAH
equivalenza.it	IT_FAC	IT_ABO	FITH / AITH
equivalenza.fr	FR_FAC	FR_ABO	FFRH / AFRH
equivalenza.pt	PT_FAC	PT_ABO	FHPT / AHPT (Bill.pt)

Los abonos (NC) van en su propio asiento, con importe positivo; el signo lo pone el tipo de asiento de Sage.

El payload de cada asiento se construye con el esquema acordado para el servicio XX6AISTG de Sage X3 (objeto FTC), rellenando cuatro valores: fecha del grupo (VCRDAT, AAAAMMDD), primer y último número de factura (TCKINI, TCKFIN) y el importe neto (GROPRI e IMPORTE).

Qué queda fuera

Un documento que no se puede agrupar no se contabiliza en silencio: sale en la lista omitidos con su motivo y queda registrado.

Motivo	Significado
sin_portal	No se pudo determinar el portal del documento
portal_sin_regla	El portal no tiene grupo definido
tipo_sin_regla	El tipo no es factura (FT) ni abono (NC)
sin_numero	Está completed pero no tiene número de factura
numero_no_numerico	El número no tiene dígitos para calcular el primero y el último

Entrada

No necesita datos de entrada: lee de la base de datos de Hub Fiscal. La fecha puede venir de una variable (por ejemplo, {{fecha}} de un nodo anterior).

Salida

{
  "success": true,
  "date": "2026-10-12",
  "simulated": true,
  "documents": 74,
  "batch_count": 4,
  "batches": [
    {
      "batch_id": null,
      "group_key": "ES_FAC",
      "seq": 1,
      "doc_count": 12,
      "total_net": "471.82",
      "ticket_ini": "FESH1",
      "ticket_fin": "FESH12",
      "sage_doc_origin": "TPE01",
      "payload": "{\"XX6AISW0_1\":{...},\"XX6AISW1_1\":{...},...}",
      "reintento": false,
      "simulated": true
    }
  ],
  "omitidos": [],
  "message": "[SIMULACIÓN] 2026-10-12: 74 documentos → 4 asientos nuevos"
}

• batches contiene un elemento por asiento. Es la lista que recorre el nodo Iterator.
• payload es el JSON del asiento, como texto, listo para el campo object_xml de SageX3Soap con {{payload}}.
• batch_id es null en simulación y el identificador del lote cuando se escribe.
• reintento: true marca un lote de ese día que no se envió bien y vuelve a salir.

Seguridad del proceso

• Simulación por defecto: úsala hasta cuadrar los importes. En simulación no se crea ningún lote ni se enlaza ningún documento.
• Guarda de regresión: si saliera un número de asientos mayor que el de grupos posibles (10), o si los documentos de entrada no cuadraran con los contabilizados y los omitidos, el nodo se detiene con un error.
• Rezagados: un documento del día D que llega después de ejecutar D no se pierde ni se contabiliza solo. Si se vuelve a lanzar la fecha D, forma un segundo lote (seq 2) y el primero no se toca.
• Ejecuciones simultáneas: si dos ejecuciones coinciden sobre el mismo día, una crea el asiento y la otra falla sin duplicar nada.

Requisitos

La base de datos de Hub Fiscal necesita las columnas portal y zone en documents, las tablas document_sequences y portal_providers, y las tablas de lotes sage_batches y sage_batch_documents. Si faltan, el nodo se detiene indicando qué ficheros SQL hay que aplicar.

Los documentos deben tener portal y numeración: lo hacen los nodos de entrada HubfiscalStoreShopify y HubfiscalCreateDocument con la opción Numerar y completar.

Flujo Típico

Cron diario → HubfiscalAggregateSales
            → Decision (¿hay asientos?)
            → Iterator (recorrer asientos)
            → Decision (¿envío real?, no es simulación)
            → SageX3Soap (save, XX6AISTG, object_xml = {{payload}})
            → HubfiscalLogSageBatch (batch_id = {{batch_id}})
            → End

La decisión «¿envío real?» impide que una simulación llegue a llamar a Sage.

Notas

• Si Sage falla en un asiento, el lote queda pendiente y se reenvía en la siguiente ejecución del mismo día; los documentos ya están enlazados a él y no vuelven a entrar como nuevos.
• Con un día sin ventas el nodo devuelve batch_count: 0 sin error; usa una decisión posterior para terminar el flujo.
• Un documento completed sin número de factura (por ejemplo, una nota de crédito de Bill.pt) se informa en omitidos; no bloquea el resto. Revísalo en el proveedor fiscal, porque sin número no se puede fijar el primer y el último ticket del grupo.

Nodos Relacionados

• HubfiscalLogSageBatch - Guarda el resultado de Sage en el lote y en los documentos
• SageX3Soap - Envía cada asiento a Sage X3
• HubfiscalStoreShopify - Registra el pedido y asigna portal y numeración
• HubfiscalCreateDocument - Registra el documento en Hub Fiscal