Общо

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

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

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

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

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

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

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

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

X-API-Key: your_api_key_here

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

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

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

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

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

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

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

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

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

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

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

{
  "uic": "123456789",                    // Company UIC (ЕИК)
  "name": "Example Ltd",                 // Name
  "legalForm": "ООД",                    // Legal form
  "status": "N",                         // Status (N = active, L = liquidated)
  "transliteration": "Example OOD"       // Transliteration
}

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

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

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

    // Contacts
    "contacts": {
      "email": "contact@example.com",
      "phone": "+359 2 123 4567",
      "fax": "+359 2 123 4568",
      "website": "https://example.com"
    },

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

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

    // Financial information
    "capital": {
      "amount": "2000",
      "currency": "BGN",
      "paidAmount": "2000"
    },

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

    // VAT registration
    "registerInfo": {
      "name": "Example Ltd",
      "vat": "BG123456789",
      "address": "София, ул. Витоша 1",
      "registrationDate": "2020-01-15"
    },

    // Metadata
    "lastUpdated": "2024-01-15T10:30:00Z"
  },

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

  // Subsidiaries
  "daughters": [
    {
      "uic": "987654321",
      "company_name": {
        "name": "Subsidiary Ltd"
      },
      "roles": [
        {
          "position": "Manager",
          "from": "2022-05-01",
          "until": null,
        }
      ]
    }
  ]
}

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

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

Лице (Person)

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

{
  "id": "507f1f77bcf86cd799439011",      // Unique identifier
  "name": "Иван Петров",                 // Person's name
  "indent": "aaaaxxxxxxxxxxxxxxxx",                // Indent/
  "companies": 3                         // Number of related companies
}

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

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

  // All companies the person is involved in
  "personCompanies": [
    {
      "uic": "123456789",
      "legalForm": "Дружество с ограничена отговорност",
      "share": "50.00",                          // Share in the company (if a partner)
      "company_name": {
        "name": "Example Ltd",
        "name_tags": ["example", "ltd"]
      },
      "roles": [
        {
          "position": "Manager",                  // Position / role
          "from": "2020-01-15",                   // From date
          "until": null,                          // To date (null = active)
        },
        {
          "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",                  // Inactive role
          "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": [ /* дъщерни фирми */ ]
}

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

// Get a company by UIC (ЕИК)
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();
}

// Usage examples
// Basic data
const basicData = await getCompany("{uic}");

// Full data (includes history, subsidiaries)
const fullData = await getCompany("{uic}", true);

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

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

GET /api/v2/companies/search

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

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

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

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

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

Pro параметри за търсене (изискват платен 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
}

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

// Search companies
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();
}

// Free API key: standard filters
const activeCompanies = await searchCompanies({
  name: "Example",
  status: true,
  limit: 20
});

// Paid API key: premium registration and financial filters
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": [ /* тагове */ ]
}

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

// Get a person by identifier
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();
}

// Basic data
const basicData = await getPerson("{indent}");

// Full data (includes all companies)
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
}

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

// Search people
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
    }
  ]
}

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

// Unified search across companies and people
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 {
  // Keyed by fiscal year - contains only the requested year
  data: Record<string, YearData>;
  // Fiscal years that require a paid plan
  paid_data_years: string[];
}

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_liab: number;
    financial_institutions_debt: number;
    trade_payables: number;
    other: number;
  };
}

GeneralInfo

interface GeneralInfo {
  // Core metrics  — all monetary values are in THOUSANDS of BGN
  revenue: number;
  profit: number;
  accounting_profit: number; // profit before tax
  tax: number;               // corporate income tax
  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 — returned as DECIMAL FRACTIONS, not percentages
  //   (e.g. roa 0.157 means 15.7%). Multiply by 100 to display a percentage.
  roa: number;              // Return on Assets      (fraction, e.g. 0.157)
  profit_margin: number;    // Net Profit Margin     (fraction, e.g. 0.135)
  operating_margin: number; // Operating Margin      (fraction)
  roe: number;              // Return on Equity      (fraction, e.g. 0.225)
  current_ratio: number;    // Current Assets / Current Liabilities
  equity_ratio: number;     // Equity / Total Assets (financial autonomy, fraction)
  ebitda: number;           // Earnings Before Interest, Taxes, Depreciation and Amortization (thousands BGN)
}

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

