Conceptes clau
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 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.
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 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. |
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). 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. 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. |
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/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. |
Declaracions tributàries
| Terme | Definició |
|---|---|
| Modelo 303 | 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ó). |
Esdeveniments
Objectes event de només lectura amb un id opac. Consulta històrica via l'API i entrega per webhook.
Verificació censal AEAT
Contrasta el parell raó social + NIF de la teva empresa — i el dels teus clients — contra el cens de l'AEAT abans d'emetre factures VeriFactu — estats deterministes, NIFs màgics del sandbox i comportament fail-open.