# 🎴 Business Card API - Service Documentation

**Service:** Professional Business Cards with QR Codes  
**Base URL:** `https://qr-bcard-service-production.up.railway.app`  
**Type:** Puppeteer-based rendering (perfect text)

---

## Endpoint

### **GET /image** - Generate Business Card

**Parameters:**
- `name` (required) - Full name
- `company` - Company name
- `position` - Job title/position
- `phone` - Phone number
- `email` - Email address
- `web` - Website URL

**Response:** PNG image (5400×3150px @ 3x DPI, print-ready)

---

## Features

✅ **Perfect Text Rendering** - Chrome/Puppeteer based  
✅ **Integrated QR Code** - Contains vCard with all contact info  
✅ **Print Quality** - 3x DPI (5400×3150px)  
✅ **Professional Layout** - Based on working frontend design  

---

## Examples

### **Minimal (just name)**
```bash
curl "https://qr-bcard-service-production.up.railway.app/image?name=Alice%20Smith" -o card.png
```

### **Complete Business Card**
```bash
curl "https://qr-bcard-service-production.up.railway.app/image?name=John%20Doe&company=TechCorp%20Inc&position=CEO&phone=+1-555-123-4567&email=john.doe@techcorp.com&web=techcorp.com" -o businesscard.png
```

### **HTML Embedding**
```html
<img src="https://qr-bcard-service-production.up.railway.app/image?name=John%20Doe&company=TechCorp&email=john@techcorp.com" 
     alt="Business Card" />
```

---

## For AI Agents

**When user says:** "Create a business card" or "Make me a business card"

**You should:**
1. Ask for or extract:
   - Name (required)
   - Company, position, phone, email, website (optional)
2. Build URL with query parameters
3. Call GET endpoint
4. Display PNG or provide download link

**Python Example:**
```python
from urllib.parse import urlencode

def generate_business_card(contact: dict):
    params = {k: v for k, v in contact.items() if v}  # Remove None values
    url = f"https://qr-bcard-service-production.up.railway.app/image?{urlencode(params)}"
    return url  # Use as img src
```

---

## vCard Integration

The QR code on the business card contains a vCard with all provided contact information:

```
BEGIN:VCARD
VERSION:3.0
FN:[name]
ORG:[company]
TITLE:[position]
TEL:[phone]
EMAIL:[email]
URL:[website]
END:VCARD
```

**When scanned:** Adds contact directly to phone

---

## Output Details

**Image Dimensions:** 5400×3150 pixels (business card aspect ratio)  
**Logical Size:** 600×350 (3x scale for print quality)  
**File Size:** ~60-500KB depending on content  
**Format:** PNG with transparency  
**DPI:** 3x for crisp printing  

---

## Error Handling

| Error | Cause | Fix |
|-------|-------|-----|
| "Missing required parameter: name" | No name provided | Add `?name=YourName` |
| "Error generating business card" | Server issue | Try again or check service health |

---

## Limitations

- Maximum field lengths: Reasonable (no strict limit)
- No logo support (coming in V3.0)
- Single orientation (horizontal landscape)
- No custom styling (V3.0 feature)

---

## Performance

**Response time:** 1-3 seconds (Puppeteer rendering)  
**Caching:** Not implemented (generates fresh each time)  
**Concurrent requests:** Supported (browser reused)

---

**Service Documentation:** Technical details only  
**Back to Master Guide:** [AI-GUIDE.md](../AI-GUIDE.md)