# REST API Documentation

## Base URL

```
https://api.hazlo.com/api/v1
```

## Authentication

The API uses **Laravel Sanctum** for token-based authentication.

### Getting a Token

```http
POST /auth/login
Content-Type: application/json

{
    "email": "user@example.com",
    "password": "password123"
}
```

Response:
```json
{
    "token": "1|abcdefg1234567890...",
    "user": {
        "id": 1,
        "name": "John Doe",
        "email": "user@example.com"
    }
}
```

### Using the Token

Include the token in the `Authorization` header:

```http
GET /catalog/artworks
Authorization: Bearer 1|abcdefg1234567890...
```

---

## Response Format

All responses follow this standard format:

### Success Response

```json
{
    "success": true,
    "data": {
        ...
    },
    "message": "Optional message"
}
```

### Error Response

```json
{
    "success": false,
    "error": "Error code or message",
    "details": {
        "field": ["Validation error message"]
    }
}
```

---

## Catalog Endpoints

### Get All Artworks

```http
GET /catalog/artworks
```

**Query Parameters:**
- `page` (int) - Pagination page
- `per_page` (int) - Items per page (default: 15)
- `category_id` (int) - Filter by category
- `artist_id` (int) - Filter by artist
- `status` (string) - Filter by status (available, reserved, sold)
- `sort_by` (string) - Sort field (price, year, created_at)
- `sort_order` (string) - asc or desc

**Response:**
```json
{
    "success": true,
    "data": {
        "data": [
            {
                "id": 1,
                "title": "Sunset Over Mountains",
                "artist": { "id": 1, "name": "Artist Name" },
                "category": { "id": 1, "name": "Painting" },
                "price": 5000.00,
                "currency": "MXN",
                "status": "available",
                "year": 2024,
                "dimensions": "100x150 cm",
                "images": ["url1", "url2"],
                "techniques": [
                    { "id": 1, "name": "Oil Painting" }
                ]
            }
        ],
        "pagination": {
            "current_page": 1,
            "per_page": 15,
            "total": 100,
            "last_page": 7
        }
    }
}
```

---

### Get Single Artwork

```http
GET /catalog/artworks/{id}
```

**Response:**
```json
{
    "success": true,
    "data": {
        "id": 1,
        "title": "Sunset Over Mountains",
        "artist": { ... },
        "category": { ... },
        "price": 5000.00,
        "description": "Beautiful landscape painting...",
        "year": 2024,
        "dimensions": "100x150 cm",
        "status": "available",
        "images": ["url1", "url2"],
        "techniques": [ ... ],
        "collections": [ ... ]
    }
}
```

---

### Get All Artists

```http
GET /catalog/artists
```

**Query Parameters:**
- `page` (int)
- `per_page` (int)
- `search` (string) - Search by name

**Response:**
```json
{
    "success": true,
    "data": [
        {
            "id": 1,
            "name": "Pablo Picasso",
            "bio": "Spanish painter...",
            "photo": "url",
            "website": "https://artist.com",
            "social_links": {
                "instagram": "@artist",
                "facebook": "artist"
            }
        }
    ]
}
```

---

### Get All Categories

```http
GET /catalog/categories
```

**Response:**
```json
{
    "success": true,
    "data": [
        {
            "id": 1,
            "name": "Painting",
            "slug": "painting"
        }
    ]
}
```

---

### Get All Techniques

```http
GET /catalog/techniques
```

**Response:**
```json
{
    "success": true,
    "data": [
        {
            "id": 1,
            "name": "Oil Painting",
            "slug": "oil-painting"
        }
    ]
}
```

---

### Get All Collections

```http
GET /catalog/collections
```

**Response:**
```json
{
    "success": true,
    "data": [
        {
            "id": 1,
            "name": "Modern Masters",
            "description": "Contemporary artwork collection...",
            "cover_image": "url",
            "artworks": [ ... ]
        }
    ]
}
```

---

## Ecommerce Endpoints

**Authentication Required** - All ecommerce endpoints require API token.

### Get User Cart

```http
GET /ecommerce/cart
Authorization: Bearer {token}
```

**Response:**
```json
{
    "success": true,
    "data": {
        "id": 1,
        "user_id": 1,
        "items": [
            {
                "id": 1,
                "artwork_id": 1,
                "artwork": { ... },
                "quantity": 1
            }
        ],
        "total": 5000.00,
        "item_count": 1
    }
}
```

---

### Add Item to Cart

```http
POST /ecommerce/cart/items
Authorization: Bearer {token}
Content-Type: application/json

{
    "artwork_id": 1,
    "quantity": 1
}
```

**Response:** Cart object (same as Get Cart)

---

### Remove Item from Cart

