Ново: TheTenderBook — мониторинг на обществени поръчки с интелигентни препоръки
Разберете повече

Общо

RESTful API за българския търговски регистър

Допълнителни ресурси за разработчици

Контекстни файлове за LLM: За разработчици, използващи AI асистенти (като Claude, ChatGPT и други), предлагаме контекстни файлове: llms.txt (кратка версия) и llms-full.txt (пълна документация). Тези файлове могат да бъдат заредени в AI модели за по-добра интеграция и разбиране на API структурата.

REST API за достъп до данни за над 1 300 000 български компании. Безплатните API ключове включват обичайно търсене, справки за фирми и лица и 100 заявки/ден. Платеният абонамент отключва премиум филтри за търсене на фирми, финансово сортиране, най-новите финансови данни и по-високи лимити.

Основни възможности

Търсене на фирми по ЕИК, име, област
Търсене на лица по име и идентификатор
Детайлна информация за фирми
История на промените
JSON формат на данните
Бързо и надеждно API
Обединено търсене
Ясни безплатни и платени нива на достъп

Автентикация

Клиентските API заявки изискват валиден API ключ. Безплатните акаунти могат да създадат API ключ; платеният абонамент отключва премиум API функционалности. Ключът се предава чрез HTTP хедър:

X-API-Key: your_api_key_here

1. Регистрирайте се безплатно на companybook.bg/sign-up

2. Вземете своя API ключа от профила си

Дневни лимити на заявки

Безплатни API ключове: 100 заявки на ден
Платени API ключове: 3 000 заявки на ден
Лимитите се нулират всеки ден в полунощ (EET/EEST)

Формат на отговора

Всички отговори са в JSON формат с консистентна структура:

{
  "results": [...],
  "total": 1234
}

Структура на обекти

Структура на обектите, които API-то връща

Юридическо лице (Company)

Основни данни (with_data=false)

{
  "uic": "123456789",                    // ЕИК на юридическо лицета
  "name": "Example Ltd",                 // Наименование
  "legalForm": "ООД",                    // Правна форма
  "status": "N",                         // Статус (N=активна, L=ликвидирана)
  "transliteration": "Example OOD"       // Транслитерация
}

Пълни данни (with_data=true)

