The Factus Challenge is an open-source project that demonstrates how to integrate Colombia’s Factus electronic invoicing API into a custom full-stack system, handling every stage from OAuth 2.0 token management to invoice creation, retrieval, and deletion through a clean REST backend and a browser-based frontend.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/tutosrive/factus_challenge/llms.txt
Use this file to discover all available pages before exploring further.
What Is the Factus Challenge?
This project was proposed by Halltec, a Colombian software company that operates the Factus electronic invoicing platform. The challenge asks developers to build a working system on top of the Factus API — not just poke at it from Postman or Insomnia, but to integrate it fully into a custom application with its own backend, database, and user interface. The core engineering challenge comes from Factus’s security model: every request to the API must carry a valid OAuth 2.0 Bearer token, which expires and must be silently refreshed in the background. The project also demonstrates how to build a supporting CRUD layer in PostgreSQL to manage the customers, products, and lookup tables that feed into each invoice.This is a sandbox/challenge project created for the Halltec developer challenge. It is intended for learning and demonstration purposes. Always review Factus’s official documentation and terms before using it in a production billing context.
The Problem It Solves
Connecting to a third-party API that uses OAuth 2.0 password-grant and refresh-token flows involves several non-trivial concerns:- Obtaining an initial access token using credentials (
email+password+client_id+client_secret) - Silently refreshing that token before it expires so in-flight requests never fail
- Forwarding properly authenticated requests to the Factus endpoints
- Storing and serving supporting relational data (customers, products, payment methods) from a local database
- Presenting all of this through a browser UI without exposing credentials to the client
Tech Stack
Backend (bc-v1/)
The backend is a Node.js 22 application built with the following packages:
| Package | Version | Purpose |
|---|---|---|
express | ^4.21.2 | HTTP server and routing |
axios | ^1.7.9 | HTTP client for Factus API requests |
pg | ^8.13.1 | PostgreSQL client (connection pool) |
morgan | ^1.10.0 | HTTP request logger middleware |
qs | ^6.14.0 | Query-string serialization for OAuth form posts |
bc-v1/src/main.js, which starts an Express server on port 4500, immediately fetches an OAuth 2.0 token, and then registers three route groups: factura, querys, and page.
Frontend (fr-v1/)
The frontend is a fully static, zero-build interface:
- Vanilla JavaScript — modular ES6 files loaded directly in the browser
- Bootstrap 5.3.3 (Vapor dark theme) — responsive layout and UI components, bundled locally in
fr-v1/resources/utils/ - Tabulator 6.3 — interactive data tables for invoices and database records, bundled locally in
fr-v1/resources/utils/ config.json— a single JSON file that points the frontend at the backend URL
Hosting
| Layer | Platform |
|---|---|
| Backend | Koyeb |
| Frontend | Render |
| PostgreSQL database | Azure Database for PostgreSQL |
Explore the Project
Quickstart
Clone the repo, configure your environment, and send your first invoice in under 10 minutes.
Architecture
Understand how the backend, database, frontend, and Factus API fit together.
Backend Setup
Detailed guide to configuring the Express server, environment variables, and PostgreSQL connection.
Invoice API
Browse the full reference for the
/factura endpoints exposed by the backend.