Excel Format Requirements

Overview

The Electronic Invoice Processing API expects Excel files with specific columns and data formats. This guide details all requirements to ensure successful invoice processing.

Required Columns

Your Excel file must include the following columns in any order:

Invoice Information

Correlativo
Fecha Emision
Fecha Vencimiento
Fecha Pago
Forma de Pago

Customer Information

DNI/C.I./C.C./IFE
Documento
Cliente
Dirección
Telefono
Correo

Service Information

Plan
ID Servicio

Financial Information

Total
Tasa
bolivares
bolivares sin iva
precio sin iva

Column Specifications

Invoice Fields

Correlativo

Type: String/NumberDescription: Invoice sequential number used as unique identifierFormat: Numeric value (will be zero-padded to 6 digits)Example: 1, 42, 1234Notes:

Converted to format: 000001, 000042, 001234
Used in NumeroDocumento and TransaccionId fields

Fecha Emision

Type: DateDescription: Invoice issue dateFormat: Any date format recognizable by pandas (dd/mm/yyyy recommended)Output Format: dd/mm/yyyyExample: 15/01/2026, 2026-01-15Notes: Parsed with dayfirst=True parameter

Fecha Vencimiento

Type: DateDescription: Invoice due dateFormat: Any date format recognizable by pandasOutput Format: dd/mm/yyyyExample: 30/01/2026

Fecha Pago

Type: DateDescription: Payment dateFormat: Any date format recognizable by pandasOutput Format: dd/mm/yyyyExample: 15/01/2026

Forma de Pago

Type: StringDescription: Payment method descriptionExample: Transferencia, Efectivo, Tarjeta de Crédito

Customer Fields

DNI/C.I./C.C./IFE

Type: StringDescription: Customer identification numberExample: V12345678, J408185431Notes: Stored as string to preserve leading zeros and letter prefixes

Documento

Type: StringDescription: Type of identification documentExample: V, J, E, PNotes: Used in TipoIdentificacion field

Cliente

Type: StringDescription: Customer name or business nameExample: Juan Pérez, Empresa XYZ C.A.

Dirección

Type: StringDescription: Customer addressExample: Av. Principal, Edificio Centro, Piso 3, Oficina 301

Telefono

Type: StringDescription: Customer phone numberExample: +58-212-1234567, 04141234567Notes: Stored as string and placed in an array

Correo

Type: StringDescription: Customer email addressExample: [email protected]Notes: Placed in an array for multiple email support

Service Fields

Plan

Type: StringDescription: Service plan or product descriptionExample: Plan Internet 100MB, Servicio PremiumNotes: Used in invoice item description

ID Servicio

Type: String/NumberDescription: Service contract identifierExample: SRV-001, 12345Notes: Stored in additional information as “Contrato”

Financial Fields

Total

Type: NumericDescription: Total amount in USD (with IVA)Precision: Rounded to 0 decimal placesExample: 50, 100, 250Calculation: precio sin iva + iva_usd

Tasa

Type: Numeric (Decimal)Description: Exchange rate from USD to BolivaresExample: 36.50, 40.25Notes: Used to calculate bolivares amounts from USD

bolivares

Type: Numeric (Decimal)Description: Total amount in Bolivares (with IVA)Precision: 2 decimal placesExample: 1825.00, 3650.50Calculation: bolivares sin iva + iva_bs

bolivares sin iva

Type: Numeric (Decimal)Description: Subtotal in Bolivares (without IVA)Precision: 2 decimal placesExample: 1573.28, 3147.84Notes: Base amount for IVA calculation

precio sin iva

Type: Numeric (Decimal)Description: Subtotal in USD (without IVA)Precision: 2 decimal placesExample: 43.10, 86.21Notes: Base amount for USD IVA calculation

Example Excel Structure

Here’s an example of how your Excel file should be structured:

Correlativo	Fecha Emision	Fecha Vencimiento	Fecha Pago	DNI/C.I./C.C./IFE	Documento	Cliente	Dirección	Telefono	Correo	Plan	ID Servicio	Total	Tasa	bolivares	bolivares sin iva	precio sin iva	Forma de Pago
1	15/01/2026	30/01/2026	15/01/2026	V12345678	V	Juan Pérez	Av. Principal	04141234567	[email protected]	Plan 100MB	SRV-001	50	36.50	1825.00	1573.28	43.10	Transferencia
2	15/01/2026	30/01/2026	15/01/2026	J408185431	J	Empresa XYZ	Torre Financiera	02121234567	[email protected]	Plan Premium	SRV-002	100	36.50	3650.00	3146.56	86.21	Efectivo

