Chatbot API¶

The Chatbot API provides customer support integration endpoints specifically designed for the Menzzo chatbot system.

Overview¶

5 endpoints for chatbot customer support operations: - Sale and customer information retrieval - SAV creation and status - Product information

Authentication¶

All Chatbot API endpoints use custom authentication with the X-API-Token header:

X-API-Token: {api_token}

Note: This is different from the Bearer token used by Core API endpoints.

Endpoints¶

Get Sale Details by Increment ID¶

GET /api/sale/details/{incrementId}

Retrieve comprehensive sale information including products, delivery, and SAV status for chatbot queries.

Parameters: - incrementId (string, required): Magento order increment ID (e.g., "15000012345")

Authentication: X-API-Token header required

Response: Detailed sale object with: - Order information (status, dates, amounts) - Product details with availability and tracking - Delivery tracking status - SAV status and history - Container tracking information - Payment status

Example:

curl -X GET \
  -H "X-API-Token: {your_api_token}" \
  https://api.menzzo.fr/api/sale/details/15000012345

Response Example:

href="#__codelineno-3-1">{ "success": true, "data": { "id": 12345, "incrementId": "15000012345", "status": "processing", "customer": { "firstname": "John", "lastname": "Doe", "email": "john@example.com" }, "products": [ { "sku": "PROD-123", "name": "Product Name", "qty": 1, "price": 250.00, "tracking": "1234567890", "carrier": "CHRONOPOST" } ], "sav_status": { "has_sav": false, "sav_count": 0 } } }

Error Responses: - 401 Unauthorized: Invalid or missing API token - 404 Not Found: Sale not found

Get Customer Details by Email¶

GET /api/Customer/details/{email}

Retrieve customer information and order history by email address.

Parameters: - email (string, required): Customer email address

Authentication: X-API-Token header required

Response: Customer object with: - Customer profile information - Order history - SAV history

Example:

curl -X GET \
  -H "X-API-Token: {your_api_token}" \
  https://api.menzzo.fr/api/Customer/details/customer@example.com

Response Example:

{
  "success": true,
  "customer": {
    "email": "customer@example.com",
    "firstname": "John",
    "lastname": "Doe",
    "orders": [
      {
        "increment_id": "15000012345",
        "status": "complete",
        "created_at": "2026-01-15"
      }
    ]
  }
}

Create SAV¶

POST /api/sav

Create a SAV (Service After Sale) request through the chatbot interface.

Parameters: (JSON body) - SAV request data (structure varies by request type)

Authentication: X-API-Token header required

Response: JSON with SAV creation status and ID

Example:

curl -X POST \
  -H "X-API-Token: {your_api_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "increment_id": "15000012345",
    "complaint_type": "damage",
    "description": "Product arrived damaged"
  }' \
  https://api.menzzo.fr/api/sav

Response Example:

{
  "success": true,
  "sav_id": 789,
  "message": "SAV request created successfully"
}

Get Customer SAV Status¶

GET /api/customer/sav-status

Retrieve SAV (Service After Sale) status and history for customer support queries.

Parameters: (Query string) - email (string, conditional): Customer email address - increment_id (string, conditional): Order increment ID - product_sku (string, optional): Filter by specific product SKU - sale_product_id (integer, optional): Filter by specific sale product ID

Note: Either email OR increment_id is required (not both).

Authentication: X-API-Token header required

Response: JSON object with SAV status, history, and related information

Example - By Email:

curl -X GET \
  -H "X-API-Token: {your_api_token}" \
  "https://api.menzzo.fr/api/customer/sav-status?email=customer@example.com"

Example - By Order ID:

curl -X GET \
  -H "X-API-Token: {your_api_token}" \
  "https://api.menzzo.fr/api/customer/sav-status?increment_id=15000012345"

Response Example:

{
  "success": true,
  "sav_records": [
    {
      "id": 789,
      "sale_ref": "15000012345",
      "status": "in_progress",
      "complaint_type": "damage",
      "created_at": "2026-01-20",
      "products": [
        {
          "sku": "PROD-123",
          "name": "Product Name"
        }
      ]
    }
  ]
}

See also: API Customer SAV Status for complete documentation with all parameters and response formats.

Get Product Details by SKU¶

GET /api/product/{sku}

Retrieve product information by SKU for chatbot product queries.

Parameters: - sku (string, required): Product SKU

Authentication: X-API-Token header required

Response: Product object with: - Product details (name, description, price) - Availability information - Stock status - Images

Example:

curl -X GET \
  -H "X-API-Token: {your_api_token}" \
  https://api.menzzo.fr/api/product/PROD-12345

Response Example:

{
  "success": true,
  "product": {
    "sku": "PROD-12345",
    "name": "Product Name",
    "price": 250.00,
    "description": "Product description...",
    "availability": "In Stock",
    "images": [
      "https://example.com/image1.jpg"
    ]
  }
}

Authentication Setup¶

Getting Your API Token¶

