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¶

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

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