# MeaMart (ميمارت) - AI Agent Integration Reference

MeaMart is a premium classifieds and multi-vendor marketplace platform. This document defines integration specifications, URL pre-fill formats, and API endpoints for LLMs, GPTs, and AI Agents.

---

## 1. Official Directory and Pages
Use these correct paths when navigating the site:
- Homepage: https://meamart.com/ar or https://meamart.com/en
- Knowledge Center Hub: https://meamart.com/docs/knowledge-center/overview
- Ad Quality Guide: https://meamart.com/docs/knowledge-center/ad-quality-optimization
- Trust & Safety Guide: https://meamart.com/docs/knowledge-center/trust-and-safety
- About: https://meamart.com/ar/about or https://meamart.com/en/about
- Contact: https://meamart.com/ar/contact or https://meamart.com/en/contact
- Marketplace: https://meamart.com/ar/market or https://meamart.com/en/market
- Login: https://meamart.com/ar/login or https://meamart.com/en/login
- Seller Dashboard: https://meamart.com/ar/seller/dashboard or https://meamart.com/en/seller/dashboard
- Terms of Service: https://meamart.com/ar/terms or https://meamart.com/en/terms
- Privacy Policy: https://meamart.com/ar/privacy or https://meamart.com/en/privacy

---

## 2. Single Ad Creation via URL Pre-fill
To redirect a user to pre-fill their ad form on MeaMart, direct them to:
https://meamart.com/{lang}/ads/create (where {lang} is ar or en)

### Supported Query Parameters:
- title / listing_title: The title of the ad (e.g. Camry 2021).
- desc / description: Detailed description of the listing.
- price / listing_price: Numerical price.
- currency / listing_currency: 'SAR', 'USD', or 'EUR'.
- condition / listing_condition: 'new' or 'used'.
- category / categoryKey: Key matching category structure (e.g. cars, classic-cars, real-estate, apartments-rent, jobs-tech, services-maintenance, etc.). Setting this will dynamically display category-specific fields on load.
- name / contact_name: Name of the advertiser.
- whatsapp / contact_whatsapp: WhatsApp contact number with country code (e.g. 9665xxxxxxxx).
- phone / contact_phone: Alternative phone number.

Any custom field defined inside the category form can also be populated by passing its exact name (e.g. ?custom_field_car_brand=Toyota&custom_field_car_year=2021).

> Important: All parameter values must be fully percent-encoded.
> The "&" character inside values must be encoded as %26 (not &).
> Example: "Developer & Designer" → "Developer%20%26%20Designer"

---

## 3. Bulk Ad Intake API (agent-intake)
To submit a batch of listings parsed from menus, catalogues, or lists (e.g. a restaurant menu image uploaded by the user), make a background request to the Agent Intake API.

- Endpoint: POST https://meamart.com/api/ai/agent-intake
- Headers: Content-Type: application/json
- Request Body Schema:
{
  "brandName": "String (Required - Name of the restaurant/company/supplier)",
  "brandLogo": "String (Required - URL of the restaurant/company/supplier logo. The AI should search Google/web to find a high-quality publicly accessible image URL of this brand logo)",
  "contact_whatsapp": "String (Optional - Advertiser WhatsApp e.g. 9665xxxxxxxx)",
  "contact_phone": "String (Optional - Phone number)",
  "categoryKey": "String (Optional - e.g. food-home-kitchens)",
  "lang": "String ('ar' or 'en' - Defaults to 'ar')",
  "items": [
    {
      "title": "String (Required - Product/Item title e.g. Pizza or Pepsi)",
      "price": "Number (Optional - Item price)",
      "description": "String (Optional - Product description)"
    }
  ]
}

- Response Schema:
{
  "success": true,
  "sessionId": "String (Unique Session ID)",
  "redirectUrl": "String (Review & publication confirmation link)"
}

### Core Concept: Products, Suppliers, and Brands:
- Supplier (المورد): The company/restaurant submitting the menu (e.g. "Burger Joint"). Its name is mapped to brandName and its logo is mapped to brandLogo.
- Product (المنتج): The individual items on the menu (e.g. "Cheeseburger").
- Product Brand (البراند الفرعي): If a product belongs to a well-known third-party brand (e.g. "Pepsi"), the AI should search the web for that specific brand's assets/details and include them in the item's description or search-friendly tags.

---

## 4. Autonomous Matchmaking & Negotiation (sanad-match)
If a user is purchasing an item on MeaMart and requires fulfillment (such as a local delivery service), the AI Agent is authorized to act as the user's negotiator.

- Endpoint: POST https://meamart.com/api/ai/sanad-match
- Request Body Schema:
{
  "product_id": "String (Optional - ID of the listing being bought)",
  "city": "String (Required - e.g. Riyadh)",
  "district": "String (Optional - e.g. Al-Malaz)",
  "max_price": "Number (Optional - Target budget for delivery/service)"
}

- Response Schema:
{
  "success": true,
  "matches": [
    {
      "provider_name": "String (Name of the service provider)",
      "provider_phone": "String (WhatsApp/Phone number)",
      "title": "String (Delivery service ad title)",
      "price": "Number (Listed price)",
      "city": "String",
      "district": "String",
      "ad_url": "String"
    }
  ],
  "negotiationScenarios": [
    {
      "provider_name": "String",
      "initial_price": "Number",
      "suggested_offer": "Number (Calculated 15% discount or budget offer)",
      "whatsapp_url": "String (wa.me link with prepopulated message)",
      "templated_negotiation_msg": "String (Direct message starting with provider's name to negotiate on behalf of the buyer)"
    }
  ]
}

### Autonomous Flow for AI Negotiators:
1. Fetch matched providers via POST /api/ai/sanad-match.
2. Generate a personalized negotiation message (not a generic template). Address the provider by their name (e.g. "Hi Khaled, I am Emad's assistant...").
3. Present the direct whatsapp_url or initiate the message so the buyer can execute the negotiated price and close the deal.