Supplier APIs¶

The Supplier APIs provide integration endpoints for AsirGroup and Notio suppliers to manage orders, shipments, and acknowledgements.

Overview¶

6 endpoints for supplier integrations: - AsirGroup API (3 endpoints): AsirGroup supplier integration - Notio API (3 endpoints): Notio supplier integration

Both suppliers use identical endpoint patterns with supplier-specific paths.

Authentication¶

All Supplier API endpoints use Token Bearer authentication:

Authorization: Bearer {token}

AsirGroup API¶

Endpoints for AsirGroup supplier integration to retrieve orders and manage shipments.

Get AsirGroup Sales¶

GET /api/asir-group/get-sales

Retrieve paginated list of sales/orders for AsirGroup supplier with shipping labels.

Parameters: (Query string) - page (integer, optional): Page number (default: 1) - date_from (string, optional): Start date filter (YYYY-MM-DD) - date_to (string, optional): End date filter (YYYY-MM-DD) - last_menzzo_order_number (string, optional): Last processed order number for pagination - order_number (string, optional): Specific order number to retrieve

Authentication: Token Bearer required

Response: JSON array of sales with shipping information

Caching: Results are cached for 30 minutes

Example:

curl -H "Authorization: Bearer {token}" \
  "https://api.menzzo.fr/api/asir-group/get-sales?page=1&date_from=2026-01-01"

Response Example:

[
  {
    "menzzo_order_id": "15000012345_789",
    "sku": "PRODUCT-SKU",
    "quantity": 1,
    "price": 250.00,
    "link_to_label": "https://api.menzzo.fr/api/files/path/to/label.pdf",
    "order_date": "2026-01-15",
    "carrier": "CHRONOPOST"
  }
]

Response Fields: - menzzo_order_id: Format is {increment_id}_{sale_product_id} - sku: Product SKU - quantity: Quantity ordered - price: Wholesale price - link_to_label: Direct link to shipping label PDF - order_date: Order creation date - carrier: Shipping carrier name

Ship AsirGroup Sale¶

POST /api/asir-group/ship-sale

Mark a sale product as shipped by AsirGroup supplier.

Parameters: (JSON body) - menzzo_order_id (string, required): Format: {increment_id}_{sale_product_id}

Authentication: Token Bearer required

Response: JSON with success status

Side Effects: - Sets prepared_at timestamp on sale product - Logs shipment in sale log with cron user - Updates product status to shipped

Example:

curl -X POST \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"menzzo_order_id": "15000012345_789"}' \
  https://api.menzzo.fr/api/asir-group/ship-sale

Response Example:

{
  "success": true,
  "message": "Votre produit a été expédié avec succès"
}

Error Response:

{
  "success": false,
  "message": "Aucun produit livrable n'a été trouvé pour être expédié"
}

Acknowledge AsirGroup Sale¶

POST /api/asir-group/acknowledge-sale

Confirm receipt of order by AsirGroup supplier.

Parameters: (JSON body) - menzzo_order_id (string, required): Format: {increment_id}_{sale_product_id}

Authentication: Token Bearer required

Response: JSON with acknowledgement status

Side Effects: - Updates product acknowledgement status - Logs acknowledgement in sale log - May trigger subsequent workflows

Example:

curl -X POST \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"menzzo_order_id": "15000012345_789"}' \
  https://api.menzzo.fr/api/asir-group/acknowledge-sale

Response Example:

{
  "success": true,
  "message": "Votre produit a bien été acquitté"
}

Notio API¶

Endpoints for Notio supplier integration (identical pattern to AsirGroup).

Get Notio Sales¶

GET /api/notio/get-sales

Retrieve paginated list of sales/orders for Notio supplier.

Parameters: (Query string) - page (integer, optional): Page number (default: 1) - date_from (string, optional): Start date filter (YYYY-MM-DD) - date_to (string, optional): End date filter (YYYY-MM-DD) - last_menzzo_order_number (string, optional): Last processed order number for pagination

Authentication: Token Bearer required

