HubfiscalStoreBillpt

Descripción

Almacena la salida de BillptCreateInvoiceFromShopify (o cualquier nodo de documento Bill.pt) en la base de datos centralizada Hub Fiscal (MySQL/MariaDB). Debe colocarse inmediatamente después del paso de creación en Bill.pt, tanto si la factura fue exitosa como si fallo.

Caracteristicas principales:

Upsert: Si el pedido ya tiene un registro lo actualiza, si no lo inserta. Evita duplicados en reintentos.
Trazabilidad completa: Almacena atcud, fiscal_doc_number, totales, datos del contacto y el payload JSON completo.
Transacción atomica: Inserta en documents, fiscal_status y logs en una sola transacción — hace rollback completo en caso de error.
Registro de fallos: Almacena los intentos fallidos con status: failed y el mensaje de error, incrementando retry_count.

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 (PT, ES, AO…). Por defecto se extrae del contacto Bill.pt. Default: `PT`
entity_source	text	No	Origen del pedido: `shopify`, `manual`, `api`. Default: `shopify`
document_type	select	No	Tipo de documento fallback si no viene en la respuesta Bill.pt: FT, FR, ORC, NC. Default: `FT`
save_payload	select	No	Guardar el payload JSON completo (hasta 50KB) en `payload_json`. Default: Si

Credenciales

Requiere una credencial de tipo sqlQuery (MySQL/MariaDB) con:

host: Host de la base de datos (ej: 127.0.0.1)
user: Usuario de la base de datos (ej: user_hubfiscal)
password: Contrasena del usuario
database: Nombre de la base de datos Hub Fiscal (ej: hubfiscal)
port: Puerto (por defecto 3306, o 3307 para entorno dev)

Schema de Base de Datos

La base de datos Hub Fiscal requiere 5 tablas. El schema SQL esta en modules/hubfiscalStoreBillpt/schema.sql.

Tabla	Proposito
documents	Un registro por documento fiscal — estado, ATCUD, totales, payload
fiscal_status	Cada intento de fiscalización con request/response completo
logs	Eventos del sistema y errores
countries	Paises habilitados para fiscalización
reports_cache	Cache de reportes pre-calculados

La tabla documents tiene una restricción única sobre (entity_id, entity_source, type) para evitar duplicados.

Entrada

Entrada esperada: la salida de BillptCreateInvoiceFromShopify o cualquier nodo de documento Bill.pt:

{
  "success": true,
  "document_id": 789,
  "document_number": "FT FHPT/3",
  "shopify_order_id": 6684429451477,
  "shopify_order_number": 14522,
  "document": {
    "id": 789,
    "tipificacao": "FT",
    "invoice_number": "FT FHPT/3",
    "atcud": "J6X8WR2G-3",
    "net_total": 63.56,
    "tax_total": 14.62,
    "gross_total": 78.18,
    "moeda": "EUR_€",
    "invoice_date": "2026-04-20",
    "contato": {
      "nome": "Juan Garcia",
      "nif": "999999990",
      "email": "cliente@ejemplo.com",
      "pais": "PT"
    }
  }
}

Salida

{
  "success": true,
  "hub_document_id": 15,
  "entity_id": "6684429451477",
  "order_number": "14522",
  "country_iso": "PT",
  "type": "FT",
  "status": "completed",
  "fiscal_provider": "billpt",
  "fiscal_doc_id": "789",
  "fiscal_doc_number": "FT FHPT/3",
  "atcud": "J6X8WR2G-3",
  "total_gross": 78.18,
  "currency": "EUR",
  "message": "Documento registrado en Hub Fiscal (ID: 15, ATCUD: J6X8WR2G-3)"
}

Mapeo de Campos

El nodo extrae automáticamente los campos de la respuesta Bill.pt:

Campo Hub Fiscal	Origen
`entity_id`	`data.shopify_order_id` → `data.entity_id` → `document.id`
`order_number`	`data.shopify_order_number` → `data.order_number`
`country_iso`	config → `document.contato.pais` → `PT`
`type`	`document.tipificacao` → config `document_type` → `FT`
`fiscal_doc_id`	`data.document_id` → `document.id`
`fiscal_doc_number`	`document.invoice_number` → `data.document_number`
`atcud`	`document.atcud`
`currency`	`document.moeda` (elimina el sufijo `_€`)
`issued_at`	`document.invoice_date` → `document.system_entry_date` → hoy
`contact_name`	`document.contato.nome`
`contact_nif`	`document.contato.nif`
`contact_email`	`document.contato.email` → `data.email`

Registro de Fallos

Cuando el nodo Bill.pt anterior devuelve success: false, el documento se almacena igualmente con status: failed. En cada reintento se incrementa retry_count. Esto permite monitorizar fiscalizaciones pendientes o fallidas desde la base de datos Hub Fiscal.

-- Buscar documentos fallidos
SELECT entity_id, order_number, error_message, retry_count
FROM documents
WHERE status = 'failed' AND fiscal_provider = 'billpt'
ORDER BY updated_at DESC;

Notas

El campo ATCUD (atcud) es obligatorio por la normativa portuguesa (regulación AT) y se almacena en una columna dedicada para facilitar consultas y auditorias.
currency se normaliza del formato EUR_€ de Bill.pt al ISO estándar EUR.
payload_json almacena la entrada completa hasta 50KB. Establece save_payload: false para guardar solo los datos fiscales.
El campo action en fiscal_status se establece a void para documentos NC (Nota de Crédito) y create para el resto.
Usuarios de MariaDB: el test de credencial (tipo sqlQuery) incluye un workaround para autenticación GSSAPI. Usa mysql_native_password para el usuario de la base de datos para evitar errores de autenticación.

Nodos Relacionados

BillptCreateInvoiceFromShopify - Crea la factura Bill.pt desde Shopify
HubfiscalGetDocuments - Consultar y filtrar documentos almacenados
HubfiscalUpdateDocument - Actualizar un registro de documento existente
BillptSendDocumentEmail - Enviar la factura por email después de almacenarla