Termes fiscals i de domini espanyols usats a tota l'API de Factuarea — NIF, VeriFactu, AEAT, FacturaE, Modelo 303/347, sèries, rectificativa, huella, CSV i més.
L'API de Factuarea modela conceptes de facturació i compliment fiscal
espanyols. Si integres des de fora d'Espanya — o simplement vols una
referència precisa — aquest glossari explica els termes del domini que
apareixen en noms de camps, valors d'enum i missatges d'error, i com es
correspon cadascun amb l'API.
Els missatges d'error de l'API (error.message) es retornen en castellà
perquè reflecteixen la resposta real de l'API. Els camps type, code i
subcode són identificadors estables en anglès — fes match sobre aquests, no
sobre el text del missatge. Consulta Errors.
El número fiscal tributari espanyol. El NIF (Número de Identificación Fiscal) identifica residents i empreses, el CIF era el codi heretat per a persones jurídiques, i el NIE (Número de Identidad de Extranjero) identifica residents estrangers. A l'API tots resideixen en l'únic camp tax_id de clients, suppliers i el teu compte. Per a contraparts no espanyoles usa alternative_id al seu lloc — és mútuament excloent amb tax_id.
VAT ID (NIF intracomunitario)
Un número d'IVA intracomunitari de la UE, exposat com el camp vat_id a clients i suppliers. Diferent de tax_id: identifica la part per a operacions intracomunitàries exemptes d'IVA, no per a finalitats fiscals domèstiques.
AEAT
Agencia Estatal de Administración Tributaria — l'agència tributària espanyola. És la receptora dels registres VeriFactu, l'autoritat darrere de les declaracions Modelo i l'emissora del CSV. Tots els camps aeat_* i els endpoints /v1/verifactu/aeat-access/* s'hi relacionen.
Impuesto sobre el Valor Añadido — l'impost sobre el valor afegit espanyol. A l'API és un impost de type: "vat" al catàleg d'impostos. Aplica'l per línia mitjançant tax_rate_id; els totals els calcula l'API (subtotal + total_vat + total_surcharge − total_retention). Consulta la secció Taxes a l'API Reference.
Retención (IRPF withholding)
Una retenció deduïda d'una línia i remesa a l'AEAT en nom del destinatari, normalment IRPF (Impuesto sobre la Renta de las Personas Físicas) per a autònoms. Es modela com un impost de type: "retention". Resta del total del document, a diferència de l'IVA i el recàrrec.
Recargo de equivalencia (equivalence surcharge)
Un règim especial d'IVA per a minoristes: un recàrrec addicional sumat sobre l'IVA perquè el minorista no presenti declaracions d'IVA per separat. Es modela com un impost de type: "surcharge"; una contrapart subjecta a ell porta is_surcharge_subject: true. Suma al total del document.
La seqüència de numeració correlativa i sense buits a la qual pertany una factura (series_id). Una sèrie és immutable per compliment de l'AEAT — un cop creada no es pot editar (el mètode PUT retorna 405). El mode de prova usa les pròpies sèries de l'empresa sandbox i mai toca la teva numeració de producció. Consulta la secció Series a l'API Reference i Test mode.
Rectificativa (corrective invoice)
Una factura rectificativa que corregeix una d'emesa prèviament — la manera legal d'arreglar una factura, ja que les factures emeses no es poden editar ni eliminar. Es crea mitjançant POST /v1/invoices/{id}/corrective; el resultat és una factura nova amb is_corrective: true i un objecte corrective, mapejada a un codi de tipus R1–R5 de l'AEAT. El codi es deriva del slug correction_reason per defecte, però el pots forçar de manera explícita amb correction_code (R1–R5): una original simplificada (F2) només admet R5, i una original completa (F1/F3) només R1–R4 — un codi incompatible retorna 422 amb els codis legals a error.allowed_values. Una justification opcional (min:10) registra la traça documental que la LIVA exigeix per a algunes causes (concurs, incobrable). Compara-la amb anul·lar (POST /v1/invoices/{id}/annul), que anul·la sense corregir.
Factura simplificada (simplified invoice)
Una factura amb dades reduïdes (tipus F2 de l'AEAT) permesa per a imports petits sota el Real Decreto 1619/2012 art. 4, sense les dades completes del destinatari. Comprova l'elegibilitat amb POST /v1/invoices/simplified-eligibility; agrupa'n diverses en una sola factura substitutiva completa (tipus F3) amb POST /v1/invoices/substitute-simplified. Una factura ordinària completa és de tipus F1.
Proforma
Una factura proforma de previsualització no fiscal usada per pressupostar o sol·licitar el pagament abans d'emetre la factura real (fiscal). No porta numeració legal i es pot convertir en factura mitjançant POST /v1/proformas/{id}/convert. Cicle de vida: draft, accepted, rejected, cancelled, expired, converted.
Albarán (delivery note)
Un document que registra les mercaderies lliurades a un client (el recurs delivery_notes), que més tard es pot convertir en factura. Admet una signatura manuscrita del destinatari (PNG en base64). Cicle de vida públic: draft, sent, signed, invoiced, cancelled.
external_id (clau d'integració)
Un identificador de negoci extern — l'ID del registre al teu propi ERP/CRM/e-commerce — desat en un recurs per mapejar-lo i deduplicar-lo entre integracions. De format lliure (≤ 100 caràcters), únic per empresa i ortogonal als identificadors propis de Factuarea (id, number, sku). Cerca un registre per ell amb POST /v1/{recurs}/find-by-external-id (body { "external_id": "..." }). Ideal com a clau de mapeig en migrar des d'una altra plataforma — consulta Migració des de Holded.
El sistema espanyol de facturació antifrau (SIF) sota el qual cada factura emesa genera un registre "Alta" a prova de manipulacions enviat a l'AEAT. En live el registre es transmet a l'AEAT; en test es crea localment però mai es transmet. Es gestiona sota els endpoints /v1/verifactu/*. Consulta Test mode.
Huella (hash chain)
La huella encadenada SHA-256 d'un registre VeriFactu (camp huella) que enllaça cada registre amb l'anterior, fent la seqüència a prova de manipulacions. Cerca un registre per ella amb POST /v1/verifactu/records/find-by-huella, i verifica la integritat de tota la cadena amb GET /v1/verifactu/chain/validate.
CSV (Código Seguro de Verificación)
El Código Seguro de Verificación que l'AEAT retorna quan accepta un registre VeriFactu (el camp aeat_csv; null fins que s'assigna). És un codi de rebut de l'AEAT — no un fitxer de valors separats per comes. Cerca un registre per ell amb POST /v1/verifactu/records/find-by-csv.
FacturaE
El format XML espanyol de factura electrònica (FacturaE 3.2.2) requerit per a facturació B2G a l'administració pública. Descarrega'l per a una factura amb GET /v1/invoices/{id}/facturae (signat XAdES-EPES amb certificat actiu) i envia'l a FACe via /v1/face-submissions. Consulta Facturació FACe.
FACe
El punt general d'entrada de factures electròniques de l'administració pública espanyola (Ley 25/2013). Factuarea presenta l'XML FacturaE signat al web service de FACe i segueix l'estat de tramitació (submitted → registered_rcf → accounted → paid). Consulta Facturació FACe.
DIR3
El directori espanyol d'unitats de l'administració pública. Tot client B2G porta tres codis DIR3 — oficina contable (01), órgano gestor (02) i unidad tramitadora (03) — requerits per FACe, amb format ^[A-Z][A-Z0-9]{8,9}$.
Declaración responsable
Una declaració formal de compliment (declaración responsable) que el productor del programari SIF — Factuarea — emet per acreditar la conformitat amb VeriFactu. És a nivell de productor i de només lectura (no per empresa): recupera l'actual amb GET /v1/verifactu/declaracion-responsable.
L'autoliquidació trimestral espanyola de l'IVA presentada davant l'AEAT. Genera-la amb POST /v1/tax_reports/303, indicant el trimestre (1–4). La resposta inclou un desglossament per tipus d'IVA ({base, cuota} en cèntims). Consulta la secció Tax reports a l'API Reference.
Modelo 347
La declaració informativa anual que declara tercers amb qui les operacions anuals van superar el llindar legal. Genera-la amb POST /v1/tax_reports/347; és anual i no accepta un trimestre (enviar-ne un retorna un error de validació).
El sistema de control horari cobreix el deure
espanyol de registre de jornada. Els seus termes apareixen en noms de camp i
valors d'enum dels dominis de control horari, tots darrere el mòdul
control_horario.
Terme
Definició
RD-ley 8/2019
El Reial Decret-llei 8/2019 (art. 34.9 de l'Estatut dels Treballadors), que obliga les empreses espanyoles a portar un registre diari objectiu, fiable i inalterable de la jornada de cada empleat i conservar-lo quatre anys per a la Inspecció de Treball (ITSS). Factuarea el construeix com un ledger immutable (de sola addició) segellat per una cadena de hash SHA-256 per empresa — el patró d'inviolabilitat de VeriFactu aplicat a la jornada. Consulta Control horari.
Fichaje (time entry)
Cada esdeveniment de fitxatge — entrada, pausa, represa, sortida — afegit al ledger immutable (el recurs time_entries) i mai editat ni esborrat. L'estat de sessió en viu (working, paused, finished) es deriva del ledger, no es desa en una columna. Consulta Fitxatges.
Jornada (working day)
La jornada laboral d'un empleat. Es pot partir en diversos torns (jornada partida) quan l'empleat fitxa sortida i torna a fitxar entrada el mateix dia; les hores setmanals esperades vénen de l'horari de treball assignat.
Registro inalterable (ledger)
El registre horari immutable i encadenat per hash. No es pot actualitzar ni esborrar: un error es corregeix amb una sol·licitud de correcció que afegeix un assentament nou referit a l'original, de manera que tant la fallada com el seu arreglament queden al registre. Verifica'n la integritat amb GET /v1/time-entries/chain/validate.
Cierre mensual (monthly close)
Una instantània que congela els saldos i el desglossament d'absències d'un mes finalitzat i bloqueja el període davant fitxatges retroactius (el recurs monthly-register-closes). Va de closed ⇄ reopened; la reobertura és una recuperació auditada. Consulta Tancament mensual.
Sellado (seal)
La signatura opcional i irreversible d'un tancament mensual: un digest SHA-256 canònic més una signatura RSA-SHA256 desacoblada feta amb el certificat de l'empresa, perquè un auditor pugui provar que la instantània no ha canviat des de la seva signatura. Un segellat per tancament — tornar a segellar retorna 409.
Asiento de empleado (employee seat)
La unitat de facturació del control horari. Els empleats es facturen mitjançant un add-on mensual dedicat (employee-seats) la quantitat del qual segueix el cens actiu; un empleat mai compta contra el límit users del pla. Consulta Facturació d'assentaments d'empleat.
Tipo de ausencia (absence type)
El que un empleat pot sol·licitar — vacances, baixa per malaltia, un dia personal — amb si és retribuïda, si requereix aprovació, i una unitat de mesura (days o hours). Cada empresa nova rep un conjunt espanyol per defecte. Consulta Absències.
Política de ausencia (absence policy)
La regla que decideix quant i per a qui: una dotació (limited dies o unlimited), un mètode de meritació (annual o monthly), els tipus que cobreix i els empleats als quals s'assigna.
Saldo (balance)
La dotació restant per empleat i tipus d'absència, derivada de la meritació de la política menys les sol·licituds aprovades (el recurs absence-balances).
Presencialidad (presence)
La vista de només lectura de qui està treballant ara mateix i qui és a l'oficina o en remot avui, derivada del ledger, els horaris i el cens — mai persistida. No existeix el scope presence:write: declarar presència a l'oficina o en remot és una tasca només del portal. Consulta Presència.
