# Appels en lot

Une même mission, plusieurs numéros : par exemple demander à dix garages leur premier créneau disponible, ou confirmer
un rendez-vous auprès de vingt cabinets. Réservé aux offres **Pro** et **Entreprise** (un compte Particulier reçoit 403
`fonction_reservee_pro`).

> Les appels en lot servent à des demandes que tu as le droit de faire à chaque interlocuteur. Le démarchage commercial
> et les appels en masse non sollicités sont interdits (CGU) et refusés (`mission_interdite`), comme pour un appel seul.

## Créer un lot

```bash
curl -s -X POST $TEL_API/v1/lots \
  -H "Authorization: Bearer $TEL_KEY" -H "Content-Type: application/json" \
  -d '{
    "nom": "Garages – révision",
    "numeros": ["+33142000000", "+33143000000", "+33144000000"],
    "mission": "Demande le premier créneau disponible pour une révision de Clio 4, au nom de Moha K. Ne prends pas de rendez-vous.",
    "langue": "fr",
    "webhook_url": "https://ton-serveur.fr/hooks/telephone"
  }'
```

- `numeros` : 100 au plus par lot (sinon 422 `lot_trop_grand`), au format `+33…` ou `0X XX XX XX XX`. Les doublons, les
  numéros invalides et ceux que les règles anti-abus écartent sont listés dans `refuses` (numéro et motif) ; si aucun
  numéro ne peut être appelé : 422 `lot_vide`.
- `mission` (texte libre de 10 à 2 000 caractères, ou mission structurée), `nom`, `voix`, `langue`, `webhook_url`,
  `quand` et `reglages_voix` fonctionnent comme pour un appel seul. L'annonce IA est toujours faite.
- Chaque numéro devient une mission ordinaire (`lot_id` rempli) : même suivi, mêmes webhooks, même facturation.
- **Limites de l'offre** : les appels partent dans la limite des appels en même temps (5 en Pro) ; les autres
  attendent leur tour et partent dès qu'une place se libère. Le lot entier est refusé (429
  `plafond_journalier_atteint`, avec `erreur.demandes` et `erreur.restants`) s'il dépasse ce qu'il te reste d'appels
  sur 24 h glissantes (300 en Pro).
- Un appel du lot qui attend sa place plus de 15 minutes après l'heure demandée ne part qu'entre 8 h et 21 h (heure de
  la personne appelée).

La réponse (201) contient l'`id` du lot, `total`, `par_statut`, `refuses`, la liste `appels` et tes `limites`.

## Suivre un lot

```bash
curl -s $TEL_API/v1/lots/lot_7c2e… -H "Authorization: Bearer $TEL_KEY"
```

La réponse donne `statut` (`en_cours`, `termine`, `annule`), `total`, `par_statut` (nombre d'appels par statut),
`reussis`, `refuses` et la liste `appels` (`id`, `numero`, `statut`, `resultat`, `resume`, `tentatives`).
`GET /v1/lots` liste les lots du compte, les plus récents d'abord.

## Annuler

`POST /v1/lots/{lot_id}/cancel` annule les appels du lot **pas encore partis** (en file ou relance prévue) ; leurs
crédits réservés sont rendus. Les appels en cours continuent : arrête-les un par un avec
`POST /v1/missions/{id}/cancel` si besoin.

## En MCP

- `place_batch_calls(phone_numbers, task, language?, voice?, scheduled_at?, name?)` crée le lot et renvoie son
  identifiant.
- `get_batch_calls(batch_id)` donne l'avancement et les résultats.
- Erreurs : `plan_feature_required` (offre Particulier), `batch_too_large` (plus de 100 numéros).