SageStoreFromHubfiscal

Description

Reads the output of HubfiscalStoreBillpt (or any Hub Fiscal node) and writes the fiscal document directly into the Sage X3 MSSQL staging tables, following the EQZ_MigracionEcomm_Sage 3-line structure.

Key features:

Auto country mapping: Derives plant, entry type, document prefix, and account codes from the country ISO code (PT / ES / FR / IT). All values can be overridden via config.
3-line accounting: Inserts one debtors line (430xxx), one sales line (700xxx), and one VAT line (477xxx) per document.
3 analytics rows: Inserts one YFACTERAN row per accounting line with CCE_0=country, CCE_1=channel, CCE_2=delegation, CCE_3=tercero.
Credit-note support: Inverts sign for NC documents (debtors −1 / sales +1 / VAT +1).
Atomic transaction: All three tables are committed together — rolls back fully on error.

Configuration

Field	Type	Required	Description
credentials_id	credentials	Yes	Sage X3 MSSQL credential (`sageCreateDocument` provider)
sage_schema	select	No	Sage schema: `LIVE` (production) or `DEV`. Default: `LIVE`
country_iso	text	No	Override country ISO. Defaults to `country_iso` from Hub Fiscal output
planta	text	No	Sage plant code. Auto-detected: PT→`22_PT`, ES→`21_ES`, FR→`23_FR`, IT→`24_IT`
tipasiiento	text	No	Entry type (TIPASIIENTO_0). Auto: PT/FT→`TPE03`, PT/NC→`AEC02`, ES/FT→`TPE01`, ES/NC→`AEC01`, FR/FT→`TPE05`, IT/FT→`TPE06`
doc_prefix	text	No	Prefix stored in header TERCERO_0 (e.g. `FPT`, `FES`, `FFR`). Auto by country+type
tercero_deb	text	No	Tercero code for the debtors line. Auto: PT→`CT-000028`, ES→`CT-000008`, FR→`CT-000040`
vat_code	text	No	Sage VAT code. Auto: PT→`PT023`, ES→`SP001`, FR→`FR020`, IT→`IT022`
canal	text	No	Sales channel for analytics CCE_1. Default: `E-COMMERCE`
delegacion	text	No	Delegation code for analytics CCE_2. Default: `06`
descripcion	text	No	Entry description. Default: `Ventas Ecomm DD/MM/YYYY` using the document date
sage_user	text	No	Sage user for CREUSR_0 and UPDUSR_0. Default: `ADMIN`

Country Auto-Mapping

Country	Planta	FT entry type	NC entry type	Doc prefix FT	Debtors account	VAT code
PT	22_PT	TPE03	AEC02	FPT	430150 / CT-000028	PT023
ES	21_ES	TPE01	AEC01	FES	430000 / CT-000008	SP001
FR	23_FR	TPE05	AEC05	FFR	430100 / CT-000040	FR020
IT	24_IT	TPE06	AEC06	FIT	310000	IT022

Accounting Structure

Each document produces 3 lines in YFACTERLIN:

Line	Account type	Account (PT)	Amount	Sign FT	Sign NC
1	Debtors	430150	total_gross	+1	−1
2	Sales	700050	total_net	−1	+1
3	VAT	477000	total_tax	−1	+1

And 3 rows in YFACTERAN mirroring each line with CCE_0=country_iso, CCE_1=canal, CCE_2=delegacion, CCE_3=tercero_deb.

Input

Expected input: the output of HubfiscalStoreBillpt:

{
  "success": true,
  "hub_document_id": 12,
  "entity_id": "6684429451477",
  "order_number": "14522",
  "country_iso": "PT",
  "type": "FT",
  "status": "completed",
  "fiscal_provider": "billpt",
  "fiscal_doc_id": "1042",
  "fiscal_doc_number": "FT 2025/1042",
  "total_net": 63.56,
  "total_tax": 14.62,
  "total_gross": 78.18,
  "currency": "EUR",
  "issued_at": "2026-04-20"
}

Output

{
  "success": true,
  "idRegistro": 2047,
  "sage_schema": "LIVE",
  "planta": "22_PT",
  "tipasiiento": "TPE03",
  "doc_prefix": "FPT",
  "country_iso": "PT",
  "type": "FT",
  "total_gross": 78.18,
  "total_net": 63.56,
  "total_tax": 14.62,
  "fiscal_doc_number": "FT 2025/1042",
  "fecha": "2026-04-20",
  "message": "Documento Sage creado (ID: 2047) en LIVE.YFACTERCAB — FPT FT 2025/1042"
}

Typical Workflow

Shopify Webhook → HubfiscalStoreShopify (pending)
               → HubfiscalStoreBillpt (completed)
               → SageStoreFromHubfiscal  ← inserts into Sage X3

MSSQL Tables

Table	Description
`YFACTERCAB`	Document header — TIPODOC=2, TIPASIIENTO, PLANTA, TERCERO (doc_prefix), dates, reference
`YFACTERLIN`	Accounting lines — 3 lines per document (debtors, sales, VAT)
`YFACTERAN`	Analytics rows — 3 rows with channel, delegation, country, tercero

Notes

TIPODOC is always 2 (e-commerce style), matching the EQZ_MigracionEcomm_Sage procedure pattern. This differs from the TP migration procedure which uses TIPODOC=1.
INVTYP is always 0 and REGIVA is always empty, since Bill.pt already handles the fiscal registration.
IDREGISTRO_0 is computed as MAX(IDREGISTRO_0) + 1 inside the transaction — no sequence object is required.
If total_tax is not present in the Hub Fiscal output it is inferred as total_gross − total_net.

HubfiscalStoreBillpt - Store Bill.pt result in Hub Fiscal (feeds this node)
HubfiscalStoreShopify - Register the Shopify order before fiscalization
SageCreateDocument - Alternative: create Sage document directly from Shopify data
HubfiscalStoreSage - Store SageCreateDocument result in Hub Fiscal MySQL