Получаване на финансовата информация за компания за една финансова година – отчет за приходите и разходите, баланс и ключови показатели. Годината се избира със задължителния параметър year, а отговорът съдържа само нея.

GET /api/companies/:uic/financial?year=YYYY

Параметри

uic *
ЕИК на компанията (може да включва "BG" префикс)
year *
Финансова година, точно четири цифри (например 2023). Задължителен – заявка без него се отхвърля.

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

Всяка заявка изисква валиден API ключ, подаден чрез хедъра X-API-Key.

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

• Абонирани потребители: Достъп до всички налични финансови години, включително най-новите
• Неабонирани потребители: Достъп само до по-стари финансови години; за най-новите се връща 403 financialSubscriptionRequired
Масивът paid_data_years изброява финансовите години, за които е необходим платен план.

Дневна квота

Достъпът до финансови данни се измерва в различни комбинации компания и година. Всяка нова комбинация, заявена през деня, изразходва една единица от дневната ви квота, а размерът ѝ зависи от вашия план:

• Безплатни потребители: 30 различни комбинации компания и година на ден
• Абонирани потребители: 300 различни комбинации компания и година на ден с Pro; 100 на ден с Pro Lite
• Повторна заявка за същата компания и същата година в рамките на същия ден е безплатна и не изразходва квота.
• Неуспешните и отхвърлените заявки, както и тези без данни за годината, не се таксуват от квотата.
⚠️ Квотата се нулира всеки ден в полунощ по часовата зона Европа/София.

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

// GET /api/companies/123456789/financial?year=2023
{
  "data": {
    "2023": {
      "income_statement": { ... },
      "balance_sheet": { ... },
      "general_info": {
        // NOTE: all monetary values are in THOUSANDS of BGN.
        // revenue 12800 = 12,800,000 BGN.
        "revenue": 12800,
        "profit": 1730,
        "accounting_profit": 1922,
        "tax": 192,
        // ratios are decimal fractions (0.135 = 13.5%)
        "roa": 0.157,
        "profit_margin": 0.135,
        "roe": 0.225,
        // ... други показатели
      }
    }
  },
  "paid_data_years": ["2024", "2025"]
}

Примери с код

// Get a company's financial data for one year
async function getCompanyFinancial(uic, year) {
  const response = await fetch(
    `https://api.companybook.bg/api/companies/${uic}/financial?year=${year}`,
    {
      headers: { "X-API-Key": "your_api_key_here" }
    }
  );
  return await response.json();
}

const financialData = await getCompanyFinancial("123456789", 2023);

// The response contains only the requested year
const year2023 = financialData.data["2023"];
console.log("Приходи 2023:", year2023.general_info.revenue);
console.log("Платени години:", financialData.paid_data_years);

Грешки

Отговори при грешка, връщани от тази крайна точка.

Статус Код Значение
400 fiscalYearRequired Липсва параметърът year.
400 invalidFiscalYear Параметърът year не е валидна четирицифрена година.
403 financialSubscriptionRequired Годината съществува, но вашият план не дава достъп до нея.
404 financialDataForYearNotFound Няма финансови данни за тази компания за заявената година.
429 dailyFiscalYearLimitExceeded Дневната квота от различни комбинации компания и година е изчерпана.

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

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

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

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

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

roa Рентабилност на активите (%)
roe Рентабилност на капитала (%)
profit_margin Норма на печалбата (%)
operating_margin Оперативна рентабилност (%)

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

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
Превишен лимит на заявки. Изчакайте преди следваща заявка