firmeapi

FirmeAPI Node.js SDK

Official Node.js/TypeScript SDK for FirmeAPI.ro - Romanian company data API.

Installation

npm install firmeapi

Quick Start

import FirmeApi from 'firmeapi';

const client = new FirmeApi({
  apiKey: 'your_api_key_here',
});

// Get company details
const company = await client.getCompany('12345678');
console.log(company.denumire);

Sandbox Mode

Use sandbox mode to test your integration without consuming credits:

const client = new FirmeApi({
  apiKey: 'your_api_key_here',
  sandbox: true,
});

// Test CUIs available in sandbox:
// 00000001 - Active company with all data
// 00000002 - Inactive/deleted company
// 00000003 - Company with multiple VAT periods
// 00000004 - Company with ANAF debts
// 00000005 - Company with MOF publications
// 99999999 - Returns 404 (for testing errors)

API Methods

getCompany(cui: string): Promise<Company>

Get detailed company information by CUI.

const company = await client.getCompany('12345678');

console.log(company.denumire);           // Company name
console.log(company.stare);              // Registration status
console.log(company.tva.platitor);       // VAT payer status
console.log(company.adresa_sediu_social); // Headquarters address

getBilant(cui: string): Promise<Bilant>

Get company balance sheet data.

const bilant = await client.getBilant('12345678');

for (const year of bilant.ani) {
  console.log(`${year.an}:`);
  console.log(`  Revenue: ${year.detalii.I1} RON`);
  console.log(`  Profit: ${year.detalii.I5} RON`);
  console.log(`  Employees: ${year.detalii.I10}`);
}

getRestante(cui: string): Promise<RestanteResponse>

Get company ANAF debts.

const restante = await client.getRestante('12345678');

if (restante.restante.length > 0) {
  console.log('Company has outstanding debts:');
  for (const debt of restante.restante) {
    console.log(`  ${debt.tip_obligatie}: ${debt.suma_restanta} RON`);
  }
}

getMof(cui: string): Promise<MofResponse>

Get company Monitorul Oficial publications.

const mof = await client.getMof('12345678');

for (const publication of mof.rezultate) {
  console.log(`${publication.data}: ${publication.titlu_publicatie}`);
}

searchCompanies(filters: SearchFilters): Promise<SearchResponse>

Search companies with filters.

const results = await client.searchCompanies({
  judet: 'B',           // County code
  caen: '6201',         // CAEN code
  tva: true,            // VAT payer only
  telefon: true,        // Has phone number
  data_start: '2024-01-01',
  data_end: '2024-12-31',
  page: 1,
});

console.log(`Found ${results.pagination.total} companies`);

for (const company of results.items) {
  console.log(`${company.cui}: ${company.denumire}`);
}

getAdministratori(cui: string)

Get company administrators and legal representatives.

const admins = await client.getAdministratori('12345678');

getPuncteLucru(filters)

Search work points (secondary offices) with filters.

const puncte = await client.getPuncteLucru({ judet: 'CJ', caen: '4711', page: 1 });

getArr(cui: string)

Get ARR transport licenses (freight, passengers, own account).

const arr = await client.getArr('36731044');

getAlternativ(cui: string)

Get alternative transport authorizations.

const alt = await client.getAlternativ('51608780');

getBpiCui(cui: string, options?)

Get BPI insolvency publications by CUI. Premium credits required.

const bpi = await client.getBpiCui('16970632', { page: 1, include_document: true });

getBpiDosar(numarDosar: string, options?)

Get BPI publications by case number.

const bpi = await client.getBpiDosar('103/89/2014');

getBpiSearch(query: string, options?)

Search BPI publications by text.

const bpi = await client.getBpiSearch('lichidator');

getBpiByNumber(numarBpi: string, options?)

Get BPI publication by BPI number.

const bpi = await client.getBpiByNumber('17605/2022');

getDosare(filters)

Get court cases with filters.

const dosare = await client.getDosare({
  cui: '53509960',
  categorie: 'Civil',
  is_finished: true,
  page: 1,
});

getFreeCompany(cui: string): Promise<FreeCompany>

Get basic company info using the free API (no API key required, rate limited).

const company = await client.getFreeCompany('12345678');
console.log(company.denumire);

Error Handling

The SDK throws typed errors for different scenarios:

import FirmeApi, {
  AuthenticationError,
  NotFoundError,
  RateLimitError,
  InsufficientCreditsError,
  ValidationError,
} from 'firmeapi';

try {
  const company = await client.getCompany('12345678');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Company not found');
  } else if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof InsufficientCreditsError) {
    console.log(`Not enough credits. Have: ${error.availableCredits}, need: ${error.requiredCredits}`);
  } else if (error instanceof ValidationError) {
    console.log(`Invalid input: ${error.message}`);
  }
}

Configuration Options

const client = new FirmeApi({
  apiKey: 'your_api_key',     // Required
  sandbox: false,              // Enable sandbox mode (default: false)
  baseUrl: 'https://...',      // Custom base URL (default: https://firmeapi.ro/api)
  timeout: 30000,              // Request timeout in ms (default: 30000)
});

TypeScript Support

Full TypeScript support with exported types:

import type {
  Company,
  Bilant,
  RestanteResponse,
  MofResponse,
  SearchFilters,
  SearchResponse,
} from 'firmeapi';

License

MIT