BeeL.es
Back to API
Developer Tools

Invoicing API for Developers

If you invoice by code, BeeL. is your invoicing backend

Automated scripts, custom CLIs, internal tools. If you write code to invoice, BeeL.'s API gives you the full tax engine without building it. Integrate in minutes, invoice from terminal or cron jobs.

Why do developers choose BeeL.'s API?

When you're a developer and invoicing is part of your workflow, you need an API that speaks your language: REST, JSON, idempotency, OpenAPI.

Downloadable OpenAPI 3.0 contract

Complete specification of all endpoints, parameters, responses and errors. Generate typed clients for TypeScript, Python, Go, Rust with standard tools (openapi-generator). No need to read human documentation — the contract is the source of truth.

Two environments: test and production

test.beel.es for development and testing with dummy data. app.beel.es for production with real invoices. Same API, completely isolated data. Develop and test risk-free before deploying.

Native idempotency with headers

X-Idempotency-Key included in POST requests. Safe retry without duplicates. If your script fails mid-process and you retry, BeeL. recognizes the key and returns the original result. Zero duplicate invoices from network errors or timeouts.

Authentication via API Keys

No complex OAuth flows. One API key in the X-API-Key header and you're set. Rotate keys from the dashboard without touching code. Perfect for scripts, cron jobs and CLIs where OAuth is overkill.

Perfect for CLIs and scripts

curl, httpie, Postman, your favorite language (Node, Python, Go, Ruby). The API is pure REST with no specific dependencies. Write a 10-line bash script and invoice from terminal.

No mandatory SDKs or lock-in

No need to install proprietary libraries. Use fetch, axios, requests, your language's native http.get. The API is standard HTTP/JSON. Switch tools or languages without issues.

Typical use cases for developers

Real examples of how developers use the API day to day.

1

CLI to invoice from terminal

Create a CLI script that reads data from a CSV or arguments, calls the API and issues invoices in bulk. Useful for importing data or invoicing completed work batches.

  • $ beel-invoice --client acme --amount 1500 --description 'Project X'
  • Script validates data locally before calling the API
  • Output: invoice_id and link to the downloaded PDF
2

Monthly cron job for recurring invoicing

Set up a cron that on the 1st of each month reads your list of recurring clients (retainers, SaaS) and issues invoices automatically.

  • 0 9 1 * * /usr/local/bin/invoice-recurring.sh
  • Script iterates clients, generates invoice with current month date
  • Logs saved for auditing, Slack/email notifications on failure
3

GitHub Actions to invoice on merge to main

CI workflow that automatically invoices when you merge a PR to main. Useful if your repo represents billable work (client projects).

  • Trigger: on push to main
  • Reads commit or PR metadata (client, hours, description)
  • Calls POST /facturas if conditions are met (tag, label, etc.)
4

Webhook receiver to integrate with other APIs

Express/Flask server that receives webhooks from Stripe, PayPal, Shopify, etc. and transforms the data to BeeL.'s format to issue invoices automatically.

  • POST /webhook/stripe validates Stripe signature
  • Extracts event data (customer, amount, description)
  • POST to BeeL. with X-Idempotency-Key = stripe_payment_id
5

Internal dashboard with real-time invoicing data

Custom frontend (React, Vue, Svelte) that consumes GET /facturas to display financial dashboards. Filter by date, client, export to CSV.

  • GET /facturas?fecha_inicio=2024-01-01&estado=emitida
  • Render tables, charts, invoicing metrics
  • PDF download button per invoice (GET /facturas/:id/pdf)

Why BeeL.'s API is developer-friendly

Designed with automation, integration and developer experience in mind.

Downloadable OpenAPI spec

openapi.json publicly available. Generate typed clients, validate requests offline, integrate with testing tools (Postman, Insomnia). The API is self-documenting.

Clear and consistent errors

Standard HTTP codes (400, 401, 404, 422, 500) with structured JSON error messages. You know exactly what failed and how to fix it without reading extensive docs.

Latency <200ms in production

Infrastructure optimized for fast responses. Your scripts don't block waiting for responses. Rate limit of 1000 req/hour by default, scalable with enterprise plans.

API versioning with backward compatibility

/api/v1 is stable and doesn't break backward compatibility. New features are opt-in. Code written today will work in 2 years without changes.

Frequently asked questions for developers

Is there rate limiting on the API?

Yes, 1000 requests/hour by default on the standard API plan. If you hit the limit, you get 429 Too Many Requests with a Retry-After header indicating when you can retry. For higher volumes, enterprise plans with custom rate limits.

Can I make parallel calls or do I need to sequence them?

You can make parallel calls without any issues. The API is stateless and thread-safe. If you issue 100 invoices simultaneously (Promise.all in JS, asyncio in Python), it works. Just make sure to respect the 1000 req/hour rate limit.

How do I handle network errors or timeouts?

Use X-Idempotency-Key on all your POST calls. If your request fails due to timeout or network error, retry with the same key. BeeL. will respond with the original result if the operation already completed, or execute the operation if it didn't arrive. Safe retry without duplicates.

Can I use webhooks to receive notifications from BeeL.?

Currently BeeL. doesn't send webhooks to your system (future roadmap). If you need polling, use GET /facturas with last sync date to get new invoices. Alternatively, store invoice_ids when you issue and only query those.

Are there official SDKs for Node, Python, Go?

There are no official SDKs maintained by BeeL. However, you can generate typed clients from the OpenAPI spec using tools like openapi-generator or Swagger Codegen. This gives you TypeScript types, Python classes, Go structs automatically.

Ready to automate your invoicing?

Integrate BeeL.'s API and start invoicing in minutes.