Firmify Public API — Developer's Guide

1. Get Your API Key

Visit the Developer Portal and log in or create an account. Click Create API Key, give it a name, and save the key — it is shown only once.

Your key looks like: fmfy_a1b2c3d4...

Headless signup (no UI)

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

→ Returns { "userId": "...", "apiKey": "fmfy_...", "keyPrefix": "fmfy_..." }

---

2. Make Your First Request

curl -H "Authorization: Bearer fmfy_YOUR_KEY" https://app.firmify.bg/api/v1/pricing

Also try the catalog (no auth required):

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

---

3. Generate a Document

Step-by-step flow (recommended)

1. Create (DRAFT):

curl -X POST https://app.firmify.bg/api/v1/legal-docs \
 -H "Authorization: Bearer fmfy_YOUR_KEY" \
 -H "Content-Type: application/json" \
 -d '{"docType": "GDPR_POLICY"}'

2. Fill in data:

curl -X PUT https://app.firmify.bg/api/v1/legal-docs/{id} \
 -H "Authorization: Bearer fmfy_YOUR_KEY" \
 -H "Content-Type: application/json" \
 -d '{"companyName": "Acme OOD", "companyEik": "123456789"}'

3. Pay via checkout:

curl -X POST https://app.firmify.bg/api/v1/legal-docs/{id}/checkout \
 -H "Authorization: Bearer fmfy_YOUR_KEY"

4. Generate:

curl -X POST https://app.firmify.bg/api/v1/legal-docs/{id}/generate \
 -H "Authorization: Bearer fmfy_YOUR_KEY"

5. Download:

curl https://app.firmify.bg/api/v1/legal-docs/{id}/download \
 -H "Authorization: Bearer fmfy_YOUR_KEY" -o document.pdf

If you have API Pro quota, key-tier quota, or credits, step 3 may be skipped — the API debits automatically on /generate.

---

4. Available Document Types

Category	Path	Notes
Legal Docs	/api/v1/legal-docs	GDPR, ToS, NDA (7 types)
HR Docs	/api/v1/hr-docs	Employment contracts (9 types)
Business Docs	/api/v1/business-docs	Offers, invoices
VAT Reg	/api/v1/vat	VAT application bundle
BULSTAT	/api/v1/bulstat	BULSTAT registration
Bank	/api/v1/bank	Bank onboarding
Amendments	/api/v1/amendments	Registry changes
Share Transfers	/api/v1/share-transfers	Share transfer
Dissolution	/api/v1/dissolution	Company dissolution
Company Reg	/api/v1/company-reg	Registration docs (async)
Procurement	/api/v1/procurement	TED cases + doc-packs

Full list with JSON schemas: GET /api/v1/catalog.

For amendments and dissolution workflows, see the reference guide (Registry Workflows section).

---

5. Payment Options

Option A: Stripe Checkout (end-user pays)

/checkout → Stripe URL → user pays → /generate

Option B: Direct charge (automated)

1. POST /api/v1/billing/setup → clientSecret
2. Stripe.js on your frontend
3. POST /api/v1/{category}/{id}/charge → /generate

Option C: Quota or credits

Subscribe to API Pro (30 docs/month) or buy credit packs via /developer/billing or /api/v1/billing/*.

---

6. Rate Limits

Plan	Requests/min	Docs/month	Price
Free	10	10	€0
Starter	30	100	€19/mo
Pro	100	500	€49/mo
Enterprise	300	10,000	€99/mo

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

---

7. Error Handling

{ "error": "Description", "details": [...] }

• 401 — invalid/missing API key
• 402 — payment required (checkoutUrl / chargeUrl in body)
• 403 — insufficient permissions or unverified email
• 429 — rate limit exceeded

---

8. Testing Without Paying

Use the free plan (10 docs/month). No credit card required.

---

9. Sandbox Mode

Create a sandbox API key in the Developer Portal — check Sandbox when creating the key.

• No real Stripe charges or document generation
• Mock IDs for batch/quick-generate testing
• Ideal for CI/CD

For real end-to-end tests, use a regular key and the free monthly quota.

---

10. Webhook Callbacks

curl -X POST https://app.firmify.bg/api/v1/webhooks \
 -H "Authorization: Bearer fmfy_YOUR_KEY" \
 -H "Content-Type: application/json" \
 -d '{"url": "https://myapp.com/webhook", "events": ["payment.completed", "doc.generated"]}'

Events: payment.completed, doc.generated, doc.failed, job.completed, job.failed

Verify HMAC-SHA256: X-Firmify-Signature, X-Firmify-Event.

---

11. Async Generation

For a single-call flow (legal/hr/business only):

curl -X POST https://app.firmify.bg/api/v1/docs/generate \
 -H "Authorization: Bearer fmfy_YOUR_KEY" \
 -H "Content-Type: application/json" \
 -d '{"docType": "GDPR_POLICY", "params": {"companyName": "Acme OOD", "companyEik": "123456789"}}'

Poll the job:

curl -H "Authorization: Bearer fmfy_YOUR_KEY" \
 https://app.firmify.bg/api/v1/jobs/{jobId}

Use the step-by-step CRUD flow when you need checkout control or registry-specific steps. Company registration and procurement doc-packs always use async jobs.

---

12. Idempotency

Retry safely with Idempotency-Key:

curl -X POST https://app.firmify.bg/api/v1/legal-docs \
 -H "Authorization: Bearer fmfy_YOUR_KEY" \
 -H "Idempotency-Key: my-order-001" \
 -H "Content-Type: application/json" \
 -d '{"docType": "GDPR_POLICY"}'

Duplicate requests within 24 hours return the cached response.

---

13. Catalog-Driven Integration

Discover products programmatically before building your UI:

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

Returns doc types, JSON schemas, and credit costs per category. Combine with POST /api/v1/estimate for price quotes.

---

14. Client Libraries

Generate a client from OpenAPI:

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

Import the Postman collection for manual testing.

---

Quick Reference

Resource	URL
Scalar docs	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
Developer portal	https://app.firmify.bg/en/developer
Reference guide	/en/guide/public-api
Changelog	/en/guide/api-changelog
Support	api@firmify.bg