# Face Registration API

## Endpoint
**POST** `/api/face/register`

Proxies face registration requests to the Python face engine.

## Authentication
Requires API key via `X-API-KEY` header.

## Request

**Headers:**
```
X-API-KEY: face_JxIR1I802dHu6ZKtnBOrzccp3ip7qYE18IFIU0p1
Content-Type: application/json
```

**Body:**
```json
{
  "reference_id": "user_12345",
  "image": "base64_encoded_image_string"
}
```

## Response
Returns the Python service response as-is (no modification).

**Success Example:**
```json
{
  "success": true,
  "reference_id": "user_12345",
  "message": "Face registered successfully"
}
```

**Error Example:**
```json
{
  "success": false,
  "error": "Invalid base64 image"
}
```

## Flow
1. Client sends request with API key
2. Laravel validates API key (middleware)
3. Laravel validates request payload
4. Laravel forwards to Python service with internal key
5. Python service registers face embedding
6. Laravel returns Python response unchanged

## Testing

```bash
# Create client and get API key
curl -X POST http://localhost:8000/api/admin/clients \
  -H "Content-Type: application/json" \
  -d '{"name":"Test Client"}'

# Register face
curl -X POST http://localhost:8000/api/face/register \
  -H "X-API-KEY: face_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_id": "user_123",
    "image": "base64_image_data"
  }'
```

## Error Responses

**401 Unauthorized** - Invalid/missing API key
```json
{
  "error": "API key required"
}
```

**422 Validation Error** - Missing required fields
```json
{
  "message": "The image field is required.",
  "errors": {
    "image": ["The image field is required."]
  }
}
```

**503 Service Unavailable** - Python engine unreachable
```json
{
  "error": "Face engine unavailable"
}
```

## Important Notes

- ✅ Images are NOT stored in Laravel
- ✅ Embeddings are NOT stored in Laravel
- ✅ All face data is managed by Python engine
- ✅ Laravel only proxies requests