HubfiscalGetDocuments

Description

Queries the Hub Fiscal database to retrieve fiscal documents with powerful filtering capabilities. Supports filtering by country, status, type, provider, date range and free-text search. Returns paginated JSON results with configurable inclusion/exclusion of heavy binary fields (ticket HTML, ticket PDF, original payload).

Key features:

Multiple filters: Combine country, status, type, provider, date range and text search
Multi-value filters: Country and status accept comma-separated values (e.g. PT,ES)
Binary control: Include or exclude ticket_html, ticket_pdf and payload_json independently
Fiscal history: Optionally join with fiscal_status table to include attempt history
Pagination: limit + offset with total count for cursor-based navigation
Safe ordering: Whitelist-validated column names to prevent SQL injection

Configuration

Field	Type	Required	Description
credentials_id	credentials	Yes	Hub Fiscal SQL Server (MSSQL) credential
document_id	text	No	Document ID(s): single or comma-separated
entity_id	text	No	External entity ID (Shopify order ID)
order_number	text	No	Visible order number
country_iso	text	No	Country ISO: single (`PT`) or multiple (`PT,ES`)
status	select	No	Filter by status: pending, processing, completed, failed, voided
doc_type	select	No	Filter by type: FT, FR, NC, ORC
fiscal_provider	select	No	Filter by provider: billpt, fiskaly, sage
date_from	text	No	Issue date from (YYYY-MM-DD)
date_to	text	No	Issue date to (YYYY-MM-DD)
search	text	No	Free-text search in order_number, contact_name, contact_email, fiscal_doc_number
include_html	select	No	Include ticket_html in response. Default: Yes
include_pdf	select	No	Include ticket_pdf (base64) in response. Default: No (heavy)
include_payload	select	No	Include original order payload_json. Default: Yes
include_fiscal_status	select	No	Include fiscal attempt history per document. Default: No
limit	text	No	Max documents to return (default: 100)
offset	text	No	Skip N records for pagination (default: 0)
order_by	select	No	Sort by: created_at, issued_at, updated_at, total_gross, order_number, status, country_iso
order_dir	select	No	Sort direction: DESC (default) or ASC
timeout	text	No	Timeout in milliseconds (default: 30000)

Credentials

Uses the same credential type as HubfiscalCreateDocument (hubfiscalCreateDocument provider).

Output

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

Usage Examples

Get all failed documents for Portugal

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

Search by customer name with fiscal history

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

Get documents for a date range across multiple countries

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

Lightweight query (no binaries) for dashboard

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

Notes

The include_pdf option is false by default because PDF base64 data is very large. Use HubfiscalExportPdf to download PDFs as files instead
When include_pdf is true, the binary VARBINARY(MAX) data is converted to base64 string in the response
The include_fiscal_status option performs an additional JOIN query with the fiscal_status table, adding a fiscal_history array to each document
The search filter performs a LIKE search across order_number, contact_name, contact_email and fiscal_doc_number
The order_by column is validated against a whitelist to prevent SQL injection
Pagination returns has_more: true when there are more results beyond the current page
All filter parameters use parameterized queries (no string concatenation) for security

Common Errors

Error	Cause	Solution
Timeout	Query too slow with large result sets	Reduce `limit`, add filters, or increase `timeout`
No documents found	Filters too restrictive	Relax filters or verify data exists in Hub Fiscal
Large response	`include_pdf: true` with many documents	Set `include_pdf: false` and use HubfiscalExportPdf for PDFs

HubfiscalExportPdf - Export tickets as files (PDF/HTML/ZIP)
HubfiscalCreateDocument - Create/register document
HubfiscalUpdateDocument - Update existing document