Общо

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

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

Swagger документация: Интерактивна API документация с възможност за тестване на живо е достъпна на api.companybook.bg/docs

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

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

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

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

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

Всички отговори са в 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": "1234567890",                // ЕГН/ЛНЧ
  "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}`
  );
  return await response.json();
}

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

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

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

Търсене на фирми с различни филтри.

GET /api/companies/search

Query параметри

Параметър
Тип
Описание
uic string Точен ЕИК
name string Име на юридическо лице
district number ID на област
status boolean Активни/неактивни
legal_form string Правна форма
with_data boolean Пълни данни
limit integer Брой резултати

Отговор

{
  "results": [
    {
      "uic": "123456789",
      "name": "Example Ltd",
      "legalForm": "ООД",
      "status": "N"
    }
  ],
  "total": 145
}

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

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

// Примери за търсене
// Основни резултати
const activeCompanies = await searchCompanies({
  name: "Example",
  status: true,
  limit: 20
});

// Пълни данни с with_data
const companiesWithData = await searchCompanies({
  district: 1, // София (столица)
  legal_form: "ООД",
  with_data: true
});

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

Получаване на данни за документи на фирма по УИК. Връща финансови отчети и други документи (тип AJ и BH).

GET /api/companies/documents/:uic

Параметри

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

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

• Не е задължителна - разширени данни при автентикация

• Session cookie или X-API-Key header

• ID на документи се включват само за автентикирани потребители

Отговор

{
  "uic": "123456789",
  "name": "Example Ltd",
  "financial_documents": {
    "2024": [
      {
        "id": "doc123", // Only for authenticated
        "name": "Financial Report 2024",
        "date": "2024-12-31",
        "type": "financial",
      }
    ]
  },
  "other_documents": {
    "statements_aj": [...],
    "statements_bh": [...]
  }
}

Изтегляне на документ на фирма

Изтегляне на конкретни документи за фирма. Изисква автентикация и позволява само финансови, AJ или BH документи.

GET /api/companies/:uic/download

Параметри

uic *
УИК на фирмата. Може да включва "BG" префикс
id *
ID на документа (от documents endpoint)
type *
Тип документ: financial, statements_aj, statements_bh
year
Година на документа (изисква се за някои типове)

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

• X-API-Key header

• Лимит: 20 изтегляния на минута

Примерна заявка

# Using session authentication
curl "https://api.companybook.bg/api/companies/123456789/download?id=doc123&type=financial&year=2024" \
  -H "Authorization: Bearer session_token"

# Using API key authentication  
curl "https://api.companybook.bg/api/companies/BG123456789/download?id=doc123&type=aj" \
  -H "X-API-Key: your_api_key"

Отговор

• Успех: Изтегляне на файл с подходящи headers

• Грешка: JSON с локализирани съобщения за грешки

Отговори при грешки

  • • 400 - Невалидни параметри или неподдържан тип документ
  • • 401 - Изисква се автентикация
  • • 404 - Документът не е намерен
  • • 429 - Превишен лимит на заявки
  • • 500 - Вътрешна грешка на сървъра

Статистика

GET /api/companies/count

Получаване на общия брой фирми в регистъра

Лица

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

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

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

GET /api/people/:indent

Параметри

indent *
Идентификационен номер (ЕГН/ЛНЧ)
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}`
  );
  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}`
  );
  return await response.json();
}

// Пример за използване
const people = await searchPeople("Иван Петров");
console.log(people);

Статистика

GET /api/people/count

Получаване на общия брой лица в регистъра

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

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

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}`
  );
  return await response.json();
}

// Пример за използване
const results = await unifiedSearch("Иван");
console.log("Фирми:", results.companies);
console.log("Лица:", results.people);

Предимства

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

API за несъстоятелност

Ендпойнти за търгове за несъстоятелност, синдици и съдилища

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

TypeScript интерфейси за отговорите от API-то.

Announcement

interface Announcement {
  id: string;
  debtor_name: string;
  debtor_eik: string;
  case_number: string;
  case_year: number;
  court_name: string;
  offering_date?: Date;
  offer_deadline?: Date;
  status: string;
  is_closed: boolean;
  publish_date: Date;
  syndic: Syndic;
  second_syndic?: Syndic;
  objects: AnnouncementObject[];
  parsed_objects?: ParsedObject[];
}

Syndic

interface Syndic {
  id: string;
  full_name: string;
  full_address: string;
  phone?: string;
  email?: string;
  syndic_specialty?: string;
  order_date?: string;
  order_number?: string;
}

AnnouncementObject

interface AnnouncementObject {
  id: string;
  object_type: string;
  object_kind: string;
  condition?: string;
  notes?: string;
  value?: string;
  address?: Address;
}

PaginatedResponse

interface PaginatedResponse<T> {
  data: T[];
  current_page: number;
  page_size: number;
  total_pages: number;
  total_count: number;
  has_next: boolean;
  has_prev: boolean;
}

Получаване на търг по ID

Получаване на детайлна информация за конкретен търг по неговия уникален идентификатор.

GET /api/announcements/:id

Параметри

id *
Уникален идентификатор на търга

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

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

Отговор

{
  "id": "1234567890",
  "debtor_name": "Example Company",
  "debtor_eik": "123456789",
  "case_number": "1/2024",
  "case_year": 2024,
  "court_name": "Sofia City Court",
  "status": "active",
  "is_closed": false,
  "publish_date": "2024-01-15",
  "syndic": {
    "full_name": "John Doe",
    "full_address": "Sofia, Bulgaria"
  },
  "objects": [...]
}

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

// Получаване на търг по ID
async function getAnnouncement(id) {
  const response = await fetch(
    `https://api.companybook.bg/api/announcements/${id}`
  );
  return await response.json();
}

