Add comprehensive API documentation for QR Code Generation API
All checks were successful
Build and Push Docker Images / docker (push) Successful in 22s
All checks were successful
Build and Push Docker Images / docker (push) Successful in 22s
- Document QR Code Generation API with three calculation types (fuel, distance, custom) - Include PNG vs SVG format comparison table with use case recommendations - Provide usage examples in cURL, JavaScript, Python, and HTML - Document Checkout API endpoints - Add best practices, error handling, and future enhancements section - Clarify that vessel metadata in QR codes is informational only (not stored in orders) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Matt
parent
9cdf7b0786
commit
48022f38d4
417
API_DOCUMENTATION.md
Normal file
417
API_DOCUMENTATION.md
Normal file
@ -0,0 +1,417 @@
|
|||||||
|
# Puffin Offset API Documentation
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
- [QR Code Generation API](#qr-code-generation-api)
|
||||||
|
- [Endpoint](#endpoint)
|
||||||
|
- [Request Format](#request-format)
|
||||||
|
- [Calculation Types](#calculation-types)
|
||||||
|
- [Response Format](#response-format)
|
||||||
|
- [Format Comparison (PNG vs SVG)](#format-comparison-png-vs-svg)
|
||||||
|
- [Usage Examples](#usage-examples)
|
||||||
|
- [Checkout API](#checkout-api)
|
||||||
|
- [Best Practices](#best-practices)
|
||||||
|
- [Error Handling](#error-handling)
|
||||||
|
|
||||||
|
## QR Code Generation API
|
||||||
|
|
||||||
|
### Endpoint
|
||||||
|
```
|
||||||
|
POST /api/qr-code/generate
|
||||||
|
```
|
||||||
|
|
||||||
|
Generate QR codes that encode carbon calculation parameters. The QR code directs users to the Puffin Offset calculator with pre-filled calculation data.
|
||||||
|
|
||||||
|
### Request Format
|
||||||
|
|
||||||
|
The API accepts three types of calculations:
|
||||||
|
|
||||||
|
#### 1. Fuel-Based Calculation
|
||||||
|
Calculate carbon offset based on fuel consumption:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"calculationType": "fuel",
|
||||||
|
"fuelAmount": 1000,
|
||||||
|
"fuelUnit": "liters",
|
||||||
|
"vessel": {
|
||||||
|
"imo": "1234567",
|
||||||
|
"name": "Sample Yacht",
|
||||||
|
"type": "Motor Yacht",
|
||||||
|
"enginePower": 2250
|
||||||
|
},
|
||||||
|
"timestamp": "2025-03-15T10:00:00Z",
|
||||||
|
"source": "marina-api"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Fields:**
|
||||||
|
- `calculationType`: Must be `"fuel"`
|
||||||
|
- `fuelAmount`: Number of fuel units consumed
|
||||||
|
- `fuelUnit`: Either `"liters"` or `"gallons"`
|
||||||
|
- `vessel`: Optional vessel metadata (for informational purposes only)
|
||||||
|
- `timestamp`: Optional ISO timestamp
|
||||||
|
- `source`: Optional identifier (e.g., "marina-api", "broker-portal")
|
||||||
|
|
||||||
|
#### 2. Distance-Based Calculation
|
||||||
|
Calculate carbon offset based on trip distance and vessel characteristics:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"calculationType": "distance",
|
||||||
|
"distance": 150,
|
||||||
|
"speed": 12,
|
||||||
|
"fuelRate": 85,
|
||||||
|
"vessel": {
|
||||||
|
"imo": "1234567",
|
||||||
|
"name": "Sample Yacht",
|
||||||
|
"type": "Motor Yacht",
|
||||||
|
"enginePower": 2250
|
||||||
|
},
|
||||||
|
"timestamp": "2025-03-15T10:00:00Z",
|
||||||
|
"source": "marina-api"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Fields:**
|
||||||
|
- `calculationType`: Must be `"distance"`
|
||||||
|
- `distance`: Distance in nautical miles
|
||||||
|
- `speed`: Average speed in knots
|
||||||
|
- `fuelRate`: Fuel consumption rate in liters per hour
|
||||||
|
- `vessel`: Optional vessel metadata
|
||||||
|
- `timestamp`: Optional ISO timestamp
|
||||||
|
- `source`: Optional identifier
|
||||||
|
|
||||||
|
#### 3. Custom Amount
|
||||||
|
Direct monetary amount for carbon offsetting:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"calculationType": "custom",
|
||||||
|
"customAmount": 250.00,
|
||||||
|
"vessel": {
|
||||||
|
"name": "Corporate Event",
|
||||||
|
"type": "Conference"
|
||||||
|
},
|
||||||
|
"timestamp": "2025-03-15T10:00:00Z",
|
||||||
|
"source": "event-organizer"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Fields:**
|
||||||
|
- `calculationType`: Must be `"custom"`
|
||||||
|
- `customAmount`: Dollar amount (USD) for direct offset purchase
|
||||||
|
- `vessel`: Optional context information
|
||||||
|
- `timestamp`: Optional ISO timestamp
|
||||||
|
- `source`: Optional identifier
|
||||||
|
|
||||||
|
### Response Format
|
||||||
|
|
||||||
|
The API returns both PNG and SVG formats of the QR code:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"data": {
|
||||||
|
"qrCodeDataURL": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
|
||||||
|
"qrCodeSVG": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 256 256\">...</svg>",
|
||||||
|
"url": "https://puffinoffset.com/calculator?qr=eyJjYWxjdWxhdGlvblR5cGUiOi...",
|
||||||
|
"expiresAt": "2025-04-14T10:00:00.000Z"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response Fields:**
|
||||||
|
- `qrCodeDataURL`: Base64-encoded PNG image as data URL (ready for `<img>` src)
|
||||||
|
- `qrCodeSVG`: SVG markup string (ready for direct HTML injection)
|
||||||
|
- `url`: The full URL that the QR code points to
|
||||||
|
- `expiresAt`: ISO timestamp when the QR code expires (30 days from generation)
|
||||||
|
|
||||||
|
### Format Comparison (PNG vs SVG)
|
||||||
|
|
||||||
|
| Feature | PNG (qrCodeDataURL) | SVG (qrCodeSVG) |
|
||||||
|
|---------|---------------------|-----------------|
|
||||||
|
| **Format** | Base64-encoded PNG as data URL | SVG markup string |
|
||||||
|
| **Use Case** | Email, printing, basic displays | Web, scaling, professional prints |
|
||||||
|
| **File Size** | Larger (~5-10 KB) | Smaller (~2-4 KB) |
|
||||||
|
| **Scalability** | Pixelated when enlarged | Perfect at any size |
|
||||||
|
| **Browser Support** | Universal | Universal (all modern browsers) |
|
||||||
|
| **Best For** | Quick implementation, emails | Websites, responsive design, high-DPI displays |
|
||||||
|
| **Embedding** | `<img src="{qrCodeDataURL}">` | Direct HTML injection or `<img src="data:image/svg+xml,{encoded}">` |
|
||||||
|
|
||||||
|
**When to Use PNG:**
|
||||||
|
- Email campaigns (better compatibility)
|
||||||
|
- Print materials with fixed sizes
|
||||||
|
- Quick prototyping
|
||||||
|
- When exact pixel dimensions are known
|
||||||
|
|
||||||
|
**When to Use SVG:**
|
||||||
|
- Responsive web design
|
||||||
|
- High-resolution displays (Retina, 4K)
|
||||||
|
- Professional print materials (scales to any size)
|
||||||
|
- When minimizing file size is important
|
||||||
|
- Dynamic styling with CSS
|
||||||
|
|
||||||
|
### Usage Examples
|
||||||
|
|
||||||
|
#### cURL
|
||||||
|
```bash
|
||||||
|
curl -X POST https://puffinoffset.com/api/qr-code/generate \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{
|
||||||
|
"calculationType": "distance",
|
||||||
|
"distance": 150,
|
||||||
|
"speed": 12,
|
||||||
|
"fuelRate": 85,
|
||||||
|
"vessel": {
|
||||||
|
"imo": "1234567",
|
||||||
|
"name": "Sample Yacht"
|
||||||
|
}
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
#### JavaScript (Fetch API)
|
||||||
|
```javascript
|
||||||
|
const response = await fetch('https://puffinoffset.com/api/qr-code/generate', {
|
||||||
|
method: 'POST',
|
||||||
|
headers: {
|
||||||
|
'Content-Type': 'application/json',
|
||||||
|
},
|
||||||
|
body: JSON.stringify({
|
||||||
|
calculationType: 'fuel',
|
||||||
|
fuelAmount: 1000,
|
||||||
|
fuelUnit: 'liters',
|
||||||
|
vessel: {
|
||||||
|
name: 'Sample Yacht',
|
||||||
|
imo: '1234567'
|
||||||
|
}
|
||||||
|
})
|
||||||
|
});
|
||||||
|
|
||||||
|
const { data } = await response.json();
|
||||||
|
console.log('QR Code URL:', data.url);
|
||||||
|
|
||||||
|
// Use PNG format
|
||||||
|
document.getElementById('qr-png').src = data.qrCodeDataURL;
|
||||||
|
|
||||||
|
// Use SVG format
|
||||||
|
document.getElementById('qr-svg-container').innerHTML = data.qrCodeSVG;
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Python
|
||||||
|
```python
|
||||||
|
import requests
|
||||||
|
|
||||||
|
response = requests.post(
|
||||||
|
'https://puffinoffset.com/api/qr-code/generate',
|
||||||
|
json={
|
||||||
|
'calculationType': 'custom',
|
||||||
|
'customAmount': 250.00,
|
||||||
|
'source': 'python-client'
|
||||||
|
}
|
||||||
|
)
|
||||||
|
|
||||||
|
data = response.json()['data']
|
||||||
|
print(f"QR Code URL: {data['url']}")
|
||||||
|
print(f"Expires at: {data['expiresAt']}")
|
||||||
|
|
||||||
|
# Save PNG to file
|
||||||
|
import base64
|
||||||
|
png_data = data['qrCodeDataURL'].split(',')[1]
|
||||||
|
with open('qr-code.png', 'wb') as f:
|
||||||
|
f.write(base64.b64decode(png_data))
|
||||||
|
|
||||||
|
# Save SVG to file
|
||||||
|
with open('qr-code.svg', 'w') as f:
|
||||||
|
f.write(data['qrCodeSVG'])
|
||||||
|
```
|
||||||
|
|
||||||
|
#### HTML Embedding
|
||||||
|
|
||||||
|
**PNG Format:**
|
||||||
|
```html
|
||||||
|
<!-- Direct data URL in img tag -->
|
||||||
|
<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
|
||||||
|
alt="Carbon Offset QR Code"
|
||||||
|
style="width: 300px; height: 300px;">
|
||||||
|
```
|
||||||
|
|
||||||
|
**SVG Format:**
|
||||||
|
```html
|
||||||
|
<!-- Direct SVG injection (recommended for web) -->
|
||||||
|
<div id="qr-container">
|
||||||
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256">
|
||||||
|
<!-- SVG content from API -->
|
||||||
|
</svg>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<!-- Or as data URL -->
|
||||||
|
<img src="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg'>...</svg>"
|
||||||
|
alt="Carbon Offset QR Code"
|
||||||
|
style="width: 100%; max-width: 400px;">
|
||||||
|
```
|
||||||
|
|
||||||
|
**Dynamic Sizing with SVG:**
|
||||||
|
```css
|
||||||
|
/* SVG automatically scales to container */
|
||||||
|
#qr-container {
|
||||||
|
width: 100%;
|
||||||
|
max-width: 500px;
|
||||||
|
margin: 0 auto;
|
||||||
|
}
|
||||||
|
|
||||||
|
#qr-container svg {
|
||||||
|
width: 100%;
|
||||||
|
height: auto;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Checkout API
|
||||||
|
|
||||||
|
### Create Checkout Session
|
||||||
|
```
|
||||||
|
POST /api/checkout/create-session
|
||||||
|
```
|
||||||
|
|
||||||
|
Create a Stripe checkout session for carbon offset purchase.
|
||||||
|
|
||||||
|
**Request Body:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"tons": 2.5,
|
||||||
|
"portfolioId": 123,
|
||||||
|
"pricePerTon": 20.00,
|
||||||
|
"customerEmail": "customer@example.com"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"sessionId": "cs_test_...",
|
||||||
|
"url": "https://checkout.stripe.com/...",
|
||||||
|
"orderId": "order_abc123"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Note:** Vessel information is NOT included in checkout sessions or stored in orders. Vessel metadata in QR codes is for informational purposes only.
|
||||||
|
|
||||||
|
### Get Order Details
|
||||||
|
```
|
||||||
|
GET /api/checkout/session/{sessionId}
|
||||||
|
```
|
||||||
|
|
||||||
|
Retrieve order details by Stripe session ID.
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"order": {
|
||||||
|
"id": "order_abc123",
|
||||||
|
"tons": 2.5,
|
||||||
|
"portfolioId": 123,
|
||||||
|
"baseAmount": 5000,
|
||||||
|
"processingFee": 180,
|
||||||
|
"totalAmount": 5180,
|
||||||
|
"currency": "USD",
|
||||||
|
"status": "paid",
|
||||||
|
"wrenOrderId": "wren_xyz789",
|
||||||
|
"stripeSessionId": "cs_test_...",
|
||||||
|
"createdAt": "2025-03-15T10:00:00.000Z"
|
||||||
|
},
|
||||||
|
"session": {
|
||||||
|
"paymentStatus": "paid",
|
||||||
|
"customerEmail": "customer@example.com"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
### QR Code Generation
|
||||||
|
|
||||||
|
1. **Choose the Right Format:**
|
||||||
|
- Use **PNG** for emails, fixed-size prints, and quick prototypes
|
||||||
|
- Use **SVG** for websites, responsive designs, and high-quality prints
|
||||||
|
|
||||||
|
2. **Include Metadata:**
|
||||||
|
- Always include `source` field to track where QR codes originate
|
||||||
|
- Include `timestamp` for auditing and expiration tracking
|
||||||
|
- Use descriptive `vessel` names for context
|
||||||
|
|
||||||
|
3. **Handle Expiration:**
|
||||||
|
- QR codes expire after 30 days
|
||||||
|
- Check `expiresAt` timestamp in response
|
||||||
|
- Regenerate QR codes if needed for long-term use
|
||||||
|
|
||||||
|
4. **Error Handling:**
|
||||||
|
- Validate input data before sending to API
|
||||||
|
- Handle network failures gracefully
|
||||||
|
- Display user-friendly error messages
|
||||||
|
|
||||||
|
### Integration Recommendations
|
||||||
|
|
||||||
|
1. **Marinas & Brokers:**
|
||||||
|
- Generate QR codes after trip logging
|
||||||
|
- Print QR codes on receipts or invoices
|
||||||
|
- Include vessel details for tracking
|
||||||
|
|
||||||
|
2. **Event Organizers:**
|
||||||
|
- Use `custom` calculation type for flat-rate offsets
|
||||||
|
- Generate bulk QR codes for attendee packets
|
||||||
|
- Track source with `source` field
|
||||||
|
|
||||||
|
3. **Mobile Apps:**
|
||||||
|
- Use SVG format for responsive display
|
||||||
|
- Cache QR codes locally to reduce API calls
|
||||||
|
- Implement QR code scanning for peer-to-peer sharing
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
### Error Response Format
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": false,
|
||||||
|
"error": "Invalid calculation type"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Common Errors
|
||||||
|
|
||||||
|
| Error | Cause | Solution |
|
||||||
|
|-------|-------|----------|
|
||||||
|
| "Invalid calculation type" | `calculationType` not "fuel", "distance", or "custom" | Use valid calculation type |
|
||||||
|
| "Missing required fields" | Required fields for calculation type not provided | Check calculation type requirements |
|
||||||
|
| "Invalid fuel unit" | `fuelUnit` not "liters" or "gallons" | Use valid fuel unit |
|
||||||
|
| "Invalid amount" | Negative or zero values | Provide positive values |
|
||||||
|
| 500 Server Error | Server-side issue | Retry request, contact support if persistent |
|
||||||
|
|
||||||
|
### HTTP Status Codes
|
||||||
|
|
||||||
|
- **200 OK**: QR code generated successfully
|
||||||
|
- **400 Bad Request**: Invalid request data (check error message)
|
||||||
|
- **500 Internal Server Error**: Server-side error (retry or contact support)
|
||||||
|
|
||||||
|
## Future Enhancements
|
||||||
|
|
||||||
|
The following features are planned for future releases:
|
||||||
|
|
||||||
|
1. **Authentication:** API key authentication for rate limiting and analytics
|
||||||
|
2. **Batch Generation:** Generate multiple QR codes in a single request
|
||||||
|
3. **Custom Branding:** Add logos or custom colors to QR codes
|
||||||
|
4. **Analytics Dashboard:** Track QR code scans and conversion rates
|
||||||
|
5. **Webhook Support:** Receive notifications when QR codes are scanned or orders completed
|
||||||
|
|
||||||
|
## Changelog
|
||||||
|
|
||||||
|
### Version 1.0 (Current)
|
||||||
|
- Initial release
|
||||||
|
- Support for fuel-based, distance-based, and custom amount calculations
|
||||||
|
- PNG and SVG format outputs
|
||||||
|
- 30-day expiration
|
||||||
|
- No authentication required
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Support:** For questions or issues, contact [support@puffinoffset.com](mailto:support@puffinoffset.com)
|
||||||
|
|
||||||
|
**API Base URL:** `https://puffinoffset.com/api`
|
||||||
Loading…
x
Reference in New Issue
Block a user