Ново: 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 {
  // 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
  revenue: number;
  profit: 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 (%)
  ebitda: number;           // Earnings Before Interest, Taxes, Depreciation, and Amortization
}

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

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

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

Параметри

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

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

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

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

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

Дневна квота

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

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

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

// GET /api/companies/123456789/financial?year=2023
{
  "data": {
    "2023": {
      "income_statement": { ... },
      "balance_sheet": { ... },
      "general_info": {
        "revenue": 1000000.0,
        "profit": 135000.0,
        "roa": 15.7,
        "profit_margin": 13.5,
        "roe": 22.5,
        // ... други показатели
      }
    }
  },
  "paid_data_years": ["2024", "2023"]
}

Примери с код

// Получаване на финансови данни на компания за една година
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);

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