HubfiscalGetDocuments

Descripcion

Consulta la base de datos Hub Fiscal para obtener documentos fiscales con capacidades avanzadas de filtrado. Soporta filtros por pais, estado, tipo, proveedor, rango de fechas y busqueda de texto libre. Retorna resultados JSON paginados con inclusion/exclusion configurable de campos binarios pesados (ticket HTML, ticket PDF, payload original).

Caracteristicas principales:

Filtros multiples: Combina pais, estado, tipo, proveedor, rango de fechas y busqueda de texto
Filtros multi-valor: Pais y estado aceptan valores separados por coma (ej: PT,ES)
Control de binarios: Incluir o excluir ticket_html, ticket_pdf y payload_json independientemente
Historial fiscal: Opcionalmente join con tabla fiscal_status para incluir historial de intentos
Paginacion: limit + offset con conteo total para navegacion por cursor
Ordenamiento seguro: Nombres de columna validados contra whitelist para prevenir SQL injection

Configuracion

Campo	Tipo	Requerido	Descripcion
credentials_id	credentials	Si	Credencial Hub Fiscal SQL Server (MSSQL)
document_id	text	No	ID(s) de documento: uno solo o separados por coma
entity_id	text	No	ID de entidad externo (ID pedido Shopify)
order_number	text	No	Numero de pedido visible
country_iso	text	No	Pais ISO: uno (`PT`) o multiples (`PT,ES`)
status	select	No	Filtrar por estado: pending, processing, completed, failed, voided
doc_type	select	No	Filtrar por tipo: FT, FR, NC, ORC
fiscal_provider	select	No	Filtrar por proveedor: billpt, fiskaly, sage
date_from	text	No	Fecha emision desde (YYYY-MM-DD)
date_to	text	No	Fecha emision hasta (YYYY-MM-DD)
search	text	No	Busqueda de texto libre en order_number, contact_name, contact_email, fiscal_doc_number
include_html	select	No	Incluir ticket_html en respuesta. Default: Si
include_pdf	select	No	Incluir ticket_pdf (base64) en respuesta. Default: No (pesado)
include_payload	select	No	Incluir payload_json original del pedido. Default: Si
include_fiscal_status	select	No	Incluir historial de intentos fiscales por documento. Default: No
limit	text	No	Maximo de documentos a retornar (default: 100)
offset	text	No	Saltar N registros para paginacion (default: 0)
order_by	select	No	Ordenar por: created_at, issued_at, updated_at, total_gross, order_number, status, country_iso
order_dir	select	No	Direccion de orden: DESC (default) o ASC
timeout	text	No	Timeout en milisegundos (default: 30000)

Credenciales

Usa el mismo tipo de credencial que HubfiscalCreateDocument (proveedor hubfiscalCreateDocument).

Salida

{
  "documents": [
    {
      "id": 42,
      "entity_id": "6702987051221",
      "entity_source": "shopify",
      "order_number": "PT14684",
      "country_iso": "PT",
      "type": "FT",
      "status": "completed",
      "fiscal_provider": "billpt",
      "fiscal_doc_id": "789",
      "fiscal_doc_number": "FT 2026/1",
      "contact_name": "Andrea Bernardino",
      "contact_nif": "999999990",
      "contact_email": "andpaty19@gmail.com",
      "total_net": 15.95,
      "total_tax": 3.95,
      "total_gross": 19.90,
      "currency": "EUR",
      "issued_at": "2026-04-05T00:00:00.000Z",
      "ticket_html": "<html>...</html>",
      "created_at": "2026-04-06T10:21:30.000Z",
      "fiscal_history": [
        {
          "provider": "billpt",
          "action": "create",
          "status": "success",
          "generated_ms": 1250,
          "created_at": "2026-04-06T10:21:31.000Z"
        }
      ]
    }
  ],
  "pagination": {
    "total": 1523,
    "limit": 100,
    "offset": 0,
    "has_more": true
  }
}

Ejemplos de Uso

Obtener todos los documentos fallidos de Portugal

{
  "credentials_id": "10",
  "country_iso": "PT",
  "status": "failed",
  "include_html": "false",
  "include_payload": "false",
  "order_by": "created_at",
  "order_dir": "DESC"
}

Buscar por nombre de cliente con historial fiscal

{
  "credentials_id": "10",
  "search": "Bernardino",
  "include_fiscal_status": "true",
  "include_pdf": "false",
  "limit": "10"
}

Documentos por rango de fechas en multiples paises

{
  "credentials_id": "10",
  "country_iso": "PT,ES",
  "date_from": "2026-04-01",
  "date_to": "2026-04-30",
  "doc_type": "FT",
  "include_html": "false",
  "include_pdf": "false",
  "limit": "500"
}

Consulta ligera (sin binarios) para dashboard

{
  "credentials_id": "10",
  "include_html": "false",
  "include_pdf": "false",
  "include_payload": "false",
  "limit": "50",
  "order_by": "created_at"
}

Notas

La opcion include_pdf esta en false por defecto porque los datos base64 de PDF son muy pesados. Usa HubfiscalExportPdf para descargar PDFs como archivos
Cuando include_pdf esta en true, los datos binarios VARBINARY(MAX) se convierten a string base64 en la respuesta
La opcion include_fiscal_status realiza una query JOIN adicional con la tabla fiscal_status, agregando un array fiscal_history a cada documento
El filtro search realiza una busqueda LIKE en order_number, contact_name, contact_email y fiscal_doc_number
La columna order_by se valida contra una whitelist para prevenir SQL injection
La paginacion retorna has_more: true cuando hay mas resultados mas alla de la pagina actual
Todos los parametros de filtro usan queries parametrizadas (sin concatenacion de strings) por seguridad

Errores Comunes

Error	Causa	Solucion
Timeout	Query muy lenta con grandes conjuntos de resultados	Reducir `limit`, agregar filtros, o aumentar `timeout`
No se encontraron documentos	Filtros muy restrictivos	Relajar filtros o verificar que existen datos en Hub Fiscal
Respuesta muy grande	`include_pdf: true` con muchos documentos	Usar `include_pdf: false` y HubfiscalExportPdf para los PDFs

Nodos Relacionados

HubfiscalExportPdf - Exportar tickets como archivos (PDF/HTML/ZIP)
HubfiscalCreateDocument - Crear/registrar documento
HubfiscalUpdateDocument - Actualizar documento existente