# Email Validator API — Documentation

Base URL : `https://votre-domaine.com`

## Authentification

Header requis sur tous les endpoints API :

```
x-api-key: VOTRE_CLE_API
```

## Endpoints

### POST /auth/register

Crée un compte et retourne une clé API avec 10 crédits gratuits.

**Body :**
```json
{ "email": "vous@entreprise.com" }
```

**Réponse (201) :**
```json
{
  "message": "Compte créé — 10 crédits offerts",
  "email": "vous@entreprise.com",
  "credits": 10,
  "plan": "free",
  "api_key": "uuid-..."
}
```

---

### GET /auth/me

Retourne les informations du compte.

**Headers :** `x-api-key`

**Réponse (200) :**
```json
{
  "email": "vous@entreprise.com",
  "credits": 10,
  "plan": "free",
  "api_key": "uuid-..."
}
```

---

### POST /auth/regenerate-key

Génère une nouvelle clé API. L'ancienne clé est invalidée.

**Headers :** `x-api-key`

---

### POST /api/v1/validate

Valide un email. **Coût : 1 crédit.**

**Body :**
```json
{ "email": "contact@entreprise.com" }
```

**Réponse (200) :**
```json
{
  "valid": true,
  "format_ok": true,
  "mx_found": true,
  "disposable": false,
  "score": 100,
  "credits_remaining": 9
}
```

| Champ | Description |
|-------|-------------|
| `valid` | `true` si format OK + MX + non jetable + score ≥ 80 |
| `format_ok` | Format RFC basique |
| `mx_found` | Enregistrement MX (ou A) trouvé |
| `disposable` | Domaine email jetable |
| `score` | Score 0–100 |

---

### POST /api/v1/enrich

Enrichit un email. **Coût : 2 crédits.**

**Body :**
```json
{ "email": "jean@gmail.com" }
```

**Réponse (200) :**
```json
{
  "domain": "gmail.com",
  "provider": "gmail",
  "type": "personal",
  "credits_remaining": 8
}
```

| Champ | Description |
|-------|-------------|
| `provider` | gmail, outlook, yahoo, proton, custom… |
| `type` | `personal` (webmail) ou `business` (domaine custom) |

---

### POST /stripe/checkout

Crée une session Stripe Checkout. **Headers :** `x-api-key`

**Body :**
```json
{ "pack": "starter" }
```

Packs : `starter` (9 €), `pro` (49 €), `business` (199 €)

**Réponse :**
```json
{ "url": "https://checkout.stripe.com/..." }
```

---

## Exemples

### curl

```bash
curl -X POST https://votre-domaine.com/api/v1/validate \
  -H "Content-Type: application/json" \
  -H "x-api-key: VOTRE_CLE" \
  -d '{"email": "contact@entreprise.com"}'
```

### JavaScript

```javascript
const res = await fetch("https://votre-domaine.com/api/v1/validate", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "VOTRE_CLE"
  },
  body: JSON.stringify({ email: "contact@entreprise.com" })
});
console.log(await res.json());
```

### Python

```python
import requests

r = requests.post(
    "https://votre-domaine.com/api/v1/validate",
    headers={"x-api-key": "VOTRE_CLE"},
    json={"email": "contact@entreprise.com"}
)
print(r.json())
```

---

## Limites & erreurs

- **Rate limit :** 60 requêtes/minute par clé API
- **402** — Crédits insuffisants
- **429** — Rate limit dépassé

Headers de rate limit : `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`