Quickstart

Get started with the FalconAlert API in minutes - from installation to your first API call

Quickstart Guide

This guide will walk you through setting up the FalconAlert API and making your first authenticated request.

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js v18 or higher
• npm (comes with Node.js)
• MySQL 8.0 or higher
• Git for cloning the repository
• A code editor like VS Code

Installation

1. Clone the Repository

   Clone the FalconAlert backend repository to your local machine:

   git clone https://github.com/4rt21/backend-proyecto.git
   cd backend-proyecto
   
2. Install Dependencies

   Install all required npm packages:

   npm install
   

   This will install key dependencies including:

   • @nestjs/core - NestJS framework
   • @nestjs/jwt - JWT authentication
   • mysql2 - MySQL database driver
   • class-validator - Request validation
   • And many more…
3. Set Up MySQL Database

   Create the database and import the schema:

   # Restore the database from backup
   mysql -u <your_username> -p Ofraud < backup.sql
   

   This creates the Ofraud database with all necessary tables for users, reports, categories, upvotes, and notifications.

4. Configure Environment Variables

   Create a .env file in the root directory:

   touch .env
   

   Add your MySQL configuration:

   MYSQL_HOST="localhost"
   MYSQL_PORT=3306
   MYSQL_USER="<your_user>"
   MYSQL_PASSWORD="<your_password>"
   MYSQL_DB="Ofraud"
   

   Replace <your_user> and <your_password> with your MySQL credentials.

5. Start the Server

   Launch the development server:

   # Development mode with hot reload
   npm run start:dev
   
   # Production mode
   npm run start:prod
   

   You should see output indicating the server is running:

   [Nest] 12345  - Application is running on: http://localhost:3000
   
6. Verify Installation

   Open your browser and navigate to the Swagger documentation:

   http://localhost:3000/docs
   

   You should see the interactive API documentation with all available endpoints.

Making Your First API Call

Let’s walk through a complete authentication flow and make your first authenticated request.

1. Register a New User

Create a new user account by sending a POST request to /users/register:

curl -X POST http://localhost:3000/users/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "name": "John Doe",
    "password": "SecurePass123",
    "role_id": "1"
  }'

Response:

{
  "user": {
    "id": 1,
    "email": "[e-mail]",
    "name": "John Doe",
    "username": "happy_john842",
    "image_path": "profile-pictures/default.jpg",
    "role_id": 1,
    "created_at": "2026-03-04T10:30:00.000Z"
  },
  "settings": {
    "is_reactions_enabled": 1,
    "is_review_enabled": 1,
    "is_reports_enabled": 1,
    "is_anonymous_reports_enabled": 0
  }
}

Role IDs:

• 1 = Mobile user
• 2 = Web/Admin user

Usernames are automatically generated with a creative format like happy_john842.

2. Login and Get Tokens

Authenticate with your credentials to receive JWT tokens:

curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "password": "SecurePass123",
    "type": "mobile"
  }'

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIiwidHlwZSI6ImFjY2VzcyIsInByb2ZpbGUiOnsiaWQiOiIxIiwiZW1haWwiOiJ1c2VyQGV4YW1wbGUuY29tIiwibmFtZSI6IkpvaG4gRG9lIiwicm9sZV9pZCI6MX0sImlhdCI6MTcwOTU1MDAwMCwiZXhwIjoxNzA5NTUzNjAwfQ.signature",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIiwidHlwZSI6InJlZnJlc2giLCJpYXQiOjE3MDk1NTAwMDAsImV4cCI6MTcxMDE1NDgwMH0.signature"
}

Store these tokens securely. The accessToken expires in 1 hour, while the refreshToken lasts 7 days.

3. Make an Authenticated Request

Use your access token to fetch your user profile:

curl http://localhost:3000/auth/profile \
  -H "Authorization: Bearer <your_access_token>"

Response:

{
  "profile": {
    "profile": {
      "id": "1",
      "email": "[e-mail]",
      "name": "John Doe",
      "role_id": 1
    }
  }
}

4. Create Your First Report

Now let’s create a fraud report:

curl -X POST http://localhost:3000/users/report \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Suspicious phishing website",
    "description": "This website is impersonating a legitimate bank and requesting login credentials.",
    "report_url": "https://fake-bank-site.com",
    "category": [1, 5],
    "is_anonymous": 0
  }'

Response:

{
  "reportId": 48,
  "report_category": [1, 5]
}

Categories represent different types of fraud:

• 1 = Phishing
• 2 = Fake e-commerce
• 3 = Investment scams
• 4 = Tech support fraud
• 5 = General fraud

5. Retrieve All Reports

Fetch a list of all reports (with optional filtering):

# Get all reports
curl http://localhost:3000/reports

# Get only pending reports (status_id=1)
curl "http://localhost:3000/reports?status=1"

# Get reports with pagination
curl "http://localhost:3000/reports?page=1"

Response:

[
  {
    "id": 1,
    "title": "Suspicious phishing website",
    "image": "report-pictures/abc123.jpg",
    "description": "This website is impersonating a legitimate bank...",
    "created_at": "2026-03-04T10:35:00.000Z",
    "updated_at": "2026-03-04T10:35:00.000Z",
    "user_name": "John Doe",
    "created_by": 1,
    "user_image": "profile-pictures/default.jpg",
    "report_url": "https://fake-bank-site.com",
    "categories": [1, 5]
  }
]

Common Status Codes

Code	Meaning	Description
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid authentication
404	Not Found	Resource doesn’t exist
409	Conflict	Resource already exists (e.g., duplicate email)

Next Steps

Now that you have the API running:

Authentication Guide

Learn about JWT tokens, refresh flows, and securing endpoints

API Reference

Explore all available endpoints and their parameters

Swagger Documentation

Visit http://localhost:3000/docs for interactive API testing

WebSocket Events

Set up real-time notifications for reports

Troubleshooting

Database connection failed

Verify your .env file has the correct MySQL credentials and that the MySQL service is running:

# Check MySQL status
sudo systemctl status mysql

Port 3000 already in use

Change the port by setting the PORT environment variable:

PORT=3001 npm run start:dev

Invalid token errors

Ensure you’re including the Bearer prefix:

Authorization: Bearer <token>

Check that your access token hasn’t expired (1 hour lifetime).

Email already exists

Each user must have a unique email. Use a different email address or delete the existing user from the database.