# BillX Invoice API v1.0

RESTful API for invoice and customer management with Hungarian NAV integration.

## 🔗 Base URL

```
https://billx.hu/api/billx
```

## 🔐 Authentication

All requests require authentication using Bearer token:

```http
Authorization: Bearer YOUR_API_KEY
```

Get your API key from the Dashboard.

### Test Mode

For testing and development, you can use the following test API key:

```
test_billx_api_key_demo_12345678
```

**Test mode features:**
- ✅ Validates your API requests
- ✅ Returns realistic mock data
- ✅ Calculates totals correctly
- ❌ Does NOT create actual invoices
- ❌ Does NOT send data to NAV
- ❌ Does NOT affect your account

**Example test request:**
```bash
curl -X POST https://billx.hu/api/billx/invoices \
  -H "Authorization: Bearer test_billx_api_key_demo_12345678" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": 1, "fulfillment_date": "2025-01-15", ...}'
```

Response will include `"test_mode": true` to indicate it's a simulation.

## 📚 Endpoints

### Customers

#### List Customers
```http
GET /api/billx/customers
```

**Response:**
```json
{
  "data": [
    {
      "id": 1,
      "name": "Acme Corp",
      "email": "info@acme.com",
      "tax_number": "12345678-1-23",
      "phone": "+36301234567",
      "postal_code": "1011",
      "city": "Budapest",
      "address": "Fő utca 1.",
      "country": "HU",
      "created_at": "2025-01-01 10:00:00"
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "per_page": 20
  }
}
```

#### Create Customer
```http
POST /api/billx/customers
Content-Type: application/json

{
  "name": "Acme Corp",
  "email": "info@acme.com",
  "tax_number": "12345678-1-23",
  "phone": "+36301234567",
  "postal_code": "1011",
  "city": "Budapest",
  "address": "Fő utca 1."
}
```

### Invoices

#### List Invoices
```http
GET /api/billx/invoices?page=1&per_page=20
```

**Response:**
```json
{
  "data": [
    {
      "id": 123,
      "invoice_number": "2025-0001",
      "invoice_type": "invoice",
      "invoice_date": "2025-01-15",
      "fulfillment_date": "2025-01-15",
      "due_date": "2025-01-22",
      "status": "unpaid",
      "payment_method": "transfer",
      "total_net": 10000,
      "total_vat": 2700,
      "total_gross": 12700,
      "currency": "HUF",
      "customer": {
        "id": 1,
        "name": "Acme Corp"
      },
      "created_at": "2025-01-15 10:00:00"
    }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "per_page": 20
  }
}
```

#### Create Invoice
```http
POST /api/billx/invoices
Content-Type: application/json

{
  "customer_id": 1,
  "invoice_type": "invoice",
  "block_id": 1,
  "fulfillment_date": "2025-01-15",
  "due_date": "2025-01-22",
  "payment_method": "transfer",
  "currency": "HUF",
  "notes": "Thank you for your business",
  "items": [
    {
      "name": "Web Development",
      "unit": "hour",
      "quantity": 10,
      "unit_price": 10000,
      "vat_rate": 27
    },
    {
      "name": "Hosting",
      "unit": "month",
      "quantity": 1,
      "unit_price": 5000,
      "vat_rate": 27
    }
  ]
}
```

**Response:**
```json
{
  "id": 123,
  "invoice_number": "BILLX-2025/0001",
  "invoice_type": "invoice",
  "total_net": 105000,
  "total_vat": 28350,
  "total_gross": 133350,
  "currency": "HUF"
}
```

**Note:** Invoice numbers follow your invoice series format (e.g., `BILLX-2025/0001`, `BILLX-ABC-2025/0042`). If `block_id` is not specified, the default invoice series will be used.

### Products

#### List Products
```http
GET /api/billx/products
```

