Create a rectifying invoice
Issue rectificativas through the same create endpoint: correct an invoice by differences or substitution, whether the original was issued through Finseed or elsewhere.
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:differencesrecords only the delta. Theline_itemsare the change (usually negative lines to reduce, positive to add).substitutionrestates the invoice in full. Theline_itemsare the complete replacement.
invoice_id— an invoice issued through Finseed, by its opaqueinv_id. This is a linked rectificativa: it inherits the recipient from the corrected invoice, so on adifferencesyou omit the recipient entirely, and on asubstitutionyou may supply arecipientblock 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 fullrecipient, and asubstitutionrequiresrectified_amounts(the base, tax and optional surcharge of the original, which the tax agency needs and Finseed cannot infer).
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:recipient block restates the recipient on the replacement:
rectified_amounts. The amounts are the original’s base and tax in cents:
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
API key sent as a bearer token in the Authorization header.
Encabezados
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
The invoice to issue.
- Option 1
- Option 2
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.
The lines to bill. At least one.
1 - 500 elementsA 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.
"complete"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.
"ns_clx456def789"
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.
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.
^(\d{4})-(\d{2})-(\d{2})$"2025-06-15"
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.
false
Free-form text printed at the bottom of the invoice PDF.
2000"Pago a 30 días."
The identified recipient of a complete invoice.
Respuesta
The issued invoice.
A tax invoice as exposed by the public API.
Opaque, prefixed invoice identifier.
"inv_clx123abc456"
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.
"issued"
Human-readable invoice number.
"2026-000123"
Lowercase ISO 4217 currency code.
"eur"
Net total before tax, in minor units (cents) of the currency.
8300
Total tax, in minor units (cents) of the currency.
1743
Gross total including tax, in minor units (cents) of the currency. Always equals subtotal + tax.
10043
Fiscal name of the invoice recipient (company or person), or null when none is recorded.
"ACME, S.L."
Tax identifier of the recipient (e.g. NIF/CIF), or null when none is recorded.
"B12345678"
Recipient email, or null when none is recorded.
"cliente@example.com"
Customer identifier from the originating integration, or null when unavailable.
"cus_9aZ"
Invoice issue date, RFC 3339 in UTC.
"2026-06-01T09:30:00Z"
Date the underlying operation took place, RFC 3339 in UTC. Often equal to invoice_date.
"2026-06-01T09:30:00Z"
Creation timestamp, RFC 3339 in UTC.
"2026-06-01T09:30:00Z"
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.
"complete"
Identifier of the number series the invoice was issued on. See the Number Series resource.
"ns_clx456def789"
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.
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.
"https://api.finseed.es/v1/invoices/inv_clx123abc456/file?token=..."
Verifactu artifacts and AEAT registration state. Null only for legacy invoices imported before Verifactu tracking existed.
The lines that make up the invoice.
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.
"original"
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 } }).
- Option 1
- Option 2
The rectifying invoices that correct this invoice, one { invoice_id } entry each. Empty when nothing rectifies it. Voided rectificativas are excluded.