Customer SAV Status API - Complete Documentation

📋 Overview

This documentation covers the new API endpoint that allows checking if a customer has SAV (Service After Sale) records for specific products.

Endpoint: GET /api/customer/sav-status

Purpose: Enable customer support, AI chatbots, and other systems to check customer SAV history and status.

📚 Documentation Index

This feature includes comprehensive documentation across multiple files:

1. API Reference Guide

For: API Consumers, Frontend Developers, Integration Teams

Complete API documentation including:

Endpoint URL and authentication
Request parameters and query strings
Response format and data structures
Error codes and messages
Use case examples
SAV status reference table

Quick Links:

2. Implementation Summary

For: Backend Developers, DevOps, System Architects

Technical implementation details including:

Code changes and file modifications
Database queries and ORM usage
Security measures implemented
Performance optimizations
Maintenance notes
Future enhancement suggestions

Quick Links:

3. Testing Guide

For: QA Engineers, Testers, DevOps

Comprehensive testing documentation including:

Manual testing scenarios with curl examples
Automated testing scripts (bash)
Postman collection
Performance testing with Apache Bench
Integration test examples (PHPUnit)
Troubleshooting common issues

Quick Links:

🚀 Quick Start

Prerequisites

Valid API token configured in system parameters
Access to the application server
Customer email addresses for testing

The API token can be sent as X-API-Token: YOUR_API_TOKEN, Authorization: YOUR_API_TOKEN, or Authorization: Bearer YOUR_API_TOKEN.

Basic Usage

# Check all SAV for a customer
curl -X GET \
  'https://your-domain.com/api/customer/sav-status?email=customer@example.com' \
  -H 'X-API-Token: YOUR_API_TOKEN'

# Filter by specific product
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'

Response Example

{
  "success": true,
  "customerEmail": "customer@example.com",
  "productSku": "SKU123",
  "hasSav": true,
  "totalSav": 2,
  "savRecords": [
    {
      "savId": 123,
      "status": 1,
      "statusLabel": "Validé",
      "saleRef": "ORDER123",
      "typePb": "garantie",
      "products": [...]
    }
  ]
}

📝 SAV Create/Update API

Endpoints

Action	Method	Endpoint
Create SAV	POST	`/sav/create-sale-sav`
Check forgotten coupon SAV eligibility	POST	`/api/sav/forgotten-coupon/eligibility`
Create chatbot SAV	POST	`/api/sav`
Update SAV	POST	`/sav/update-new-sale-sav/{id}`

Chatbot Forgotten Coupon SAV

Eligibility check

POST /api/sav/forgotten-coupon/eligibility validates whether the chatbot is allowed to open an oublie de code promo ticket without creating any SAV, canceling the order, or creating a pre-refund.

Required JSON payload:

{
  "increment_id": "100000123",
  "coupon_code": "SUMMER10",
  "commercial_offer_percentage": 10
}

Allowed response:

{
  "success": true,
  "allowed": true,
  "sale_id": 456,
  "coupon_code": "SUMMER10",
  "commercial_offer_percentage": 10,
  "proposed_gesture_amount": 20,
  "type": "forgotten_coupon_eligibility"
}

Rejected response:

{
  "success": true,
  "allowed": false,
  "message": "Cette commande utilise déjà un code promo",
  "error_code": "SALE_ALREADY_HAS_COUPON"
}

Business rejections return HTTP 200 with allowed: false. Missing required controller fields return HTTP 422, unknown orders return HTTP 404, and authentication failures are handled by the shared API token guard.

Ticket creation

POST /api/sav can open a chatbot ticket when a customer asks to cancel because they forgot to use a discount coupon. The order is not canceled. The SAV is resolved as a geste co for the proposed gesture amount and a pre-refund is created automatically.

Required JSON payload:

{
  "increment_id": "100000123",
  "sav_type": "oublie de code promo",
  "coupon_code": "SUMMER10",
  "commercial_offer_percentage": 10
}

Accepted sav_type aliases are oublie de code promo, forgotten-coupon, and forgot-coupon.

