Skip to main content
POST
Create an invoice
Alpha endpointThis endpoint is in alpha. Request and response shapes, error codes, and behavior may still change without notice. Avoid relying on it for production traffic until it is announced as stable.
A rectificativa (corrective invoice) is issued through the same POST /v1/invoices endpoint as an ordinary invoice: add a rectifies block. A rectificativa is a real invoice — its own number from a rectifying series, its own Verifactu record and hash, its own PDF — so the response is the full invoice object, with kind set to rectifying_differences or rectifying_substitution and rectifies[] pointing at the corrected original.

Choosing method and reference

Method decides how the correction books:
  • differences records only the delta. The line_items are the change (usually negative lines to reduce, positive to add).
  • substitution restates the invoice in full. The line_items are the complete replacement.
Reference names the original with exactly one of:
  • invoice_id — an invoice issued through Finseed, by its opaque inv_ id. This is a linked rectificativa: it inherits the recipient from the corrected invoice, so on a differences you omit the recipient entirely, and on a substitution you may supply a recipient block to restate it.
  • external — an invoice issued elsewhere (a pre-Finseed original a migrated merchant corrects). This is an external rectificativa: because there is no original in Finseed, a complete invoice requires a full recipient, and a substitution requires rectified_amounts (the base, tax and optional surcharge of the original, which the tax agency needs and Finseed cannot infer).
Sending both invoice_id and external, or neither, is rejected with invalid_rectifies_reference. Reason (reason) encodes the cause in the AEAT R1-R4 code. It defaults to correction (R1). Use insolvency (R2) for concurso, uncollectible (R3) for créditos incobrables, or other (R4). Simplified rectificativas always register as R5. The number_series_id, when supplied, must name a rectifying series (unlike an ordinary invoice, which uses a standard series). Omit it to use the environment’s default rectifying series.

Examples

Partial refund by differences against a Finseed invoice (linked). The recipient is inherited from the corrected invoice:
Full substitution with a corrected recipient (linked). The recipient block restates the recipient on the replacement:
Differences against a pre-Finseed original (external). A complete invoice requires the recipient:
Substitution of a pre-Finseed original (external) with rectified_amounts. The amounts are the original’s base and tax in cents:
Simplified rectificativa (a corrected ticket) against an external original. No recipient is required:

Dry-running and errors

POST /v1/invoices/validate accepts the same rectifies block and runs the identical checks without persisting anything, returning the totals the rectificativa would carry. Every corrective rule surfaces as a stable error code — for example invoice_pending_at_aeat when the original has not finished registering, invoice_not_family_tip when a later rectificativa already supersedes it, or rectified_amounts_required_for_substitution on an external substitution. See Errors for the full list.

Autorizaciones

Authorization
string
header
requerido

API key sent as a bearer token in the Authorization header.

Encabezados

Idempotency-Key
string

Optional key that makes the request safe to retry: 1 to 255 printable ASCII characters. Sending the same key with the same body within 24 hours returns the stored response instead of executing again; such a replay carries an Idempotent-Replayed: true header. Reusing a key with a different body is rejected.

Cuerpo

application/json

The invoice to issue.

The invoice to issue. The invoice number, issue date and totals are assigned server-side; the optional operation_date is the only date the caller sets. Issuance is immediate and the AEAT registration progresses asynchronously (poll verifactu.status). Include a rectifies block to issue a rectificativa instead of an ordinary invoice.

line_items
object[]
requerido

The lines to bill. At least one.

Required array length: 1 - 500 elements
type
string
requerido

A complete invoice: the recipient is identified and their tax id is validated against the census. On a linked rectificativa (a rectifies.invoice_id) the recipient is inherited from the corrected invoice and may be omitted; when supplied on a substitution it restates the recipient.

Allowed value: "complete"
number_series_id
string

Number series to issue on (see the Number Series resource). Defaults to the environment default series. For an ordinary invoice this must be a standard series; for a rectificativa (a rectifies block) it must be a rectifying series.

