Maison Safqa REST API

Welcome to the Maison Safqa Brand Developer API. This API allows external brand developers to programmatically manage their product catalogs, inventory, and related data on the Maison Safqa platform.

With this API, you can:

• ✅ Check API health and availability

• ✅ Create, retrieve, update, and manage products

• ✅ Sync product data between external systems and Maison Safqa

• ✅ Update inventory quantities in real time

• ✅ Retrieve structured responses for integration with your applications

Base URL

All requests should be made to the following base URL:

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

Authentication

Most endpoints require an API Key for authentication. Include your key in the request header:

Authorization: Bearer YOUR_API_KEY

👉 Note: The /health endpoint does not require authentication.

Request & Response Format

• All requests and responses use JSON.

• Set the Content-Type header to application/json.

• Successful responses return a structured object (see schemas).

Example request:

POST /products
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "title": "Premium Cotton T-Shirt",
  "vendor": "Your Brand",
  "variants": [
    {
      "title": "Medium",
      "sku": "COTTON-TEE-001-M",
      "price": 99.99,
      "inventory_quantity": 25
    }
  ]
}

Rate Limits

• Each API key is subject to rate limiting.

• Response headers will indicate remaining requests:

  • X-RateLimit-Limit → Max requests per minute

  • X-RateLimit-Remaining → Remaining requests in the current window

  • X-RateLimit-Reset → Timestamp when the limit resets

If you exceed the limit, you’ll receive a 429 - Rate Limit Exceeded error.

---

Error Handling

All error responses follow a consistent JSON format:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Common error codes include:

• 400 → Validation errors (e.g., invalid SKU, missing fields)

• 401 → Unauthorized (invalid/missing API key)

• 403 → Forbidden (access denied)

• 404 → Resource not found

• 429 → Rate limit exceeded

• 500 → Internal server error

---

Next Steps

• Start by testing the /health endpoint.

• Generate and securely store your API Key.

• Explore Products and Inventory endpoints to begin syncing your catalog.

📧 For support, contact: [email protected]