// Пример за използване
const announcement = await getAnnouncement("1234567890");
console.log("Търг:", announcement.debtor_name);

Търсене на търгове

Търсене на търгове за несъстоятелност с различни филтри за длъжник, съд, дата и статус.

GET /api/announcements

Query параметри

Параметър
Тип
Описание
debtor_name string Име на длъжника
debtor_eik string ЕИК на длъжника
court_name string Име на съда
is_closed boolean Затворен/активен
publish_date_from date Дата от
page integer Страница (по подразбиране 1)
page_size integer Резултати на страница (макс 100)

Отговор

{
  "data": [
    {
      "id": "1234567890",
      "debtor_name": "Example Company",
      "debtor_eik": "123456789",
      "status": "active",
      "is_closed": false,
      "publish_date": "2024-01-15"
    }
  ],
  "current_page": 1,
  "page_size": 50,
  "total_pages": 10,
  "total_count": 500,
  "has_next": true,
  "has_prev": false
}

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

// Търсене на търгове
async function searchAnnouncements(params) {
  const queryString = new URLSearchParams(params).toString();
  const response = await fetch(
    `https://api.companybook.bg/api/announcements?${queryString}`
  );
  return await response.json();
}

// Примери за търсене
const activeAnnouncements = await searchAnnouncements({
  is_closed: false,
  page: 1,
  page_size: 50
});

// Търсене по дата
const recentAnnouncements = await searchAnnouncements({
  publish_date_from: "2024-01-01",
  publish_date_to: "2024-12-31"
});

Получаване на списък със синдици

Получаване на пагиниран списък със синдици по несъстоятелност.

GET /api/syndics

Query параметри

Параметър
Тип
Описание
page integer Страница (по подразбиране 1)
page_size integer Резултати на страница (макс 100)

Отговор

{
  "data": [
    {
      "id": "syndic123",
      "full_name": "John Doe",
      "full_address": "Sofia, Bulgaria",
      "phone": "+359888123456",
      "email": "john@example.com",
      "syndic_specialty": "Commercial Law"
    }
  ],
  "current_page": 1,
  "page_size": 50,
  "total_pages": 5,
  "total_count": 250,
  "has_next": true,
  "has_prev": false
}

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

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

GET /api/syndics/search

Query параметри

Параметър
Тип
Описание
name string Име на синдика (частично съвпадение)
page integer Страница
page_size integer Резултати на страница

Отговор

{
  "data": [
    {
      "id": "syndic123",
      "full_name": "John Doe",
      "full_address": "Sofia, Bulgaria",
      "announcements_count": 15
    }
  ],
  "current_page": 1,
  "page_size": 20,
  "total_count": 5
}

Получаване на търгове по синдик

Получаване на всички търгове, свързани с конкретен синдик.

GET /api/syndics/:id/announcements

Параметри

id *
ID на синдика

Query параметри

page - Страница
page_size - Резултати на страница
is_closed - Филтър по статус

Отговор

{
  "data": [
    {
      "id": "1234567890",
      "debtor_name": "Example Company",
      "debtor_eik": "123456789",
      "case_number": "1/2024",
      "status": "active",
      "is_closed": false,
      "publish_date": "2024-01-15"
    }
  ],
  "current_page": 1,
  "page_size": 50,
  "total_count": 15
}

Търсене на обекти от търгове по тип

Търсене на обекти от търгове за несъстоятелност по тип, локация и други критерии. Връща обекти с детайлна информация и данни за свързаните търгове.

GET /api/announcements/objects/search

Query параметри

