Guides
Glossary
Spanish-English glossary of fiscal and business terms used in the BeeL. API.
The BeeL. API serves self-employed professionals (autónomos) 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 |
| Base imponible | Taxable base | taxable_base |
| 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 |
| Serie de facturación | Invoice series | series |
| Número de factura | Invoice number | invoice_number |
| 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 |
| Fecha de vencimiento | Due date | due_date |
| Borrador | Draft | status: DRAFT |
| Emitida | Issued | status: ISSUED |
| Enviada | Sent | status: SENT |
| Pagada | Paid | status: PAID |
| Vencida | Overdue | status: OVERDUE |
| Anulada | Voided / Cancelled | status: VOIDED |
| Rectificada | Corrected | status: RECTIFIED |
| Programada | Scheduled | status: SCHEDULED |
| Factura duplicada | Duplicate invoice | duplicateInvoice endpoint |
| Factura recurrente | Recurring invoice | Scheduled invoices with repeat |
Invoice Status Flow
DRAFT → ISSUED → SENT → PAID
│ │ │
│ │ └→ OVERDUE → PAID
│ │
│ └→ PAID (direct)
│
└→ SCHEDULED → DRAFT or ISSUED (on scheduled date)
ISSUED/SENT → VOIDED (via corrective TOTAL)
ISSUED/SENT → RECTIFIED (via corrective PARTIAL)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 |
| Otro | Other | OTHER |
Corrective Invoice Reason Codes
When creating a corrective invoice, you must specify a reason code (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 | Description |
|---|---|---|
PARTIAL | Rectificación parcial | Partially corrects the original invoice. Original status → RECTIFIED. |
TOTAL | Rectificación total | Completely cancels the original invoice. Original status → VOIDED. |
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 + letter (e.g., 12345678A) |
| 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)
For non-Spanish customers without a NIF, use alternative_id with one of these types:
| Code | Description |
|---|---|
02 | VAT-ID (intra-community) |
03 | Passport |
04 | Country of residence ID |
05 | Residence certificate |
06 | Other document |
07 | Not registered |
Customer Terms
| Spanish | English | API Field / Context |
|---|---|---|
| Cliente | Customer | Customer |
| Persona física | Individual | customer_type: INDIVIDUAL |
| Persona jurídica | Legal entity | customer_type: LEGAL_ENTITY |
| 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 | Soft-deleted customer |
Product Terms
| Spanish | English | API Field / Context |
|---|---|---|
| Producto | Product | type: PRODUCT |
| Servicio | Service | type: SERVICE |
| 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 | setDefaultSeries endpoint |
| Reinicio de numeración | Counter reset | reset_frequency |
| Reinicio anual | Annual reset | reset_frequency: ANNUAL |
| Reinicio mensual | Monthly reset | reset_frequency: MONTHLY |
| Sin reinicio | No reset | reset_frequency: 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 | Invoice record | VeriFactu submission |
| Alta | Registration record | New invoice submission |
| Anulación | Cancellation record | Invoice cancellation |
| 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
| Status | Spanish | Description |
|---|---|---|
PENDING | Pendiente | Submitted to AEAT, awaiting response |
ACCEPTED | Aceptado | AEAT accepted the registration |
REJECTED | Rechazado | AEAT rejected the registration |
NO_VERIFACTU | Sin VeriFactu | VeriFactu not configured or not applicable |
NIF Validation Statuses
| Status | Spanish | Description |
|---|---|---|
VALID | Válido | NIF exists in the AEAT tax registry |
INVALID | Inválido | NIF not found or invalid format |
PENDING | Pendiente | Validation in progress or AEAT unavailable |
NIF_INVALID | NIF no válido | NIF not valid according to AEAT census (VeriFactu) |
Tax Regime Keys
These are the regime_key values used in VeriFactu submissions.
| Code | Spanish | English |
|---|---|---|
01 | Régimen general | General regime |
02 | Exportación | Export |
03 | Bienes usados, arte, antigüedades | Used goods, art, antiques |
04 | Oro de inversión | Investment gold |
05 | Agencias de viaje | Travel agencies |
06 | Grupos de entidades | Group of entities |
07 | Criterio de caja | Cash basis |
08 | Operaciones IPSI/IVA/IGIC | IPSI/IVA/IGIC operations |
09 | Cobros por cuenta de terceros | Mediating agencies |
10 | Cobros por cuenta de terceros | Third-party collections |
11 | Arrendamiento local | Local rental |
14 | IVA pendiente en certificaciones | VAT pending in certifications |
15 | IVA pendiente en tracto sucesivo | VAT pending successive tract |
17 | OSS e IOSS | OSS and IOSS |
18 | Recargo de equivalencia | Equivalence surcharge |
19 | REAGYP | Agriculture, livestock & fishing |
20 | Régimen simplificado | Simplified regime |
Webhook Terms
| Term | Description |
|---|---|
| Subscription | A registered URL that receives webhook events |
| Event | A notification triggered by an action (e.g., invoice.emitted) |
| 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 (up to 5 total) |
| Deduplication | Using BeeL-Event-Id to prevent processing the same event twice |