**Response:**
```json
{
  "data": [
    {
      "id": 1,
      "name": "Web Development",
      "unit": "hour",
      "price": 10000,
      "vat_rate": 27,
      "description": "Hourly rate for web development"
    }
  ]
}
```

#### Create Product
```http
POST /api/billx/products
Content-Type: application/json

{
  "name": "Web Development",
  "unit": "hour",
  "price": 10000,
  "vat_rate": 27,
  "description": "Hourly rate for web development"
}
```

## 📋 Field Reference

### Customer Fields
- `id` - Unique identifier (read-only)
- `name` - Customer name (required)
- `email` - Email address
- `tax_number` - Hungarian tax number (e.g. "12345678-1-23")
- `phone` - Phone number
- `postal_code` - Postal code
- `city` - City name
- `address` - Street address
- `country` - Country code (always "HU")

### Invoice Fields
- `customer_id` - Customer ID (required)
- `invoice_type` - Invoice type: "invoice" (final), "proforma" (pro forma), "draft" (draft) (default: "invoice")
- `block_id` - Invoice series ID (optional, uses default series if not specified)
- `fulfillment_date` - Service delivery date (YYYY-MM-DD, required)
- `due_date` - Payment deadline (YYYY-MM-DD, required)
- `payment_method` - Payment method: "transfer", "cash", "card" (required)
- `currency` - Currency code (default: "HUF")
- `exchange_rate` - Exchange rate (default: 1.0)
- `notes` - Additional notes

### Invoice Item Fields
- `name` - Item description (required)
- `unit` - Unit of measurement (default: "db")
- `quantity` - Quantity (required)
- `unit_price` - Net unit price (required)
- `vat_rate` - VAT rate percentage (default: 27)

## 🔢 Invoice Series (Számlatömbök)

Invoice numbers are generated based on your **invoice series** (számlatömb). Each series has a prefix and maintains its own sequential numbering.

### Using Invoice Series

**Option 1: Use default series (recommended)**
```json
{
  "customer_id": 1,
  "fulfillment_date": "2025-01-15",
  ...
}
```
The API automatically uses your default invoice series. Invoice number format: `BILLX-{prefix}-{year}/{number}`

**Option 2: Specify series explicitly**
```json
{
  "customer_id": 1,
  "block_id": 5,
  "fulfillment_date": "2025-01-15",
  ...
}
```
Use a specific invoice series by providing its `block_id`.

### Invoice Number Format Examples
- `BILLX-2025/0001` - Simple format with year
- `BILLX-ABC-2025/0042` - Custom prefix "ABC"
- `BILLX-PROFORMA-2025/0001` - Pro forma invoice
- `DRAFT-xxxxx-XXXX` - Draft invoice (no sequential number)

**Important:** Each invoice series maintains its own counter. Using different series allows you to separate invoices by category, business unit, or any other criteria.

## 📝 Invoice Types

The API supports three invoice types:

### Final Invoice (`invoice`)
Standard invoice for completed transactions. This is the default type.
```json
{
  "customer_id": 1,
  "invoice_type": "invoice",
  "fulfillment_date": "2025-01-15",
  "due_date": "2025-01-22",
  "payment_method": "transfer",
  "items": [...]
}
```

### Pro Forma Invoice (`proforma`)
Preliminary invoice issued before delivery or as a quote.
```json
{
  "customer_id": 1,
  "invoice_type": "proforma",
  "fulfillment_date": "2025-01-15",
  "due_date": "2025-01-22",
  "payment_method": "transfer",
  "items": [...]
}
```

### Draft Invoice (`draft`)
Draft invoice for internal review before finalization.
```json
{
  "customer_id": 1,
  "invoice_type": "draft",
  "fulfillment_date": "2025-01-15",
  "due_date": "2025-01-22",
  "payment_method": "transfer",
  "items": [...]
}
```

## 🔄 Integration Examples

Check the `/examples` folder for complete integration examples in PHP, Python, and JavaScript.

Full documentation: https://billx.hu/api/docs