Skip to main content
Factus Challenge is an open-source reference implementation that shows how to integrate with the Factus electronic invoicing API — including OAuth 2.0 token lifecycle management, invoice CRUD operations, and a generic PostgreSQL data layer. It was built as a response to the challenge proposed by Halltec and demonstrates a complete full-stack approach using Node.js, Express, PostgreSQL, and a vanilla-JS frontend.

Quickstart

Clone the repo, configure your environment, and send your first invoice in minutes.

Architecture

Understand how the backend, frontend, and Factus API fit together.

Backend Setup

Install dependencies, configure Express routes, and start the server.

API Reference

Explore every endpoint — invoices, clients, products, and database CRUD.

​
What’s Inside

OAuth 2.0 Auth

Automatic token refresh every 55 minutes using the password and refresh_token grant flows.

Invoice CRUD

Create, list, retrieve, download (PDF base64), and delete electronic invoices via the Factus API.

Generic DB Layer

Generic GET, POST, PUT/PATCH, and DELETE endpoints for any PostgreSQL table.

​
Get Running in 4 Steps

1

Clone and install

Clone the repository and install backend dependencies in the bc-v1/ directory.
2

Configure environment variables

Copy .env.example to .env and fill in your Factus API credentials and PostgreSQL connection details.
3

Start the backend

Run npm run dev — the server starts on port 4500 and immediately fetches an OAuth 2.0 access token.
4

Open the frontend

Point the frontend’s config.json at your backend URL and open index.html in a browser or serve it from Render.
This project targets the Factus sandbox environment (api-sandbox.factus.com.co). Switch url_api in your .env to api.factus.com.co when you are ready for production.