Backend Setup: Configure and Run the Express Server

The bc-v1/ directory contains the Node.js backend for the Factus Challenge project. It is built on Express 4 and requires Node.js 22 or later. The server listens on port 4500 by default (overridable via the PORT environment variable), connects to a PostgreSQL database, and communicates with the Factus electronic invoicing API using OAuth 2.0 tokens managed by the src/auth/token.js module.

Prerequisites

Before running the backend, make sure you have the following installed and available:

Node.js ≥ 22 — the server uses the native --env-file and --watch flags introduced in Node 22
npm — bundled with Node.js
PostgreSQL — a running instance accessible from the machine where the backend will run

Installation

Navigate to the backend directory

All backend source code lives under bc-v1/. Move into it before running any commands.

cd bc-v1

Install dependencies

Install the five production dependencies with npm:

npm install

The following packages will be installed:

Package	Version	Purpose
`axios`	`^1.7.9`	HTTP client for Factus API requests
`express`	`^4.21.2`	Web framework and router
`morgan`	`^1.10.0`	HTTP request logger middleware
`pg`	`^8.13.1`	PostgreSQL client (`pg.Pool`)
`qs`	`^6.14.0`	Query-string serialization for OAuth form data

Create the .env file

The server loads environment variables from a .env file in the bc-v1/ root using Node’s native --env-file flag. Create the file and populate every variable before starting:

.env

# Server
PORT=4500

# Factus API
url_api=https://api-sandbox.factus.com.co
client_id=your_client_id
client_secret=your_client_secret
email=your_factus_email
password=your_factus_password
# refresh_token is written at runtime — leave blank on first run
refresh_token=

# PostgreSQL
DB_USER=postgres
DB_HOST=localhost
DB_NAME=factus_db
DB_PASSWORD=your_db_password
DB_SSL=false

refresh_token is optional at startup. token.js falls back to the password grant when it is absent and writes the received refresh_token directly into process.env for subsequent refreshes.

Start the development server

Run the dev script to start the server with hot reload:

npm run dev

You should see:

Running server in port:  4500
SÍ existe un refresh token   (or NO existe... on first run)

Available npm Scripts

The package.json exposes five scripts:

Script	Command	Description
`npm start`	`node ./src/main.js`	Production start — no hot reload, no env-file flag
`npm run dev`	`node --env-file .env --watch ./src/main.js`	Development mode with hot reload via `--watch`
`npm run fact`	`node --env-file .env ./src/controllers/factura.controller.js`	Run `factura.controller.js` as a standalone script
`npm run token`	`node --env-file .env --watch ./src/auth/token.js`	Run the token module standalone with hot reload
`npm test`	`node --env-file .env --watch ./src/helpers/helpers.mjs`	Run the helpers module standalone with hot reload

Use npm run dev during development. The --watch flag tells Node.js to automatically restart the process whenever any source file changes, eliminating the need for a separate file-watcher like nodemon.

Route Structure

The Express app mounts three routers, registered in order inside src/main.js:

Page Routes

GET /Served by page.routes.js → page.controller.js. Returns the frontend entry point.

Invoice Routes

/factura*Served by factura.routes.js. Handles all Factus API invoice operations (list, get, create, download, delete).

Database Query Routes

/get-data, /add-data, /get-join, /update-data, /deleteServed by querys.routes.js. Generic CRUD endpoints backed by pg.Pool.

Full Route Map

Method	Path	Router file	Description
`GET`	`/`	`page.routes.js`	Serve frontend
`GET`	`/factura`	`factura.routes.js`	List recent invoices
`GET`	`/factura/:number`	`factura.routes.js`	Get one invoice by number
`GET`	`/factura-download/:number`	`factura.routes.js`	Download invoice PDF (base64)
`POST`	`/factura`	`factura.routes.js`	Create and validate a new invoice
`DELETE`	`/factura/:reference_code`	`factura.routes.js`	Delete an unvalidated invoice
`GET`	`/get-data/:table`	`querys.routes.js`	Select all rows from a table
`POST`	`/add-data/:table`	`querys.routes.js`	Insert a row into a table
`POST`	`/get-join`	`querys.routes.js`	Execute a raw JOIN query
`PUT` / `PATCH`	`/update-data/:table/:property/:value`	`querys.routes.js`	Update rows matching a column value
`DELETE`	`/delete/:table/:property/:value`	`querys.routes.js`	Delete rows matching a column value

CORS Configuration

The backend applies a manual CORS middleware in main.js before any route is handled. It uses a wildcard origin so that the frontend can be served from any host during development:

app.use((req, res, next) => {
  res.header('Access-Control-Allow-Origin', '*');
  res.header('Access-Control-Allow-Methods', 'GET,POST,PUT,DELETE,PATCH');
  res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization');
  next();
});

The Authorization header is explicitly allowed because every Factus API proxy request includes a Bearer token forwarded from the client.

src/main.js — Full Source

src/main.js

import express from 'express';
import querys_route from './routes/querys.routes.js';
import morgan from 'morgan';
import factura_route from './routes/factura.routes.js';
import token from './auth/token.js';
import page_route from './routes/page.routes.js';

// Principal app
const app = express();
const port = process.env.PORT || 4500;

// Generar token de acceso
token();
// Escuchar puerto (localhost:4500)
app.listen(port, () => {
  console.log('Running server in port: ', port);
});

app.use((req, res, next) => {
  res.header('Access-Control-Allow-Origin', '*');
  res.header('Access-Control-Allow-Methods', 'GET,POST,PUT,DELETE,PATCH');
  res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization');
  next();
});

// Para que la API comprenda los "POST" con body JSON
app.use(express.json());

// "Debug", mostrar solicitudes realizadas
app.use(morgan('dev'));

app.use([querys_route, factura_route, page_route]);

Get Started

Backend

Frontend

Deployment

Backend Setup: Configure and Run the Express Server

Prerequisites

Installation

Available npm Scripts

Route Structure

Page Routes

Invoice Routes

Database Query Routes

Full Route Map

CORS Configuration

src/main.js — Full Source

​Prerequisites

​Installation

​Available npm Scripts

​Route Structure

Page Routes

Invoice Routes

Database Query Routes

​Full Route Map

​CORS Configuration

​src/main.js — Full Source

Prerequisites

Installation

Available npm Scripts

Route Structure

Full Route Map

CORS Configuration

src/main.js — Full Source