Core concepts
Glossary
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.
Fiscal identifiers
| Term | Definition |
|---|---|
| NIF / CIF / NIE | 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. |
Taxes
| Term | Definition |
|---|---|
| IVA (VAT) | 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. |
Documents
| Term | Definition |
|---|---|
| Serie (numbering series) | 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. 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. |
VeriFactu & AEAT compliance
| Term | Definition |
|---|---|
| VeriFactu | 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. |
Tax declarations
| Term | Definition |
|---|---|
| Modelo 303 | 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). |
Events
Read-only event objects with an opaque id. Historical query via the API and webhook delivery.
AEAT census verification
Check your company's — and your clients' — name + NIF pair against the AEAT census before issuing VeriFactu invoices — deterministic states, sandbox magic NIFs and fail-open behavior.