Skip to main content

​
Introduction

The Electronic Invoice Processing API is a FastAPI-based service that transforms Excel spreadsheets containing invoice data into structured JSON documents following the Venezuelan electronic invoice standard.

​
Base URL

http://localhost:8000

​
Authentication

Currently, this API does not require authentication. All endpoints are publicly accessible.
In a production environment, you should implement proper authentication mechanisms to secure your API endpoints.

​
Available Endpoints

The API currently provides one main endpoint:

POST /process_excel

Upload an Excel file and receive a ZIP archive containing structured JSON invoices

​
Rate Limiting

There are currently no rate limits enforced on API endpoints.
For production deployments, consider implementing rate limiting to prevent abuse and ensure service availability.

​
Response Format

The API returns responses in the following format:
  • Success Response: application/zip - A ZIP file containing organized JSON invoice documents
  • Error Response: application/json - Standard FastAPI error response with detail message

​
ZIP File Organization

The returned ZIP file is structured as follows: 
FAC-YYYYMMDD.zip
└── FAC-YYYYMMDD/
    ├── J408185431-YYYYMMDD-001/
    │   ├── 0000001.json
    │   ├── 0000002.json
    │   └── ... (up to 100 invoices per batch)
    ├── J408185431-YYYYMMDD-002/
    │   ├── 0000101.json
    │   └── ...
    └── ...
Invoices are automatically organized into batches of 100 documents, with each batch in a separate folder.

​
Error Handling

The API uses standard HTTP status codes:
Status CodeDescription
200Request successful - ZIP file returned
422Validation error - Invalid file format or missing required fields
500Internal server error - Processing failed

​
Error Response Structure

{
  "detail": "Error description"
}
Or for validation errors: 
{
  "detail": [
    {
      "loc": ["body", "file"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

​
CORS Configuration

The API is currently configured to accept requests from any origin (allow_origins=["*"]).
CORS settings (main.py:16-22):
  • Allowed Origins: * (all origins)
  • Allow Credentials: true
  • Allowed Methods: * (all methods)
  • Allowed Headers: * (all headers)
For production environments, restrict allow_origins to specific domains (e.g., ["http://localhost:3000"] or your frontend domain).

​
Data Processing

The API performs the following transformations:
  1. Excel Parsing: Reads uploaded Excel file using pandas
  2. Data Transformation: Converts each row into a structured JSON document following Venezuelan electronic invoice standards
  3. Calculations: Automatically calculates IVA (VAT), currency conversions, and amount-to-words conversions
  4. Batch Organization: Groups invoices into batches of 100 documents
  5. ZIP Generation: Creates an in-memory ZIP archive with organized JSON files

​
Supported Invoice Fields

The API expects Excel files with the following columns:
  • Correlativo (Invoice number)
  • Fecha Emision (Issue date)
  • Fecha Vencimiento (Due date)
  • Fecha Pago (Payment date)
  • Cliente (Customer name)
  • Documento (Document type)
  • DNI/C.I./C.C./IFE (ID number)
  • Dirección (Address)
  • Telefono (Phone)
  • Correo (Email)
  • Plan (Service description)
  • Total (Total in USD)
  • bolivares (Total in Bolivares)
  • bolivares sin iva (Bolivares without VAT)
  • precio sin iva (USD without VAT)
  • Tasa (Exchange rate)
  • Forma de Pago (Payment method)
  • ID Servicio (Service ID)

​
Next Steps

Process Excel Endpoint

View detailed endpoint documentation

Response Structure

Learn about the JSON invoice format

Build docs developers (and LLMs) love

Get started for freeTalk to us