# Getting Started

### Base URL

All API requests should be made to:

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

### Authentication

All API endpoints require authentication using an API key. Include your API key in the `X-MaisonSafqa-Api-Key` header with every request.

#### API Key Formats

| Environment | Key Prefix    | Usage                        |
| ----------- | ------------- | ---------------------------- |
| Development | `ms_test_...` | Testing and development only |
| Production  | `ms_live_...` | Live production environment  |

> ⚠️ **Important**: API keys are environment-specific. A test key will not work in production, and vice versa.

#### Getting Your API Key

Contact the Maison Safqa team at <itsupport@maisonsafqa.com> to request API access for your brand.

When you receive your API key, store it securely. The full key is only shown once at creation time.

### Quick Start Example

Here's a simple example to create your first product:

```bash
curl -X POST https://api.maisonsafqa.com/v1/products \
  -H "Content-Type: application/json" \
  -H "X-MaisonSafqa-Api-Key: ms_test_your_api_key_here" \
  -d '{
    "title": "Premium Cotton T-Shirt",
    "body_html": "<p>High quality cotton t-shirt.</p>",
    "vendor": "Your Brand Name",
    "product_type": "Apparel",
    "tags": "cotton,premium,t-shirt",
    "variants": [
      {
        "title": "Small",
        "sku": "TSHIRT-001-S",
        "price": 99.99,
        "inventory_quantity": 25
      },
      {
        "title": "Medium",
        "sku": "TSHIRT-001-M",
        "price": 99.99,
        "inventory_quantity": 50
      },
      {
        "title": "Large",
        "sku": "TSHIRT-001-L",
        "price": 99.99,
        "inventory_quantity": 30
      }
    ],
    "images": [
      {
        "src": "https://example.com/images/tshirt-front.jpg",
        "alt": "T-shirt front view",
        "position": 1
      }
    ]
  }'
```

#### Response

A successful response returns status `201 Created`:

```json
{
  "error": null,
  "product": {
    "id": "product_1234567890123456",
    "title": "Premium Cotton T-Shirt",
    "handle": "premium-cotton-t-shirt",
    "status": "draft",
    "variants": [
      {
        "sku": "TSHIRT-001-S",
        "price": 99.99,
        "inventory_quantity": 25
      }
    ],
    "synced": false,
    "created_at": "2024-01-15T10:30:00Z"
  },
  "message": "Product created successfully. It will be synced to Shopify when activated."
}
```

### Rate Limits

The API enforces rate limiting to ensure fair usage:

| Limit                    | Value |
| ------------------------ | ----- |
| Requests per minute      | 300   |
| Bulk operation max items | 500   |

#### Rate Limit Headers

Every response includes rate limit information:

| Header                  | Description                               |
| ----------------------- | ----------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed per minute (300) |
| `X-RateLimit-Remaining` | Requests remaining in current window      |
| `X-RateLimit-Reset`     | Unix timestamp when the limit resets      |

If you exceed the rate limit, you'll receive a `429 Too Many Requests` response with a `Retry-After` header indicating how many seconds to wait.

### Key Concepts

#### Product Status

Products are created in `draft` status and will be synced to Shopify when activated by the Maison Safqa team.

#### Inventory Sync

Inventory updates are stored locally and periodically synced to Shopify. Your brand's inventory data always takes precedence in case of conflicts.

#### Bulk Operations

For efficiency, you can create up to 500 products or update inventory for up to 500 products in a single request. Bulk operations support **partial success** - valid items are processed even if some fail validation.

### Error Handling

All errors follow a consistent format:

```json
{
  "error": {
    "field": "variants.sku",
    "message": "SKUs already exist for this brand: TSHIRT-001-S"
  }
}
```

Common HTTP status codes:

| Code  | Description                                                       |
| ----- | ----------------------------------------------------------------- |
| `200` | Success                                                           |
| `201` | Created                                                           |
| `207` | Multi-Status (partial success in bulk operations)                 |
| `400` | Bad Request - Validation errors                                   |
| `401` | Unauthorized - Invalid or missing API key                         |
| `404` | Not Found - Product doesn't exist or doesn't belong to your brand |
| `429` | Too Many Requests - Rate limit exceeded                           |
| `500` | Internal Server Error                                             |

### Next Steps

* **Products API** - Create, retrieve, and update products
* **Inventory API** - Manage inventory levels
* **Error Reference** - Complete list of error codes and messages

### Support

If you have questions or need assistance:

* **Email**: <itsupport@maisonsafqa.com>
* **Documentation Issues**: Open an issue on our developer portal