Import Fuel Records

Endpoint

POST /api/tanqueos/import

Bulk import fuel records from spreadsheet data (typically from Excel files). This endpoint processes multiple records in a single request, validates each one, and provides detailed error reporting for any records that fail to import.

Authentication

Requires JWT authentication token. The authenticated user’s ID is automatically recorded as creado_por for all imported records.

Request Body

area_operacion_id

number

required

Operational area identifier to assign to all imported records

bomba_id

number

required

Fuel station identifier to assign to all imported records

records

array

required

Array of record objects to import. Each record should contain:

FECHA

string | number

required

Date in format DD/MM/YYYY or Excel serial date number

NOMBRE CONDUCTOR

string

Driver’s full name (matched against existing drivers)

PLACA

string

required

Vehicle plate (will be normalized to format ABC-123)

TIPO COMBUSTIBLE

string

Fuel type: ACPM, GASOLINA, or EXTRA. Defaults to GASOLINA if not specified

VALOR TANQUEO

string | number

required

Total fuel cost (can include thousand separators and currency symbols)

CANTIDAD GALONES

string | number

required

Quantity in gallons (can include decimal separators)

Response

imported

number

Number of records successfully imported

totalProcessed

number

Total number of records in the import file

errors

array

Array of error objects for records that failed to import

index

number

Zero-based index of the failed record in the input array

error

string

Brief error description

detail

string

Detailed error message with specific information

row

object

The original row data that failed to import

Examples

curl -X POST 'https://api.example.com/api/tanqueos/import' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  -H 'Content-Type: application/json' \
  -d '{
    "area_operacion_id": 2,
    "bomba_id": 7,
    "records": [
      {
        "FECHA": "15/03/2024",
        "NOMBRE CONDUCTOR": "JUAN CARLOS PEREZ",
        "PLACA": "ABC123",
        "TIPO COMBUSTIBLE": "ACPM",
        "VALOR TANQUEO": "$150,000",
        "CANTIDAD GALONES": "12.5"
      },
      {
        "FECHA": "15/03/2024",
        "NOMBRE CONDUCTOR": "MARIA GONZALEZ",
        "PLACA": "DEF-456",
        "TIPO COMBUSTIBLE": "GASOLINA",
        "VALOR TANQUEO": "95000",
        "CANTIDAD GALONES": "7.3"
      }
    ]
  }'

Import with Excel Serial Dates

curl -X POST 'https://api.example.com/api/tanqueos/import' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  -H 'Content-Type: application/json' \
  -d '{
    "area_operacion_id": 2,
    "bomba_id": 7,
    "records": [
      {
        "FECHA": 45361,
        "NOMBRE CONDUCTOR": "CARLOS LOPEZ",
        "PLACA": "GHI789",
        "TIPO COMBUSTIBLE": "ACPM",
        "VALOR TANQUEO": "180000",
        "CANTIDAD GALONES": "15.0"
      }
    ]
  }'

Success Response Example

Status Code: 200 OK

{
  "imported": 2,
  "totalProcessed": 3,
  "errors": [
    {
      "index": 2,
      "error": "Placa no encontrada",
      "detail": "La placa 'XYZ-999' (original: XYZ999) no existe en el sistema.",
      "row": {
        "FECHA": "15/03/2024",
        "NOMBRE CONDUCTOR": "PEDRO MARTINEZ",
        "PLACA": "XYZ999",
        "TIPO COMBUSTIBLE": "ACPM",
        "VALOR TANQUEO": "120000",
        "CANTIDAD GALONES": "10.0"
      }
    }
  ]
}

Data Processing

Plate Normalization

The system automatically normalizes vehicle plates:

ABC123 → ABC-123 (adds hyphen after 3 letters)
DEF 456 → DEF-456 (replaces space with hyphen)
GHI-789 → GHI-789 (no change needed)

For 6-character plates without hyphens, the hyphen is inserted after the 3rd character.

