# Glossary

Spanish-English glossary of fiscal and business terms used in the BeeL. API.

The BeeL. API serves businesses in Spain. Since Spanish tax and invoicing terminology appears throughout the API, this glossary maps each term to its English equivalent and the relevant API fields.

## Tax terms

| Spanish | English | API Field / Context |
|---------|---------|---------------------|
| IVA (Impuesto sobre el Valor Añadido) | VAT (Value Added Tax) | `TaxType: IVA`, `total_vat` |
| IGIC (Impuesto General Indirecto Canario) | Canary Islands General Indirect Tax | `TaxType: IGIC` |
| IPSI (Impuesto sobre la Producción, Servicios e Importación) | Production, Services & Import Tax (Ceuta & Melilla) | `TaxType: IPSI` |
| IRPF (Impuesto sobre la Renta de las Personas Físicas) | Personal Income Tax Withholding | `default_irpf_rate`, `total_irpf` |
| Recargo de equivalencia | Equivalence surcharge | `default_equivalence_surcharge`, `total_equivalence_surcharge` |
| Inversión del sujeto pasivo | Reverse charge | `exemption_reason` from `ISP_ART_84_2_A` to `ISP_ART_84_2_F` |
| Base imponible | Taxable base | `taxable_base` |
| Suplido | Disbursement: a payment on behalf of the client (art. 78.Tres.3 LIVA) | `line_type: SUPLIDO`, `total_disbursements`, `total_to_pay` |
| Retención | Withholding | `total_irpf`, `irpf_rate` |
| Tipo impositivo | Tax rate | `percentage` |
| Cuota tributaria | Tax amount | `amount` in breakdowns |
| Exento | Exempt | `irpf_exempt`, 0% rates |
| Régimen fiscal | Tax regime | `TaxRegime`, `regime_key` |
| Desglose | Breakdown | `vat_breakdown`, `irpf_breakdown`, `surcharge_breakdown` |

## Invoice terms

| Spanish | English | API Field / Context |
|---------|---------|---------------------|
| Factura | Invoice | `Invoice` |
| Factura ordinaria | Standard invoice | `type: STANDARD` |
| Factura rectificativa | Corrective invoice | `type: CORRECTIVE` |
| Factura simplificada | Simplified invoice | `type: SIMPLIFIED` |
| Proforma / Presupuesto | Proforma (formal quote, no fiscal validity) | `type: PROFORMA` |
| Serie de facturación | Invoice series | `series` |
| Número de factura | Invoice number | `invoice_number` (assigned on issue — see [Series and numbering](/guides/series-and-numbering)) |
| Emisor | Issuer | `issuer` |
| Receptor / Destinatario | Recipient | `recipient` |
| Línea de factura | Invoice line item | `lines[]` |
| Forma de pago | Payment method | `payment_method` |
| Fecha de emisión | Issue date | `issue_date` (read-only, set to the day the invoice is issued) |
| Fecha de operación | Operation date | `operation_date` |
| Fecha de vencimiento | Due date | `due_date` |
| Borrador | Draft | `status: DRAFT` |
| Emitida | Issued | `status: ISSUED` |
| Enviada | Sent | `status: SENT` |
| Pagada | Paid | `status: PAID` |
| Anulada | Voided / Cancelled | `status: VOIDED` |
| Rectificada | Corrected | `status: RECTIFIED` |
| Programada | Scheduled | `status: SCHEDULED` |
| Proforma activa | Active proforma | `status: ACTIVE` |
| Proforma caducada | Expired proforma | `status: EXPIRED` (derived from `valid_until`, never stored) |
| Proforma convertida | Converted proforma | `status: CONVERTED` (terminal — the proforma survives, linked to the invoice) |
| Factura duplicada | Duplicate invoice | `POST …/invoices/derivations` with `mode: DUPLICATE` |
| Factura recurrente | Recurring invoice | Scheduled invoices with repeat |

## Invoice status flow

