Glossari
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, DeCA — més el model de comptes: NIF addicionals, accés cedit, comptes gestionats i traspassos de NIF.
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.
Noms de producte
| Nom de producte | Interfície estable | Significat |
|---|---|---|
| Despeses (abans factures de compra) | purchase_invoices | Registres de compra amb els documents del proveïdor, les línies i els pagaments. |
| Factures (abans factures de venda) | invoices | Factures emeses a clients. |
Els noms són Expenses / Invoices en anglès i Gastos / Facturas en castellà. Els noms de recursos, scopes, esdeveniments, tools MCP, mètodes SDK, ordres CLI i URLs publicades no canvien. Fes servir les interfícies existents; no hi ha cap recurs nou anomenat expenses.
La despesa es distingeix del seu justificant fiscal. Factura del proveïdor, número de factura, factura simplificada i factura rectificativa conserven el significat fiscal. Els noms nous no canvien els tipus documentals admesos, els camps obligatoris ni el tractament fiscal.
Identificadors fiscals
| Terme | Definició |
|---|---|
| NIF / CIF / NIE | 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/companies/{company}/verifactu/aeat-access/* s'hi relacionen. |
Comptes i NIF
El client de Factuarea és un compte, i els NIF que facturen li pertanyen. Aquests termes apareixen en rutes com /v1/accounts/{account}/…, en noms de camps com origin i account_relationship, en scopes i en codis d'error. Els valors de codi (owner, admin, member, view, operate, granted, provisioned) són els que envies i reps i mai no es tradueixen; els noms en prosa són els que mostra l'aplicació web. Comptes i NIF és la guia per on començar.
| Terme | Definició |
|---|---|
| Compte (account) | El client de Factuarea. Guarda el pla, les claus d'API, l'equip, els NIF que facturen i el que es cobra per ells. Una credencial pertany a un compte, i {account} a /v1/accounts/{account}/… és l'id d'aquell compte, un UUID v7 que GET /v1/me retorna com a account.id. Les capacitats del compte (equip, invitacions, titularitat, claus d'API, cartera de NIF, traspassos, webhooks i registres de peticions) són sempre les del teu propi compte: qualsevol altre {account} respon 404 account_not_found, llevat dels comptes que gestiones, que una llista tancada de rutes sí que accepta. Consulta Comptes i NIF. |
| NIF del compte (account tax ID) | Un NIF registrat en un compte. A l'API és una empresa: /v1/companies/{company}/… l'anomena amb el seu id, un UUID v7, mai amb el seu tax_id. Conserva les seves pròpies factures, contactes, sèries i registres VeriFactu, i pertany com a màxim a un compte. El seu status és active, inactive o archived. El primer NIF d'un compte és el seu NIF titular, l'empresa amb què es va obrir el compte: no és un NIF addicional i no es pot traspassar. Consulta l'estat d'un NIF. |
| Cartera de NIF (tax ID portfolio) | Els NIF d'un compte: el NIF titular i cada NIF addicional, que llista GET /v1/accounts/{account}/companies. Els NIF als quals només arribes per un accés cedit o un compte gestionat pertanyen a un altre compte, així que no formen part de la teva cartera. El valor cartera de l'abast d'una regla d'automatització és més ampli: consulta Automatitzacions. Consulta Cartera de NIF. |
| NIF addicional (additional tax ID) | Tot NIF d'un compte a més del titular. Ocupa una de les places contractades additional-nifs del compte: afegir-lo n'ocupa una de lliure sense cobrament, i només comprar places cobra. Necessita el pla empresario o enterprise, és gratis durant el trial, i el topall de contracte max_additional_nifs pot limitar quants en té el compte. El bloc de facturació que descriu aquesta subscripció conserva el seu nom anterior, gestoria_seats. Consulta NIF addicionals. |
| Titular (account holder) | La persona propietària del compte: el rol owner. N'hi ha exactament una, i només el titular en traspassa la titularitat, amb PATCH /v1/accounts/{account}/owner i l'scope account:owner. No confonguis la persona amb el NIF titular, que és una empresa. Consulta Titularitat del compte. |
| Rol del compte (account role) | El que és una persona dins d'un compte: owner, admin o member. En prosa els noms són titular, administrador i membre; els valors de codi es queden tal qual. Un titular i un administrador arriben a tots els NIF sense grants i administren el compte: equip, NIF i facturació. Un membre només arriba als NIF sobre els quals té un grant. Consulta Rols i grants. |
| Grant (permís per NIF) | L'accés d'un membre a un NIF, amb el nivell view o operate. Només un membre té grants: passar un membre a admin els revoca, perquè un administrador ja arriba a tot. Es fixa amb PUT /v1/accounts/{account}/members/{member}/grants/{company}. Consulta Membres. |
| Nivell d'accés (access level) | El que pot fer una persona, una clau o un altre compte sobre un NIF: view, operate o none. view llegeix; operate llegeix i escriu. Una escriptura amb view respon 403 company_read_only. none no arriba a res, i existeix només en un compte gestionat, on el proveïdor continua pagant sense arribar a cap NIF: no és un nivell que puguis concedir. En un NIF assolit per una relació entre comptes, el nivell d'una clau es fixa en emetre-la i només baixa. |
| Accés cedit (granted access) | L'accés que un compte dona a un altre als seus NIF, amb el nivell view o operate, a tots (all, inclosos els que afegeixi després) o a una llista. És una relació entre comptes amb origin granted. Es gestiona només a l'aplicació web, no necessita pla ni mòdul, no ocupa plaça d'usuari en cap dels dos comptes i el compte cedent continua pagant els seus NIF. El compte receptor arriba als NIF pel segment {company}. Consulta Accés cedit entre comptes. |
| Compte cedent i compte receptor (granting and receiving account) | En un accés cedit, el compte cedent (grantor) el dona i el compte receptor (grantee) el rep. Un titular o administrador de cada banda opera la seva meitat a l'aplicació web. Les capacitats del compte cedent mai no passen al receptor: les de compte responen 404 account_not_found, i les d'empresa, com GET …/billing o els webhooks d'empresa, responen 403 forbidden_action. |
| Compte gestionat (managed account) | Un compte normal, separat del del proveïdor, que un proveïdor de comptes gestionats aprovisiona per a un client amb POST /v1/accounts: té el seu propi NIF, el seu propi perfil fiscal, el seu propi pla i, un cop reclamat, el seu propi titular. Neix sense una persona titular i passa per provisioned i claimed fins a active. El proveïdor l'opera per una relació amb origin provisioned i el nivell none, view o operate, i el paga fins que el client assumeix el pagament. Consulta Comptes gestionats. |
| Proveïdor de comptes gestionats (managed-account provider) | El compte que aprovisiona i opera comptes gestionats per als seus clients: una gestoria que treballa a l'aplicació web, que necessita el mòdul gestoria i un titular o administrador, o una plataforma per l'API amb els scopes privilegiats accounts:* que concedim al compte. Paga el pla de cada compte gestionat live que aprovisiona, més els seus NIF addicionals i places d'empleat, en una única subscripció mensual managed-accounts, llevat dels comptes amb contracte enterprise. GET /v1/me el marca amb account.is_provider. No el confonguis amb un proveïdor (supplier), la contrapart que emet factures de compra a una empresa. |
| Pagador (payer) | Qui paga un compte. Cada compte es paga a si mateix, llevat d'un compte gestionat mentre el seu proveïdor el paga: llavors el seu titular no pot comprar un pla, places d'empleat ni NIF addicionals i rep 403 billing_managed_by_provider. El pagador canvia quan el titular assumeix el pagament: el client conserva el mateix pla i preu i la relació passa a ser un accés cedit amb el mateix nivell (amb none no queda res per cedir, i la gestió acaba). Quan la gestió acaba després de la reclamació, el pagament també passa al titular, però el proveïdor perd tot l'accés. Consulta Canvi de pagador. |
| Reclamació (claim) | El que fa el client per fer seu un compte gestionat, a l'aplicació web: amb el val, una persona nova o una que ja té compte a Factuarea passa a ser l'owner. El proveïdor conserva el seu nivell i continua pagant fins que el client assumeix el pagament. Un compte de proves no es pot reclamar. La paraula és només dels comptes gestionats: un NIF que canvia de compte es traspassa. Consulta La reclamació. |
| Val de reclamació (claim voucher) | El secret d'un sol ús que obre la reclamació, als camps claim_token i claim_url de la resposta d'aprovisionament. Caduca als 14 dies, es retorna una sola vegada i reemetre'l invalida els pendents. Amb send_email: true viatja només al correu i els dos camps valen null. Consulta El val de reclamació. |
| Traspàs de NIF (tax ID transfer) | Com passa un NIF d'un compte a un altre. El compte que l'entrega l'emet amb POST /v1/accounts/{account}/nif-transfers, que retorna el secret una sola vegada, i el compte receptor l'accepta amb POST /v1/accounts/{account}/nif-transfers/accept. Dura 24 hores tret que expires_at fixi un altre instant, com a màxim d'aquí a 7 dies, i el compte que l'entrega el pot revocar fins que algú l'accepti. El NIF que arriba és un NIF addicional del compte receptor, tret que aquell compte es registrés sense NIF. Consulta Traspassos de NIF. |
| Assessor extern (external advisor) | L'única persona externa a la qual un compte pot donar accés, per exemple el seu gestor: sempre un member, un per compte, en qualsevol pla, amb grants com qualsevol altre membre i sense ocupar plaça. Un titular o administrador el marca amb external_advisor a PATCH /v1/accounts/{account}/members/{member}; un segon respon 422 external_advisor_already_assigned. Consulta Assessor extern. |
| Importació massiva (bulk import) | La manera de donar d'alta NIF i aprovisionar comptes gestionats d'una vegada a partir de fitxers: POST /v1/accounts/imports/preview, POST /v1/accounts/imports i GET /v1/accounts/imports/template. Cada fila tria el seu mode, own_nif o managed_account, i s'aplica per si sola, així que la importació no és atòmica, i importar el mateix fitxer una altra vegada reconcilia el que ja existeix en lloc de duplicar-ho. No té eina MCP. Consulta Importació massiva de comptes gestionats. |
| Webhook de compte (account webhook) | Un endpoint de webhook d'un compte, sota /v1/accounts/{account}/webhooks, davant d'un d'empresa. Escolta els esdeveniments dels NIF del compte, dels comptes que gestiona i els esdeveniments account.* del mateix compte, en un entorn, live o test. Els seus esdeveniments porten el mateix id que els seus bessons d'empresa. Consulta Webhooks de compte. |
| Registre de peticions del compte (account request log) | El registre de les peticions fetes amb les credencials d'un compte, que es llegeix amb GET /v1/accounts/{account}/request-logs i l'scope developers:read. Suma totes les credencials del compte, a l'entorn de la credencial que pregunta, i mai les d'un altre compte. Consulta Registres de peticions del compte. |
account_relationship | El filtre d'un endpoint de webhook de compte, own, managed o all (el valor per defecte): els NIF del teu compte, els comptes que gestiones, o tots dos. Cada entrega porta a més el seu propi account_relationship, own o managed, que diu com es relaciona aquell esdeveniment amb el teu compte. Els valors es queden tal qual. Consulta el filtre. |
| Compte de proves (test account) | Un compte gestionat creat amb una clau fact_test_: viu només a l'entorn de proves i la seva única empresa és un sandbox. Mai no es cobra, mai no es reclama ni es promou a live, no compta per a max_managed_accounts, i només hi arriba una clau de proves o l'aplicació web en mode proves. Consulta Provar comptes gestionats amb clau fact_test_. |
Impostos
| Terme | Definició |
|---|---|
| IVA (VAT) | 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. |
Documents
| Terme | Definició |
|---|---|
| Serie (numbering series) | La seqüència de numeració correlativa i sense buits a la qual pertany una factura (series_id). Cada sèrie de factures té un propòsit fix (invoice_kind: completes, simplificades, rectificatives o rectificatives de simplificades) i un document només es numera en una sèrie del seu propi propòsit; la sèrie que falta es crea sola en el primer ús. Una sèrie mai no s'elimina i la seva numeració està protegida: PATCH /v1/companies/{company}/series/{id} l'edita (name, code, counter_reset, number_format, initial_number, invoice_kind) sota les guardes fiscals — el codi, la màscara i el propòsit queden fixos quan existeixen documents, i res de la numeració canvia quan l'AEAT accepta un registre de les seves factures. PUT i DELETE retornen 405; arxiva la sèrie en lloc d'eliminar-la. 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. |
| Emitida (issued invoice) | Una factura que ja s'ha emès: té el número definitiu de sèrie, el registre VeriFactu i els moviments d'stock, i ja no es pot editar. Estat issued des de la versió de l'API 2026-10-01; les versions anteriors la publiquen com a sent. Emet un esborrany amb POST /v1/companies/{company}/invoices/{id}/issue. Emetre mai no envia la factura per correu. |
| Enviada (sent invoice) | Una factura emesa que ha arribat al client: el servidor de correu en va acceptar l'email de lliurament o vas registrar el lliurament amb POST /v1/companies/{company}/invoices/{id}/mark-sent (versió 2026-10-01). És una marca independent de l'estat i del cobrament, exposada com a is_sent, sent_at (primer lliurament) i sent_via (email o manual), i s'esborra amb POST /v1/companies/{company}/invoices/{id}/unsend. Consulta Treballar amb factures. |
| Modo de generación (generation mode) | Què fa cada execució d'una factura recurrent amb la factura que genera (generation_mode): draft deixa un esborrany, issue l'emet sense enviar-la per correu i issue_and_send l'emet i l'envia per correu. Consulta Factures recurrents. |
| 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/companies/{company}/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/companies/{company}/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/companies/{company}/invoices/simplified-eligibility; agrupa'n diverses en una sola factura substitutiva completa (tipus F3) amb POST /v1/companies/{company}/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/companies/{company}/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/companies/{company}/{resource}/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. |
Catàleg de productes i preus
| Terme | Definició |
|---|---|
| Unitat base | Unitat UNECE canònica que mesura producte i estoc (C62, KGM, GRM, LTR, MLT, MTR, MTK, HUR o DAY). |
| Presentació | Envàs o mesura comercial. fixed multiplica per un factor; variable_measure exigeix la quantitat base real a cada línia. Mai té estoc. |
| Variant | Identitat de producte amb SKU/codi de barres i overrides de preu/cost opcionals. Pot tenir estoc o delegar moviments al producte. |
| Oferta de proveïdor | Condicions de compra per a producte/variant: proveïdor, unitat, conversió, disponibilitat, cost i termini. Mai canvia el preu de venda. |
| Tarifa | Conjunt tenant-scoped de preus EUR explícits per a destins producte/variant/presentació, assignable a clients i esborranys. |
| Snapshot de catàleg | Context immutable de producte, quantitat i preu copiat a una línia perquè editar el catàleg no reescrigui l'històric. |
Consulta Catàleg de productes i Tarifes.
Compliment VeriFactu i AEAT
| Terme | Definició |
|---|---|
| VeriFactu | 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/companies/{company}/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/companies/{company}/verifactu/records/find-by-huella, i verifica la integritat de tota la cadena amb GET /v1/companies/{company}/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/companies/{company}/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/companies/{company}/invoices/{id}/facturae (signat XAdES-EPES amb certificat actiu) i envia'l a FACe via POST /v1/companies/{company}/invoices/{id}/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/companies/{company}/verifactu/declaracion-responsable. |
Declaracions tributàries
| Terme | Definició |
|---|---|
| Modelo 303 | L'autoliquidació trimestral espanyola de l'IVA presentada davant l'AEAT. Genera-la amb POST /v1/companies/{company}/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/companies/{company}/tax-reports/347; és anual i no accepta un trimestre (enviar-ne un retorna un error de validació). |
Control horari
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/companies/{company}/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. |
| Plaça d'empleat (employee seat) | La unitat de facturació del control horari. Es contracten places a l'add-on mensual dedicat employee-seats i crear un empleat n'ocupa una; un empleat mai compta contra el límit users del pla. Consulta Facturació de places d'empleat. |
| Plaça contractada (contracted seat) | Una plaça que el compte paga, per producte: employee-seats per a empleats i additional-nifs per a NIF addicionals. La quantitat de la subscripció mensual és la contractada, i mai baixa de l'ocupada. Consulta Places contractades. |
| Plaça ocupada (occupied seat) | Una plaça contractada que fa servir una entitat activa: un empleat actiu o un NIF addicional actiu del compte. Es calcula a cada lectura i mai es desa. Consulta Places contractades. |
| Plaça lliure (free seat) | Una plaça contractada que ningú ocupa. Crear o reactivar un empleat o un NIF n'ocupa una de lliure sense cobrament, i desactivar-lo l'allibera sense tocar la factura. Sense cap de lliure, l'aplicació web respon 422 contracted_seats_exhausted, mentre que l'API v1 i el MCP compren les que falten. Consulta Comprar places. |
| Mínim pactat (agreed minimum) | El nombre de places del qual depèn el preu pactat d'una línia d'un paquet d'oferta. No impedeix reduir: baixar-ne exigeix acceptar la pèrdua del paquet, i la reducció que arriba a efecte acaba el paquet sencer. Consulta Mínim pactat. |
| Paquet d'oferta (offer package) | D'una a tres línies (pla, places d'empleat, NIF addicionals) que es canvien amb un sol codi i s'apliquen una vegada al compte. Acaba sencer, amb totes les línies de tornada al preu de catàleg, si es trenca una de les seves condicions. Només es canvia a l'aplicació web, mai per l'API v1 ni el MCP. Consulta Paquets d'oferta. |
| Reducció pendent (pending reduction) | Una reducció de places contractades desada perquè tingui efecte a la renovació, sense cobrament ni abonament. Porta el que es desactivarà en aquell moment, i una compra o demanar la quantitat actual l'anul·la. Consulta Reduir places. |
| 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. |
Automatitzacions
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/companies/{company}/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/companies/{company}/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) | Quins NIF 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 la cartera del compte que la posseeix: els altres NIF reals d'aquell compte, més els NIF que un altre compte posa al seu abast per una relació vigent amb nivell operate, un accés cedit o un compte gestionat. Mai no vigila l'empresa que posseeix la regla, i n'entrega l'avís a aquella empresa, el NIF titular del compte. No es pot canviar un cop existeix la regla. |
| Gestoría (accounting firm) | El despatx espanyol que porta la comptabilitat d'altres empreses. Factuarea no té un tipus de compte especial per a ella: una gestoria és un compte com qualsevol altre, i la seva cartera es compon dels NIF que té i als quals arriba —els NIF addicionals del seu compte, els que altres comptes li cedeixen i els comptes gestionats que aprovisiona—. El mòdul gestoria (plans empresario i enterprise) li dona les operacions de proveïdor de l'aplicació web i les regles de cartera, que només pot crear l'empresa titular del compte. Aquestes regles només admeten cinc dels dotze tipus d'acció —els que avisen, més create_task— perquè els altres set tindrien per subjecte un document o una tasca d'una altra empresa 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. |
Documents de control (DeCA)
El document de control és obligatori en format digital
en el transport públic de mercaderies per carretera. Els seus termes apareixen al recurs
transport_documents i als camps de pes del catàleg.
| Terme | Definició |
|---|---|
| DeCA (documento de control) | El document electrònic de control administratiu del transport de mercaderies per carretera (Ordre FOM/2861/2012). Identifica les parts, els enviaments, la mercaderia, el vehicle i les dates, i viatja amb el conductor com un PDF el codi QR del qual obre una URL pública permanent. No és una factura ni un registre VeriFactu. A l'API és el recurs transport_documents. |
| Carregador contractual | Qui contracta el transport en nom propi. La teva empresa declara el seu paper a cada document amb company_role: "shipper". |
| Transportista efectiu | Qui fa materialment el transport, inclòs el transportista que el subcontracta. company_role: "carrier". Un transportista estranger (cabotatge) s'identifica amb tax_id_country. |
| Enviament | Un tram origen-destinació d'un document, amb les seves línies de mercaderia, la seva data i la seva magnitud declarada (shipments[]). Un document pot agrupar diversos enviaments que comparteixen carregador i transportista, i cadascun pot sortir d'un albarà. |
| Magnitud declarada | El pes en kg o una altra magnitud (un valor i una unitat lliure, com palets) declarada per a un enviament (declared_measure). És obligatòria per emetre; el pes del catàleg només ajuda a omplir-la. |
| Pes brut de transport | El que pesa en kg una unitat tal com es carrega, embalatge inclòs (gross_weight_kg): per unitat base en productes i variants i per unitat comercial en presentacions fixes. Les línies d'albarà el congelen en crear-se o editar-se en esborrany. |
| Modificació | Un canvi sobre un document emès durant el servei: mateix número, URL i QR, una versió nova del PDF amb el motiu, qui va comunicar la dada (data_origin) i les dades anteriors marcades com a ja no vàlides. |
| Registre d'emissió | El registre de versions, enviaments per email i descàrregues públiques d'un document, que s'exporta a demanda com a justificant d'emissió en PDF. És la prova que eximeix el carregador que demostra haver-lo emès (art. 7.1 de l'Ordre). |
| Lloc de càrrega | Una adreça de l'empresa de la qual surten els enviaments, gestionada a l'app. Un enviament sense origen pren el lloc de càrrega per defecte o, si no n'hi ha, el domicili fiscal. |
| Transport privat complementari | El transport que una empresa fa amb vehicles i conductors propis per a la seva pròpia mercaderia. No necessita DeCA. |
Tasques i projectes
El mòdul de tasques parla el vocabulari de l'app. Tres parells es confonen fàcilment amb conceptes anteriors i es mantenen separats a propòsit: una etiqueta de tasca no és una etiqueta de document, un camp personalitzat de tasca no és un camp personalitzat de document, i el temps imputat a una tasca no és un fitxatge de jornada.
| Terme | Definició |
|---|---|
| Tasca (task) | Una unitat de treball d'un projecte, amb una clau (DEV-12), un status de tauler (planned, active o archived), una prioritat, dates opcionals, una persona assignada, etiquetes i valors de camps personalitzats. Recurs tasks, scopes tasks:*. Consulta Projectes i tasques. |
| Projecte (project) | Agrupa tasques i és propietari del seu tauler. La seva clau (DEV) prefixa les claus de les seves tasques i és única a l'empresa (recurs projects, scopes projects:*). Porta els valors de facturació per defecte per facturar el temps imputat. |
| Columna (column) | Un pas del tauler d'un projecte. Una columna final (is_final) completa les tasques que hi entren. planned (el backlog) i archived són estats virtuals, no columnes. |
| Etiqueta de tasca (task label) | Una entrada del catàleg d'etiquetes de tasca de l'empresa (/v1/companies/{company}/task-labels), amb un nom, un color i tasks_count. No és una etiqueta de document: les etiquetes de document classifiquen factures, pressupostos i altres documents i tenen les seves pròpies regles. Consulta Etiquetes i camps personalitzats. |
| Camp personalitzat de tasca (task custom field) | Un camp definit per projecte —text, number, date, dropdown, boolean o multiselect— els valors del qual viuen a les tasques d'aquest projecte. No és un camp personalitzat de document, que amplia factures i altres documents. |
| Imputació de temps de tasca (task time entry) | Temps imputat a una tasca, a mà o amb un temporitzador (/v1/companies/{company}/tasks/{task}/time-entries), facturable per defecte i susceptible de facturar-se. No és un fitxatge: els fitxatges de jornada del control horari són el registre legal de /v1/companies/{company}/time-entries, amb els seus propis scopes i esdeveniments. Consulta Temps imputat a tasques. |
| Temporitzador (timer) | Una imputació de temps de tasca en marxa —ended_at és null— de la qual cada usuari en pot tenir una per empresa. Aturar-lo tanca la imputació. |
| Agenda | El calendari combinat d'una finestra de dates (GET /v1/companies/{company}/agenda): tasques amb venciment i, en cada capa que la credencial també pot llegir, venciments de documents, terminis fiscals, absències i festius. |
| Feed iCal (iCal feed) | Una subscripció de calendari de només lectura, darrere d'una URL secreta, que publica les tasques amb data d'un projecte o d'una persona. Només a l'app. Consulta Feed iCal. |
| Tauler públic (public board) | Una vista de només lectura del tauler d'un projecte que es pot compartir sense iniciar sessió. Només a l'app: no té operació a l'API. |
| Enllaç de pujada (upload link) | Un enllaç d'un sol ús, vàlid 30 minuts, amb el qual algú sense compte puja fitxers a una tasca (POST /v1/companies/{company}/tasks/{task}/upload-links). |
Identificadors de botiga i comanda
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.