Skip to main content

​
Request Format

The API accepts Excel files for batch invoice generation.

​
Endpoint

POST /process_excel

​
Content Type

​
Content-Type
string
required
multipart/form-data

​
Request Body

​
file
file
required
Excel file (.xlsx) containing invoice data
The API processes the uploaded Excel file using FastAPI’s UploadFile mechanism, reads it into memory with pandas, and generates JSON invoice files for each row.

​
Excel File Requirements

The Excel file must contain the following columns:
​
Required Columns
object
Empty cells are automatically filled with empty strings. Date fields must be parseable by pandas. Numeric fields must contain valid numbers.

​
Data Processing

The API performs the following transformations:
1

Date Formatting

Dates are parsed with dayfirst=True and formatted to DD/MM/YYYY
2

Numeric Rounding

  • Bolivares amounts: Rounded to 2 decimals
  • USD amounts: Rounded to 0 decimals
  • VAT calculations: Rounded to 2 decimals (BSD) and 0 decimals (USD)
3

VAT Calculation

VAT = Total Amount - Subtotal (calculated separately for BSD and USD)
4

Amount to Words

Numeric amounts converted to Spanish words using num2words library
5

Random Navigation Data

Generates 5 random consumption values (1000-6000 range) with calculated average

​
Response Format

​
Content Type

​
Content-Type
string
application/zip

​
Response Headers

​
Content-Disposition
string
attachment; filename=FAC-YYYYMMDD.zip
Where YYYYMMDD is the current date (e.g., FAC-20250309.zip)
The API generates the ZIP file in memory using Python’s io.BytesIO and streams it back to the client without writing to disk.

​
ZIP File Structure

The response ZIP file contains a hierarchical folder structure: 
FAC-YYYYMMDD.zip
└── FAC-YYYYMMDD/
    ├── J408185431-YYYYMMDD-001/
    │   ├── 0000001.json
    │   ├── 0000002.json
    │   └── ... (up to 100 files)
    ├── J408185431-YYYYMMDD-002/
    │   ├── 0000101.json
    │   ├── 0000102.json
    │   └── ... (up to 100 files)
    └── J408185431-YYYYMMDD-NNN/
        └── ...
The structure groups invoices into batches of 100 files per folder for easier management.

​
Folder Naming Convention

​
Root Folder

​
Root Folder
string
FAC-YYYYMMDD
Where:
  • FAC = Fixed prefix for invoices
  • YYYYMMDD = Current date (e.g., 20250309)

​
Batch Folders

​
Batch Folder
string
J408185431-YYYYMMDD-NNN
Where:
  • J408185431 = Fixed company RIF/tax ID
  • YYYYMMDD = Current date
  • NNN = Batch number (zero-padded to 3 digits)

Batch Calculation

Batch number is calculated as: (row_index // 100) + 1Examples:
  • Rows 0-99 → Batch 001
  • Rows 100-199 → Batch 002
  • Rows 200-299 → Batch 003

​
Invoice File Naming

​
Invoice Filename
string
0NNNNNN.json
Where:
  • 0 = Fixed prefix
  • NNNNNN = Correlativo (invoice number) zero-padded to 6 digits

​
Examples

CorrelativoFilename
10000001.json
420000042.json
67460006746.json
1234560123456.json
correlativo = str(row["Correlativo"]).zfill(6)
filename = f"{folder}0{correlativo}.json"

​
JSON File Format

Each invoice JSON file contains a complete DocumentoElectronico object as described in the Invoice Document Structure page.

File Encoding

JSON files are written with:
  • 4-space indentation (indent=4)
  • UTF-8 encoding (ensure_ascii=False)
  • Pretty-printed for readability

​
Example File Content

0006746.json (abbreviated)
{
  "DocumentoElectronico": {
    "Encabezado": {
      "IdentificacionDocumento": {
        "TipoDocumento": "01",
        "NumeroDocumento": "6746",
        "FechaEmision": "09/09/2025",
        "TransaccionId": "FA6746",
        ...
      },
      "Comprador": {
        "TipoIdentificacion": "V",
        "NumeroIdentificacion": "14965208",
        "RazonSocial": "CARLOS ALBERTO SOLANO",
        ...
      },
      "Totales": {
        "MontoGravadoTotal": "4494.49",
        "TotalAPagar": "4494.49",
        ...
      },
      "TotalesOtraMoneda": {
        "Moneda": "USD",
        "TipoCambio": "154.9825",
        "TotalAPagar": "29.0",
        ...
      }
    },
    "DetallesItems": [
      {
        "NumeroLinea": "1",
        "Descripcion": "PLAN OPTIMO 300 MBPS",
        ...
      }
    ],
    "InfoAdicional": [
      {"Campo": "Contrato", "Valor": "2802"},
      ...
    ]
  }
}

​
Complete Request/Response Example

curl -X POST "http://api.example.com/process_excel" \
  -H "Content-Type: multipart/form-data" \
  -F "[email protected]" \
  -o "FAC-20250309.zip"

​
Response Processing

1

Receive ZIP File

The API returns a streaming response with the ZIP file
2

Extract Archive

Extract the ZIP file to access the folder structure
3

Process by Batch

Iterate through batch folders (J408185431-YYYYMMDD-NNN)
4

Load Invoice JSON

Parse each JSON file to access the DocumentoElectronico object
5

Integrate with Systems

Import invoice data into accounting, ERP, or invoicing systems
The API processes all rows in the Excel file. Ensure data is validated before upload to avoid generating incorrect invoices.

​
Error Handling

If the uploaded file is not a valid Excel file:
{
  "detail": "Error reading Excel file"
}
Status Code: 400 Bad Request
If required columns are missing from the Excel file:
KeyError: 'Correlativo'
Status Code: 500 Internal Server Error
If dates cannot be parsed:The fmt_fecha() function returns the original value or None if parsing fails, and processing continues.
If numeric fields contain non-numeric values:
ValueError: could not convert string to float
Status Code: 500 Internal Server Error
Validate Excel data before uploading to ensure:
  • All required columns are present
  • Dates are in recognizable formats
  • Numeric fields contain valid numbers
  • No missing critical data (Correlativo, Cliente, etc.)

Build docs developers (and LLMs) love

Get started for freeTalk to us