Invoicing API for Custom Apps
Your business logic, our tax infrastructure
Any business workflow that needs invoicing can integrate with BeeL. The API adapts to your architecture and logic, not the other way around. From vertical applications to complex multi-tenant platforms.
Why build your app on the BeeL. API?
Every business has unique workflows. BeeL. gives you the tax foundations so you can focus on what makes your application special.
Complete tax abstraction
No deep knowledge of VAT, income tax, VeriFactu or sequential numbering needed. BeeL. encapsulates all the complexity. You send business data (client, amount, description) and receive a legally valid invoice.
Integration flexibility
Standard REST API that works with any stack: SPA frontend, Node/Python/Go/PHP backend, serverless functions, webhooks. You're not tied to any specific framework or platform.
Composability with other services
BeeL. is just another piece of your architecture. Combine it with Stripe for payments, SendGrid for emails, your database for clients. Each service does what it does best — you orchestrate the complete flow.
Full control over the user experience
You decide when and how invoices are issued in your app. It can be automatic on order confirmation, manual from a button, scheduled with cron, or triggered by external events. The API is your backend — you control the frontend.
Arbitrarily complex business logic
Volume discounts, promotions, dynamic pricing, tiered commissions, multiple currencies converted to EUR... calculate whatever you need in your app and send the result to BeeL. You're not limited by templates or preset rules.
Innovation without tax friction
You're building something new, an unconventional business model. Don't let invoicing slow you down. BeeL. lets you innovate on your value proposition while maintaining automatic regulatory compliance.
Common integration patterns for custom apps
Typical architectures and workflows that developers implement with BeeL.
Event-driven: invoicing from domain events
Your app emits business events (OrderCompleted, SubscriptionRenewed, ProjectDelivered). A consumer listens for these events and calls BeeL. to invoice.
- Pub/Sub with RabbitMQ, Redis, Kafka, or your framework's native event bus
- Consumer receives event, validates data, calls POST /invoices
- Idempotency via event ID guarantees one invoice per event
Serverless: cloud functions that invoice on-demand
AWS Lambda, Vercel Functions, Cloudflare Workers. Your function fires via HTTP request or cloud event and executes invoicing logic.
- Function receives payload (client, amount, description)
- fetch() to BeeL. API from serverless environment
- Responds to your frontend with invoice_id and status
Background jobs: async invoicing queue
Queue invoicing jobs (Sidekiq, Celery, Bull) for background processing. Useful when invoicing shouldn't block the user response.
- User confirms action in frontend → backend enqueues job
- Worker processes job when capacity is available
- Job calls BeeL., updates status in DB, notifies user
Multi-tenant: each tenant with their own BeeL. account
If your app is SaaS with multiple companies as clients, each company has its own BeeL. API key. Your app stores the key per tenant and invoices on behalf of the corresponding tenant.
- Tenants table with beel_api_key column
- When invoicing, read the active tenant's API key
- Calls to BeeL. use the tenant's key, not yours
Batch processing: bulk issuance with error handling
Process batches of invoices (end of month, project close with multiple clients). Iterate, call BeeL. for each one, log results.
- Script iterates over clients to invoice
- try/catch per client to isolate errors
- Log of successful vs failed for manual retry if needed
Advanced capabilities for complex apps
API features that support sophisticated use cases.
Drafts vs. issued invoices
Create invoices in 'draft' status (they don't count toward the monthly limit) for review. When confirmed, issue them with a second call. Useful if you need human approval before issuing.
Programmatic credit notes
POST /invoices with type 'credit_note' and reference to the original invoice. BeeL. manages the invoice chain automatically. Perfect for returns, cancellations or adjustments.
Multi-language PDFs (ES, EN, CA)
Specify the language when creating an invoice. BeeL. generates the PDF in the requested language. Useful if you have international clients or regions with co-official languages.
Advanced pagination and filtering
GET /invoices with pagination parameters (page, limit), filters (start_date, end_date, client_id, status). Build dashboards and reports with no performance limits.
Frequently asked questions for custom apps
Can I invoice on behalf of multiple companies from one app?
Yes, if your app is multi-tenant. Each company that invoices needs its own BeeL. account and API key. Your app stores the API key per tenant and uses it when invoicing. You cannot invoice on behalf of third parties with your own key.
Does the API support invoicing in currencies other than EUR?
No. BeeL. issues invoices in EUR because it's designed for Spanish tax compliance. If you charge in USD, GBP, etc., you must convert to EUR before calling the API. You can record the original currency in description or notes fields for reference.
How do I manage invoice access permissions in my app?
BeeL. doesn't manage roles or user permissions for your app. Your backend is responsible for authenticating users and verifying they only access permitted invoices. BeeL. only validates the tenant/company API key. Implement your authorization logic before calling BeeL.
Can I integrate BeeL. with a frontend without a backend (Jamstack)?
It's not recommended. Never expose your API key in the frontend (client's browser). You need a backend (serverless or traditional) that handles the API key and calls BeeL. The frontend calls your backend, and your backend calls BeeL. securely.
What if my app requires custom fields on invoices?
You can use the 'notes' field to add additional information that will appear on the PDF. However, mandatory tax fields cannot be modified. If you need internal tracking (order IDs, references), store them in your DB linked to BeeL.'s invoice_id.
Ready to automate your invoicing?
Integrate BeeL.'s API and start invoicing in minutes.