Общо
RESTful API за българския търговски регистър
Допълнителни ресурси за разработчици
Swagger документация: Интерактивна API документация с възможност за тестване на живо е достъпна на api.companybook.bg/docs
Контекстни файлове за LLM: За разработчици, използващи AI асистенти (като Claude, ChatGPT и други), предлагаме контекстни файлове: llms.txt (кратка версия) и llms-full.txt (пълна документация). Тези файлове могат да бъдат заредени в AI модели за по-добра интеграция и разбиране на API структурата.
RESTful API за достъп до данни от българския търговски регистър. Търсете, извличайте и интегрирайте данни за фирми и физически лица с лекота и надеждност.
Основни възможности
Ограничения на заявките
Нашето API е безплатно за използване, но прилагаме лимит от 100 заявки на минута на IP адрес за да осигурим стабилност на услугата за всички потребители. При надвишаване на лимита ще получите HTTP статус код 429.
Формат на отговорите
Всички отговори са в 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": "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 Получаване на общия брой лица в регистъра
Мрежа от връзки
Проследяване на собственост и управление между фирми и лица
Получаване на мрежа от връзки
Мощен 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": "Описание на грешката"
}