Response: JSON array (same format as AsirGroup)

Example:

curl -H "Authorization: Bearer {token}" \
  "https://api.menzzo.fr/api/notio/get-sales?page=1&date_from=2026-01-01"

Response Example:

[
  {
    "menzzo_order_id": "15000012345_790",
    "sku": "NOTIO-PROD-123",
    "quantity": 2,
    "price": 180.00,
    "link_to_label": "https://api.menzzo.fr/api/files/path/to/label.pdf",
    "order_date": "2026-01-15",
    "carrier": "GEODIS"
  }
]

Ship Notio Sale¶

POST /api/notio/ship-sale

Mark a sale product as shipped by Notio supplier.

Parameters: (JSON body) - menzzo_order_id (string, required): Format: {increment_id}_{sale_product_id}

Authentication: Token Bearer required

Response: JSON with success status

Side Effects: - Sets prepared_at timestamp - Logs shipment in sale log - Updates product status

Example:

curl -X POST \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"menzzo_order_id": "15000012345_790"}' \
  https://api.menzzo.fr/api/notio/ship-sale

Response Example:

{
  "success": true,
  "message": "Votre produit a été expédié avec succès"
}

Acknowledge Notio Sale¶

POST /api/notio/acknowledge-sale

Confirm receipt of order by Notio supplier.

Parameters: (JSON body) - menzzo_order_id (string, required): Format: {increment_id}_{sale_product_id}

Authentication: Token Bearer required

Response: JSON with acknowledgement status

Side Effects: - Updates acknowledgement status - Logs acknowledgement - May trigger workflows

Example:

curl -X POST \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"menzzo_order_id": "15000012345_790"}' \
  https://api.menzzo.fr/api/notio/acknowledge-sale

Response Example:

{
  "success": true,
  "message": "Votre produit a bien été acquitté"
}

Integration Workflow¶

Typical Supplier Integration Flow¶

Retrieve Orders
Call GET /api/{supplier}/get-sales regularly (e.g., every hour)
Use pagination parameters to process all orders
Store menzzo_order_id for each order
Acknowledge Receipt
Call POST /api/{supplier}/acknowledge-sale for each order
Confirms you've received the order details
Important for tracking and inventory management
Process Orders
Pick, pack, and prepare items for shipment
Generate shipping labels using the provided links
Handle any special instructions or notes
Confirm Shipment
Call POST /api/{supplier}/ship-sale when order is shipped
Updates Menzzo system with shipment status
Triggers customer notifications

Example Integration Code¶

import requests
from datetime import datetime, timedelta

class MenzzoSupplierAPI:
    def __init__(self, base_url, token, supplier):
        self.base_url = base_url
        self.token = token
        self.supplier = supplier  # 'asir-group' or 'notio'

    def _headers(self):
        return {
            'Authorization': f'Bearer {self.token}',
            'Content-Type': 'application/json'
        }

    def get_sales(self, page=1, date_from=None, date_to=None):
        """Retrieve sales for the supplier"""
        params = {'page': page}
        if date_from:
            params['date_from'] = date_from
        if date_to:
            params['date_to'] = date_to

        url = f'{self.base_url}/api/{self.supplier}/get-sales'
        response = requests.get(url, headers=self._headers(), params=params)
        response.raise_for_status()
        return response.json()

    def acknowledge_sale(self, menzzo_order_id):
        """Acknowledge receipt of an order"""
        url = f'{self.base_url}/api/{self.supplier}/acknowledge-sale'
        data = {'menzzo_order_id': menzzo_order_id}
        response = requests.post(url, headers=self._headers(), json=data)
        response.raise_for_status()
        return response.json()

    def ship_sale(self, menzzo_order_id):
        """Mark an order as shipped"""
        url = f'{self.base_url}/api/{self.supplier}/ship-sale'
        data = {'menzzo_order_id': menzzo_order_id}
        response = requests.post(url, headers=self._headers(), json=data)
        response.raise_for_status()
        return response.json()