Success response:

{
  "success": true,
  "sav_id": 123,
  "sale_id": 456,
  "coupon_code": "SUMMER10",
  "commercial_offer_percentage": 10,
  "proposed_gesture_amount": 20,
  "type": "forgotten_coupon_ticket"
}

The request is rejected when the order cannot be canceled by the chatbot, already has a coupon code, already has an unarchived oublie de code promo SAV, or the coupon/percentage payload is invalid. The write path rechecks eligibility while locking the order, so a retry or concurrent call that races with the first ticket creation returns FORGOTTEN_COUPON_SAV_ALREADY_EXISTS instead of creating a duplicate ticket.

coupon_code is currently validated as a non-empty payload field. Logidav does not check this endpoint's forgotten coupon code against an external coupon source before opening the ticket.

Pickup Return Parameters

Parameter	Type	Description
`pickup_rdv_date`	string	Pickup appointment date (e.g., `2026-03-15`)
`date_retour`	string	Direct value (overridden if pickup params provided)

Pickup Return Logic

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

2026-03-15

Example: 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'

🔑 Key Features

✅ Security

API Token Authentication: Required for all requests
Parameter Validation: Email validation and sanitization
SQL Injection Prevention: Using Doctrine ORM with parameter binding
Access Control: Only non-archived SAV records returned

⚡ Performance

Optimized Queries: Efficient database queries with proper indexing
Array Operations: Using !empty() instead of count() > 0
SQL Compatibility: Standard SQL syntax for cross-database support

📊 Data Returned

SAV Metadata: ID, status, dates (claim, creation, validation)
Customer Info: Name, email, phone
Problem Details: Type, observations, propositions
Actions: Final actions, return info, communication type
Products: Associated products with SKU, name, quantity

🎯 Use Cases

1. Customer Support

Check customer SAV history during support calls
Verify status of existing SAV tickets
Identify recurring issues with products

2. AI Chatbot Integration

Provide real-time SAV status to customers
Answer questions about SAV progress
Route to appropriate support channels

3. Quality Monitoring

Track products with multiple SAV records
Identify quality issues across product lines
Generate reports on SAV trends

4. Customer Portal

Customer self-service SAV lookup
Track SAV resolution progress
View SAV history

📊 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

🛠️ Technical Stack

Framework: Symfony 3.4+ with FOSRestBundle
Database: MySQL/MariaDB with Doctrine ORM
Authentication: API Token (X-API-Token header)
Response Format: JSON
HTTP Methods: GET

📦 Files Modified

src/AppBundle/
├── Api/
│   └── MenzzoChatbotWrapperApiController.php  (+109 lines)
└── Repository/
    └── SaleSavRepository.php                   (+30 lines)

docs/
├── API-Customer-SAV-Status.md                  (141 lines, API docs)
├── API-Customer-SAV-Status-IMPLEMENTATION-SUMMARY.md  (208 lines, tech details)
├── API-Customer-SAV-Status-TESTING.md          (409 lines, testing guide)
└── API-Customer-SAV-Status-README.md           (this file)

Total: 4 code files modified, 897 lines of documentation added

🚦 Getting Started Checklist

For API Consumers

Read the API Reference Guide
Obtain API token from system administrator
Test endpoint using provided curl examples
Integrate into your application
Implement error handling

For Developers

Review Implementation Summary
Understand database schema and relationships
Review security measures
Check code in MenzzoChatbotWrapperApiController.php
Review SaleSavRepository::findSavByCustomerAndProduct()

For QA/Testing

For DevOps

Ensure API token is configured
Verify database indexes are in place
Set up monitoring and alerting
Configure rate limiting (if needed)
Plan deployment strategy
Prepare rollback plan

🐛 Troubleshooting

Common Issues

401 Unauthorized

Verify API token in configuration
Check X-API-Token header is set correctly
Ensure token matches system parameter

400 Bad Request

Verify email parameter is provided
Check email format is valid
Review request URL encoding

500 Internal Server Error

Check application logs
Verify database connection
Ensure SAV service is running
Check Doctrine entity mappings

