API Endpoint: Customer SAV Status Check

Overview

This API endpoint allows checking if a customer has any SAV (Service After Sale) records, optionally filtered by product SKU or sale product ID.

Endpoint Details

URL

GET /api/customer/sav-status

Authentication

Requires API token authentication via header:

X-API-Token: your_api_token_here

Query Parameters

Parameter	Type	Required	Description
email	string	Yes*	Customer email address
increment_id	string	Yes*	Order increment ID (alternative to email)
product_sku	string	No	Product SKU to filter SAV records by specific product
sale_product_id	integer	No	Sale product ID to filter SAV records by specific sale product

*Note: Either email OR increment_id is required, not both.

Example Requests

Check all SAV records for a customer by email

curl -X GET \
  'https://your-domain.com/api/customer/sav-status?email=customer@example.com' \
  -H 'X-API-Token: your_api_token_here'

Check all SAV records for a customer by order increment ID

curl -X GET \
  'https://your-domain.com/api/customer/sav-status?increment_id=ORDER123456' \
  -H 'X-API-Token: your_api_token_here'

Check SAV records for a specific product SKU

curl -X GET \
  'https://your-domain.com/api/customer/sav-status?email=customer@example.com&product_sku=SKU123' \
  -H 'X-API-Token: your_api_token_here'

Check SAV records for a specific sale product ID

curl -X GET \
  'https://your-domain.com/api/customer/sav-status?email=customer@example.com&sale_product_id=456' \
  -H 'X-API-Token: your_api_token_here'

Check SAV records filtering by both product SKU and sale product ID

curl -X GET \
  'https://your-domain.com/api/customer/sav-status?email=customer@example.com&product_sku=SKU123&sale_product_id=456' \
  -H 'X-API-Token: your_api_token_here'

Response Format

Success Response (HTTP 200)

Optimized for AI consumption - contains only essential fields:

{
  "success": true,
  "hasSav": true,
  "totalSav": 2,
  "savRecords": [
    {
      "savId": 123,
      "status": 1,
      "statusLabel": "Validé",
      "orderRef": "ORDER123",
      "problemType": "garantie",
      "createdAt": "2024-01-10 14:20:00",
      "clientObservation": "Customer feedback about the issue",
      "refund": {
        "status": "Completed",
        "amount": 150.50,
        "type": "bank_transfer"
      },
      "products": [
        {
          "sku": "SKU123",
          "name": "Product Name",
          "qty": 1
        }
      ]
    },
    {
      "savId": 124,
      "status": 0,
      "statusLabel": "En cours",
      "orderRef": "ORDER123",
      "problemType": "transport",
      "createdAt": "2024-01-15 10:30:00",
      "clientObservation": "Damaged during delivery",
      "hasPreRefund": true,
      "preRefund": {
        "amount": 70.40,
        "type": "Bon achat",
        "codeCoupon": "VOUCHER2024"
      },
      "products": [
        {
          "sku": "SKU456",
          "name": "Another Product",
          "qty": 2
        }
      ]
    }
  ]
}

Field Descriptions:

• success: Boolean indicating if the request was successful
• hasSav: Boolean indicating if any SAV records exist
• totalSav: Total number of SAV records found
• savRecords: Array of SAV records with:
  • savId: SAV record ID
  • status: SAV status code
  • statusLabel: Human-readable status
  • orderRef: Order reference number
  • problemType: Type of problem/issue
  • createdAt: SAV creation date
  • clientObservation: Customer's description of the issue
  • refund: Refund information (only included when refund is validated/processed, status > 0). Contains:
    • status: Refund status label
    • amount: Refund amount
    • type: Refund type
    • codeCoupon: Coupon code (only included for 'Bon achat' type refunds)
  • hasPreRefund: Boolean flag indicating a pre-refund exists (only present when true, for refunds with status 0)
  • preRefund: Pre-refund details (only included when hasPreRefund is true). Contains:
    • amount: Pre-refund amount
    • type: Pre-refund type (e.g., "Geste co", "Bon achat")
    • codeCoupon: Coupon code (only included for 'Bon achat' type pre-refunds)
  • products: Array of products involved in the SAV

Error Responses

Missing Required Parameter (HTTP 400)

{
  "success": false,
  "error": "Paramètre manquant",
  "message": "Le paramètre email ou increment_id est requis"
}

Both Parameters Provided (HTTP 400)

{
  "success": false,
  "error": "Paramètres invalides",
  "message": "Les paramètres email et increment_id ne peuvent pas être utilisés ensemble"
}

Invalid sale_product_id (HTTP 400)

{
  "success": false,
  "error": "Paramètre invalide",
  "message": "Le paramètre sale_product_id doit être un entier positif"
}

Authentication Failed (HTTP 401)

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

Server Error (HTTP 500)

{
  "success": false,
  "error": "Erreur serveur",
  "message": "Error details..."
}

SAV Status Values

Status	Label	Description
0	En cours	SAV in progress
1	Validé	SAV validated
2	Complet	SAV completed
4	Annulé	SAV canceled
5	Urgent	Urgent SAV
6	En attente	SAV waiting
7	Transmis	SAV transmitted

Use Cases

1. Customer Support: Check if a customer has existing SAV records when they contact support
2. Chatbot Integration: Allow AI chatbot to check SAV status and provide relevant information
3. Product Quality Tracking: Identify products with multiple SAV records
4. Customer History: Review complete SAV history for a customer
5. Specific Product Inquiry: Filter SAV records by product SKU or sale product ID for targeted support

SAV Create/Update API

Create SAV Endpoint

POST /sav/create-sale-sav

Update SAV Endpoint

POST /sav/update-new-sale-sav/{id}

Pickup Return Parameters

Parameter	Type	Required	Description
pickup_rdv_date	string	No	Pickup appointment date (e.g., 2026-03-15)

Pickup Return Logic

When both pickup_rdv_date are provided, the date_retour field is automatically formatted as:

pickup_rdv_date

Example:

• pickup_rdv_date: 2026-03-15 Result in date_retour: 2026-03-15

Example Request (Create SAV with Pickup Date)

curl -X POST \
  'https://your-domain.com/sav/create-sale-sav' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'sale_ref=ORDER123' \
  -d 'customer_email=customer@example.com' \
  -d 'customer_name=John Doe' \
  -d 'pickup_rdv_date=2026-03-15'

Notes

• The endpoint only returns non-archived SAV records
• Results are ordered by creation date (most recent first)
• Either email OR increment_id must be provided, but NOT both - the API will return an error if both are provided
• The sale_product_id parameter must be a positive integer if provided
• When filtering by product_sku, only SAV records containing that product are returned
• When filtering by sale_product_id, only SAV records for that specific sale product are returned
• When both product_sku and sale_product_id are provided: The filters are combined with AND logic, meaning only SAV records for that specific sale product ID that also belongs to the specified product SKU are returned
• The hasSav field provides a quick boolean check for SAV existence
• Response is optimized for AI consumption: Only essential fields are included to minimize token usage and improve processing efficiency
• Refund handling:
  • Validated/processed refunds (status > 0) include a refund object with status, amount, and type
  • Pre-refunds (status 0) include a hasPreRefund: true flag and a preRefund object with amount and type (but no status)
  • This distinction allows API consumers to identify whether a refund is in progress or completed