factus-js

TypeScript/JavaScript SDK for the Factus API for Colombian e-invoicing.

Full documentation: https://factusjs.vercel.app

Features

• Full coverage of Factus API domains: bills, credit notes, support documents, adjustment notes, RADIAN reception, numbering ranges, catalogs, and more.
• Automatic OAuth2 authentication with refresh and one-time retry on expired token.
• Strong TypeScript typing for payloads and responses.
• Typed DIAN constants (PaymentFormCode, IdentityDocumentTypeId, and more) as direct value maps.
• Automatic pagination iterator with listAll() for paginated modules.
• AbortSignal support and client-level timeout.
• Runtime compatibility with Node.js >= 18, Deno, and Bun.
• Zero runtime dependencies.

Installation

# npm
npm install factus-js

# yarn
yarn add factus-js

# pnpm
pnpm add factus-js

# bun
bun add factus-js

Basic usage

import {
  FactusClient,
  PaymentFormCode,
  PaymentMethodCode,
  IdentityDocumentTypeId,
  OrganizationTypeId,
  CustomerTributeId,
  ProductStandardId,
} from "factus-js";

const factus = new FactusClient({
  clientId: process.env.FACTUS_CLIENT_ID!,
  clientSecret: process.env.FACTUS_CLIENT_SECRET!,
  username: process.env.FACTUS_USERNAME!,
  password: process.env.FACTUS_PASSWORD!,
  environment: "sandbox", // use "production" for live usage
});

const invoice = await factus.bills.create({
  numbering_range_id: 8,
  reference_code: "INV-001",
  payment_form: PaymentFormCode.CreditPayment,
  payment_due_date: "2026-12-31",
  payment_method_code: PaymentMethodCode.Cash,
  customer: {
    identification_document_id: IdentityDocumentTypeId.CitizenshipId,
    identification: "123456789",
    names: "Alan Turing",
    address: "Calle 1 # 2-68",
    email: "[email protected]",
    phone: "1234567890",
    legal_organization_id: OrganizationTypeId.NaturalPerson,
    tribute_id: CustomerTributeId.NotApplicable,
    municipality_id: 980,
  },
  items: [
    {
      code_reference: "PROD-001",
      name: "Test product",
      quantity: 1,
      discount_rate: 0,
      price: 50000,
      tax_rate: "19.00",
      unit_measure_id: 70,
      standard_code_id: ProductStandardId.TaxpayerAdoption,
      is_excluded: 0,
      tribute_id: 1,
    },
  ],
});

console.log(invoice.data);

Available modules

| Module | Description | | ------------------------- | ----------------------------------------------- | | factus.bills | Electronic sales invoices | | factus.creditNotes | Credit notes | | factus.supportDocuments | Support documents | | factus.adjustmentNotes | Adjustment notes for support documents | | factus.reception | RADIAN reception and invoice events | | factus.company | Company data | | factus.numberingRanges | DIAN numbering ranges | | factus.subscription | Subscription and quota status | | factus.catalog | Municipalities, countries, tributes, and others |

DIAN constants

Constants are direct typed values. Use them directly in payloads, without .value.

import {
  PaymentFormCode,
  PaymentMethodCode,
  IdentityDocumentTypeId,
  OrganizationTypeId,
  CustomerTributeId,
  ProductStandardId,
  EventCode,
  PaymentFormCodeInfo,
  IdentityDocumentTypeIdInfo,
} from "factus-js";

const paymentForm = PaymentFormCode.CreditPayment;
const paymentLabel = PaymentFormCodeInfo[paymentForm].description;

Error handling

import { FactusClient, FactusError } from "factus-js";

try {
  await factus.bills.create({
    // ...
  });
} catch (error) {
  if (error instanceof FactusError) {
    console.error(error.statusCode);
    console.error(error.message);
    console.error(error.validationErrors);
  }
}

Exports

import {
  FactusClient,
  FactusError,
  PaymentMethodCode,
  PaymentFormCode,
  IdentityDocumentTypeId,
  PaymentFormCodeInfo,
  IdentityDocumentTypeIdInfo,
  type RequestOptions,
  type FactusClientConfig,
} from "factus-js";

License

MIT