# BarGen API Documentation

## Introduction

The BarGen API enables generation of SVG format barcodes and QR codes through simple HTTP requests.

- **API Base URL:** `https://api.bargen.pro`
- **Dashboard:** `https://bargen.pro/dashboard`

## Authentication

Every API request requires an API key, which can be generated from your dashboard at https://bargen.pro/dashboard/api-keys

The key must be sent in the `X-API-Key` header:

```bash
curl -H "X-API-Key: your-api-key" \
  "https://api.bargen.pro/v1/barcode/qrcode?data=Hello"
```

### Alternative Authentication Methods

You can also pass the API key via:

1. **Bearer Token:** `Authorization: Bearer your-api-key`
2. **Query Parameter:** `?api_key=your-api-key`

## Endpoints

### List Supported Formats

```
GET https://api.bargen.pro/v1/formats
```

Returns a list of all supported barcode formats. No authentication required.

**Response:**

```json
{
  "success": true,
  "data": {
    "formats": [
      {"type": "qrcode", "name": "QR Code", "category": "2D"},
      {"type": "code128", "name": "Code 128", "category": "1D"},
      ...
    ]
  }
}
```

### Generate Barcode

```
GET https://api.bargen.pro/v1/barcode/{type}
```

Generate a single barcode in SVG format.

**Path Parameters:**

| Parameter | Description |
|-----------|-------------|
| type | Barcode type (see supported types below) |

**Query Parameters:**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| data | string | yes | - | Data to encode |
| scale | integer | no | 2 | Scale factor (1-10) |
| height | integer | no | 50 | Height in pixels (1D codes only) |
| color | string | no | 000000 | Foreground color (hex without #) |
| bgcolor | string | no | ffffff | Background color (hex without #) |
| includetext | boolean | no | true | Show text below barcode (1D codes) |
| ecl | string | no | M | Error correction level for QR (L/M/Q/H) |

**Supported Barcode Types:**

| Type | Name | Category | Description |
|------|------|----------|-------------|
| qrcode | QR Code | 2D | General purpose 2D code |
| aztec | Aztec | 2D | Compact 2D code |
| datamatrix | DataMatrix | 2D | Small 2D code |
| pdf417 | PDF-417 | 2D | Driver's licenses, shipping |
| code128 | Code 128 | 1D | General purpose, high density |
| code39 | Code 39 | 1D | Alphanumeric, industrial |
| codabar | Codabar | 1D | Libraries, blood banks |
| ean13 | EAN-13 | 1D | European product identifier |
| ean8 | EAN-8 | 1D | Short EAN for small products |
| upca | UPC-A | 1D | USA product identifier |
| upce | UPC-E | 1D | Short UPC |
| itf14 | ITF-14 | 1D | Carton/pallet identifier |

**Example Request:**

```bash
curl -H "X-API-Key: your-api-key" \
  "https://api.bargen.pro/v1/barcode/qrcode?data=https://example.com&scale=4&color=00d4aa"
```

**Response:**

Content-Type: `image/svg+xml`

```xml
<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" ...>
  ...
</svg>
```

### Batch Generation

```
POST https://api.bargen.pro/v1/barcode/batch
```

Generate multiple barcodes in a single request (max 50 per request).

**Request Body (JSON):**

```json
{
  "codes": [
    {"type": "qrcode", "data": "https://example.com"},
    {"type": "ean13", "data": "5901234123457"},
    {"type": "code128", "data": "HELLO-123"}
  ],
  "options": {
    "scale": 2,
    "color": "000000",
    "bgcolor": "ffffff"
  }
}
```

**Response:**

```json
{
  "success": true,
  "data": {
    "results": [
      {"index": 0, "type": "qrcode", "svg": "<svg>...</svg>"},
      {"index": 1, "type": "ean13", "svg": "<svg>...</svg>"},
      {"index": 2, "type": "code128", "svg": "<svg>...</svg>"}
    ],
    "total": 3,
    "successful": 3,
    "failed": 0
  }
}
```

### Validate API Key

```
GET https://api.bargen.pro/v1/validate
```

Check if your API key is valid and get usage information.

**Response:**

```json
{
  "success": true,
  "data": {
    "valid": true,
    "name": "My API Key",
    "requests_count": 1234,
    "created_at": "2025-01-15T10:30:00Z"
  }
}
```

## Error Responses

All error responses follow this format:

```json
{
  "success": false,
  "error": "Error message here",
  "code": 400
}
```

**Error Codes:**

| Code | Meaning |
|------|---------|
| 400 | Bad Request - Invalid parameters |
| 401 | Unauthorized - Missing or invalid API key |
| 404 | Not Found - Endpoint not found |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Server Error - Internal server error |

## Code Examples

### JavaScript (Fetch)

```javascript
const response = await fetch(
  'https://api.bargen.pro/v1/barcode/qrcode?data=Hello%20World',
  {
    headers: {
      'X-API-Key': 'your-api-key'
    }
  }
);

const svg = await response.text();
document.getElementById('barcode').innerHTML = svg;
```

### Python (Requests)

```python
import requests

response = requests.get(
    'https://api.bargen.pro/v1/barcode/qrcode',
    params={'data': 'Hello World'},
    headers={'X-API-Key': 'your-api-key'}
)

svg_content = response.text
```

### PHP (cURL)

```php
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.bargen.pro/v1/barcode/qrcode?data=' . urlencode('Hello World'),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: your-api-key']
]);

$svg = curl_exec($ch);
curl_close($ch);
```

### Node.js (Axios)

```javascript
const axios = require('axios');

const response = await axios.get('https://api.bargen.pro/v1/barcode/qrcode', {
  params: { data: 'Hello World' },
  headers: { 'X-API-Key': 'your-api-key' }
});

const svg = response.data;
```

## Rate Limits

Currently, the API is free with unlimited requests. Rate limits may be introduced in the future.

## Support

- **Documentation:** https://bargen.pro/docs
- **Dashboard:** https://bargen.pro/dashboard
- **Email:** support@bargen.pro