Contact the development team to obtain your API token: - Email: technique@menzzo.fr - Include your chatbot integration details

Using the Token¶

Include the token in the X-API-Token header for all requests:

curl -H "X-API-Token: your_token_here" \
  https://api.menzzo.fr/api/endpoint

Token Security¶

Never commit tokens to version control
Store securely in environment variables or secret managers
Use HTTPS only for all API requests
Rotate tokens regularly in production

Error Handling¶

Authentication Errors¶

401 Unauthorized - Missing Token:

{
  "success": false,
  "error": "Non autorisé",
  "message": "Token d'API manquant ou invalide"
}

401 Unauthorized - Invalid Token:

{
  "success": false,
  "error": "Non autorisé",
  "message": "Token d'API manquant ou invalide"
}

Resource Not Found¶

404 Not Found:

{
  "success": false,
  "error": "Commande non trouvée",
  "message": "Aucune commande trouvée avec l'increment ID: 15000012345"
}

Bad Request¶

400 Bad Request:

{
  "success": false,
  "error": "Paramètres invalides",
  "message": "Email ou increment_id requis"
}

Server Errors¶

500 Internal Server Error:

{
  "success": false,
  "error": "Erreur serveur",
  "message": "Une erreur inattendue s'est produite"
}

Rate Limiting¶

Currently, there are no explicit rate limits enforced for Chatbot API endpoints. However:

Implement client-side throttling to avoid excessive requests
Consider caching responses when appropriate
Contact the development team for high-volume integrations

Best Practices¶

1. Error Handling¶

Always check the success field in responses before processing data:

const response = await fetch('https://api.menzzo.fr/api/sale/details/15000012345', {
  headers: {
    'X-API-Token': process.env.API_TOKEN
  }
});

const data = await response.json();

if (data.success) {
  // Process data
  console.log(data.data);
} else {
  // Handle error
  console.error(data.error, data.message);
}

2. Timeout Handling¶

Set appropriate timeouts for chatbot responsiveness:

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 5000); // 5 second timeout

try {
  const response = await fetch(url, {
    signal: controller.signal,
    headers: { 'X-API-Token': token }
  });
  clearTimeout(timeoutId);
  return await response.json();
} catch (error) {
  if (error.name === 'AbortError') {
    console.error('Request timeout');
  }
}

3. Caching¶

Cache frequently accessed data to reduce API calls:

// Cache customer data for 5 minutes
const cache = new Map();
const CACHE_TTL = 5 * 60 * 1000;

async function getCustomerData(email) {
  const cached = cache.get(email);
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }

  const data = await fetchFromAPI(`/api/Customer/details/${email}`);
  cache.set(email, { data, timestamp: Date.now() });
  return data;
}

Integration Example¶

Here's a complete example of integrating the Chatbot API:

class MenzzoAPI {
  constructor(apiToken) {
    this.baseURL = 'https://api.menzzo.fr';
    this.token = apiToken;
  }

  async request(endpoint, options = {}) {
    const url = `${this.baseURL}${endpoint}`;
    const response = await fetch(url, {
      ...options,
      headers: {
        'X-API-Token': this.token,
        'Content-Type': 'application/json',
        ...options.headers
      }
    });

    const data = await response.json();

    if (!data.success) {
      throw new Error(data.message || 'API request failed');
    }

    return data;
  }

  async getSaleDetails(incrementId) {
    return this.request(`/api/sale/details/${incrementId}`);
  }

  async getCustomerByEmail(email) {
    return this.request(`/api/Customer/details/${email}`);
  }

  async createSAV(savData) {
    return this.request('/api/sav', {
      method: 'POST',
      body: JSON.stringify(savData)
    });
  }

  async getSAVStatus(params) {
    const query = new URLSearchParams(params).toString();
    return this.request(`/api/customer/sav-status?${query}`);
  }

  async getProduct(sku) {
    return this.request(`/api/product/${sku}`);
  }
}

// Usage
const api = new MenzzoAPI(process.env.MENZZO_API_TOKEN);

// Get order details
const order = await api.getSaleDetails('15000012345');
console.log(order.data);

// Check SAV status
const savStatus = await api.getSAVStatus({ 
  email: 'customer@example.com' 
});
console.log(savStatus.sav_records);

Core API - General sales and SAV operations
Supplier APIs - Supplier integration endpoints
Authentication Guide - Detailed authentication information
API Customer SAV Status - Complete SAV status documentation

Chatbot API¶

Overview¶

Authentication¶

Endpoints¶

Get Sale Details by Increment ID¶

Get Customer Details by Email¶

Create SAV¶

Get Customer SAV Status¶

Get Product Details by SKU¶

Authentication Setup¶

Getting Your API Token¶

Using the Token¶

Token Security¶

Error Handling¶

Authentication Errors¶

Resource Not Found¶

Bad Request¶

Server Errors¶

Rate Limiting¶

Best Practices¶

1. Error Handling¶

2. Timeout Handling¶

3. Caching¶

Integration Example¶

Related Documentation¶