Spanish fiscal and domain terms used across the Factuarea API — NIF, VeriFactu, AEAT, FacturaE, Modelo 303/347, series, rectificativa, huella, CSV and more.
The Factuarea API models Spanish invoicing and tax-compliance concepts. If
you are integrating from outside Spain — or just want a precise reference —
this glossary explains the domain terms that appear in field names, enum
values and error messages, and how each maps to the API.
API error messages (error.message) are returned in Spanish because
they mirror the real API response. The type, code and subcode
fields are stable English identifiers — match on those, not on the
message text. See Errors.
The Spanish fiscal tax number. NIF (Número de Identificación Fiscal) identifies residents and companies, CIF was the legacy code for legal entities, and NIE (Número de Identidad de Extranjero) identifies foreign residents. In the API they all live in the single tax_id field on clients, suppliers and your account. For non-Spanish counterparties use alternative_id instead — it is mutually exclusive with tax_id.
VAT ID (NIF intracomunitario)
An EU intra-community VAT number, exposed as the vat_id field on clients and suppliers. Distinct from tax_id: it identifies the party for VAT-exempt intra-EU operations, not for domestic fiscal purposes.
AEAT
Agencia Estatal de Administración Tributaria — the Spanish tax agency. It is the recipient of VeriFactu records, the authority behind Modelo declarations, and the issuer of the CSV. All aeat_* fields and the /v1/verifactu/aeat-access/* endpoints relate to it.
Impuesto sobre el Valor Añadido — Spanish value-added tax. In the API it is a tax of type: "vat" in the tax catalog. Apply it per line via tax_rate_id; totals are computed by the API (subtotal + total_vat + total_surcharge − total_retention). See the Taxes section in the API Reference.
Retención (IRPF withholding)
A withholding deducted from a line and remitted to the AEAT on the recipient's behalf, typically IRPF (Impuesto sobre la Renta de las Personas Físicas) for freelancers. Modeled as a tax of type: "retention". It subtracts from the document total, unlike VAT and surcharge.
Recargo de equivalencia (equivalence surcharge)
A special VAT regime for retailers: an extra surcharge added on top of VAT so the retailer does not file VAT returns separately. Modeled as a tax of type: "surcharge"; a counterparty subject to it carries is_surcharge_subject: true. It adds to the document total.
The sequential, gap-free numbering sequence an invoice belongs to (series_id). A series is immutable per AEAT compliance — once created it cannot be edited (the PUT method returns 405). Test mode uses the sandbox company's own series and never touches your production numbering. See the Series section in the API Reference and Test mode.
Rectificativa (corrective invoice)
A corrective invoice that amends a previously issued one — the legal way to fix an invoice, since issued invoices cannot be edited or deleted. Created via POST /v1/invoices/{id}/corrective; the result is a new invoice with is_corrective: true and a corrective object, mapped to an AEAT R1–R5 type code. The code is derived from the correction_reason slug by default, but you can force it explicitly with correction_code (R1–R5): a simplified (F2) original admits only R5, a complete (F1/F3) original only R1–R4 — an incompatible code returns 422 with the legal codes in error.allowed_values. An optional justification (min:10) records the documentary trace the LIVA requires for some causes (insolvency, bad debt). Compare with annul (POST /v1/invoices/{id}/annul), which voids without amending.
Factura simplificada (simplified invoice)
A reduced-data invoice (AEAT type F2) allowed for small amounts under Real Decreto 1619/2012 art. 4, with no full recipient details. Check eligibility with POST /v1/invoices/simplified-eligibility; group several into one full substitutive invoice (type F3) with POST /v1/invoices/substitute-simplified. A full ordinary invoice is type F1.
Proforma
A non-fiscal preview invoice used to quote or request payment before issuing the real (fiscal) invoice. It carries no legal numbering and can be converted to an invoice via POST /v1/proformas/{id}/convert. Lifecycle: draft, accepted, rejected, cancelled, expired, converted.
Albarán (delivery note)
A document tracking goods delivered to a customer (the delivery_notes resource), which can later be converted to an invoice. Supports a handwritten recipient signature (base64 PNG). Public lifecycle: draft, sent, signed, invoiced, cancelled.
external_id (integration key)
An external business identifier — the record's ID in your own ERP/CRM/e-commerce — stored on a resource to map and deduplicate it across integrations. Free-format (≤ 100 chars), unique per company, and orthogonal to Factuarea's own identifiers (id, number, sku). Look a record up by it with POST /v1/{resource}/find-by-external-id (body { "external_id": "..." }). Ideal as the mapping key when migrating from another platform — see Migrate from Holded.
The Spanish anti-fraud invoicing system (SIF) under which each issued invoice generates a tamper-evident "Alta" record submitted to the AEAT. In live the record is transmitted to the AEAT; in test it is created locally but never transmitted. Managed under the /v1/verifactu/* endpoints. See Test mode.
Huella (hash chain)
The chained SHA-256 fingerprint of a VeriFactu record (huella field) that links each record to the previous one, making the sequence tamper-evident. Look up a record by it with POST /v1/verifactu/records/find-by-huella, and verify the whole chain's integrity with GET /v1/verifactu/chain/validate.
CSV (Código Seguro de Verificación)
The Secure Verification Code the AEAT returns when it accepts a VeriFactu record (the aeat_csv field; null until assigned). This is an AEAT receipt code — not a comma-separated-values file. Look up a record by it with POST /v1/verifactu/records/find-by-csv.
FacturaE
The Spanish electronic-invoice XML format (FacturaE 3.2.2) required for B2G invoicing to public administration. Download it for an invoice with GET /v1/invoices/{id}/facturae (signed XAdES-EPES when a certificate is active) and submit it to FACe via /v1/face-submissions. See FACe invoicing.
FACe
The general entry point of the Spanish public administration for electronic invoices (Ley 25/2013). Factuarea presents the signed FacturaE XML to the FACe web service and tracks the processing status (submitted → registered_rcf → accounted → paid). See FACe invoicing.
DIR3
The Spanish directory of public-administration units. Every B2G client carries three DIR3 codes — oficina contable (01), órgano gestor (02) and unidad tramitadora (03) — required by FACe, with format ^[A-Z][A-Z0-9]{8,9}$.
Declaración responsable
A formal compliance declaration (declaración responsable) that the SIF software producer — Factuarea — issues to attest VeriFactu conformity. It is producer-level and read-only (not per-company): retrieve the current one with GET /v1/verifactu/declaracion-responsable.
The quarterly Spanish VAT (IVA) self-assessment return filed with the AEAT. Generate it with POST /v1/tax_reports/303, indicating the quarter (1–4). The response includes a per-VAT-rate breakdown ({base, cuota} in cents). See the Tax reports section in the API Reference.
Modelo 347
The yearly informational return declaring third parties with whom annual operations exceeded the legal threshold. Generate it with POST /v1/tax_reports/347; it is annual and does not accept a quarter (sending one returns a validation error).
The time-tracking system covers the Spanish
working-time duty. Its terms appear in field names and enum values across the
workforce domains, all gated behind the control_horario module.
Term
Definition
RD-ley 8/2019
Royal Decree-law 8/2019 (art. 34.9 of the Workers' Statute), which obliges Spanish employers to keep an objective, reliable and unalterable daily record of every employee's working day and retain it for four years for the Labour Inspectorate (ITSS). Factuarea builds it as an append-only ledger sealed by a per-company SHA-256 hash chain — the VeriFactu tamper-evidence pattern applied to attendance. See Time tracking.
Fichaje (time entry)
Each clock event — clock in, pause, resume, clock out — appended to the immutable ledger (the time_entries resource) and never edited or deleted. The live session state (working, paused, finished) is derived from the ledger, not stored in a column. See Time clock.
Jornada (working day)
An employee's working day. It may split into several shifts (jornada partida) when the employee clocks out and back in on the same day; the expected weekly hours come from the assigned work schedule.
Registro inalterable (ledger)
The append-only, hash-chained time record. There is no update or delete: a mistake is fixed by a correction request that appends a new entry referencing the original, so both the error and its fix stay in the record. Verify its integrity with GET /v1/time-entries/chain/validate.
Cierre mensual (monthly close)
A snapshot that freezes a finished month's balances and absence breakdown and locks the period against retroactive entries (the monthly-register-closes resource). It moves closed ⇄ reopened; reopening is an audited recovery. See Monthly close.
Sellado (seal)
The optional, irreversible signature of a monthly close: a canonical SHA-256 digest plus a detached RSA-SHA256 signature made with the company certificate, so an auditor can prove the snapshot has not changed since it was signed. One seal per close — re-sealing returns 409.
Asiento de empleado (employee seat)
The billing unit for time tracking. Employees are billed through a dedicated monthly employee-seats add-on whose quantity follows the active roster; an employee never counts against the plan users limit. See Employee seat billing.
Tipo de ausencia (absence type)
What an employee can request — holiday, sick leave, a personal day — carrying whether it is paid, whether it needs approval, and a measurement unit (days or hours). A default Spanish set is seeded into every new company. See Absences.
Política de ausencia (absence policy)
The rule that decides how much and for whom: an allowance (limited days or unlimited), an accrual method (annual or monthly), the types it covers and the employees it is assigned to.
Saldo (balance)
The remaining allowance per employee and absence type, derived from the policy accrual minus approved requests (the absence-balances resource).
Presencialidad (presence)
The read-only view of who is working right now and who is in office or remote today, derived from the ledger, the schedules and the roster — never persisted. There is no presence:write scope: declaring office/remote presence is a portal-only task. See Presence.
