--- title: "Get list of fiscal documents" method: GET path: "/fiscal-document/v1/fiscal-documents" tags: ["Fiscal Documents"] --- # Get list of fiscal documents `GET /fiscal-document/v1/fiscal-documents` ## Request - Base URL: `https://api.cloudbeds.com` - URL: `https://api.cloudbeds.com/fiscal-document/v1/fiscal-documents` - Auth: one of: - HTTP bearer - OAuth 2 - Authorization code: `https://api.cloudbeds.com/auth/oauth/authorize` - Token URL: `https://api.cloudbeds.com/auth/oauth/token` scopes: `read:reservation` Retrieves a paginated list of fiscal documents filtered by optional criteria. ## Query parameters - `pageToken` string - `sort` string - `limit` integer - `filters` FiscalDocumentFilters - `ids` string[]: List of IDs to filter by - `sourceIds` string[]: List of source IDs to filter by - `sourceIdentifiers` string[]: List of source-specific identifiers - `sourceKind` 'GROUP_PROFILE' | 'RESERVATION' | 'HOUSE_ACCOUNT' | 'ACCOUNTS_RECEIVABLE_LEDGER': Kind of the source entity - `sourceKinds` SourceKind[]: Filter by source kind - `numberContains` string: Filter by document number partial match - `statuses` FiscalDocumentStatus[]: List of fiscal document statuses to filter by - `kinds` FiscalDocumentKind[]: List of fiscal document kinds to filter by - `origins` Origin[]: List of fiscal document origins to filter by - `createdAtFrom` string, date-time: Creation date-time range start - `createdAtTo` string, date-time: Creation date-time range end - `invoiceDateFrom` string, date: Invoice date range start - `invoiceDateTo` string, date: Invoice date range end - `invoiceDatePropertyTimezoneFrom` string, date: Invoice date range start - `invoiceDatePropertyTimezoneTo` string, date: Invoice date range end - `dueDateFrom` string, date: Due date range start - `dueDateTo` string, date: Due date range end - `dueDatePropertyTimezoneFrom` string, date: Due date range start - `dueDatePropertyTimezoneTo` string, date: Due date range end - `amountFrom` number: Minimum document amount - `amountTo` number: Maximum document amount - `balanceFrom` number: Minimum document balance - `balanceTo` number: Maximum document balance - `hasDiscrepancies` boolean: Filter by whether the document has pending-transaction discrepancies. Reads the persisted `hasDiscrepancies` flag, the same one returned in the response payload. ## Headers - `X-Property-ID` integer, required ## Response `200` OK - FiscalDocumentPaginated - `fiscalDocuments` FiscalDocumentDetailedResponse[] - `id` string - `number` string - `propertyId` string - `userId` string - `userFullName` string - `sourceName` string - `sourceId` string - `sourceKind` 'GROUP_PROFILE' | 'RESERVATION' | 'HOUSE_ACCOUNT' | 'ACCOUNTS_RECEIVABLE_LEDGER': Kind of the source entity - `kind` 'INVOICE' | 'CREDIT_NOTE' | 'RECEIPT' | 'RECTIFY_INVOICE' | 'PRO_FORMA_INVOICE' | 'REFUND_RECEIPT' | 'INVOICE_RECEIPT' | 'ADVANCE_INVOICE' | 'SETTLEMENT_INVOICE' | 'TAX_WITHHOLDING': Kind of fiscal document - `invoiceDate` string, date - `invoiceDatePropertyTimezone` string, date - `fileName` string - `files` FiscalDocumentFile[], required: All files available for this document, primary first followed by any additional stored files (e.g. the Portuguese duplicate). Always present as an array, but may be empty for documents whose file has not been generated yet (e.g. REQUESTED or early FAILED status). The primary file entry, when present, has a null id (the download endpoint serves it without a fileId; additional entries are downloaded by passing their id as the fileId query parameter). - `id` string, nullable: Id of the stored file, passed as the download endpoint's fileId query parameter. Null for the primary file (the document itself), which the download endpoint serves without a fileId. - `category` 'PRIMARY' | 'DUPLICATE' | 'XML' | 'UNOFFICIAL_COPY' | 'CANCELLATION_ACK', required: The role this file plays for the document. Clients must tolerate unknown values. - `mimeType` string, required: Mime type of the file, derived from its extension (e.g. application/pdf). - `filename` string, required: Display file name, including extension. - `amount` number - `balance` number - `dueDate` string, date - `dueDatePropertyTimezone` string, date - `recipients` RecipientDetails[] - `id` string - `firstName` string - `lastName` string - `email` string, email - `type` 'COMPANY' | 'PERSON' | 'MANUAL' - `companyName` string - `status` 'COMPLETED' | 'VOIDED' | 'PAID' | 'PENDING_INTEGRATION' | 'PARTIALLY_PAID' | 'COMPLETED_INTEGRATION' | 'FAILED_INTEGRATION' | 'CORRECTION_NEEDED' | 'CANCELED' | 'CANCEL_REQUESTED' | 'OPEN' | 'REQUESTED' | 'VOID_REQUESTED' | 'FAILED' | 'MANUALLY_RECONCILED' | 'REJECTED' | 'ACCEPTED' | 'PENDING_TRANSACTION' | 'ALLOCATED' | 'APPLIED': Status of the fiscal document - `origin` string - `externalId` string - `failReason` string - `reason` string, nullable: Correction reason recorded when the document was created (credit notes and rectifying invoices). One of the slugs offered by the credit-note action's reason field, or free text on the Spanish rectify path. Null when no reason was given. - `method` 'VOID' | 'ADJUSTMENT' - `createdAt` string, date-time - `parentId` string - `updatedAt` string, date-time - `governmentIntegration` GovernmentIntegration - `number` string - `series` string - `invoiceType` string, nullable: AR ARCA invoice class (A/B/C/T) for this document, used to disambiguate documents that share series + number across classes. Null for non-AR documents. - `status` string - `qr` object - `url` string, uri - `string` string - `url` string, uri - `officialId` string - `externalId` string - `rectifyingInvoiceType` string - `cancellationFailedFallbackStatus` 'COMPLETED' | 'VOIDED' | 'PAID' | 'PENDING_INTEGRATION' | 'PARTIALLY_PAID' | 'COMPLETED_INTEGRATION' | 'FAILED_INTEGRATION' | 'CORRECTION_NEEDED' | 'CANCELED' | 'CANCEL_REQUESTED' | 'OPEN' | 'REQUESTED' | 'VOID_REQUESTED' | 'FAILED' | 'MANUALLY_RECONCILED' | 'REJECTED' | 'ACCEPTED' | 'PENDING_TRANSACTION' | 'ALLOCATED' | 'APPLIED': Status of the fiscal document - `cancellationStatus` 'PENDING' | 'CANCELLED' | 'FAILED': Outcome of the latest cancellation request sent to the tax authority. - `pdfFileBase64` string, byte: Base64-encoded PDF file content. Only allowed when status is COMPLETED_INTEGRATION. - `handwritten` boolean: Indicates this is a handwritten receipt created during POS unavailability. - `signatures` IntegrationSignature[]: Array of semantic signatures/response data from the government integration. - `type` string: Semantic type (JWT_TOKEN, QR_CODE_DATA, TRANSACTION_ID, COMPLIANCE_CHECK, etc.) - `label` string: Human-readable display label. - `value` string: The actual signature data/value. - `format` 'TEXT' | 'BASE64' | 'HEX' | 'URL' | 'UNKNOWN': Format of the value. - `source` string: Source integration (FISKALTRUST_FR, FISKALTRUST_IT, etc.) - `rawMetadata` object: Original integration-specific codes for debugging/auditing. - `folioFiscal` string: MX SAT UUID (Folio Fiscal) — populated after CFDI acceptance by Fonoa. - `satQrCode` string: MX SAT validation URL used to verify a CFDI at verificacfdi.facturaelectronica.sat.gob.mx. - `ext` object: Provider-returned extension values for the document, keyed by extension or stamp code (e.g. AR "ar-arca-doc-type", and "arca-cae-expiry" for the CAE expiry date as YYYY-MM-DD; the CAE itself is in officialId). Read-only. - `connectionId` integer: The fiscalization connection this document was dispatched through; its provider and channel are those of the connection. Read-only — a partner reporting an outcome cannot change where the document was routed, and uses this to confirm the document was addressed to it before acting on it. - `latestLinkedDocument` LatestLinkedDocument: Information about the latest document in a rectification chain - `id` string: ID of the latest linked document - `number` string: Number of the latest linked document - `createdAt` string, date-time: Creation date of the latest linked document - `kind` 'INVOICE' | 'CREDIT_NOTE' | 'RECEIPT' | 'RECTIFY_INVOICE' | 'PRO_FORMA_INVOICE' | 'REFUND_RECEIPT' | 'INVOICE_RECEIPT' | 'ADVANCE_INVOICE' | 'SETTLEMENT_INVOICE' | 'TAX_WITHHOLDING': Kind of fiscal document - `status` 'COMPLETED' | 'VOIDED' | 'PAID' | 'PENDING_INTEGRATION' | 'PARTIALLY_PAID' | 'COMPLETED_INTEGRATION' | 'FAILED_INTEGRATION' | 'CORRECTION_NEEDED' | 'CANCELED' | 'CANCEL_REQUESTED' | 'OPEN' | 'REQUESTED' | 'VOID_REQUESTED' | 'FAILED' | 'MANUALLY_RECONCILED' | 'REJECTED' | 'ACCEPTED' | 'PENDING_TRANSACTION' | 'ALLOCATED' | 'APPLIED': Status of the fiscal document - `linkedDocuments` LinkedDocument[]: List of documents linked to this fiscal document (both parent and child relationships) - `id` string: ID of the linked document - `number` string: Number of the linked document - `createdAt` string, date-time: Creation date of the linked document - `kind` 'INVOICE' | 'CREDIT_NOTE' | 'RECEIPT' | 'RECTIFY_INVOICE' | 'PRO_FORMA_INVOICE' | 'REFUND_RECEIPT' | 'INVOICE_RECEIPT' | 'ADVANCE_INVOICE' | 'SETTLEMENT_INVOICE' | 'TAX_WITHHOLDING': Kind of fiscal document - `status` 'COMPLETED' | 'VOIDED' | 'PAID' | 'PENDING_INTEGRATION' | 'PARTIALLY_PAID' | 'COMPLETED_INTEGRATION' | 'FAILED_INTEGRATION' | 'CORRECTION_NEEDED' | 'CANCELED' | 'CANCEL_REQUESTED' | 'OPEN' | 'REQUESTED' | 'VOID_REQUESTED' | 'FAILED' | 'MANUALLY_RECONCILED' | 'REJECTED' | 'ACCEPTED' | 'PENDING_TRANSACTION' | 'ALLOCATED' | 'APPLIED': Status of the fiscal document - `isLatest` boolean: Whether this is the latest document in the chain - `relationshipType` 'PARENT' | 'CHILD' | 'REPLACED' | 'REPLACED_BY': PARENT means this document is linked to the current document, CHILD means the current document is linked to this one. REPLACED and REPLACED_BY are the two sides of a replacement: on an invoice, REPLACED names a receipt it withdrew — one that already declared the same charges and was voided when the invoice was issued; on that receipt, REPLACED_BY names the invoice that withdrew it. A client that presents the two differently should read this field; one that lists related documents plainly needs no change. - `actions` Action[]: Returns the list of actions available for the transaction - `type` 'CANCEL' | 'RECTIFY' | 'DOWNLOAD' | 'CREDIT_NOTE' | 'VOID_AND_CREDIT_NOTE' | 'VOID' | 'VOID_AND_REFUND' | 'ADD_PAYMENT' | 'APPLY_TO_INVOICE' | 'GENERATE_SETTLEMENT': Action that can be performed on a fiscal document - `fields` FieldDefinition[]: Action-specific input fields the UI must collect before submitting. Uses the same FieldDefinition schema as /fiscalization/rules. - `path` string, required: Field path (e.g., "name", "tax_id.code", "addresses") - `label` string, required: Display label for the field - `type` 'text' | 'email' | 'password' | 'file' | 'select' | 'boolean' | 'array' | 'object', required: Field input type - `category` 'company' | 'tax' | 'address' | 'contact' | 'supplementary' | 'custom': Field grouping category - `sectionKey` string: Key of the RulesSection that hosts this field. Defaults to "registration" when absent. Nested fields inside arrays/objects inherit the parent's section and should omit this attribute. - `required` boolean, required: Whether field is required - `requiredIf` FieldCondition - `field` string, required: Path of the sibling field whose value is tested (e.g. "taxId"). - `pattern` string, required: Regex applied to the referenced field's value. The owning field is required only when the referenced value matches this pattern. - `primary` boolean: Indicates primary tax ID field - `editable` boolean: Whether this field can still be edited once the property is a connected provider. Defaults to false; the registration email and any country-specific editable fields (e.g. Croatia's Business Premises Code and POS Device Code) are true. - `validation` FieldValidation - `pattern` string: Regex pattern for validation - `min` integer: Minimum length or items - `max` integer: Maximum length - `checksum` boolean: Whether field has checksum validation - `format` string: Display format mask (e.g., XX.XXX.XXX/XXXX-XX) - `message` string: Human-readable description of the rule, suitable for FE error messages (e.g. "NFS-e series must be 1-5 alphanumeric characters"). - `example` string: A valid example value that can be shown as a placeholder hint (e.g. "ABC12" for NFS-e, "1" for NFC-e). - `data` FieldData - `placeholder` string: Input placeholder text - `help` string: Help text for the field - `alternatives` string[]: Alternative accepted formats (e.g., CPF for CNPJ fields) - `options` SelectOption[] - `value` string, required - `label` string, required - `item` ArrayItemDefinition - `type` 'object', required - `fields` FieldDefinition[], required - `properties` object: Object properties for object type fields - `default` union - string - boolean - number - `description` string: Field description - `sourceIdentifier` string: Reservation Identifier or a group code - `simplified` boolean: Applies to invoices only. - `requireAttention` boolean: Indicates whether this document requires manual attention. - `hasDiscrepancies` boolean: Indicates whether this document has pending transaction discrepancies. - `packageBreakdown` boolean, nullable: Per-document override for package breakdown. Null means use property default. - `vatDisplay` 'PER_LINE' | 'SUMMARY_ONLY' - `currency` string, nullable: Currency the document amount is expressed in. Equals the invoice/document currency, which may differ from the property base currency when a foreign-currency invoice was issued. - `propertyCurrency` string, nullable: The property's base currency code. - `propertyCurrencyAmount` number, nullable: The document amount converted to the property's base currency using the property's configured exchange rates. Null when the document currency already equals the property base currency (no conversion needed). - `nextPageToken` string: Token for fetching the next page of results --- [API](https://skmtc.dev/cloudbeds/apis/fiscal-document-service-api.md) - [All operations](https://skmtc.dev/cloudbeds/apis/fiscal-document-service-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cloudbeds/apis/fiscal-document-service-api/revisions/9c2a47775e5e?raw)