Ръководства/Firmify Public API — документация за разработчици

Firmify Public API — документация за разработчици

Общ преглед

Public API на Firmify позволява програмно генериране на документи, регистрови работни потоци, procurement doc-packs и интеграция със счетоводния модул.

Базови URL адреси

https://firmify.bg/api/v1
https://firmify.bg/v1 # mirror (Next.js proxy)

Текуща версия: v1. Автентикираните отговори включват X-Api-Version: 2026-07.

Два начина на достъп

Повърхност Автентикация За какво
/api/v1/* Bearer fmfy_... Програмно генериране, billing, webhooks
/developer/* Session cookie (JWT) Портал за разработчици — ключове, billing, webhooks

Интерактивна документация: Scalar · Swagger · Redoc · Changelog


Бърз старт

  1. Създайте API ключ в Портала за разработчици (или POST /api/v1/register за headless регистрация).
  2. Автентикирайте се с Authorization: Bearer fmfy_....
  3. Генерирайте документ — стъпка по стъпка:
curl -X POST https://firmify.bg/api/v1/legal-docs \
 -H "Authorization: Bearer fmfy_ВАШИЯ_API_КЛЮЧ" \
 -H "Content-Type: application/json" \
 -d '{"docType": "GDPR_POLICY"}'

curl -X PUT https://firmify.bg/api/v1/legal-docs/{id} \
 -H "Authorization: Bearer fmfy_ВАШИЯ_API_КЛЮЧ" \
 -H "Content-Type: application/json" \
 -d '{"companyName": "Акме ООД", "companyEik": "123456789"}'

curl -X POST https://firmify.bg/api/v1/legal-docs/{id}/checkout \
 -H "Authorization: Bearer fmfy_ВАШИЯ_API_КЛЮЧ"

curl -X POST https://firmify.bg/api/v1/legal-docs/{id}/generate \
 -H "Authorization: Bearer fmfy_ВАШИЯ_API_КЛЮЧ"

curl https://firmify.bg/api/v1/legal-docs/{id}/download \
 -H "Authorization: Bearer fmfy_ВАШИЯ_API_КЛЮЧ" \
 -o dokument.pdf

Вижте практическото ръководство за webhooks, sandbox и async jobs.


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

Всички автентикирани /api/v1/* заявки изискват Bearer токен:

curl -H "Authorization: Bearer fmfy_ВАШИЯ_API_КЛЮЧ" \
 https://firmify.bg/api/v1/pricing

Формат на API ключа

Ключовете започват с fmfy_ и се показват само веднъж при създаване.

Права (permissions)

Permission Описание
public_api:v1 Пълен достъп до public API v1 (по подразбиране)
documents:generate Legacy alias за генериране на документи
accounting:read Read-only счетоводни данни за една фирма
accounting:multi Счетоводни данни за всички достъпни фирми

Accounting API е на /accounting/api/*. Използвайте X-Company-Id или ?companyId=.

Sandbox ключове

Създайте sandbox ключ в Портала за тестване без реални Stripe такси и генериране на документи.


Генериране на документи

Жизнен цикъл: DRAFT → READY → PAID → GENERATED.

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

Път: /api/v1/legal-docs

Типове: GDPR_POLICY, TERMS_OF_SERVICE, COOKIE_POLICY, NDA, SERVICE_CONTRACT, PRIVACY_NOTICE, DATA_PROCESSING_AGREEMENT

След POST → PUT /{id} → checkout/charge/quota → POST /{id}/generate → GET /{id}/download.

HR документи

Път: /api/v1/hr-docs — същият CRUD + checkout + generate + download pattern.

Други категории

Категория Път
Бизнес документи /api/v1/business-docs
ДДС регистрация /api/v1/vat
БУЛСТАТ /api/v1/bulstat
Банков onboarding /api/v1/bank
Промени /api/v1/amendments
Прехвърляне на дялове /api/v1/share-transfers
Закриване /api/v1/dissolution
Регистрация на фирма /api/v1/company-reg/{orgId}
Procurement /api/v1/procurement

Всички продукти и credit costs: GET /api/v1/catalog.


Плащане

Опция A: Stripe Checkout

curl -X POST https://firmify.bg/api/v1/legal-docs/{id}/checkout \
 -H "Authorization: Bearer fmfy_ВАШИЯ_API_КЛЮЧ"

Пренасочете потребителя към url. След плащане — POST /generate.

Опция B: Директно таксуване

  1. POST /api/v1/billing/setup → clientSecret
  2. Съберете карта с Stripe.js
  3. POST /api/v1/{category}/{id}/charge → POST /generate

Или използвайте месечна квота / credits — вижте Billing.


Billing

Ред на разрешаване на плащане:

  1. API Pro — абонамент на ниво потребител (€29/мес, 30 док/мес)
  2. Key tier quota — лимит на ключа (free/starter/pro/enterprise)
  3. Credit wallet — предплатени credits
  4. Stripe Checkout / charge — per-document

При липса на quota/credits: 402 с checkoutUrl или chargeUrl.

Управление: /developer/billing (session) или /api/v1/billing/* (Bearer).


Rate Limits

План Заявки/мин Док/мес Цена
free 10 10 €0
starter 30 100 €19/мес
pro 100 500 €49/мес
enterprise 300 10 000 €99/мес

Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

При превишаване: 429 с { "error": "...", "limit": 100, "window": "1m", "plan": "pro" }.


Обработка на грешки

{
 "error": "Validation failed",
 "details": [{ "path": ["companyName"], "message": "Required" }]
}
Status Значение
400 Validation error
401 Невалиден API ключ
402 Изисква се плащане
403 Недостатъчни права или непотвърден email
404 Не е намерен
429 Rate limit
500 Вътрешна грешка

X-Locale: en за съобщения на английски.


Idempotency

Изпратете Idempotency-Key при mutating заявки:

curl -X POST https://firmify.bg/api/v1/legal-docs \
 -H "Authorization: Bearer fmfy_ВАШИЯ_API_КЛЮЧ" \
 -H "Idempotency-Key: order-2026-07-14-001" \
 -H "Content-Type: application/json" \
 -d '{"docType": "GDPR_POLICY"}'

Кеширан отговор за 24 часа per key + method + path.


Webhooks

curl -X POST https://firmify.bg/api/v1/webhooks \
 -H "Authorization: Bearer fmfy_ВАШИЯ_API_КЛЮЧ" \
 -H "Content-Type: application/json" \
 -d '{"url": "https://myapp.com/webhook", "events": ["doc.generated"]}'

Събития: payment.completed, doc.generated, doc.failed, job.completed, job.failed

Верификация: HMAC-SHA256 в X-Firmify-Signature; тип в X-Firmify-Event.

Алтернатива: /developer/webhooks (session).


Async Jobs

Quick generate:

curl -X POST https://firmify.bg/api/v1/docs/generate \
 -H "Authorization: Bearer fmfy_ВАШИЯ_API_КЛЮЧ" \
 -H "Content-Type: application/json" \
 -d '{"docType": "GDPR_POLICY", "params": {"companyName": "Акме ООД", "companyEik": "123456789"}}'

Poll: GET /api/v1/jobs/{jobId}

За пълен контрол използвайте per-category CRUD flow.


Utility Endpoints

Method Path Цел
GET /api/v1/pricing Планове (без auth)
GET /api/v1/catalog Каталог (без auth)
POST /api/v1/register Headless signup
POST /api/v1/estimate Оценка на цена
POST /api/v1/batch Batch операции
GET /api/v1/analytics Аналитика

Registry Workflows

Промени, прехвърляне на дялове, закриване:

  1. Create → fill data
  2. POST /{id}/validate
  3. Pay → POST /{id}/generate
  4. Download / zip
  5. POST /{id}/upload-signed-pdf
  6. POST /{id}/mark-submitted

Продължението на регистрацията е под /api/v1/company-reg/{orgId}/generate, /zip, /upload-signed.

Криптираните създавания (RSA-4096 OAEP-SHA512 + AES-256-GCM) са под /api/v1/company-registration. Ако пропуснете незадължително поле, остава досегашното поведение.

Заявка Път
ЕООД POST /company-registration/eood
ООД POST /company-registration/ood
Евро превалутиране POST /company-registration/euro-conversion
Промяна POST /company-registration/amendments
ООД: евро + увеличение в едно събрание POST /company-registration/amendments/batch
  • articlesVariant при ЕООД и ООД: "short" (по подразбиране) или "long". Видовете документи и имената във ZIP остават същите.
  • shareNominalCents при евро превалутиране и в обекта euro на батча: цели евроцентове, минимум 2. Без полето важи едноцентовото превалутиране G1. Стойност 1 е грешка при валидация. Запазен брой дялове извън 5% толеранс връща HTTP 422 (BLOCKED).
  • newData.unanimityOptIn при промени: незадължителен boolean. Прилага се само при дългия вариант на дружествения договор и се игнорира при "short".
  • Самостоятелно евро превалутиране може да върне euroDeadlineWarning след 31 декември 2028 г. Преди тази дата полето липсва. Заявката не се отказва.

Батчът създава две свързани заявления. EURO редът се генерира в същото извикване и струва 0 кредита. CAPITAL редът струва 20 кредита и остава PAID с evidenceRequired: true, докато не качите POST /api/v1/amendments/{capitalAppId}/contribution-evidence и после извикате POST /api/v1/amendments/{capitalAppId}/generate (без второ таксуване). ЕООД връща HTTP 422.

Подписан ZIP

POST /api/v1/company-reg/{orgId}/upload-signed приема multipart поле zip и преминава организацията в SIGNED.

  • Всички очаквани файлове трябва да са в архива. Файл, който не е PDF, е 400 с INVALID_SIGNED_ZIP / NOT_A_PDF.
  • MANAGER_SPECIMEN е нотариално завереният образец от подписа, сканиран като PDF. API-то проверява само заглавката %PDF. Не изисква квалифициран електронен подпис, не сравнява текста с генерирания бланкет и не праща файла към QSVS. Заверката остава при вас.
  • Контролният лист А4 е помощен и не се изисква да е подписан.
  • Всеки друг очакван PDF трябва да съдържа цифров подпис (/ByteRange или /Type /Sig) и текстът му трябва да съвпада с генерирания оригинал. Когато сървърът има настроен QSVS, тези други PDF файлове се валидират криптографски. Образецът не се валидира така.
  • Същото правило за образеца важи и при качване на един файл MANAGER_SPECIMEN.

Procurement

TED opportunities, cases, doc-packs:

  • Profile: GET/PUT /api/v1/procurement/profile
  • Opportunities, cases, doc-packs

Пълен списък в OpenAPI.


Accounting API

Отделно от public v1 — същите ключове с accounting:read или accounting:multi:

GET https://firmify.bg/accounting/api/companies

Изисква X-Company-Id. Rate limit: 100 req/min per key + company.


Sandbox Mode

Sandbox ключове — без реални такси и генериране. Mock отговори за batch/quick-generate. За E2E тест — regular key + free tier (10 docs/мес).


Примери с код

const API_BASE = "https://firmify.bg/api/v1";
const headers = {
 Authorization: `Bearer ${process.env.FIRMIFY_API_KEY}`,
 "Content-Type": "application/json",
};
const createRes = await fetch(`${API_BASE}/legal-docs`, {
 method: "POST",
 headers: { ...headers, "Idempotency-Key": "order-001" },
 body: JSON.stringify({ docType: "GDPR_POLICY" }),
});
if (!createRes.ok) throw new Error((await createRes.json()).error);

API референция

Ресурс URL
Scalar https://firmify.bg/api/v1/docs
Swagger https://firmify.bg/api/v1/docs/swagger
Redoc https://firmify.bg/api/v1/docs/redoc
OpenAPI JSON https://firmify.bg/api/v1/openapi.json
Postman https://firmify.bg/api/v1/postman.json
Портал https://firmify.bg/developer
Ръководство /guide/public-api-guide
Changelog /guide/api-changelog
Поддръжка api@firmify.bg

Всички ръководства

Полезна ли беше тази статия?