> ## 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. # Retrieve an invoice > Returns a single invoice by id, in the same shape as each row of the list endpoint. The invoice must belong to the environment the API key belongs to, otherwise the response is a 404. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/invoices/{id} 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/{id}: get: tags: - Invoices summary: Retrieve an invoice description: >- Returns a single invoice by id, in the same shape as each row of the list endpoint. The invoice must belong to the environment the API key belongs to, otherwise the response is a 404. operationId: getInvoice parameters: - name: id in: path required: true description: Opaque invoice identifier — the `id` from a list row. schema: type: string responses: '200': description: The requested invoice. content: application/json: schema: $ref: '#/components/schemas/Invoice' '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 '404': description: >- No invoice matches the supplied identifier in the environment the API key belongs to. An invoice created with a live key is not visible to a test key, and vice versa. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: code: invoice_not_found detail: >- No invoice matches that identifier in this environment. Note that test and live keys see different invoices. errors: [] doc_url: >- https://www.finseed.es/docs/api-reference/errors#invoice_not_found '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: 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: [] 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). 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. ````