Which status can move to which, and how, is in [Invoice lifecycle](/guides/invoice-lifecycle#the-state-diagram) — with what each status allows and the error you get outside it.

## Payment methods

| Spanish | English | API Value |
|---------|---------|-----------|
| Transferencia bancaria | Bank transfer | `BANK_TRANSFER` |
| Tarjeta | Card | `CARD` |
| Efectivo | Cash | `CASH` |
| Cheque | Check | `CHECK` |
| Domiciliación bancaria | Direct debit | `DIRECT_DEBIT` |
| Bizum | Bizum | `BIZUM` |
| Otro | Other | `OTHER` |
| Sin forma de pago | None | `NONE` — no payment information is shown on the invoice |

## Corrective invoice reason codes

When creating a corrective invoice, you must specify a reason code in `rectification_code` (the free-text explanation goes in `reason`):

| Code | Spanish | English |
|------|---------|---------|
| `R1` | Error fundado en derecho y Art. 80 Uno, Dos y Seis LIVA | Legal error and Art. 80 One, Two and Six LIVA |
| `R2` | Artículo 80 Tres LIVA (Concurso de acreedores) | Article 80 Three LIVA (Bankruptcy proceedings) |
| `R3` | Artículo 80 Cuatro LIVA (Créditos incobrables) | Article 80 Four LIVA (Uncollectable debts) |
| `R4` | Resto de causas | Other causes |
| `R5` | Facturas simplificadas (Art. 80 Uno y Dos LIVA) | Simplified invoices only |

### Corrective invoice types

| Type | Spanish | English |
|------|---------|---------|
| `PARTIAL` | Rectificación por diferencias | Partial correction (a delta) |
| `TOTAL` | Rectificación por sustitución | Total correction (replaces the original) |

What each code and type is for, and what it does to the original invoice: [Corrective invoices](/verifactu/corrective-invoices).

## Tax ID terms

| Spanish | English | Notes |
|---------|---------|-------|
| NIF (Número de Identificación Fiscal) | Tax Identification Number | Umbrella term for all Spanish tax IDs |
| DNI (Documento Nacional de Identidad) | National ID (individuals) | Format: 8 digits + check letter (e.g., `12345678Z`) |
| NIE (Número de Identidad de Extranjero) | Foreigner ID Number | Format: X/Y/Z + 7 digits + letter (e.g., `X1234567A`) |
| CIF (Código de Identificación Fiscal) | Company Tax ID | Legacy term, now part of NIF |

### Alternative ID types (foreign customers)

A customer without a Spanish NIF is identified with `alternative_id` (`NIF_IVA`, `PASSPORT`, `COUNTRY_ID`, `RESIDENCE_CERTIFICATE`, `OTHER_DOCUMENT` or `NOT_REGISTERED`). Which type each country allows, and the errors for a wrong combination, are in [International customers](/verifactu/international-customers#identifying-foreign-customers).

> **Rules that apply here:** [CNT-021 · A recipient without a Spanish NIF is identified by an alternative id](/rules/contents#cnt-021)

## Customer terms

| Spanish | English | API Field / Context |
|---------|---------|---------------------|
| Cliente | Customer | `Customer` |
| Persona física | Individual | `entity_type: INDIVIDUAL` (on a company/NIF — customers carry no type field) |
| Persona jurídica | Legal entity | `entity_type: LEGAL_ENTITY` (on a company/NIF) |
| Autónomo | Self-employed person | An individual with an economic activity; `entity_type: INDIVIDUAL` |
| Gestoría | Accounting firm | A provisioner in [Managed accounts](/multi-nif/managed-accounts) |
| Razón social | Legal name | `legal_name` |
| Nombre comercial | Trade name | `trade_name` |
| Dirección | Address | `address` |
| Código postal | Postal code | `postal_code` |
| Provincia | Province | `province` |
| Desactivado | Deactivated | `active: false` — the customer stays retrievable and is listed with `?active=false`. Not the same as `DELETE`, which removes it from the API and releases its NIF |

## Product terms

| Spanish | English | API Field / Context |
|---------|---------|---------------------|
| Producto | Product | `category: PRODUCT` |
| Servicio | Service | `category: SERVICE` (also `CONSULTING`, `SOFTWARE`, `TRAINING`, `OTHER`) |
| Precio unitario | Unit price | `default_price` |
| Unidad | Unit | `unit` |

## Invoice series terms

| Spanish | English | API Field / Context |
|---------|---------|---------------------|
| Serie | Series | `series` |
| Código de serie | Series code | `code` |
| Serie por defecto | Default series | `default_series`, `PUT …/series/{series_id}/default` |
| Reinicio de numeración | Counter reset | `counter_reset` |
| Reinicio anual | Annual reset | `counter_reset: ANNUAL` |
| Reinicio mensual | Monthly reset | `counter_reset: MONTHLY` |
| Sin reinicio | No reset | `counter_reset: NEVER` |

## VeriFactu & regulatory terms

| Spanish | English | Notes |
|---------|---------|-------|
| AEAT (Agencia Estatal de Administración Tributaria) | Spanish Tax Agency | Government entity |
| VeriFactu (Sistema de Facturación Verificable) | Verifiable Invoice System | AEAT's chain-integrity system |
| Registro de facturación | Billing record | VeriFactu submission |
| Alta | Registration record | New invoice submission |
| Anulación | Cancellation record | Invoice cancellation |
| Subsanación | Kept in Spanish: replacing a registration record with a corrected one | See [Cancel vs amend](/verifactu/cancel-and-fix#subsanación) |
| Declaración responsable | Kept in Spanish: the producer's signed statement that its billing system complies | See [Compliance and responsibilities](/verifactu/compliance-and-responsibilities#declaracion-responsable) |
| Huella | Hash / Fingerprint | SHA-256, chain integrity |
| Código QR | QR Code | `qr_url`, `qr_base64` |
| Representación | Representation | Digital signature delegation document |
| Censo de obligados tributarios | Tax registry | AEAT database for NIF validation |

### VeriFactu statuses

The values of `verifactu.submission_status` — what each one means and when you must act — are in [Submission states](/verifactu/submission-states#the-fiscal-states).

### NIF validation statuses

| Status | Spanish | Description |
|--------|---------|-------------|
| `VALID` | Válido | Successfully validated against the AEAT tax registry |
| `INVALID` | Inválido | Invalid tax ID, or it does not exist in the AEAT tax registry |
| `PENDING` | Pendiente | Not yet validated, or the AEAT service is temporarily unavailable |
| `ERROR` | Error | Technical error after exhausting retries |

The finer-grained outcome of a census lookup travels in `census_status` (`IDENTIFIED`, `IDENTIFIED_DEREGISTERED`, `IDENTIFIED_REVOKED`, `NOT_IDENTIFIED`, `NOT_IDENTIFIED_SIMILAR`, `UNKNOWN`).

## Tax regime keys

The `regime_key` values (*clave de régimen*) with their Spanish names and when each applies are in [Regime keys](/verifactu/regime-keys#the-catalogue).

## Webhook terms

| Term | Description |
|------|-------------|
| Subscription | A registered URL that receives webhook events |
| Event | A notification triggered by an action (e.g., `invoice.issued`) |
| Delivery | A single HTTP attempt to deliver an event to your URL |
| Secret | HMAC key used to sign and verify webhook payloads |
| Signature | `BeeL-Signature` header with `t=timestamp,v1=hmac` format |
| Retry | Automatic re-delivery after a failed attempt — see [Retries](/webhooks/retries#retry-policy) |
| Deduplication | Using `BeeL-Event-Id` to prevent processing the same event twice |

## Related

<Related>

- [Invoice lifecycle](/guides/invoice-lifecycle) — the statuses in context
- [Corrective invoices](/verifactu/corrective-invoices) — the R1–R5 codes in use
- [Regime keys](/verifactu/regime-keys) — the full regime catalogue

</Related>

---

Full OpenAPI spec: https://docs.beel.es/api/openapi