Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/4rt21/backend-proyecto/llms.txt

Use this file to discover all available pages before exploring further.

​
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": "user@example.com",
    "name": "John Doe",
    "password": "SecurePass123",
    "role_id": "1"
  }'
Response: 
{
  "user": {
    "id": 1,
    "email": "user@example.com",
    "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": "user@example.com",
    "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": "user@example.com",
      "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

CodeMeaningDescription
200OKRequest succeeded
201CreatedResource created successfully
400Bad RequestInvalid request parameters
401UnauthorizedMissing or invalid authentication
404Not FoundResource doesn’t exist
409ConflictResource 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

Verify your .env file has the correct MySQL credentials and that the MySQL service is running:
# Check MySQL status
sudo systemctl status mysql
Change the port by setting the PORT environment variable:
PORT=3001 npm run start:dev
Ensure you’re including the Bearer prefix:
Authorization: Bearer <token>
Check that your access token hasn’t expired (1 hour lifetime).
Each user must have a unique email. Use a different email address or delete the existing user from the database.

Build docs developers (and LLMs) love

Get started for freeTalk to us