AlphaBill API

REST API for invoice automation • v1.0

Authentication
Current User
Invoices
Clients
Products
Statistics
Error Handling
Examples

🔑 Authentication

All API requests require an API key. Pass it via one of these methods:

Method	Example
Header (recommended)	`X-API-Key: your_key_here`
Bearer token	`Authorization: Bearer your_key_here`
Query parameter	`?api_key=your_key_here`

Base URL: https://api.alphabill.hu

User Scoping: Each API key is tied to a user account. You can only access invoices, clients, and statistics belonging to your account. Products are shared across all users. Manage your keys in Settings → API Keys.

👤 Current User

API Key Info

GET /me

Returns information about the current API key and its owner.

📄 Invoices

List Invoices

GET /invoices

Query parameters:

Param	Type	Description
`status`	string	optional Filter: draft, sent, paid, overdue, cancelled
`client_id`	int	optional Filter by client ID
`from`	date	optional Issue date from (YYYY-MM-DD)
`to`	date	optional Issue date to (YYYY-MM-DD)
`limit`	int	optional Max results (default 50, max 200)
`offset`	int	optional Pagination offset

Get Invoice

GET /invoices/{id}

Returns full invoice details including line items, share URL, and PDF URL.

Create Invoice

POST /invoices

Create a new invoice. Totals, tax amounts, and HUF conversions are calculated automatically.

Field	Type	Description
`client_id`	int	required* Existing client ID
`buyer_name`	string	required* Buyer name (alternative to client_id)
`buyer_company`	string	optional Override buyer company
`buyer_email`	string	optional Override buyer email
`buyer_address`	string	optional Override buyer address
`buyer_country`	string	optional Override buyer country
`buyer_city`	string	optional Override buyer city
`buyer_zipcode`	string	optional Override buyer zipcode
`buyer_tax`	string	optional Override buyer tax number
`items`	array	required Array of line items (see below)
`issue_date`	date	optional Default: today
`fulfillment_date`	date	optional Default: issue_date
`due_date`	date	optional Default: +30 days
`currency`	string	optional EUR, USD, GBP, HUF (default from settings)
`huf_rate`	float	optional Override HUF exchange rate (auto-fetched if omitted)
`payment_method`	string	optional Default from settings
`status`	string	optional draft (default), sent, or paid
`notes`	string	optional Invoice notes/comments

Line item fields:

Field	Type	Description
`description`	string	required* Item description (on invoice)
`product_id`	int	required* Load from product (fills defaults)
`quantity`	float	optional Default: 1 (or product default)
`unit_price`	float	optional Default: 0 (or product price)
`tax_rate`	float	optional Default: 27% (or product rate)
`comment`	string	optional Additional notes for this item

Note: Each item needs either description or product_id. When using product_id, the product's name, price, quantity, tax rate, and comment are used as defaults — you can still override any of them.

Update Invoice Status

PUT /invoices/{id}/status

Field	Type	Description
`status`	string	required draft, sent, paid, or cancelled

Setting to paid auto-records a payment. Setting to sent generates the PDF.

Download Invoice PDF

GET /invoices/{id}/pdf

Returns the PDF binary. Generates it on-the-fly if missing.

👥 Clients

List Clients

GET /clients

Param	Type	Description
`search`	string	optional Search in name, company, email
`limit`	int	optional Default 100, max 500
`offset`	int	optional Pagination offset

Get Client

GET /clients/{id}

Create Client

POST /clients

Field	Type	Description
`name`	string	required Client name
`company`	string	optional
`email`	string	optional
`phone`	string	optional
`address`	string	optional
`country`	string	optional
`city`	string	optional
`zipcode`	string	optional
`tax_number`	string	optional
`notes`	string	optional

📦 Products

List Products

GET /products

Param	Type	Description
`active`	int	optional Filter: 1 = active only, 0 = inactive only

Get Product

GET /products/{id}

📊 Statistics

GET /stats

Param	Type	Description
`year`	int	optional Default: current year

Returns total invoices, total clients, revenue by status, and payment totals.

⚠️ Error Handling

All errors return a consistent JSON format:

{
  "error": true,
  "message": "Description of what went wrong",
  "code": 422,
  "details": ["Field-level errors if applicable"]
}

Code	Meaning
`401`	Missing or invalid API key
`404`	Resource not found
`422`	Validation error (check details array)
`500`	Server error

🚀 Examples

Create an invoice from products

curl -X POST https://api.alphabill.hu/invoices \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "client_id": 1,
    "status": "sent",
    "items": [
      {"product_id": 1, "quantity": 2},
      {"product_id": 3}
    ]
  }'

Create an invoice with custom items

curl -X POST https://api.alphabill.hu/invoices \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "client_id": 1,
    "issue_date": "2026-03-25",
    "due_date": "2026-04-25",
    "currency": "EUR",
    "payment_method": "Átutalás",
    "status": "draft",
    "notes": "Thank you for your business",
    "items": [
      {
        "description": "Web Development - March 2026",
        "quantity": 1,
        "unit_price": 2500.00,
        "tax_rate": 27,
        "comment": "Frontend + backend work"
      },
      {
        "description": "Hosting",
        "quantity": 1,
        "unit_price": 50.00,
        "tax_rate": 27
      }
    ]
  }'

Create invoice for a new buyer (no client record)

curl -X POST https://api.alphabill.hu/invoices \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "buyer_name": "John Doe",
    "buyer_company": "ACME Corp",
    "buyer_address": "123 Main St",
    "buyer_city": "Budapest",
    "buyer_country": "Hungary",
    "buyer_tax": "12345678-1-42",
    "items": [
      {"description": "Consulting", "quantity": 10, "unit_price": 100, "tax_rate": 27}
    ]
  }'

Mark invoice as paid

curl -X PUT https://api.alphabill.hu/invoices/5/status \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"status": "paid"}'

List unpaid invoices

curl https://api.alphabill.hu/invoices?status=sent \
  -H "X-API-Key: YOUR_API_KEY"

Create a client

curl -X POST https://api.alphabill.hu/clients \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "name": "Jane Smith",
    "company": "Smith & Co",
    "email": "jane@smith.co",
    "address": "456 Oak Ave",
    "city": "Vienna",
    "country": "Austria",
    "tax_number": "ATU12345678"
  }'

Download invoice PDF

curl https://api.alphabill.hu/invoices/5/pdf \
  -H "X-API-Key: YOUR_API_KEY" \
  -o invoice.pdf

AlphaBill API v1.0 • Back to Dashboard