Installation

System Requirements

Before installing the Electronic Invoice Processing API, ensure your system meets these requirements:

Python Version

Python 3.9 or higher required

Disk Space

Minimum 200 MB for dependencies

RAM

At least 512 MB available memory

Operating System

Linux, macOS, or Windows

Installation Methods

pip (Recommended)
Docker
Manual Installation

Using pip and Virtual Environment

Clone the Repository

git clone <your-repository-url>
cd <repository-name>

Create Virtual Environment

Creating a virtual environment is recommended to isolate dependencies:

python3 -m venv venv
source venv/bin/activate

You should see (venv) or (invoice-api) in your terminal prompt after activation.

Install Dependencies

Install all required packages from requirements.txt:

pip install -r requirements.txt

This will install the following packages:

View All Dependencies

fastapi==0.100.0 - Modern web framework for building APIs
pandas==2.0.3 - Data manipulation and Excel file processing
openpyxl==3.1.2 - Excel file format support (.xlsx)
python-multipart==0.0.6 - File upload support for FastAPI
num2words==0.5.11 - Convert numbers to words in Spanish
uvicorn==0.23.2 - ASGI server for running FastAPI
numpy==1.25.2 - Numerical computing library (pandas dependency)

Verify Installation

Check that all dependencies are installed correctly:

python -c "import fastapi, pandas, openpyxl; print('All packages installed successfully!')"

Start the server to verify everything works:

uvicorn main:app --reload

Visit http://localhost:8000/docs to see the interactive API documentation.

Using Docker

Docker provides a containerized environment with all dependencies pre-configured.

Install Docker

Ensure Docker is installed on your system:

docker --version

If Docker is not installed, visit docker.com for installation instructions.

Clone the Repository

git clone <your-repository-url>
cd <repository-name>

Build the Docker Image

The project includes a Dockerfile based on Python 3.9-slim:

dockerfile:1-18

FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Build the image:

docker build -t invoice-api .

Run the Container

Docker
Docker Compose

Run the container directly:

docker run -d -p 8000:8000 --name invoice-api-container invoice-api

The API will be available at http://localhost:8000

Use docker-compose for easier management:

docker-compose.yml:1-10

version: '3.8'
services:
  web:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - .:/app
    command: uvicorn main:app --host 0.0.0.0 --port 8000

Start the service:

docker-compose up -d

Verify Container is Running

Check container status:

docker ps

View logs:

docker logs invoice-api-container
# or with docker-compose
docker-compose logs -f

Test the API:

curl http://localhost:8000/docs

The Docker container includes volume mounting (.:/app) which allows code changes to reflect immediately without rebuilding the image.

Manual Package Installation

If you prefer to install packages individually:

Install Core Framework

pip install fastapi==0.100.0 uvicorn==0.23.2

Install Data Processing Libraries

pip install pandas==2.0.3 numpy==1.25.2 openpyxl==3.1.2

Install Utility Packages

pip install python-multipart==0.0.6 num2words==0.5.11

Verify Installation

pip list | grep -E "fastapi|pandas|uvicorn"

Environment Configuration

The API uses FastAPI’s built-in configuration. Key settings are defined in the main application:

CORS Configuration

The API is configured with CORS middleware to allow cross-origin requests:

main.py:16-22

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # In production, specify allowed origins
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

For production environments, replace allow_origins=["*"] with specific domains like ["http://localhost:3000"] to enhance security.

Server Configuration

You can customize the server settings when starting Uvicorn:

uvicorn main:app --reload --host 127.0.0.1 --port 8000

Verification Steps

After installation, verify that the API is working correctly:

Check API Health

Start the server and visit the interactive documentation:

uvicorn main:app --reload

Open your browser to:

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

Test the Endpoint

Verify the /process_excel endpoint is available:

curl -X GET http://localhost:8000/docs

You should see the FastAPI documentation page.

Process a Sample File

Create a minimal Excel file with the required columns and test processing:

curl -X POST "http://localhost:8000/process_excel" \
  -F "file=@test_invoices.xlsx" \
  --output test_output.zip

If successful, you’ll receive a ZIP file containing the processed invoices.

Troubleshooting

ImportError: No module named 'fastapi'

This means FastAPI is not installed. Ensure you’ve activated your virtual environment and run:

pip install -r requirements.txt

Port 8000 is already in use

Another process is using port 8000. Either stop that process or use a different port:

uvicorn main:app --port 8001

Excel file processing fails

Ensure your Excel file:

Contains all required columns
Has the correct column names (case-sensitive)
Contains valid data types (dates as dates, numbers as numbers)
Is in .xlsx format (not .xls)

Docker container won't start

Check the container logs:

docker logs invoice-api-container

Common issues:

Port conflict (change port mapping: -p 8001:8000)
Missing files (ensure all files are copied correctly)
Permission issues (check file permissions)

Next Steps

Quickstart Guide

Learn how to process your first invoice in under 5 minutes

API Reference

Explore detailed API endpoint documentation

Excel Format

Learn about required Excel columns and data formats

Invoice Structure

Understand the electronic invoice JSON output format

Understanding the Dependencies

Core Framework

FastAPI: Modern, high-performance web framework for building APIs with automatic documentation
Uvicorn: Lightning-fast ASGI server implementation

Data Processing

pandas: Powerful data manipulation library for reading and processing Excel files
openpyxl: Engine for reading Excel 2010+ (.xlsx) files
numpy: Fundamental package for numerical operations (pandas dependency)

Utilities

python-multipart: Handles multipart form data for file uploads
num2words: Converts numeric amounts to Spanish words for invoice text fields (main.py:36-71)

The num2words library is specifically configured for Spanish (lang='es') to comply with Venezuelan electronic invoice requirements.

Getting Started

Core Concepts

Guides

System Requirements

Python Version

Disk Space

RAM

Operating System

Installation Methods

Using pip and Virtual Environment

Using Docker

Manual Package Installation

Environment Configuration

CORS Configuration

Server Configuration

Verification Steps

Troubleshooting

Next Steps

Quickstart Guide

API Reference

Excel Format

Invoice Structure

Understanding the Dependencies

Core Framework

Data Processing

Utilities

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Guides

​System Requirements

Python Version

Disk Space

RAM

Operating System

​Installation Methods

​Using pip and Virtual Environment

​Using Docker

​Manual Package Installation

​Environment Configuration

​CORS Configuration

​Server Configuration

​Verification Steps

​Troubleshooting

​Next Steps

Quickstart Guide

API Reference

Excel Format

Invoice Structure

​Understanding the Dependencies

​Core Framework

​Data Processing

​Utilities

Build docs developers (and LLMs) love

System Requirements

Installation Methods

Using pip and Virtual Environment

Using Docker

Manual Package Installation

Environment Configuration

CORS Configuration

Server Configuration

Verification Steps

Troubleshooting

Next Steps

Understanding the Dependencies

Core Framework

Data Processing

Utilities