{
  "company": {
    // Основна информация
    "id": "507f1f77bcf86cd799439011",
    "uic": "123456789",
    "companyName": {
      "name": "Example Ltd",
      "name_tags": ["exa", "xam"]
    },
    "companyNameTransliteration": {
      "name": "Example OOD"
      "name_tags": ["exa", "xam]
    },
    "legalForm": "Дружество с ограничена отговорност",
    "status": "N",

    // Адреси
    "seat": {
      "country": "България",
      "region": "София",
      "district": "София (столица)",
      "municipality": "София",
      "settlement": "София",
      "area": "Център",
      "street": "ул. Витоша",
      "streetNumber": "15",
      "block": "2",
      "entrance": "А",
      "floor": "3",
      "apartment": "5",
      "postCode": "1000",
      "districtid": 1
    },
    "correspondenceSeat": { /* същата структура */ },

    // Контакти
    "contacts": {
      "email": "contact@example.com",
      "phone": "+359 2 123 4567",
      "fax": "+359 2 123 4568",
      "website": "https://example.com"
    },

    // Дейност
    "subjectOfActivity": "Консултантски услуги",
    "nkids": [
      {
        "code": "62.02",
        "description": "Дейности в областта на информационните технологии",
        "id": "nkid123"
      }
    ],

    // Мениджмънт
    "managers": [
      {
        "name": "Иван Петров",
        "indent": "1234567890",
        "address": "София, ул. Витоша 1"
      }
    ],
    "representatives": [ /* същата структура */ ],
    "boardOfDirectors": [ /* същата структура */ ],

    // Финансова информация
    "capital": {
      "amount": "2000",
      "currency": "BGN",
      "paidAmount": "2000"
    },

    // Собственост
    "partners": [
      {
        "person": {
          "name": "Иван Петров",
          "indent": "1234567890",
          "address": "София"
        },
        "liabilityType": "ограничена",
        "contribution": "1000 BGN"
      }
    ],

    // ДДС регистрация
    "registerInfo": {
      "name": "Example Ltd",
      "vat": "BG123456789",
      "address": "София, ул. Витоша 1",
      "registrationDate": "2020-01-15"
    },

    // Метаданни
    "lastUpdated": "2024-01-15T10:30:00Z"
  },

  // История на промените
  "history": [
    {
      "deedUIC": "123456789",
      "timestamp": "2024-01-15T10:30:00Z",
      "changeType": "address_change",
      "field": "seat.address",
      "oldValue": "ул. Стара 5",
      "newValue": "ул. Витоша 1"
    }
  ],

  // Дъщерни фирми
  "daughters": [
    {
      "uic": "987654321",
      "company_name": {
        "name": "Subsidiary Ltd"
      },
      "roles": [
        {
          "position": "Manager",
          "from": "2022-05-01",
          "until": null,
        }
      ]
    }
  ]
}

Забележка: Пълните данни съдържат всички налични полета за юридическо лицета.

Някои полета могат да липсват в зависимост от наличната информация.

Лице (Person)

Основни данни (with_data=false)

{
  "id": "507f1f77bcf86cd799439011",      // Уникален идентификатор
  "name": "Иван Петров",                 // Име на лицето
  "indent": "aaaaxxxxxxxxxxxxxxxx",                // Indent/
  "companies": 3                         // Брой свързани фирми
}

Пълни данни (with_data=true)

{
  "_id": "507f1f77bcf86cd799439011",
  "indent": "1234567890",
  "name": "Иван Петров",
  "nameTags": ["иван", "петров", "ivan", "petrov"],

  // Всички фирми, в които участва лицето
  "personCompanies": [
    {
      "uic": "123456789",
      "legalForm": "Дружество с ограничена отговорност",
      "share": "50.00",                          // Дял в компанията (ако е съдружник)
      "company_name": {
        "name": "Example Ltd",
        "name_tags": ["example", "ltd"]
      },
      "roles": [
        {
          "position": "Manager",                  // Длъжност/роля
          "from": "2020-01-15",                   // От дата
          "until": null,                          // До дата (null = активен)
        },
        {
          "position": "Partner",
          "from": "2020-01-15",
          "until": null,
          "share": 50
        }
      ]
    },
    {
      "uic": "987654321",
      "company_name": {
        "name": "Another Company"
      },
      "roles": [
        {
          "position": "BoardMember",
          "from": "2021-03-10",
          "until": "2023-12-31",                  // Неактивна роля
          "share": null
        }
      ]
    }
  ]
}

personCompanies обяснение:

  • position: Роля в компанията (управител, съдружник, член на СД, и др.)
  • from/until: Период на валидност на ролята
  • share: Дял в компанията (за съдружници/акционери)
  • Активни роли: until = null означава, че ролята е все още активна

Обединено търсене

{
  "companies": [
    {
      "uic": "123456789",
      "name": "Example Ltd",
      "legalForm": "ООД",
      "status": "N",
      "transliteration": "Example OOD"
    }
  ],
  "people": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "Иван Петров",
      "indent": "1234567890",
      "companies": 3
    }
  ]
}

Информация за типове данни

Статус на фирми

Код Описание
N Активна юридическо лице
E Активна юридическо лице (ЕООД)
L Ликвидирана
C Заличена

Правни форми

Форма Описание
ООД Дружество с ограничена отговорност
ЕООД Еднолично дружество с ограничена отговорност
АД Акционерно дружество
ЕТ Едноличен търговец

Областни кодове

ID Област
1 София (столица)
31 Бургас
32 Варна
45 Пловдив

Фирми

API endpoints за работа с фирми

Получаване на юридическо лице по ЕИК

Извличане на подробна информация за конкретно юридическо лице.

GET /api/companies/:uic

Параметри

uic *
ЕИК на юридическо лицета (може с "BG" префикс)
with_data
true/false - пълни или основни данни

Отговор

Основни данни (with_data=false):

{
  "uic": "123456789",
  "name": "Example Ltd",
  "legalForm": "ООД",
  "status": "N",
  "transliteration": "Example OOD"
}

Пълни данни (with_data=true):

{
  "company": { /* пълни данни */ },
  "history": [ /* история */ ],
  "daughters": [ /* дъщерни фирми */ ]
}

Примери за код