Параметър
Тип
Описание
object_kind string Тип обект (задължителен)
city string Град (частично съвпадение)
region string Област
min_price_bgn number Минимална цена (лв.)
max_price_bgn number Максимална цена (лв.)
is_active boolean Активен търг
page integer Страница
page_size integer Резултати на страница (макс 50)

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

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

Отговор

{
  "objects": [
    {
      "object": {
        "id": "obj123",
        "object_type": "недвижим имот",
        "object_kind": "апартамент",
        "condition": "добро състояние",
        "value": "150000",
        "address": {
          "city": "София",
          "region": "София",
          "full_address": "ул. Примерна 123"
        }
      },
      "parsedObject": {
        "price_bgn": 150000.0
      },
      "announcementId": "1234567890",
      "announcementTitle": "Example Company",
      "offeringDate": "2024-02-01",
      "offerDeadline": "2024-02-15",
      "status": "active",
      "syndic": {
        "full_name": "John Doe",
        "phone": "+359888123456"
      }
    }
  ],
  "pagination": {
    "current_page": 1,
    "page_size": 20,
    "total_count": 150
  },
  "aggregation": {
    "total_objects": 150,
    "avg_price_bgn": 175000.0,
    "price_range": {
      "min": 50000.0,
      "max": 500000.0
    }
  }
}

Получаване на списък със съдилища

Получаване на списък с всички съдилища, които разглеждат дела за несъстоятелност.

GET /api/courts

Query параметри

Параметър
Тип
Описание
city string Филтър по град
page integer Страница
page_size integer Резултати на страница

Отговор

{
  "data": [
    {
      "id": "court1",
      "name": "Софийски градски съд",
      "city": "София",
      "address": "ул. Съдебна 2",
      "phone": "+35929524200",
      "active_cases_count": 150
    },
    {
      "id": "court2", 
      "name": "Окръжен съд - Пловдив",
      "city": "Пловдив",
      "address": "бул. Шести септември 45",
      "active_cases_count": 87
    }
  ],
  "current_page": 1,
  "page_size": 20,
  "total_count": 28
}

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" префикс)

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

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

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

{
  "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`
  );
  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 Коефициент на ликвидност

Мрежа от връзки

Проследяване на собственост и управление между фирми и лица

Получаване на мрежа от връзки

Мощен endpoint за визуализация на корпоративни структури, вериги на собственост и йерархии на управление. Използва breadth-first обхождане за откриване на комплексни бизнес мрежи.

GET /api/relationships/:identifier

Параметри

identifier *
ЕИК на юридическо лице (9 цифри) или ЕГН на физическо лице
depth
integer (1-5, по подразбиране: 2) - Дълбочина на обхождане
type
all/ownership/management - Филтър по тип връзка
include_historical
boolean - Включване на исторически връзки

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

{
  "root": {
    "id": "123456789",
    "type": "company",
    "name": "Example OOD"
  },
  "relationships": [
    {
      "entity": { "id", "name", "type" },
      "relationshipType": "Partners",
      "depth": 1,
      "metadata": {
        "share": "60.00%"
      },
      "isActive": true,
      "direction": "owned_by"
    }
  ],
  "graph": {
    "nodes": [...],
    "edges": [...]
  },
  "totalEntities": 15
}

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

// Получаване на мрежа от връзки за юридическо лице
async function getRelationships(identifier, depth = 3, type = 'all') {
  const response = await fetch(
    `https://api.companybook.bg/api/relationships/${identifier}?depth=${depth}&type=${type}`
  );
  return await response.json();
}

// Примери за използване
// Пълна мрежа (собственост + управление) на 3 нива
const fullNetwork = await getRelationships("123456789", 3, "all");

// Само собственост на 4 нива
const ownershipOnly = await getRelationships("123456789", 4, "ownership");

// Само управление
const managementOnly = await getRelationships("1234567890", 2, "management");

Типове връзки

Собственост

  • SoleCapitalOwner Едноличен собственик (100%)
  • Partners Съдружници/акционери
  • ActualOwners Действителни собственици
  • PhysicalPersonTrader Едноличен търговец

Управление

  • Managers Управители
  • Representatives Представители
  • BoardOfDirectors Съвет на директорите
  • Procurators Прокуристи

Производителност и ограничения

  • Максимална дълбочина: 5 нива (за предотвратяване на прекалено много заявки)
  • Timeout: Заявките изтичат след 10 секунди
  • Кеширане: Резултатите се кешират за 5 минути
  • Откриване на цикли: API автоматично предотвратява безкрайни цикли
  • Batch зареждане: Субектите на всяко ниво се зареждат групово за оптимална производителност

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

HTTP Status Codes

Status Описание Когато се случва
200 Успех Заявката е изпълнена успешно
400 Лоша заявка Невалидни или липсващи параметри
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
Превишен лимит на заявки. Изчакайте преди следваща заявка