Firmify Public API — ръководство за разработчици

1. Вземете API ключ

Посетете Портала за разработчици и влезте или създайте акаунт. Натиснете Създай API ключ, дайте име и запазете ключа — показва се само веднъж.

Headless регистрация

curl -X POST https://app.firmify.bg/api/v1/register \
 -H "Content-Type: application/json" \
 -d '{"email": "dev@example.com", "password": "secure-password"}'

---

2. Първа заявка

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

Каталог (без auth):

curl https://app.firmify.bg/api/v1/catalog

---

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

Стъпка по стъпка (препоръчително)

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

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

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

При API Pro quota, key-tier quota или credits, checkout може да се пропусне.

---

4. Налични типове документи

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

Пълен списък: GET /api/v1/catalog. За registry workflows вижте референцията.

---

5. Опции за плащане

A: /checkout → Stripe → /generate

B: /billing/setup → Stripe.js → /{category}/{id}/charge → /generate

C: API Pro (30 docs/мес) или credit packs — /developer/billing или /api/v1/billing/*

---

6. Rate Limits

План	Заявки/мин	Док/мес	Цена
Free	10	10	€0
Starter	30	100	€19/мес
Pro	100	500	€49/мес
Enterprise	300	10 000	€99/мес

---

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

{ "error": "Описание", "details": [...] }

401 — невалиден ключ · 402 — изисква се плащане · 403 — права/email · 429 — rate limit

---

8. Тестване без плащане

Free план — 10 документа/месец, без карта.

---

9. Sandbox Mode

Създайте sandbox ключ в Портала — без реални такси и генериране. Mock ID-та за batch/quick-generate.

---

10. Webhook Callback-и

curl -X POST https://app.firmify.bg/api/v1/webhooks \
 -H "Authorization: Bearer fmfy_ВАШИЯ_КЛЮЧ" \
 -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: X-Firmify-Signature, X-Firmify-Event

---

11. Async Generation

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

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

---

12. Idempotency

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

Кеш 24 часа.

---

13. Catalog-Driven Integration

curl https://app.firmify.bg/api/v1/catalog

Комбинирайте с POST /api/v1/estimate за оферти.

---

14. Клиентски библиотеки

npx @openapitools/openapi-generator-cli generate \
 -i https://app.firmify.bg/api/v1/openapi.json \
 -g typescript-axios \
 -o ./firmify-client

Postman: https://app.firmify.bg/api/v1/postman.json

---

Бърза справка

Ресурс	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	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
Changelog	/guide/api-changelog
Поддръжка	api@firmify.bg