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

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

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

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

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

curl -X POST https://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://firmify.bg/api/v1/pricing

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

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

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

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

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

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

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

curl https://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 (продължение). Криптирани създавания: /api/v1/company-registration
Procurement /api/v1/procurement

Пълен списък: GET /api/v1/catalog. За промени, криптирания договор за регистрация (articlesVariant, shareNominalCents, батч евро + увеличение при ООД) и правилата за подписан ZIP вижте референцията. Образецът на подписа в този ZIP е сканиран нотариално заверен PDF: трябва да е истински PDF и не се проверява за цифров подпис.


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://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://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://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://firmify.bg/api/v1/catalog

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


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

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

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


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

Ресурс 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 https://firmify.bg/api/v1/openapi.json
Postman https://firmify.bg/api/v1/postman.json
Портал https://firmify.bg/developer
Референция /guide/public-api
Changelog /guide/api-changelog
Поддръжка api@firmify.bg

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

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