HubfiscalStoreSage

Descripción

Almacena la salida de SageCreateDocument en la base de datos centralizada Hub Fiscal (MySQL/MariaDB). Debe colocarse inmediatamente después del paso de creación en Sage X3, tanto si el documento fue exitoso como si fallo.

Caracteristicas principales:

Upsert: Si el pedido ya tiene un registro lo actualiza, si no lo inserta. Evita duplicados en reintentos.
Registro de fallos: Almacena los intentos fallidos con status: failed, incrementando retry_count en cada reintento.
Transacción atomica: Inserta en documents, fiscal_status y logs en una sola transacción — hace rollback completo en caso de error.
Propagación de contacto: Lee los datos del contacto (nombre/nome, nif, email) del objeto contato propagado por el workflow.

Configuración

Campo	Tipo	Requerido	Descripción
credentials_id	credentials	Si	Credencial Hub Fiscal MySQL/MariaDB (tipo `sqlQuery`)
country_iso	text	No	Código ISO del pais. Por defecto usa el campo `pais` de la respuesta de Sage. Default: `ES`
document_type	select	No	Tipo de documento fallback si no viene en la respuesta de Sage. Default: `FT`
entity_source	text	No	Origen del pedido: `shopify`, `manual`, `api`. Default: `shopify`
currency	text	No	Moneda ISO fallback. Default: `EUR`
save_payload	select	No	Guardar el JSON completo de Sage en `payload_json` (hasta 50KB). Default: Si

Mapeo de Campos

El nodo extrae automáticamente los campos de la respuesta Sage:

Campo Hub Fiscal	Origen Sage
`entity_id`	`data.shopify_order_id` → `data.entity_id` → `_meta_.shopify_order_id` → `idRegistro`
`order_number`	`data.shopify_order_number` → `data.order_number` → `_meta_.order_number`
`country_iso`	config → `data.pais` → `ES`
`type`	`data.tipificacao` → config → `FT`
`fiscal_doc_id`	`data.idRegistro`
`fiscal_doc_number`	`data.descripcion` → `idRegistro`
`total_net`	`data.totalNet` → `data.total`
`total_tax`	`data.totalTax`
`total_gross`	`data.total`
`contact_name`	`data.contato.nombre` → `data.contato.nome` → `data.contact_name`
`contact_nif`	`data.contato.nif` → `data.contact_nif`
`contact_email`	`data.contato.email` → `data.email`
`issued_at`	`data.fecha` → hoy

Propagación de shopify_order_id

SageCreateDocument no incluye shopify_order_id en su salida nativa. Para que este nodo pueda correlacionarlo con el pedido Shopify, propaga ese campo mediante un nodo Transform o SetVariable anterior:

{
  "shopify_order_id": "{{id}}",
  "shopify_order_number": "{{order_number}}",
  "contato": {
    "nombre": "{{billing_address.name}}",
    "nif": "{{note_attributes[?name=='nif'].value}}",
    "email": "{{email}}",
    "pais": "{{billing_address.country_code}}"
  }
}

Alternativamente, el objeto _meta_ del workflow puede transportar shopify_order_id y order_number entre nodos.

Entrada

Entrada esperada: la salida de SageCreateDocument:

{
  "success": true,
  "idRegistro": 1042,
  "schema": "SAGEBCN",
  "tercero": "CT-000001",
  "planta": "22_ES",
  "total": 78.18,
  "descripcion": "Pedido Shopify #14522",
  "pais": "ES",
  "tipificacao": "FT",
  "fecha": "2026-04-20",
  "message": "Documento Sage creado (ID: 1042) en SAGEBCN.YFACTERCAB",
  "shopify_order_id": "6684429451477",
  "shopify_order_number": "14522",
  "contato": {
    "nombre": "Juan Garcia",
    "nif": "B12345678",
    "email": "cliente@ejemplo.com",
    "pais": "ES"
  }
}

Salida

{
  "success": true,
  "hub_document_id": 18,
  "entity_id": "6684429451477",
  "order_number": "14522",
  "country_iso": "ES",
  "type": "FT",
  "status": "completed",
  "fiscal_provider": "sage",
  "fiscal_doc_id": "1042",
  "fiscal_doc_number": "Pedido Shopify #14522",
  "total_gross": 78.18,
  "currency": "EUR",
  "message": "Documento Sage registrado en Hub Fiscal (ID: 18, Sage ID: 1042)"
}

Flujo Tipico

Shopify Webhook → HubfiscalStoreShopify (pending)
               → SageCreateDocument
               → HubfiscalStoreSage (actualiza a completed)

Notas

Sage no devuelve ATCUD — la columna atcud se almacena como NULL para documentos Sage.
Si entity_id esta vacío (no hay shopify_order_id en el payload), el nodo usa idRegistro de Sage como ID de entidad. Es un fallback seguro pero el registro en Hub Fiscal no se correlacionara con el pedido Shopify original si no se propaga shopify_order_id.
El campo fiscal_status.action se establece a void para documentos NC (nota de crédito / abono) y create para el resto.

Nodos Relacionados

SageCreateDocument - Crea el documento en Sage X3
HubfiscalStoreShopify - Registrar el pedido Shopify antes de fiscalizar
HubfiscalGetDocuments - Consultar y filtrar documentos almacenados
HubfiscalUpdateDocument - Actualizar manualmente un registro de documento