Skip to main content

​
Welcome

This quickstart guide will help you start processing invoices from Excel files to JSON format in minutes. The API transforms invoice data into structured electronic documents compliant with Venezuelan tax regulations.
1

Clone the Repository

Clone the project from your repository:
git clone <your-repository-url>
cd <repository-name>
2

Install Dependencies

Install the required Python packages:
pip install -r requirements.txt
Make sure you have Python 3.9 or higher installed on your system.
3

Start the Server

Launch the FastAPI server using Uvicorn:
uvicorn main:app --host 0.0.0.0 --port 8000
You should see output similar to:
INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
The API is now running at http://localhost:8000
4

Prepare Your Invoice Data

Create an Excel file with your invoice data. The file must include these columns:
  • Correlativo - Invoice number
  • Fecha Emision - Emission date
  • Fecha Vencimiento - Due date
  • Fecha Pago - Payment date
  • bolivares - Total amount in bolivares
  • Total - Total amount in USD
  • bolivares sin iva - Amount without VAT in bolivares
  • precio sin iva - Amount without VAT in USD
  • Tasa - Exchange rate
  • Documento - Document type
  • DNI/C.I./C.C./IFE - Customer ID number
  • Cliente - Customer name
  • Dirección - Customer address
  • Telefono - Customer phone
  • Correo - Customer email
  • Plan - Service plan description
  • ID Servicio - Service/Contract ID
  • Forma de Pago - Payment method
Save your file as invoices.xlsx
5

Process Your First Invoice

Send a POST request to process your Excel file:
curl -X POST "http://localhost:8000/process_excel" \
  -F "[email protected]" \
  --output invoices.zip
Replace invoices.xlsx with the path to your actual Excel file.
6

View the Results

Extract and view the generated invoice files:
unzip invoices.zip
The ZIP file contains a folder structure like:
FAC-20260304/
└── J408185431-20260304-001/
    ├── 0000001.json
    ├── 0000002.json
    └── ...
Each JSON file represents a processed electronic invoice with the following structure:
main.py:94-120
{
  "DocumentoElectronico": {
    "Encabezado": {
      "IdentificacionDocumento": {
        "TipoDocumento": "01",
        "NumeroDocumento": "000001",
        "FechaEmision": "04/03/2026",
        "FechaVencimiento": "04/04/2026",
        "HoraEmision": "10:00:00 am",
        "TipoDePago": "Inmediato",
        "Serie": "",
        "Sucursal": "002",
        "TipoDeVenta": "Interna",
        "Moneda": "BSD",
        "TransaccionId": "FA000001"
      },
      "Comprador": { ... },
      "Totales": { ... },
      "TotalesOtraMoneda": { ... }
    },
    "DetallesItems": [ ... ],
    "InfoAdicional": [ ... ]
  }
}

​
What’s Next?

Installation Guide

Learn about advanced installation methods including Docker and virtual environments

API Reference

Explore the complete API documentation and endpoint details

​
Need Help?

If you encounter issues with file processing, ensure your Excel file contains all required columns and that date fields are properly formatted.
The API automatically:
  • Converts amounts to words in Spanish
  • Calculates IVA (VAT) at 16%
  • Generates random navigation metrics
  • Groups invoices into batches of 100
  • Creates proper folder structures for electronic document submission

Build docs developers (and LLMs) love

Get started for freeTalk to us