// Получаване на юридическо лице по ЕИК
async function getCompany(uic, withData = false) {
  const response = await fetch(
    `https://api.companybook.bg/api/companies/${uic}?with_data=${withData}`,
    {
      headers: { "X-API-Key": "your_api_key_here" }
    }
  );
  return await response.json();
}

// Примери за използване
// Основни данни
const basicData = await getCompany("{uic}");

// Пълни данни (включва история, дъщерни фирми)
const fullData = await getCompany("{uic}", true);

Търсене на фирми

Търсене на фирми с обичайните филтри чрез всеки валиден API ключ. Премиум финансовите филтри, регистрационните филтри и финансовото сортиране изискват платен API ключ.

GET /api/v2/companies/search

Безплатните API ключове могат да използват обичайните параметри за търсене. Платените API ключове могат да използват и премиум финансови и регистрационни филтри, както и финансово сортиране.

Търсенето връща най-много първите 1000 класирани резултата. При повече съвпадения броят се показва като 1000+.

Търсенето на фирми връща кратки редове с резултати. Използвайте GET /api/companies/{uic}?with_data=true за пълни данни за конкретна фирма.

Обичайни параметри за търсене

Параметър Тип Описание
uic string Точен ЕИК
name string Име на юридическо лице
district string ID на област
status boolean Активни/неактивни
legal_form string Правна форма
vat boolean Статус на ДДС регистрация
has_contact_data boolean Фирми с контактни данни
limit integer Брой резултати
offset integer Отместване за странициране в първите 1000 резултата

Премиум параметри за търсене (изискват платен API ключ)

Параметър Тип Описание
has_active_financial_data boolean Фирми с финансови данни за активната година
revenue_range string Публичен диапазон на приходи: 0, 0_100k, 100k_1m, 1m_5m, 5m_15m, 15m_40m, 40m_100m, 100m_plus
registration_year_from integer Долна граница за година на регистрация. Включва фирми, за които е известна само година.
registration_year_to integer Горна граница за година на регистрация. Включва фирми, за които е известна само година.
registration_date_from string Долна граница за дата на регистрация. Използвайте YYYY-MM-DD. Връща само фирми с точни ден/месец/година.
registration_date_to string Горна граница за дата на регистрация. Използвайте YYYY-MM-DD. Връща само фирми с точни ден/месец/година.
sort_by string Поле за сортиране: revenue, net_profit, accounting_profit, assets, equity, ebitda
sort_dir string Посока на сортиране: asc или desc

Отговор

{
  "results": [
    {
      "uic": "123456789",
      "name": "Example Ltd",
      "legalForm": "ООД",
      "status": "N",
      "district": "София",
      "transliteration": "Example Ltd",
      "vatRegistered": true,
      "contactPresence": {
        "email": true,
        "phone": true,
        "website": true
      },
      "activeFinancialYear": 2024,
      "latestRevenue": "1M - 5M"
    }
  ],
  "total": "1000+",
  "totalCount": 1000,
  "hasMoreTotal": true,
  "limit": 20,
  "offset": 0
}

Примери за търсене

// Търсене на фирми
async function searchCompanies(params) {
  const queryString = new URLSearchParams(params).toString();
  const response = await fetch(
    `https://api.companybook.bg/api/v2/companies/search?${queryString}`,
    {
      headers: { "X-API-Key": "your_api_key_here" }
    }
  );
  return await response.json();
}

// Безплатен API ключ: обичайни филтри
const activeCompanies = await searchCompanies({
  name: "Example",
  status: true,
  limit: 20
});

// Платен API ключ: премиум регистрационни и финансови филтри
const premiumCompanies = await searchCompanies({
  registration_year_from: 2020,
  revenue_range: "1m_5m",
  sort_by: "revenue",
  sort_dir: "desc",
  limit: 20
});

Лица

API endpoints за работа с лица

Получаване на лице по идентификатор

Извличане на подробна информация за конкретно лице.

GET /api/people/:indent

Параметри

indent *
Идентификационен номер (Уникално ID)
with_data
true/false - пълни или основни данни

Отговор

Основни данни (with_data=false):

{
  "id": "507f1f77bcf86cd799439011",
  "name": "Иван Петров",
  "indent": "1234567890",
  "companies": 3
}

