Glossary

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`
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` (read-only, always today)
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`
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	`counter_reset`
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

Glossary

On this page