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

Общ преглед

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

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

https://app.firmify.bg/api/v1
https://app.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://app.firmify.bg/api/v1/legal-docs \
 -H "Authorization: Bearer fmfy_ВАШИЯ_API_КЛЮЧ" \
 -H "Content-Type: application/json" \
 -d '{"docType": "GDPR_POLICY"}'

curl -X PUT https://app.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://app.firmify.bg/api/v1/legal-docs/{id}/checkout \
 -H "Authorization: Bearer fmfy_ВАШИЯ_API_КЛЮЧ"

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

curl https://app.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://app.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://app.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://app.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://app.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://app.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

Company registration: /api/v1/company-reg/{orgId}/*.

---

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://app.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://app.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://app.firmify.bg/api/v1/docs
Swagger	https://app.firmify.bg/api/v1/docs/swagger
Redoc	https://app.firmify.bg/api/v1/docs/redoc
OpenAPI JSON	https://app.firmify.bg/api/v1/openapi.json
Postman	https://app.firmify.bg/api/v1/postman.json
Портал	https://app.firmify.bg/developer
Ръководство	/guide/public-api-guide
Changelog	/guide/api-changelog
Поддръжка	api@firmify.bg