Skip to main content
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.

​
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
The Factus Challenge solves all of these problems in a single, deployable reference implementation.

​
Tech Stack

​
Backend (bc-v1/)

The backend is a Node.js 22 application built with the following packages: The entry point is 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

​
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.

​
License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0). See the repository root for the full license text.