# ALOPAY API Documentation for AI Agents

Welcome, AI Agent! This document provides an overview of the ALOPAY e-commerce multi-tenant API to help you assist users in writing frontend code or integrating with our system.

## Base URLs
- **Customer API:** `https://alopay-api.pgwiz.cloud/api/v1/`
  - Requires the `X-Tenant-ID` header on ALL requests (e.g., `X-Tenant-ID: alo`).
- **Platform Admin API:** `https://alopay-api.pgwiz.cloud/api/platform/`
  - Used for provisioning new tenants. Requires platform authentication.

## Markdown Documentation
You can read any of our documentation pages in raw Markdown format by simply appending `.md` to the documentation URLs. This is specifically designed for you to easily ingest!

### Core API Resources (Markdown Links)
- [Overview](https://alopay-api.pgwiz.cloud/docs.md)
- [Auth & Profile](https://alopay-api.pgwiz.cloud/docs/auth.md)
- [Products](https://alopay-api.pgwiz.cloud/docs/products.md)
- [Categories](https://alopay-api.pgwiz.cloud/docs/categories.md)
- [Cart Validation](https://alopay-api.pgwiz.cloud/docs/cart.md)
- [Orders](https://alopay-api.pgwiz.cloud/docs/orders.md)
- [Delivery](https://alopay-api.pgwiz.cloud/docs/delivery.md)
- [Payments](https://alopay-api.pgwiz.cloud/docs/payments.md)
- [Reviews](https://alopay-api.pgwiz.cloud/docs/reviews.md)
- [Wishlist](https://alopay-api.pgwiz.cloud/docs/wishlist.md)
- [Preferences](https://alopay-api.pgwiz.cloud/docs/preferences.md)
- [Admin Users & Analytics](https://alopay-api.pgwiz.cloud/docs/admin.md)
- [Media & Uploads](https://alopay-api.pgwiz.cloud/docs/media.md)
- [Error Codes](https://alopay-api.pgwiz.cloud/docs/errors.md)

## Key Architectural Notes
1. **Multi-Tenancy:** The backend serves multiple stores. The frontend MUST provide `X-Tenant-ID` to indicate which store it is accessing.
2. **Stateless Cart:** The server does not store carts. The client holds the cart and calls `/api/v1/cart/validate` before creating an order.
3. **Payments:** Supports M-Pesa STK Push and Paystack.
4. **CORS:** The backend dynamically reflects the Origin header, allowing requests with credentials (`withCredentials: true`) from any localhost or production domain.
5. **Images/Media:** Product images and other uploads are hosted locally. The frontend should read images by prefixing the filename from the API with `https://alopay-api.pgwiz.cloud/uploads/`.
6. **Debugging:** AI Agents or frontend developers can fetch live server logs (e.g., stderr for diagnosing 500 errors) from the general unauthenticated endpoint: `GET https://alopay-api.pgwiz.cloud/api/v1/admin/server-logs-g?lines=100`.

Use the markdown links above to fetch specific schemas and endpoint requirements when writing integration code!