> ## Documentation Index > Fetch the complete documentation index at: https://www.finseed.es/docs/llms.txt > Use this file to discover all available pages before exploring further. # List invoices > Returns a cursor-paginated list of invoices for the environment the API key belongs to, most recent first. Use the optional filters to narrow the result, and follow `next_url` to page through the rest. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/invoices openapi: 3.1.0 info: title: Finseed API version: 1.0.0 description: >- REST API for programmatic Verifactu invoicing. Every request is sent over HTTPS and authenticated with an API key passed as a bearer token. Each key is scoped to a single environment (test or live). Payloads are JSON with snake_case fields: amounts are integer minor units (cents) and timestamps are RFC 3339 in UTC. List endpoints are cursor-paginated. Errors return a small application/json envelope with a stable, machine-readable `code`. servers: - url: https://api.finseed.es security: - bearerAuth: [] paths: /v1/invoices: get: tags: - Invoices summary: List invoices description: >- Returns a cursor-paginated list of invoices for the environment the API key belongs to, most recent first. Use the optional filters to narrow the result, and follow `next_url` to page through the rest. operationId: listInvoices parameters: - name: limit in: query required: false description: Maximum number of invoices to return (1–100). schema: default: 25 description: Maximum number of invoices to return (1-100). example: 25 type: integer minimum: 1 maximum: 100 - name: starting_after in: query required: false description: 'Opaque cursor: return invoices after this invoice id.' schema: description: 'Cursor: return invoices after this invoice id.' example: inv_clx123abc456 type: string - name: external_customer_id in: query required: false description: Filter to invoices for this external customer id (exact). schema: description: Filter to invoices for this external customer id (exact). example: cus_9aZ type: string - name: email in: query required: false description: >- Filter to invoices with this recipient email (exact, case-insensitive). schema: description: >- Filter to invoices with this recipient email (exact, case-insensitive). example: cliente@example.com type: string - name: number in: query required: false description: >- Filter to the invoice with this human-readable number (exact, case-insensitive). schema: description: >- Filter to the invoice with this human-readable number (exact, case-insensitive). example: 2026-000123 type: string responses: '200': description: A cursor-paginated page of invoices. content: application/json: schema: $ref: '#/components/schemas/InvoiceList' '400': description: >- The request was rejected during validation. The `errors` array lists each failing field with a reason, so you can map the failure back to a specific parameter. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: code: invalid_request detail: >- The request is not valid. A parameter is missing, malformed, or out of range. See the `errors` array for the fields that failed. errors: [] doc_url: >- https://www.finseed.es/docs/api-reference/errors#invalid_request '401': description: >- Authentication failed: the API key is missing, malformed, or revoked. Send a valid key as a bearer token in the `Authorization` header. Each key is bound to a single environment (test or live). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: code: unauthorized detail: >- Authentication failed. Send your API key as a bearer token in the `Authorization` header. Keys are scoped to one environment, so a test key cannot read live data and vice versa. errors: [] doc_url: https://www.finseed.es/docs/api-reference/errors#unauthorized '500': description: >- An unexpected error occurred on our side. No partial work is persisted, so the request can be retried safely. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: code: internal_error detail: >- Something went wrong on our side. The request did not complete and can be retried safely. errors: [] doc_url: >- https://www.finseed.es/docs/api-reference/errors#internal_error components: schemas: InvoiceList: type: object properties: data: type: array items: $ref: '#/components/schemas/Invoice' has_more: type: boolean description: Whether more invoices exist beyond this page. example: true next_cursor: anyOf: - type: string - type: 'null' description: >- Cursor to pass back as starting_after for the next page, or null on the last page. example: inv_clx123abc456 next_url: anyOf: - type: string - type: 'null' description: >- Relative path to the next page, preserving the current filters, or null on the last page. example: /v1/invoices?limit=25&starting_after=inv_clx123abc456 required: - data - has_more - next_cursor - next_url additionalProperties: false description: A cursor-paginated page of invoices. ErrorEnvelope: type: object properties: code: type: string description: >- Stable, machine-readable error code. The branch key. This is an extensible enum: new values may be added in the future, so clients must tolerate values not listed here. Known values: invalid_request, unauthorized, invoice_not_found, download_link_expired, number_series_not_found, number_series_prefix_taken, number_series_in_use, customer_not_found, customer_ambiguous, idempotency_conflict, rate_limited, invalid_number_series, invalid_tax_rate, invalid_tax_data, invalid_tax_id, tax_id_type_country_mismatch, insufficient_recipient_data, simplified_amount_exceeded, simplified_incompatible_tax_type, invalid_recargo_equivalencia, aeat_mandate_not_approved, no_active_subscription, tax_id_validation_unavailable, invalid_rectifies_reference, rectified_invoice_not_found, invoice_already_voided, invoice_already_replaced, invoice_not_family_tip, invoice_pending_at_aeat, invoice_not_rectifiable_at_aeat, family_balance_below_zero, replacement_total_negative, reason_incompatible_with_recipient, recipient_overrides_not_allowed_for_differences, rectifying_series_invalid, external_reference_invalid, external_reference_matches_existing_invoice, rectified_amounts_required_for_substitution, line_item_without_tax_items, internal_error. example: invalid_request detail: type: string description: Human-readable, context-specific explanation. example: The query parameters are not valid. errors: type: array items: type: object properties: field: type: string description: Location of the offending value (JSON path). example: limit code: type: string description: Machine-readable validation issue code. example: too_big message: type: string description: Human-readable explanation of the field-level issue. example: Number must be less than or equal to 100 required: - field - code - message additionalProperties: false description: >- Field-level issues. Always present; empty unless this is a validation failure. doc_url: type: string description: Link to the reference documentation for this error code. example: https://www.finseed.es/docs/api-reference/errors#invalid_request required: - code - detail - errors - doc_url additionalProperties: false description: >- Uniform error body returned for every non-2xx response (application/json). Invoice: type: object properties: id: type: string description: Opaque, prefixed invoice identifier. example: inv_clx123abc456 status: type: string description: >- Lifecycle status of the invoice. This is an extensible enum: new values may be added in the future, so clients must tolerate values not listed here. Known values: issued, voided. example: issued number: type: string description: Human-readable invoice number. example: 2026-000123 currency: type: string description: Lowercase ISO 4217 currency code. example: eur subtotal: type: integer description: Net total before tax, in minor units (cents) of the currency. example: 8300 tax: type: integer description: Total tax, in minor units (cents) of the currency. example: 1743 total: type: integer description: >- Gross total including tax, in minor units (cents) of the currency. Always equals subtotal + tax. example: 10043 recipient_name: anyOf: - type: string - type: 'null' description: >- Fiscal name of the invoice recipient (company or person), or null when none is recorded. example: ACME, S.L. recipient_tax_id: anyOf: - type: string - type: 'null' description: >- Tax identifier of the recipient (e.g. NIF/CIF), or null when none is recorded. example: B12345678 email: anyOf: - type: string - type: 'null' description: Recipient email, or null when none is recorded. example: cliente@example.com external_customer_id: anyOf: - type: string - type: 'null' description: >- Customer identifier from the originating integration, or null when unavailable. example: cus_9aZ invoice_date: type: string description: Invoice issue date, RFC 3339 in UTC. example: '2026-06-01T09:30:00Z' operation_date: type: string description: >- Date the underlying operation took place, RFC 3339 in UTC. Often equal to invoice_date. example: '2026-06-01T09:30:00Z' created_at: type: string description: Creation timestamp, RFC 3339 in UTC. example: '2026-06-01T09:30:00Z' type: type: string description: >- Whether this is a complete invoice (identified recipient) or a simplified invoice (ticket). This is an extensible enum: new values may be added in the future, so clients must tolerate values not listed here. Known values: complete, simplified. example: complete number_series_id: type: string description: >- Identifier of the number series the invoice was issued on. See the Number Series resource. example: ns_clx456def789 recipient: anyOf: - $ref: '#/components/schemas/InvoiceRecipient' - type: 'null' description: >- Full recipient block as recorded on the document, or null when no recipient data exists (simplified invoices). The flat recipient_name/recipient_tax_id/email fields remain as convenience aliases. pdf_url: type: string description: >- Signed link to the invoice PDF, valid for at least 24 hours from the moment this response was produced. Fetch a fresh one anytime by re-reading the invoice, or use the download endpoint. The PDF is generated shortly after creation; downloading earlier just takes a moment longer. example: https://api.finseed.es/v1/invoices/inv_clx123abc456/file?token=... verifactu: anyOf: - $ref: '#/components/schemas/InvoiceVerifactu' - type: 'null' description: >- Verifactu artifacts and AEAT registration state. Null only for legacy invoices imported before Verifactu tracking existed. line_items: type: array items: $ref: '#/components/schemas/InvoiceLineItem' description: The lines that make up the invoice. kind: type: string description: >- Whether this is an original invoice or a rectifying (corrective) one, and by which method. `rectifying_differences` corrects by the delta; `rectifying_substitution` replaces the original in full. This is an extensible enum: new values may be added in the future, so clients must tolerate values not listed here. Known values: original, rectifying_differences, rectifying_substitution. example: original rectifies: type: array items: $ref: '#/components/schemas/InvoiceRectifiedReference' description: >- The invoices this invoice rectifies. Empty for originals. A rectificativa issued against invoices in Finseed carries one `{ invoice_id }` entry per corrected invoice; one issued against an external original carries a single `{ external: { number, issued_on } }` entry. rectified_by: type: array items: $ref: '#/components/schemas/InvoiceReference' description: >- The rectifying invoices that correct this invoice, one `{ invoice_id }` entry each. Empty when nothing rectifies it. Voided rectificativas are excluded. required: - id - status - number - currency - subtotal - tax - total - recipient_name - recipient_tax_id - email - external_customer_id - invoice_date - operation_date - created_at - type - number_series_id - recipient - pdf_url - verifactu - line_items - kind - rectifies - rectified_by additionalProperties: false description: A tax invoice as exposed by the public API. example: id: inv_clx123abc456 status: issued number: 2026-000123 currency: eur subtotal: 8300 tax: 1743 total: 10043 recipient_name: ACME, S.L. recipient_tax_id: B12345678 email: cliente@example.com external_customer_id: cus_9aZ invoice_date: '2026-06-01T09:30:00Z' operation_date: '2026-06-01T09:30:00Z' created_at: '2026-06-01T09:30:00Z' type: complete number_series_id: ns_clx456def789 recipient: name: ACME, S.L. company_name: null tax_id: B12345678 tax_id_type: es_nif tax_id_country: ES email: cliente@example.com address: line1: Calle Mayor 1 line2: null postal_code: '28001' city: Madrid country: ES pdf_url: https://api.finseed.es/v1/invoices/inv_clx123abc456/file?token=abc verifactu: status: registered hash: B11F3A0151ADA655A9A0A4A64F32F440BE0EE0F5A695BB2E4DC5C0C0AF6E8D2A qr_url: >- https://www2.agenciatributaria.gob.es/wlpl/TIKE-CONT/ValidarQR?nif=B12345678&numserie=2026-000123&fecha=01-06-2026&importe=100.43 error: null line_items: - id: ili_clx789def012 description: Consulting services sku: SVC-01 quantity: 2 unit_amount: 4150 subtotal: 8300 tax: 1743 total: 10043 tax_items: - name: IVA 21% type: vat rate: 21 amount: 1743 kind: original rectifies: [] rectified_by: [] InvoiceRecipient: type: object properties: name: anyOf: - type: string - type: 'null' description: >- Name of the recipient (person or business), or null when none is recorded. example: ACME, S.L. company_name: anyOf: - type: string - type: 'null' description: Company name when it was recorded separately from `name`, or null. example: null tax_id: anyOf: - type: string - type: 'null' description: Tax identifier (e.g. NIF/CIF), or null. example: B12345678 tax_id_type: anyOf: - type: string - type: 'null' description: >- Kind of tax identifier, or null when none is recorded. This is an extensible enum: new values may be added in the future, so clients must tolerate values not listed here. Known values: es_nif, eu_vat, passport, official_document, residence_certificate, other, not_registered. example: es_nif tax_id_country: anyOf: - type: string - type: 'null' description: ISO 3166-1 alpha-2 country the tax id belongs to, or null. example: ES email: anyOf: - type: string - type: 'null' description: Recipient email, or null. example: cliente@example.com address: anyOf: - $ref: '#/components/schemas/InvoiceRecipientAddress' - type: 'null' description: Postal address, or null when no address field is recorded. required: - name - company_name - tax_id - tax_id_type - tax_id_country - email - address additionalProperties: false description: >- The invoice recipient as recorded on the document. Null on simplified invoices without any recipient data. InvoiceVerifactu: type: object properties: status: type: string description: >- AEAT registration status. `pending` means the record is queued for submission; `registered` means AEAT accepted it; `registered_with_errors` means AEAT accepted it but flagged issues that need a correction; `rejected` means AEAT refused it; `skipped` means the record was deliberately never submitted. Registration is asynchronous: poll the invoice until it leaves `pending`. This is an extensible enum: new values may be added in the future, so clients must tolerate values not listed here. Known values: pending, registered, registered_with_errors, rejected, skipped. example: registered hash: type: string description: >- Chained Verifactu fingerprint (huella) of the invoice record, computed at issue time. Part of the legal record; safe to archive. example: B11F3A0151ADA655A9A0A4A64F32F440BE0EE0F5A695BB2E4DC5C0C0AF6E8D2A qr_url: type: string description: >- AEAT verification URL encoded in the invoice QR. Encode this URL as a QR code if you render your own documents; the PDF from this API already includes it. Test-environment invoices point at a simulator instead of AEAT. example: >- https://www2.agenciatributaria.gob.es/wlpl/TIKE-CONT/ValidarQR?nif=B12345678&numserie=F-000123&fecha=01-06-2026&importe=100.43 error: anyOf: - $ref: '#/components/schemas/InvoiceVerifactuError' - type: 'null' description: >- Present when `status` is `registered_with_errors` or `rejected` and the tax agency reported a reason; null otherwise. required: - status - hash - qr_url - error additionalProperties: false description: Verifactu artifacts and AEAT registration state of the invoice. InvoiceLineItem: type: object properties: id: type: string description: Opaque, prefixed line-item identifier. example: ili_clx789def012 description: type: string description: Description of the goods or service. example: Consulting services sku: anyOf: - type: string - type: 'null' description: Stock-keeping unit, or null when none is recorded. example: SVC-01 quantity: type: integer description: Number of units billed on this line. example: 2 unit_amount: type: integer description: Net price of a single unit before tax, in minor units (cents). example: 4150 subtotal: type: integer description: Net total for this line before tax, in minor units (cents). example: 8300 tax: type: integer description: Tax total for this line, in minor units (cents). example: 1743 total: type: integer description: Gross total for this line including tax, in minor units (cents). example: 10043 tax_items: type: array items: $ref: '#/components/schemas/InvoiceTaxItem' description: The taxes applied to this line, broken down by category. required: - id - description - sku - quantity - unit_amount - subtotal - tax - total - tax_items additionalProperties: false description: A single line on an invoice. InvoiceRectifiedReference: anyOf: - $ref: '#/components/schemas/InvoiceReference' - $ref: '#/components/schemas/InvoiceExternalReference' description: >- An invoice a rectificativa corrects: either a local invoice (`{ invoice_id }`) or an external original (`{ external: { number, issued_on } }`). InvoiceReference: type: object properties: invoice_id: type: string description: Opaque, prefixed identifier of the referenced invoice. example: inv_clx123abc456 required: - invoice_id additionalProperties: false description: A reference to another invoice by its opaque id. InvoiceRecipientAddress: type: object properties: line1: anyOf: - type: string - type: 'null' description: Street address, or null when none is recorded. example: Calle Mayor 1 line2: anyOf: - type: string - type: 'null' description: Additional address line, or null. example: null postal_code: anyOf: - type: string - type: 'null' description: Postal code, or null. example: '28001' city: anyOf: - type: string - type: 'null' description: City, or null. example: Madrid country: anyOf: - type: string - type: 'null' description: ISO 3166-1 alpha-2 country code, or null. example: ES required: - line1 - line2 - postal_code - city - country additionalProperties: false description: Postal address of the invoice recipient. InvoiceVerifactuError: type: object properties: code: anyOf: - type: string - type: 'null' description: >- Error code reported by the tax agency (AEAT), verbatim, or null when only a message is available. example: '1142' message: anyOf: - type: string - type: 'null' description: >- Error message reported by the tax agency, verbatim (Spanish), or null. example: El NIF del destinatario no está identificado en el censo de la AEAT. required: - code - message additionalProperties: false description: The tax-agency error behind a problematic registration. InvoiceTaxItem: type: object properties: name: type: string description: >- Human-readable tax label as it appears on the invoice, e.g. "IVA 21%". example: IVA 21% type: type: string description: >- Tax category this line is subject to. This is an extensible enum: new values may be added in the future, so clients must tolerate values not listed here. Known values: vat, igic, ipsi, es_recargo_equivalencia, es_exempt, es_inversion_sujeto_pasivo, es_non_taxable, es_non_taxable_localization, eu_oss, eu_b2b, eu_b2b_services, export, other. example: vat rate: type: number description: >- Tax rate as a percentage. For example 21 means 21%, and 10.5 means 10.5%. Zero for exempt or non-taxable lines. example: 21 amount: type: integer description: >- Tax charged for this line, in minor units (cents) of the invoice currency. example: 1743 required: - name - type - rate - amount additionalProperties: false description: A single tax applied to an invoice line. InvoiceExternalReference: type: object properties: external: type: object properties: number: type: string description: Invoice number of the external original, as recorded. example: F-2025-091 issued_on: type: string description: >- Issue date of the external original, as a plain calendar date (YYYY-MM-DD). example: '2025-03-14' required: - number - issued_on additionalProperties: false description: >- The external original this invoice rectifies, identified by its number and issue date because it was not issued through Finseed. required: - external additionalProperties: false description: >- A reference to an invoice that lives outside Finseed (e.g. a pre-Finseed original a migrated merchant rectifies). securitySchemes: bearerAuth: type: http scheme: bearer description: API key sent as a bearer token in the `Authorization` header. ````