Пълни данни (with_data=true):

{
  "_id": "507f1f77bcf86cd799439011",
  "indent": "1234567890",
  "name": "Иван Петров",
  "personCompanies": [ /* всички фирми */ ],
  "nameTags": [ /* тагове */ ]
}

Примери за код

// Получаване на лице по идентификатор
async function getPerson(indent, withData = false) {
  const response = await fetch(
    `https://api.companybook.bg/api/people/${indent}?with_data=${withData}`,
    {
      headers: { "X-API-Key": "your_api_key_here" }
    }
  );
  return await response.json();
}

// Основни данни
const basicData = await getPerson("{indent}");

// Пълни данни (включва всички фирми)
const fullData = await getPerson("{indent}", true);

Търсене на лица

Търсене на лица по име. v2 endpoint-ът приема всеки валиден безплатен или платен API ключ.

GET /api/v2/people/search

Безплатните и платените API ключове могат да използват v2 endpoint-а за търсене на лица.

Търсенията на лица с два токена са оптимизирани за съвпадение по собствено и фамилно име, с обичайния tokenized и fuzzy fallback.

Query параметри

Параметър
Тип
Описание
name * string Име на лице
with_data boolean Пълни данни
limit integer Брой резултати
offset integer Отместване за странициране в първите 1000 резултата

Отговор

{
  "results": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "Иван Петров",
      "indent": "1234567890",
      "companies": 3
    }
  ],
  "total": "42",
  "totalCount": 42,
  "hasMoreTotal": false,
  "limit": 20,
  "offset": 0
}

Примери за търсене

// Търсене на лица
async function searchPeople(name, limit = 20) {
  const response = await fetch(
    `https://api.companybook.bg/api/v2/people/search?name=${encodeURIComponent(name)}&limit=${limit}`,
    {
      headers: { "X-API-Key": "your_api_key_here" }
    }
  );
  return await response.json();
}

const people = await searchPeople("Иван Петров");

Обединено търсене

Търсете едновременно във фирми и лица с една заявка. v2 обединеният endpoint приема всеки валиден безплатен или платен API ключ.

GET /api/v2/shared/search

Безплатните и платените API ключове могат да използват v2 endpoint-а за обединено търсене.

Query параметри

name *
Търсещ текст (минимум 3 символа)
limit
Брой резултати на тип (по подразбиране: 3, максимум: 500)

Отговор

{
  "companies": [
    {
      "uic": "123456789",
      "name": "Example Ltd",
      "legalForm": "ООД",
      "status": "N"
    }
  ],
  "people": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "Иван Петров",
      "indent": "1234567890",
      "companies": 3
    }
  ]
}

Примери за код

// Обединено търсене във фирми и лица
async function unifiedSearch(query, limit = 5) {
  const response = await fetch(
    `https://api.companybook.bg/api/v2/shared/search?name=${encodeURIComponent(query)}&limit=${limit}`,
    {
      headers: { "X-API-Key": "your_api_key_here" }
    }
  );
  return await response.json();
}

const results = await unifiedSearch("Иван");
console.log("Фирми:", results.companies);
console.log("Лица:", results.people);

Предимства

  • • Една заявка за търсене в двата типа данни
  • • Автоматично ограничение на резултатите
  • • Оптимизиран за потребителски интерфейси

API за финансови данни

Крайни точки за получаване на финансова информация за компании

Модели на данни

TypeScript интерфейси за финансовите данни.

FinancialData

interface FinancialData {
  id?: string;
  uic: string;
  financial_data: Record<string, YearData>;
  last_updated: string;
  has_2024_data?: boolean;
}

YearData

interface YearData {
  income_statement: IncomeStatement;
  balance_sheet: BalanceSheet;
  general_info: GeneralInfo;
}

IncomeStatement

interface IncomeStatement {
  revenue: {
    total: number;
    net_total: number;
  };
  expenses: {
    operating: number;
    materials_and_services: number;
    personnel: number;
    depreciation_and_amortization: number;
    interest_and_other_financial_expenses: number;
    other: number;
    total: number;
    accounting_profit: number;
    tax: number;
    profit: number;
  };
}

BalanceSheet