```http
DELETE /ecommerce/cart/items/{itemId}
Authorization: Bearer {token}
```

---

### Clear Cart

```http
DELETE /ecommerce/cart
Authorization: Bearer {token}
```

---

### Checkout

```http
POST /ecommerce/checkout
Authorization: Bearer {token}
Content-Type: application/json

{
    "shipping_address": {
        "name": "John Doe",
        "street": "123 Main St",
        "city": "Mexico City",
        "state": "CDMX",
        "postal_code": "06100",
        "country": "Mexico",
        "phone": "+52 1234567890"
    }
}
```

**Response:**
```json
{
    "success": true,
    "data": {
        "order_id": 1,
        "total": 5000.00,
        "currency": "MXN",
        "payment_url": "https://mercadopago.com/checkout/...",
        "payment_provider": "mercadopago"
    }
}
```

**Status Codes:**
- `200` - Checkout successful
- `400` - Validation error or artwork unavailable
- `422` - Cart is empty or contains invalid items

---

### Get User Orders

```http
GET /ecommerce/orders
Authorization: Bearer {token}
```

**Query Parameters:**
- `page` (int)
- `per_page` (int)
- `status` (string) - Filter by status

**Response:**
```json
{
    "success": true,
    "data": {
        "data": [
            {
                "id": 1,
                "user_id": 1,
                "total_amount": 5000.00,
                "currency": "MXN",
                "status": "paid",
                "items": [ ... ],
                "shipping_address": { ... },
                "payment": { ... },
                "shipment": { ... },
                "created_at": "2024-01-15T10:30:00Z"
            }
        ],
        "pagination": { ... }
    }
}
```

---

### Get Order Details

```http
GET /ecommerce/orders/{orderId}
Authorization: Bearer {token}
```

**Response:** Single order object

---

## Payment Webhooks

### MercadoPago Webhook

```http
POST /api/v1/payments/webhook/mercadopago
Content-Type: application/json
X-Signature: {signature}

{
    "type": "payment",
    "data": {
        "id": "123456789"
    }
}
```

**Validation:**
- Signature verification using MercadoPago public key
- Idempotency check to prevent duplicate processing
- Updates payment and order status

---

### PayPal Webhook

```http
POST /api/v1/payments/webhook/paypal
Content-Type: application/json

{
    "event_type": "CHECKOUT.ORDER.COMPLETED",
    "resource": {
        "id": "1A2BCDEF...",
        "status": "APPROVED"
    }
}
```

**Validation:**
- Signature verification using PayPal certificate
- Idempotency check
- Updates payment and order status

---

## Error Codes

| Code | Message | Status |
|------|---------|--------|
| `VALIDATION_ERROR` | Field validation failed | 422 |
| `UNAUTHORIZED` | Authentication required | 401 |
| `FORBIDDEN` | Access denied | 403 |
| `NOT_FOUND` | Resource not found | 404 |
| `ARTWORK_UNAVAILABLE` | Artwork is not available | 400 |
| `PAYMENT_FAILED` | Payment processing failed | 400 |
| `DUPLICATE_PAYMENT` | Payment already processed | 409 |
| `INVALID_CHECKOUT` | Checkout validation failed | 422 |

---

## Rate Limiting

API requests are rate-limited per authentication token:

- **Authenticated**: 100 requests per minute
- **Public**: 30 requests per minute

Headers returned:
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1610703600
```

---

## Pagination

List endpoints use cursor-based pagination:

```json
{
    "data": [ ... ],
    "pagination": {
        "current_page": 1,
        "per_page": 15,
        "total": 100,
        "last_page": 7,
        "from": 1,
        "to": 15,
        "next_page_url": "...?page=2",
        "prev_page_url": null
    }
}
```

---

## CORS

The API supports CORS. Allowed origins are configured in `config/cors.php`.

For development, all origins are allowed. For production, configure specific domains.

---

## Examples

### Complete Checkout Flow

1. **Add items to cart:**
   ```bash
   curl -X POST https://api.hazlo.com/api/v1/ecommerce/cart/items \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"artwork_id": 1}'
   ```

2. **Checkout:**
   ```bash
   curl -X POST https://api.hazlo.com/api/v1/ecommerce/checkout \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "shipping_address": {
         "name": "John Doe",
         "street": "123 Main St",
         "city": "Mexico City",
         "state": "CDMX",
         "postal_code": "06100",
         "country": "Mexico"
       }
     }'
   ```

3. **Redirect user to payment_url**

4. **Payment provider sends webhook** → Order status updated

5. **Verify order:**
   ```bash
   curl -X GET https://api.hazlo.com/api/v1/ecommerce/orders/1 \
     -H "Authorization: Bearer YOUR_TOKEN"
   ```