HubfiscalStoreSage

Description

Stores the output of SageCreateDocument in the Hub Fiscal centralized MySQL/MariaDB database. Designed to be placed immediately after the Sage X3 document creation step, whether it succeeded or failed.

Key features:

Upsert: If the order already has a record it updates it, otherwise inserts. Prevents duplicates on retries.
Failure recording: Stores failed attempts with status: failed, incrementing retry_count on each retry.
Atomic transaction: Inserts into documents, fiscal_status and logs in one transaction — rolls back fully on error.
Contact propagation: Reads contact data (nombre/nome, nif, email) from the contato object passed through the workflow.

Configuration

Field	Type	Required	Description
credentials_id	credentials	Yes	Hub Fiscal MySQL/MariaDB credential (`sqlQuery` type)
country_iso	text	No	Country ISO code. Defaults to the `pais` field in the Sage response. Default: `ES`
document_type	select	No	Fallback document type if not in the Sage response. Default: `FT`
entity_source	text	No	Order source: `shopify`, `manual`, `api`. Default: `shopify`
currency	text	No	ISO currency fallback. Default: `EUR`
save_payload	select	No	Save full Sage JSON in `payload_json` (up to 50KB). Default: Yes

Field Mapping

The node auto-maps fields from the Sage response:

Hub Fiscal field	Sage source
`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` → today

Propagating shopify_order_id

SageCreateDocument does not output shopify_order_id natively. To make it available to this node, pass it forward through the workflow using a Transform or SetVariable node:

{
  "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}}"
  }
}

Alternatively, the _meta_ object in the workflow data can carry shopify_order_id and order_number across nodes.

Input

Expected input: the output of 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": "John Doe",
    "nif": "B12345678",
    "email": "customer@example.com",
    "pais": "ES"
  }
}

Output

{
  "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)"
}

Typical Workflow

Shopify Webhook → HubfiscalStoreShopify (pending)
               → SageCreateDocument
               → HubfiscalStoreSage (updates to completed)

Notes

Sage does not return an ATCUD — the atcud column is stored as NULL for Sage documents.
If entity_id is empty (no shopify_order_id in the payload), the node falls back to using idRegistro as entity ID. This is a safe fallback but means the Hub Fiscal record won’t correlate with the original Shopify order unless shopify_order_id is propagated.
The fiscal_status.action is set to void for NC (credit note / abono) documents and create for all others.

SageCreateDocument - Creates the document in Sage X3
HubfiscalStoreShopify - Register the Shopify order before fiscalization
HubfiscalGetDocuments - Query and filter stored documents
HubfiscalUpdateDocument - Manually update a document record