Date Parsing

Supports multiple date formats:

DD/MM/YYYY: “15/03/2024”
Excel serial number: 45361 (days since 1900-01-01)
ISO format: “2024-03-15”

All dates are converted to ISO format (YYYY-MM-DD) for storage.

Number Parsing

Handles various numeric formats:

With thousand separators: “150,000” or “150.000”
With currency symbols: “$150,000” or “COP 150000”
With decimal separators: “12.5” or “12,5”
Plain numbers: “150000”

All numbers are cleaned and converted to standard numeric format.

Driver Matching

Driver names are matched using a robust algorithm:

Convert to uppercase
Remove non-alphanumeric characters
Match against existing drivers in areas_conductores table
If no match found, conductor_id is set to null

Plate Matching

Plates are matched after normalization:

Normalize format (add hyphen if needed)
Convert to uppercase
Match against active plates in areas_placas table (estado = ‘ACTIVADA’)
If no match found, the record fails with a specific error

Validation Rules

Required Fields

Each record must include:

FECHA
PLACA
VALOR TANQUEO
CANTIDAD GALONES

Records missing any required field will fail with error: “Datos incompletos”

Plate Validation

The plate must:

Exist in the areas_placas table
Have status ACTIVADA
Match after normalization

Plate not found errors include the normalized plate format to help identify issues.

Numeric Validation

VALOR TANQUEO must be a valid positive number
CANTIDAD GALONES must be a valid positive number
Both fields accept decimal values

Automatic Calculations

For each imported record:

costo_por_galon: Calculated as valor_tanqueo / cantidad_galones
tipo_operacion: Set to “TANQUEO”
concepto: Set to “OPERATIVO”
creado_por: Set to authenticated user’s ID
tipo_combustible: Defaults to “GASOLINA” if not specified or empty

Error Handling

Common Errors

“Datos incompletos”: Missing required fields (FECHA, PLACA, or VALOR TANQUEO)
“Placa no encontrada”: Vehicle plate doesn’t exist or is not active
Parse errors: Invalid date or number formats
Database errors: Constraint violations or connection issues

Partial Success

The import operation processes all records and reports:

How many were successfully imported
How many failed with detailed error information
The original row data for each failed record

Successfully imported records are saved even if other records fail.

Implementation Notes

Performance

All records are validated before insertion
Catalog data (plates, drivers) is loaded once at the start
Uses in-memory maps for fast lookups
Batch insert for all valid records

Character Encoding

Handles Spanish characters (tildes, ñ) correctly
Converts all text to uppercase for matching
Removes accents and special characters for robust matching

Transaction Safety

Valid records are inserted in a single transaction
If the batch insert fails, all records in that batch are rolled back
Error records are never inserted

Excel Template Example

FECHA	NOMBRE CONDUCTOR	PLACA	TIPO COMBUSTIBLE	VALOR TANQUEO	CANTIDAD GALONES
15/03/2024	Juan Carlos Pérez	ABC-123	ACPM	$150,000	12.5
15/03/2024	María González	DEF456	GASOLINA	95000	7.3
16/03/2024	Carlos López	GHI-789	ACPM	180,000	15.0

Best Practices

Validate plates first: Ensure all vehicle plates exist in the system before importing
Use consistent formats: Stick to one date and number format throughout the file
Include driver names: Even though optional, it helps with record keeping
Review errors: Check the error array for any failed records and fix them
Test with small batches: Import a few records first to validate the format
Keep backup: Save the original file in case you need to re-import

Create Fuel Record - Create individual records
List Fuel Records - View imported records
Update Fuel Record - Fix imported records if needed

Authentication

Fuel Tracking

Lubrication Services

Fleet Management

Vehicle Documents

Maintenance

Budgets

Fuel Station Balances

Catalogs

File Upload

Import Fuel Records

Endpoint

Authentication

Request Body

Response

Examples