Ejemplo:

"ns_clx456def789"

rectifies
object

Turns this request into a rectificativa (corrective invoice). Reference the original with exactly one of invoice_id (issued through Finseed) or external (issued elsewhere). Omit the whole block to issue an ordinary invoice.

operation_date
string

Date the underlying operation took place, as a calendar day (YYYY-MM-DD) interpreted in the Europe/Madrid timezone. Must be an existing calendar day between 2025-01-01 and today. When omitted, or when it equals the issue date, the invoice carries the issue date as its operation date. Not supported together with a rectifies block.

Pattern: ^(\d{4})-(\d{2})-(\d{2})$
Ejemplo:

"2025-06-15"

recargo_equivalencia
boolean

Applies the Spanish recargo de equivalencia regime: every VAT line gains its legally paired surcharge (21%→5.2%, 10%→1.4%, 4%→0.5%), computed server-side.

Ejemplo:

false

Free-form text printed at the bottom of the invoice PDF.

Maximum string length: 2000
Ejemplo:

"Pago a 30 días."

recipient
object

The identified recipient of a complete invoice.

Respuesta

The issued invoice.

A tax invoice as exposed by the public API.

id
string
requerido

Opaque, prefixed invoice identifier.

Ejemplo:

"inv_clx123abc456"

status
string
requerido

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.

Ejemplo:

"issued"

number
string
requerido

Human-readable invoice number.

Ejemplo:

"2026-000123"

currency
string
requerido

Lowercase ISO 4217 currency code.

Ejemplo:

"eur"

subtotal
integer
requerido

Net total before tax, in minor units (cents) of the currency.

Ejemplo:

8300

tax
integer
requerido

Total tax, in minor units (cents) of the currency.

Ejemplo:

1743

total
integer
requerido

Gross total including tax, in minor units (cents) of the currency. Always equals subtotal + tax.

Ejemplo:

10043

recipient_name
string | null
requerido

Fiscal name of the invoice recipient (company or person), or null when none is recorded.

Ejemplo:

"ACME, S.L."

recipient_tax_id
string | null
requerido

Tax identifier of the recipient (e.g. NIF/CIF), or null when none is recorded.

Ejemplo:

"B12345678"

email
string | null
requerido

Recipient email, or null when none is recorded.

Ejemplo:

"cliente@example.com"

external_customer_id
string | null
requerido

Customer identifier from the originating integration, or null when unavailable.

Ejemplo:

"cus_9aZ"

invoice_date
string
requerido

Invoice issue date, RFC 3339 in UTC.

Ejemplo:

"2026-06-01T09:30:00Z"

operation_date
string
requerido

Date the underlying operation took place, RFC 3339 in UTC. Often equal to invoice_date.

Ejemplo:

"2026-06-01T09:30:00Z"

created_at
string
requerido

Creation timestamp, RFC 3339 in UTC.

Ejemplo:

"2026-06-01T09:30:00Z"

type
string
requerido

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.

Ejemplo:

"complete"

number_series_id
string
requerido

Identifier of the number series the invoice was issued on. See the Number Series resource.

Ejemplo:

"ns_clx456def789"

recipient
object | null
requerido

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
string
requerido

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.

Ejemplo:

"https://api.finseed.es/v1/invoices/inv_clx123abc456/file?token=..."

verifactu
object | null
requerido

Verifactu artifacts and AEAT registration state. Null only for legacy invoices imported before Verifactu tracking existed.

line_items
object[]
requerido

The lines that make up the invoice.

kind
string
requerido

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.

Ejemplo:

"original"

rectifies
object[]
requerido

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.

An invoice a rectificativa corrects: either a local invoice ({ invoice_id }) or an external original ({ external: { number, issued_on } }).

rectified_by
object[]
requerido

The rectifying invoices that correct this invoice, one { invoice_id } entry each. Empty when nothing rectifies it. Voided rectificativas are excluded.