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 contacts 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 contacts. 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 canonical UNECE unit in which a product and its stock are measured (C62, KGM, GRM, LTR, MLT, MTR, MTK, HUR or DAY).
Presentation
A commercial package or measure. fixed multiplies by a conversion factor; variable_measure requires the real base quantity on each line. It never owns stock.
Variant
A product identity with optional SKU/barcode and price/cost overrides. It may own stock or delegate movements to the base product.
Supplier offer
Purchase conditions for a product/variant: supplier, purchase unit, conversion, availability, cost and lead time. It never changes the sales price.
Price list
A tenant-scoped set of explicit EUR prices for product/variant/presentation targets, assignable to clients and draft documents.
Catalog snapshot
The immutable product, quantity and price context copied onto a document line so later catalog edits cannot rewrite history.
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.
The automation engine turns an event into work. Its
vocabulary is the one the rule editor shows in Spanish, and two of its enum
values are Spanish literals you meet in the API. Everything here is gated behind
the automations module.
Term
Definition
Automatización (automation rule)
A rule with three moving pieces: the event it listens to (trigger_type), the condition that decides whether a given event is its case (conditions), and the ordered actions that run (actions). A new rule is born draft and hears nothing until you activate it. See Automations.
Disparador (trigger)
The event type a rule listens to, in resource.action form (invoice.paid). Ask GET /v1/automations/catalog for the triggers your company can subscribe to — already filtered by the modules your plan includes — and a second call for the evaluable fields of the one you picked.
Ensayo (dry run)
What a rule would do against a sample event (POST /v1/automations/rules/{rule}/dry_run). It materialises nothing: no e-mail, no webhook delivery, no mutation, no run row, and it consumes neither the monthly budget nor the engine's frequency limit.
Ejecución (run)
What an admitted event produces. It freezes the definition it executed (rule_version + rule_snapshot) and the payload of the triggering event, so a run stays readable after the rule has moved on. blocked — stopped by an engine limit before executing — is not failed.
Paso (step)
One action of the frozen definition, identified by its zero-based step_index. Steps always come back in execution order, each with its action_type, its frozen parameters, the result its adapter returned and a replayable flag.
Versión sellada (sealed version)
Editing a rule never rewrites its previous definition: it seals a new version and bumps current_version. Every run points at the exact version it executed, which can lag behind the current one — and that is the point.
Relanzamiento (replay)
Rearming parked work, a whole run or a single step. It executes for real — it sends e-mail, delivers webhooks and calls third parties — and it carries x-irreversible in the spec. Only steps parked with a replayable reason are rearmed.
Alcance empresa / cartera (rule scope)
Which companies a rule watches, in its optional scope field. The two values are Spanish literals: empresa (the default) watches the company that owns the rule; cartera watches every client company an accounting firm manages and delivers the notice to the firm. It cannot be changed once the rule exists.
Gestoría (accounting firm)
The Spanish firm that keeps other companies' books. Its cartera rules accept only the four notifying action types — the other four would take a document of the managed company as their subject — and each run names the company it acted upon in subject_company.
discard_reason_label
The human label of a typed discard_reason (condition_not_matched, rate_limit_exceeded…), always in Spanish: it belongs to the vocabulary of the engine and does not follow Accept-Language. Branch on discard_reason, which is a closed catalog, never on its label.
A store is a company’s configured ecommerce shop, identified by its public UUID. A provider connection is the authorization behind integration_id. An order has the provider’s opaque external_id. Invoice channel describes the origin and source_store_id points to the source store. In public order events, the store identifier is specifically data.store.uuid; keep that wire-format key unchanged.
