Общо
RESTful API за българския търговски регистър
Допълнителни ресурси за разработчици
Swagger документация: Интерактивна API документация с възможност за тестване на живо е достъпна на api.companybook.bg/docs
Контекстни файлове за LLM: За разработчици, използващи AI асистенти (като Claude, ChatGPT и други), предлагаме контекстни файлове: llms.txt (кратка версия) и llms-full.txt (пълна документация). Тези файлове могат да бъдат заредени в AI модели за по-добра интеграция и разбиране на API структурата.
RESTful 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 | Пловдив |
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 за работа с фирми
Получаване на юридическо лице по ЕИК
Извличане на подробна информация за конкретно юридическо лице.
/api/companies/:uic Параметри
Отговор
Основни данни (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); import requests
# Получаване на юридическо лице по ЕИК
def get_company(uic, with_data=False):
response = requests.get(
f"https://api.companybook.bg/api/companies/{uic}",
params={"with_data": str(with_data).lower()}
)
return response.json()
# Примери за използване
# Основни данни
basic_data = get_company("{uic}")
# Пълни данни (включва история, дъщерни фирми)
full_data = get_company("{uic}", True) # Получаване на юридическо лице с основни данни
curl "https://api.companybook.bg/api/companies/{uic}"
# Получаване на юридическо лице с пълни данни (история, дъщерни фирми)
curl "https://api.companybook.bg/api/companies/{uic}?with_data=true" Търсене на фирми
Търсене на фирми с различни филтри.
/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
}); # Търсене на фирми
def search_companies(**params):
response = requests.get(
"https://api.companybook.bg/api/companies/search",
params=params
)
return response.json()
# Примери за търсене
# Основни резултати
active_companies = search_companies(
name="Example",
status=True,
limit=20
)
# Пълни данни с with_data
companies_with_data = search_companies(
district=1, # София (столица)
legal_form="ООД",
with_data=True
) # Търсене по име и статус curl "https://api.companybook.bg/api/companies/search?name=Example&status=true" # Търсене с пълни данни по област (ID) curl "https://api.companybook.bg/api/companies/search?district=1&legal_form=ООД&with_data=true"
Получаване на документи на фирма
Получаване на данни за документи на фирма по УИК. Връща финансови отчети и други документи (тип AJ и BH).
/api/companies/documents/:uic Параметри
Автентикация
• Не е задължителна - разширени данни при автентикация
• 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 документи.
/api/companies/:uic/download Параметри
Автентикация
• 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 - Вътрешна грешка на сървъра
Статистика
/api/companies/count Получаване на общия брой фирми в регистъра
Лица
API endpoints за работа с лица
Получаване на лице по идентификатор
Извличане на подробна информация за конкретно лице.
/api/people/:indent Параметри
Отговор
Основни данни (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); # Получаване на лице по идентификатор
def get_person(indent, with_data=False):
response = requests.get(
f"https://api.companybook.bg/api/people/{indent}",
params={"with_data": str(with_data).lower()}
)
return response.json()
# Примери за използване
# Основни данни
basic_data = get_person("{indent}")
# Пълни данни (включва всички фирми)
full_data = get_person("{indent}", True) # Получаване на лице с основни данни
curl "https://api.companybook.bg/api/people/{indent}"
# Получаване на лице с пълни данни (всички фирми)
curl "https://api.companybook.bg/api/people/{indent}?with_data=true" Търсене на лица
Търсене на лица по име.
/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); # Търсене на лица
def search_people(name, limit=20):
response = requests.get(
"https://api.companybook.bg/api/people/search",
params={"name": name, "limit": limit}
)
return response.json()
# Пример за използване
people = search_people("Иван Петров")
print(people) # Търсене на лица по име curl "https://api.companybook.bg/api/people/search?name=Иван" # Търсене с лимит curl "https://api.companybook.bg/api/people/search?name=Петров&limit=30"
Статистика
/api/people/count Получаване на общия брой лица в регистъра
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
Получаване на детайлна информация за конкретен търг по неговия уникален идентификатор.
/api/announcements/: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); import requests
# Получаване на търг по ID
def get_announcement(id):
response = requests.get(
f"https://api.companybook.bg/api/announcements/{id}"
)
return response.json()
# Пример за използване
announcement = get_announcement("1234567890")
print("Търг:", announcement["debtor_name"]) # Получаване на търг по ID curl -X GET "https://api.companybook.bg/api/announcements/1234567890" \ -H "Accept: application/json" \ -H "User-Agent: MyApp/1.0" # За абонирани потребители (пълни данни) curl -X GET "https://api.companybook.bg/api/announcements/1234567890" \ -H "Accept: application/json" \ -H "X-API-Key: your_api_key_here"
Търсене на търгове
Търсене на търгове за несъстоятелност с различни филтри за длъжник, съд, дата и статус.
/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"
}); import requests
# Търсене на търгове
def search_announcements(**params):
response = requests.get(
"https://api.companybook.bg/api/announcements",
params=params
)
return response.json()
# Примери за търсене
active_announcements = search_announcements(
is_closed=False,
page=1,
page_size=50
)
# Търсене по дата
recent_announcements = search_announcements(
publish_date_from="2024-01-01",
publish_date_to="2024-12-31"
) # Търсене на активни търгове curl -X GET "https://api.companybook.bg/api/announcements?is_closed=false&page=1&page_size=50" \ -H "Accept: application/json" \ -H "User-Agent: MyApp/1.0" # Търсене по дата и компания curl -X GET "https://api.companybook.bg/api/announcements?publish_date_from=2024-01-01&publish_date_to=2024-12-31&debtor_name=Example" \ -H "Accept: application/json" # Комплексно търсене с множество филтри curl -X GET "https://api.companybook.bg/api/announcements?debtor_eik=123456789&court_name=София&is_closed=false" \ -H "Accept: application/json" \ -H "X-API-Key: your_api_key_here"
Получаване на списък със синдици
Получаване на пагиниран списък със синдици по несъстоятелност.
/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
} Търсене на синдици по име
Търсене на синдици по име или част от името.
/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
} Получаване на търгове по синдик
Получаване на всички търгове, свързани с конкретен синдик.
/api/syndics/:id/announcements Параметри
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
} Търсене на обекти от търгове по тип
Търсене на обекти от търгове за несъстоятелност по тип, локация и други критерии. Връща обекти с детайлна информация и данни за свързаните търгове.
/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) Контрол на достъпа
Отговор
{
"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
}
}
} Получаване на списък със съдилища
Получаване на списък с всички съдилища, които разглеждат дела за несъстоятелност.
/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
} Получаване на финансови данни на компания
Получаване на пълна финансова информация за компания по УИК включително отчети за приходи и разходи, баланс и ключови показатели.
/api/companies/:uic/financial Параметри
Контрол на достъпа
Структура на отговора
{
"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); import requests
# Получаване на финансови данни на компания
def get_company_financial(uic):
response = requests.get(
f"https://api.companybook.bg/api/companies/{uic}/financial"
)
return response.json()
# Пример за използване
financial_data = get_company_financial("123456789")
# Достъп до данни за конкретна година
year_2023 = financial_data["financial_data"]["2023"]
print("Приходи 2023:", year_2023["general_info"]["revenue"]) # Получаване на финансови данни за компания curl -X GET "https://api.companybook.bg/api/companies/123456789/financial" \ -H "Accept: application/json" \ -H "User-Agent: MyApp/1.0" # С BG префикс curl -X GET "https://api.companybook.bg/api/companies/BG123456789/financial" \ -H "Accept: application/json" # За абонирани потребители (с API ключ) curl -X GET "https://api.companybook.bg/api/companies/123456789/financial" \ -H "Accept: application/json" \ -H "X-API-Key: your_api_key_here"
Финансови показатели
Подробно описание на всички налични финансови показатели и техните изчисления.
Основни показатели
revenue Общи приходи profit Нетна печалба total_assets Общи активи equity Собствен капитал Финансови коефициенти
roa Рентабилност на активите (%) roe Рентабилност на капитала (%) profit_margin Норма на печалбата (%) current_ratio Коефициент на ликвидност Мрежа от връзки
Проследяване на собственост и управление между фирми и лица
Получаване на мрежа от връзки
Мощен endpoint за визуализация на корпоративни структури, вериги на собственост и йерархии на управление. Използва breadth-first обхождане за откриване на комплексни бизнес мрежи.
/api/relationships/:identifier Параметри
Структура на отговора
{
"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"); import requests
# Получаване на мрежа от връзки
def get_relationships(identifier, depth=3, type='all'):
response = requests.get(
f"https://api.companybook.bg/api/relationships/{identifier}",
params={"depth": depth, "type": type}
)
return response.json()
# Примери за използване
# Пълна мрежа (собственост + управление) на 3 нива
full_network = get_relationships("123456789", 3, "all")
# Само собственост на 4 нива
ownership_only = get_relationships("123456789", 4, "ownership")
# Само управление
management_only = get_relationships("1234567890", 2, "management") # Пълна мрежа от връзки на 3 нива curl "https://api.companybook.bg/api/relationships/123456789?depth=3&type=all" # Само собственост на 4 нива curl "https://api.companybook.bg/api/relationships/123456789?depth=4&type=ownership" # Включване на исторически връзки curl "https://api.companybook.bg/api/relationships/123456789?depth=2&include_historical=true"
Типове връзки
Собственост
- •
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": "Описание на грешката"
}