Skip to main content

​
Quickstart Guide

Get the Tanqueo Backend API up and running in just a few minutes.

​
Prerequisites

Before you begin, ensure you have:
  • Node.js 18.x or higher installed
  • PostgreSQL database (or Supabase account)
  • npm or yarn package manager
  • Git (optional, for cloning)

​
Installation

1

Clone or Download the Repository

If you have access to the source code repository:
git clone <repository-url> tanqueo-backend
cd tanqueo-backend
2

Install Dependencies

Install all required npm packages:
npm install
This will install:
  • Express.js for the web server
  • Supabase client for database and auth
  • TypeScript and development tools
  • CORS and middleware packages
3

Configure Environment Variables

Create a .env file in the root directory with your configuration:
.env
# Server Configuration
PORT=5000
FRONTEND_URL=http://localhost:3000

# Supabase Configuration
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key-here
The SUPABASE_URL and SUPABASE_ANON_KEY are required. The server will not start without them.
You can find your Supabase credentials in your Supabase project settings under API.
4

Build the TypeScript Code

Compile the TypeScript source to JavaScript:
npm run build
This creates the dist/ directory with compiled JavaScript files.
5

Start the Server

For production:
npm start
For development (with auto-reload):
npm run dev
You should see:
🚀 Servidor corriendo en puerto 5000
📊 Health check: http://localhost:5000/api/health

​
Verify Installation

Test that the server is running correctly: 
curl http://localhost:5000/api/health
Expected Response: 
{
  "status": "OK",
  "message": "Servidor funcionando correctamente",
  "timestamp": "2026-03-04T12:00:00.000Z"
}

​
Your First API Request

​
1. Authenticate

First, obtain an access token by logging in: 
curl -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'
Response: 
{
  "user": {
    "id": "uuid-here",
    "email": "[email protected]",
    "nombre": "John Doe",
    "rol": "admin"
  },
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "refresh-token-here",
  "expires_at": 1234567890,
  "expires_in": 3600
}
Save the access_token - you’ll need it for subsequent requests.

​
2. Make an Authenticated Request

Use the access token to fetch fuel records (tanqueos): 
curl http://localhost:5000/api/tanqueos?page=1&limit=10 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response: 
{
  "data": [
    {
      "id": 1,
      "fecha": "2026-03-04",
      "conductor": "Juan Pérez",
      "placa": "ABC123",
      "tipo_combustible": "DIESEL",
      "cantidad_galones": 50,
      "valor_tanqueo": 250000,
      "bomba": "Bomba Central",
      "area_operacion": "Zona Norte"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 150,
    "totalPages": 15
  }
}

​
3. Refresh Your Token

When your access token expires (default: 1 hour), refresh it: 
curl -X POST http://localhost:5000/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'

​
Common Configuration Options

​
CORS Configuration

The server is configured to accept requests from the frontend URL specified in .env: 
app.use(cors({
  origin: process.env.FRONTEND_URL || '*',
  credentials: true,
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Authorization']
}));

​
Port Configuration

Change the server port by setting the PORT environment variable: 
PORT=8080 npm start

​
Next Steps

Authentication Guide

Learn about JWT tokens, refresh mechanisms, and security

Architecture Overview

Understand the system architecture and design patterns

Data Models

Explore the TypeScript interfaces and data structures

Error Handling

Learn how to handle errors and status codes

​
Troubleshooting

​
Server Won’t Start

Error: SUPABASE_URL y SUPABASE_ANON_KEY deben estar definidos en .envSolution: Ensure your .env file contains both SUPABASE_URL and SUPABASE_ANON_KEY.
Error: EADDRINUSE: address already in useSolution: Either stop the process using port 5000, or change the PORT in your .env file.
Error: Build fails with TypeScript errorsSolution: Ensure you’re using TypeScript 5.9.3 or higher: npm install typescript@latest

​
Authentication Issues

  • 401 Unauthorized: Check that your token is valid and not expired
  • Invalid credentials: Verify your email and password are correct in Supabase Auth
  • User not found: Ensure the user exists in both Supabase Auth and the usuarios table

Build docs developers (and LLMs) love

Get started for freeTalk to us