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 contacts 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 contacts. 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.
El motor d'automatitzacions converteix un esdeveniment en
feina. El seu vocabulari és el que mostra l'editor de regles, i dos dels seus
valors d'enum són literals espanyols que et trobes a l'API. Tot això queda
darrere del mòdul automations.
Terme
Definició
Automatización (automation rule)
Una regla amb tres peces mòbils: l'esdeveniment que escolta (trigger_type), la condició que decideix si un esdeveniment concret és el seu cas (conditions) i les accions ordenades que s'executen (actions). Una regla nova neix en draft i no escolta res fins que l'actives. Consulta Automatitzacions.
Disparador (trigger)
El tipus d'esdeveniment que escolta una regla, en forma resource.action (invoice.paid); a l'aplicació en català se'n diu activador. Demana a GET /v1/automations/catalog els activadors als quals la teva empresa es pot subscriure —ja filtrats pels mòduls que inclou el teu pla— i fes una segona crida per als camps avaluables del que hagis triat.
Ensayo (dry run)
Allò que una regla faria davant d'un esdeveniment d'exemple (POST /v1/automations/rules/{rule}/dry_run); en català, l'assaig. No materialitza res: ni correu, ni entrega de webhook, ni mutació, ni fila d'execució, i no consumeix ni el pressupost mensual ni el límit de freqüència del motor.
Ejecución (run)
Allò que produeix un esdeveniment admès. Congela la definició que va executar (rule_version + rule_snapshot) i el payload de l'esdeveniment que la va disparar, així que continua sent llegible quan la regla ja ha avançat. blocked —aturada per un límit del motor abans d'executar— no és failed.
Paso (step)
Una acció de la definició congelada, identificada pel seu step_index començant a zero. Els passos tornen sempre en ordre d'execució, cadascun amb el seu action_type, els seus parameters congelats, el result que va retornar el seu adaptador i una marca replayable.
Versión sellada (sealed version)
Editar una regla mai reescriu la seva definició anterior: segella una versió nova i puja current_version. Cada execució apunta a la versió exacta que va executar, que pot quedar per darrere de l'actual — i aquesta és la gràcia.
Relanzamiento (replay)
Rearmar feina aparcada, una execució sencera o un sol pas; en català, el rellançament. Executa de debò —envia correu, entrega webhooks i truca a tercers— i porta x-irreversible a l'spec. Només es rearmen els passos aparcats amb una raó rellançable.
Alcance empresa / cartera (rule scope)
Quines empreses vigila una regla, al seu camp opcional scope. Els dos valors són literals espanyols: empresa (el valor per defecte) vigila l'empresa que posseeix la regla; cartera vigila totes les empreses gestionades per una gestoria i li entrega l'avís a ella. No es pot canviar un cop existeix la regla.
Gestoría (accounting firm)
El despatx espanyol que porta la comptabilitat d'altres empreses. Les seves regles de cartera només admeten els quatre tipus d'acció que avisen —els altres quatre tindrien per subjecte un document de l'empresa gestionada— i cada execució anomena a subject_company l'empresa sobre la qual va actuar.
discard_reason_label
L'etiqueta humana d'un discard_reason tipat (condition_not_matched, rate_limit_exceeded…), sempre en espanyol: pertany al vocabulari del motor i no segueix Accept-Language. Ramifica sobre discard_reason, que és un catàleg tancat, mai sobre la seva etiqueta.
Una botiga és el comerç electrònic configurat d’una empresa, identificat pel seu UUID públic. Una connexió del proveïdor és l’autorització darrere d’integration_id. Una comanda té l’external_id opac del proveïdor. channel descriu l’origen de la factura i source_store_id apunta a la botiga d’origen. Als esdeveniments públics de comanda, l’identificador de botiga és específicament data.store.uuid; conserva aquesta clau del format d’intercanvi.