Empty Results

Verify customer email exists in system
Check if customer has any SAV records
Ensure product SKU is correct (if filtering)
Verify SAV records are not archived

See Testing Guide - Troubleshooting for detailed solutions.

📈 Performance Expectations

Response Time: < 500ms for typical queries
Throughput: > 50 requests/second
Availability: 99.9% uptime
Error Rate: < 0.1%

🔄 Version History

v1.1.0 (2026-03-09): Pickup date/time parameters added
- Added pickup_rdv_date parameters for SAV create/update
- date_retour field now auto-formatted as pickup_rdv_date
v1.0.0 (2024-12-11): Initial release
- New API endpoint implementation
- Repository method added
- Comprehensive documentation created
- Testing guide provided

📞 Support

For questions, issues, or feature requests:

Documentation: Check this README and linked documents
Testing: Review the Testing Guide
Implementation: See Implementation Summary
API Usage: Consult API Reference
Development Team: Contact via internal channels

🎓 Learning Path

New to the API? Follow this learning path:

Start with this README (you are here! ✅)
Read the API Reference Guide
Try the Quick Start examples in this document
Review Test Scenarios
Explore Implementation Details

Want to integrate?

Obtain API token
Review authentication requirements
Test with curl examples
Implement in your application
Add error handling
Monitor API usage

Need to deploy?

Review Deployment Checklist
Complete all testing scenarios
Configure production environment
Set up monitoring
Execute deployment
Verify functionality

✨ Next Steps

After implementing this endpoint, consider:

Pagination: Add support for large result sets
Caching: Implement Redis caching for frequently accessed data
Webhooks: Add webhook notifications for SAV status changes
Analytics: Track API usage and response times
Rate Limiting: Implement rate limiting for API consumers
GraphQL: Consider GraphQL API for more flexible queries

📝 License

This implementation is part of the Logidav project and follows the project's licensing terms.

Last Updated: 2026-03-09 Maintained By: Development Team Version: 1.1.0

📋 Overview​

📚 Documentation Index​

1. API Reference Guide​

2. Implementation Summary​

3. Testing Guide​

🚀 Quick Start​

Prerequisites​

Basic Usage​

Response Example​

📝 SAV Create/Update API​

Endpoints​

Chatbot Forgotten Coupon SAV​

Eligibility check​

Ticket creation​

Pickup Return Parameters​

Pickup Return Logic​

Example: Create SAV with Pickup Date​

🔑 Key Features​

✅ Security​

⚡ Performance​

📊 Data Returned​

🎯 Use Cases​

1. Customer Support​

2. AI Chatbot Integration​

3. Quality Monitoring​

4. Customer Portal​

📊 SAV Status Values​

🛠️ Technical Stack​

📦 Files Modified​

🚦 Getting Started Checklist​

For API Consumers​

For Developers​

For QA/Testing​

For DevOps​

🐛 Troubleshooting​

Common Issues​

📈 Performance Expectations​

🔄 Version History​

📞 Support​

🎓 Learning Path​

✨ Next Steps​

📝 License​

📋 Overview

📚 Documentation Index

1. API Reference Guide

2. Implementation Summary

3. Testing Guide

🚀 Quick Start

Prerequisites

Basic Usage

Response Example

📝 SAV Create/Update API

Endpoints

Chatbot Forgotten Coupon SAV

Eligibility check

Ticket creation

Pickup Return Parameters

Pickup Return Logic

Example: Create SAV with Pickup Date

🔑 Key Features

✅ Security

⚡ Performance

📊 Data Returned

🎯 Use Cases

1. Customer Support

2. AI Chatbot Integration

3. Quality Monitoring

4. Customer Portal

📊 SAV Status Values

🛠️ Technical Stack

📦 Files Modified

🚦 Getting Started Checklist

For API Consumers

For Developers

For QA/Testing

For DevOps

🐛 Troubleshooting

Common Issues

📈 Performance Expectations

🔄 Version History

📞 Support

🎓 Learning Path

✨ Next Steps

📝 License