НОВО: Изтегляне на фирмени документи от ТР –
опитайте сега!

Общо

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

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

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

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

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

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

Търсене на фирми по ЕИК, име, област
Търсене на лица по име и идентификатор
Детайлна информация за фирми
История на промените
JSON формат на данните
Бързо и надеждно 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 Пловдив

Фирми

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

Предимства

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

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

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

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

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