README

Official PHP SDK for FirmeAPI.ro - Romanian company data API.

Requirements

• PHP 8.1 or higher
• cURL extension
• JSON extension

Installation

composer require firmeapi/firmeapi-php

Quick Start

use FirmeApi\FirmeApi;

$client = new FirmeApi('your_api_key_here');

// Get company details
$company = $client->getCompany('12345678');
echo $company['denumire'];

Sandbox Mode

Use sandbox mode to test your integration without consuming credits:

$client = new FirmeApi('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(string $cui): array

Get detailed company information by CUI.

$company = $client->getCompany('12345678');

echo $company['denumire'];              // Company name
echo $company['stare'];                 // Registration status
echo $company['tva']['platitor'];       // VAT payer status
print_r($company['adresa_sediu_social']); // Headquarters address

getBilant(string $cui): array

Get company balance sheet data.

$bilant = $client->getBilant('12345678');

foreach ($bilant['ani'] as $year) {
    echo "{$year['an']}:\n";
    echo "  Revenue: {$year['detalii']['I1']} RON\n";
    echo "  Profit: {$year['detalii']['I5']} RON\n";
    echo "  Employees: {$year['detalii']['I10']}\n";
}

getRestante(string $cui): array

Get company ANAF debts.

$restante = $client->getRestante('12345678');

if (!empty($restante['restante'])) {
    echo "Company has outstanding debts:\n";
    foreach ($restante['restante'] as $debt) {
        echo "  {$debt['tip_obligatie']}: {$debt['suma_restanta']} RON\n";
    }
}

getMof(string $cui): array

Get company Monitorul Oficial publications.

$mof = $client->getMof('12345678');

foreach ($mof['rezultate'] as $publication) {
    echo "{$publication['data']}: {$publication['titlu_publicatie']}\n";
}

searchCompanies(array $filters = []): array

Search companies with filters.

$results = $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,
]);

echo "Found {$results['pagination']['total']} companies\n";

foreach ($results['items'] as $company) {
    echo "{$company['cui']}: {$company['denumire']}\n";
}

getAdministratori(string $cui): array

$admins = $client->getAdministratori('12345678');

getPuncteLucru(array $filters = []): array

$puncte = $client->getPuncteLucru(['judet' => 'CJ', 'caen' => '4711']);

getArr(string $cui): array

$arr = $client->getArr('36731044');

getAlternativ(string $cui): array

$alt = $client->getAlternativ('51608780');

getBpiCui(string $cui, array $options = []): array

BPI insolvency publications by CUI. Premium credits required.

$bpi = $client->getBpiCui('16970632', ['page' => 1, 'include_document' => true]);

getBpiDosar(string $numarDosar, array $options = []): array

$bpi = $client->getBpiDosar('103/89/2014');

getBpiSearch(string $query, array $options = []): array

$bpi = $client->getBpiSearch('lichidator');

getBpiByNumber(string $numarBpi, array $options = []): array

$bpi = $client->getBpiByNumber('17605/2022');

getDosare(array $filters = []): array

$dosare = $client->getDosare(['cui' => '53509960', 'categorie' => 'Civil']);

getFreeCompany(string $cui): array

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

$company = $client->getFreeCompany('12345678');
echo $company['denumire'];

Error Handling

The SDK throws typed exceptions for different scenarios:

use FirmeApi\FirmeApi;
use FirmeApi\Exceptions\AuthenticationException;
use FirmeApi\Exceptions\NotFoundException;
use FirmeApi\Exceptions\RateLimitException;
use FirmeApi\Exceptions\InsufficientCreditsException;
use FirmeApi\Exceptions\ValidationException;
use FirmeApi\Exceptions\FirmeApiException;

try {
    $company = $client->getCompany('12345678');
} catch (NotFoundException $e) {
    echo "Company not found\n";
} catch (AuthenticationException $e) {
    echo "Invalid API key\n";
} catch (RateLimitException $e) {
    echo "Rate limited. Retry after {$e->getRetryAfter()} seconds\n";
} catch (InsufficientCreditsException $e) {
    echo "Not enough credits. Have: {$e->getAvailableCredits()}, need: {$e->getRequiredCredits()}\n";
} catch (ValidationException $e) {
    echo "Invalid input: {$e->getMessage()}\n";
} catch (FirmeApiException $e) {
    echo "API error: {$e->getMessage()}\n";
}

Configuration Options

$client = new FirmeApi('your_api_key', [
    'sandbox' => false,                    // Enable sandbox mode (default: false)
    'baseUrl' => 'https://firmeapi.ro/api', // Custom base URL
    'timeout' => 30,                        // Request timeout in seconds (default: 30)
]);

Laravel Integration

You can easily integrate with Laravel using a service provider:

// config/services.php
return [
    'firmeapi' => [
        'key' => env('FIRMEAPI_KEY'),
        'sandbox' => env('FIRMEAPI_SANDBOX', false),
    ],
];

// app/Providers/AppServiceProvider.php
use FirmeApi\FirmeApi;

public function register(): void
{
    $this->app->singleton(FirmeApi::class, function () {
        return new FirmeApi(
            config('services.firmeapi.key'),
            ['sandbox' => config('services.firmeapi.sandbox')]
        );
    });
}

// Usage in controllers
public function show(FirmeApi $firmeApi, string $cui)
{
    $company = $firmeApi->getCompany($cui);
    return response()->json($company);
}

License

MIT