# Usage example
api = MenzzoSupplierAPI(
    base_url='https://api.menzzo.fr',
    token='your_bearer_token',
    supplier='asir-group'
)

# Get today's orders
today = datetime.now().strftime('%Y-%m-%d')
sales = api.get_sales(date_from=today)

for sale in sales:
    order_id = sale['menzzo_order_id']

    # Acknowledge receipt
    ack_result = api.acknowledge_sale(order_id)
    print(f"Acknowledged {order_id}: {ack_result['success']}")

    # Process order...
    # (your picking, packing logic here)

    # Mark as shipped
    ship_result = api.ship_sale(order_id)
    print(f"Shipped {order_id}: {ship_result['success']}")

Pagination¶

For large result sets, use pagination parameters:

# Get first page
curl -H "Authorization: Bearer {token}" \
  "https://api.menzzo.fr/api/asir-group/get-sales?page=1&date_from=2026-01-01"

# Get second page
curl -H "Authorization: Bearer {token}" \
  "https://api.menzzo.fr/api/asir-group/get-sales?page=2&date_from=2026-01-01"

# Or use last_menzzo_order_number for cursor-based pagination
curl -H "Authorization: Bearer {token}" \
  "https://api.menzzo.fr/api/asir-group/get-sales?last_menzzo_order_number=15000012345_789"

Error Handling¶

Common Errors¶

401 Unauthorized:

{
  "error": "Unauthorized",
  "message": "Invalid or missing Bearer token"
}

400 Bad Request:

{
  "success": false,
  "message": "Invalid menzzo_order_id format"
}

404 Not Found:

{
  "success": false,
  "message": "Order not found or already processed"
}

Error Recovery¶

Token Expiration: Refresh your token and retry
Order Not Found: May be already processed, check order status
Network Errors: Implement retry logic with exponential backoff
Rate Limiting: Space out requests, implement queuing

Best Practices¶

1. Polling Frequency¶

Poll for new orders every 15-60 minutes during business hours
Reduce frequency during off-hours
Use date filters to minimize data transfer

2. Order Processing¶

Acknowledge orders as soon as received
Process orders in chronological order
Mark as shipped only when actually shipped

3. Error Handling¶

Log all API errors for troubleshooting
Implement retry logic for transient failures
Alert on repeated failures

4. Data Validation¶

Validate menzzo_order_id format before API calls
Check SKU availability before acknowledging
Verify shipping label availability before shipping

5. Monitoring¶

Track API response times
Monitor success/failure rates
Alert on unusual patterns (e.g., no orders for extended period)

Caching¶

The AsirGroup get-sales endpoint implements 30-minute caching:

First request fetches fresh data from database
Subsequent requests within 30 minutes return cached data
Cache is per unique query (page, dates, order_number)
Notio endpoint does not implement caching (always fresh data)

Rate Limiting¶

Currently, there are no explicit rate limits enforced at the API level. However:

Implement client-side throttling to avoid excessive requests
Recommended: Maximum 1 request per second
For bulk operations, add delays between requests

Support¶

For supplier integration support:

Email: technique@menzzo.fr
Include: Supplier name, order IDs, error messages
Response Time: Within 1 business day

Core API - General sales and SAV operations
Chatbot API - Chatbot integration endpoints
Authentication Guide - Detailed authentication information

Supplier APIs¶

Overview¶

Authentication¶

AsirGroup API¶

Get AsirGroup Sales¶

Ship AsirGroup Sale¶

Acknowledge AsirGroup Sale¶

Notio API¶

Get Notio Sales¶

Ship Notio Sale¶

Acknowledge Notio Sale¶

Integration Workflow¶

Typical Supplier Integration Flow¶

Example Integration Code¶

Pagination¶

Error Handling¶

Common Errors¶

Error Recovery¶

Best Practices¶

1. Polling Frequency¶

2. Order Processing¶

3. Error Handling¶

4. Data Validation¶

5. Monitoring¶

Caching¶

Rate Limiting¶

Support¶

Related Documentation¶