Data Processing

Numeric Calculations

The API performs the following calculations on your data:

# Amounts are rounded to specific precisions
monto_bs = round(float(row["bolivares"]), 2)
monto_usd = round(float(row["Total"]), 0)
bolivares_sin_iva = round(float(row["bolivares sin iva"]), 2)
precio_sin_iva = round(float(row["precio sin iva"]), 2)

# IVA is calculated as difference
iva_bs = round(monto_bs - bolivares_sin_iva, 2)
iva_usd = round(monto_usd - precio_sin_iva, 2)

The IVA rate is fixed at 16% in the system configuration.

Date Processing

Dates are processed with the following logic:

# Dates are converted to dd/mm/yyyy format
fecha = pd.to_datetime(valor, dayfirst=True, errors="coerce")
return fecha.strftime("%d/%m/%Y")

Empty or invalid dates will be skipped or returned as-is. Ensure all date fields contain valid date values.

Common Validation Errors

Missing Required Column

Error: Column not found in Excel fileSolution: Ensure all required columns are present with exact names (case-sensitive)Example: Correlativo, not correlativo or CORRELATIVO

Invalid Date Format

Error: Date cannot be parsedSolution: Use standard date formats (dd/mm/yyyy recommended)Example: 15/01/2026 instead of 01-15-2026

Invalid Numeric Value

Error: Cannot convert value to numberSolution: Ensure numeric fields contain only numbers and decimal pointsExample: 1825.00 not $1,825.00 or 1.825,00

Empty Required Field

Error: Required field is empty or nullSolution: Fill in all required fields. Some fields can be empty but critical ones must have valuesCritical Fields: Correlativo, Cliente, Total, bolivares, Tasa

IVA Calculation Mismatch

Error: Calculated IVA doesn’t match expected 16%Solution: Verify that:

bolivares = bolivares sin iva * 1.16
Total = precio sin iva * 1.16

Note: Small rounding differences are acceptable

Additional Information

The system automatically generates:

Random navigation values for months (1000-6000 range)
Average navigation calculation
Batch numbers for grouping invoices (100 per batch)
Zero-padded file names based on Correlativo

Best Practices

Data Validation

Validate all data before uploading
Use Excel data validation for date columns
Format numeric columns with appropriate decimals
Remove special characters from monetary values

File Preparation

Save as .xlsx or .xls format
Use the first row for column headers
Avoid merged cells in data rows
Remove empty rows between data

Testing

Test with a small sample first (2-3 rows)
Verify generated JSON structure
Check all calculated fields
Validate date conversions

Performance

Process files in batches if very large
Keep files under 1000 rows for optimal speed
Remove unnecessary columns
Compress files before uploading

Next Steps

Upload Excel

Learn how to upload and process your Excel file

API Reference

View complete API endpoint documentation

Getting Started

Core Concepts

Guides

Overview

Required Columns

Invoice Information

Customer Information

Service Information

Financial Information

Column Specifications

Invoice Fields

Customer Fields

Service Fields

Financial Fields

Example Excel Structure

Data Processing

Numeric Calculations

Date Processing

Common Validation Errors

Additional Information

Best Practices

Data Validation

File Preparation

Testing

Performance

Next Steps

Upload Excel

API Reference

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Guides

​Overview

​Required Columns

Invoice Information

Customer Information

Service Information

Financial Information

​Column Specifications

​Invoice Fields

​Customer Fields

​Service Fields

​Financial Fields

​Example Excel Structure

​Data Processing

​Numeric Calculations

​Date Processing

​Common Validation Errors

​Additional Information

​Best Practices

Data Validation

File Preparation

Testing

Performance

​Next Steps

Upload Excel

API Reference

Build docs developers (and LLMs) love

Overview

Required Columns

Column Specifications

Invoice Fields

Customer Fields

Service Fields

Financial Fields

Example Excel Structure

Data Processing

Numeric Calculations

Date Processing

Common Validation Errors

Additional Information

Best Practices

Next Steps