interface BalanceSheet {
  assets: {
    intangible: number;
    property_plant_equipment: number;
    long_term_financial: number;
    non_current: number;
    inventories: number;
    accounts_receivable: number;
    current: number;
    cash_and_equivalents: number;
    total: number;
  };
  liabilities: {
    equity: number;
    retained_earnings: number;
    total_exp: number;
    total_liabilities: number;
    current: number;
    financial_institutions_debt: number;
    trade_payables: number;
    other: number;
  };
}

GeneralInfo

interface GeneralInfo {
  // Core metrics
  revenue: number;
  profit: number;
  accounting_profit: number;
  tax: number;
  operating_expenses: number;
  personnel_expenses: number;
  total_assets: number;
  equity: number;
  retained_earnings: number;

  // Asset breakdown
  intangible: number;
  tangible: number;
  non_current: number;
  current: number;
  accounts_receivable: number;

  // Calculated ratios
  roa: number;              // Return on Assets (%)
  profit_margin: number;    // Net Profit Margin (%)
  operating_margin: number; // Operating Margin (%)
  roe: number;              // Return on Equity (%)
  current_ratio: number;    // Liquidity Ratio
  equity_ratio: number;     // Financial Autonomy (%)
  EBITDA: number;          // Earnings Before Interest, Taxes, Depreciation, and Amortization
}

Получаване на финансови данни на компания

Получаване на пълна финансова информация за компания по УИК включително отчети за приходи и разходи, баланс и ключови показатели.

GET /api/companies/:uic/financial

Параметри

uic *
ЕИК на компанията (може да включва "BG" префикс)

Контрол на достъпа

Абонирани потребители: Пълни финансови данни за всички налични години
Неабонирани потребители: Ограничени данни (без последна година)

Дневни лимити

Лимитите за достъп до финансови данни през API зависят от вашия план:

Безплатни потребители: 30 уникални заявки на ден (30 компании)
Абонирани потребители: 300 уникални заявки на ден (300 компании)
⚠️ Лимитите се нулират всеки ден в полунощ (EET/EEST)

Структура на отговора

{
  "uic": "123456789",
  "last_updated": "2024-01-15",
  "financial_data": {
    "2023": {
      "income_statement": { ... },
      "balance_sheet": { ... },
      "general_info": {
        "revenue": 1000000.0,
        "profit": 135000.0,
        "roa": 15.7,
        "profit_margin": 13.5,
        "roe": 22.5,
        // ... други показатели
      }
    }
  },
  "has_2024_data": true
}

Примери с код

// Получаване на финансови данни на компания
async function getCompanyFinancial(uic) {
  const response = await fetch(
    `https://api.companybook.bg/api/companies/${uic}/financial`,
    {
      headers: { "X-API-Key": "your_api_key_here" }
    }
  );
  return await response.json();
}

const financialData = await getCompanyFinancial("123456789");

// Достъп до данни за конкретна година
const year2023 = financialData.financial_data["2023"];
console.log("Приходи 2023:", year2023.general_info.revenue);

Финансови показатели

Подробно описание на всички налични финансови показатели и техните изчисления.

Основни показатели

revenue Общи приходи
profit Нетна печалба
total_assets Общи активи
equity Собствен капитал

Финансови коефициенти

roa Рентабилност на активите (%)
roe Рентабилност на капитала (%)
profit_margin Норма на печалбата (%)
current_ratio Коефициент на ликвидност

Грешки и статус кодове

HTTP Status Codes

Status Описание Когато се случва
200 Успех Заявката е изпълнена успешно
400 Лоша заявка Невалидни или липсващи параметри
401 Неоторизиран Липсващ или невалиден API ключ
403 Забранен достъп API ключът няма достъп до този ресурс
404 Не е намерено Търсеният обект не съществува
429 Твърде много заявки Превишен лимит на заявки
500 Сървърна грешка Вътрешна грешка на сървъра

Формат на грешките

Всички грешки се връщат в следния JSON формат:

{
  "error": "Описание на грешката"
}

Често срещани грешки

400
name query must be at least 3 characters
Търсещият текст трябва да е поне 3 символа
400
Invalid limit parameter
Параметърът limit трябва да е цяло число
404
Company/Person not found
Юридическо лицета или лицето не са намерени в базата данни
429
Rate limit exceeded
Превишен лимит на заявки. Изчакайте преди следваща заявка