Skip to content
Franklin Martinez
All work

dgii-ts

Open-source DGII validation & integration library for TypeScript

Abstract. dgii-ts is an open-source TypeScript library for working with Dominican tax identifiers like RNC, cédula, NCF, and e-NCF. It validates them and looks them up against the DGII, the country's tax authority.

Digit430587125
× Weight79865432
Product2827030402834
Sum 160160 mod 11 = 6Check digit: expected 5, got 5

RNC: digits 1 to 8 times weights 7, 9, 8, 6, 5, 4, 3, 2. The remainder of the sum over 11 gives the check digit.

validateRnc("430587125"){valid: true, formatted: "4-30-58712-5"}

Valid

Fig. 3. dgii-ts 0.3.0 from npm, imported by this page. The steps show the check-digit arithmetic; the verdict is the library's own. The example numbers are invented.

The problem

The DGII, the Dominican tax authority, has no public REST API, and it shut off its old SOAP service in January 2025. Anything that needs to check a Dominican RNC or NCF has leaned on scrapers of old ASP.NET pages whose URLs keep moving, which quietly breaks every integration that depends on them.

The design

dgii-ts hides all of that behind one typed client built in layers: offline check-digit validation for RNC, cédula, NCF (series B) and e-NCF (series E) that never touches the network; live lookups that scrape the DGII’s pages when you need current data; a client with a circuit breaker and retries with backoff, so one bad response doesn’t cascade; and a bulk import of the DGII’s daily RNC dataset.

Fig. 3 above is the library itself, imported from npm and running in this page. The check-digit arithmetic is drawn step by step, and the verdict is the library's own. A number that breaks the algorithm can still be real: dgii-ts carries whitelists of cédulas and RNCs that the DGII issued anyway, taken from python-stdnum.

What ships

npm install dgii-ts

On npm under MIT, with CI, plus an agent skill so a coding agent uses the offline validators before it reaches for the network.

Talk about this project