API Документация

Общо

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

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

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

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

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

Търсене на фирми по ЕИК, име, област

Търсене на лица по име и идентификатор

Детайлна информация за фирми

История на промените

JSON формат на данните

Бързо и надеждно API

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

Актуални данни

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

Всички API заявки изискват валиден API ключ. Ключът се предава чрез HTTP хедър:

X-API-Key: your_api_key_here

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

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

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

Безплатни потребители: 300 заявки на ден

Абонирани потребители: 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": "[email protected]",
      "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`	Пловдив
`30`	Благоевград
`33`	Велико Търново
`34`	Видин
`35`	Враца
`36`	Габрово
`37`	Добрич
`38`	Кърджали
`39`	Кюстендил
`40`	Ловеч
`41`	Монтана
`42`	Пазарджик
`43`	Перник
`44`	Плевен
`46`	Разград
`47`	Русе
`48`	Силистра
`49`	Сливен
`50`	Смолян
`51`	София
`52`	Стара Загора
`53`	Търговище
`54`	Хасково
`55`	Шумен
`56`	Ямбол

Фирми

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 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);

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

Търсене на лица по име.

GET /api/people/search

Query параметри

Параметър

Тип

Описание

name * string Име на лице

with_data boolean Пълни данни

limit integer Брой резултати

Отговор

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

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

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

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

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

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

GET /api/shared/search

Query параметри

name *

Търсещ текст (минимум 3 символа)

limit

Брой резултати на тип (по подразбиране: 3)

Отговор

{
  "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/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

Превишен лимит на заявки. Изчакайте преди следваща заявка

Свържете се с нас

Общо

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

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

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

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

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

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

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

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

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

Лице (Person)

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

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

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

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

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

Правни форми

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

Фирми

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

Параметри

Отговор

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

Лица

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

Параметри

Отговор

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

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

Query параметри

Отговор

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

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

Query параметри

Отговор

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

Предимства

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

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

FinancialData

YearData

IncomeStatement

BalanceSheet

GeneralInfo

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

Параметри

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

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

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

Примери с код

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

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

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

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

HTTP Status Codes

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

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