# outsend — Documentation complète (FR)

Toutes les pages de la documentation publique outsend, concaténées pour ingestion par un LLM. Chaque page est délimitée par `<!-- doc: <slug> -->`.


<!-- doc: index -->

---
title: Documentation outsend
slug: 
section: 
summary: Référence technique pour outsend — modules, pipelines, veille, API. Conçue pour les développeurs et les assistants AI.
---

Cette documentation décrit les **contrats publics** de chaque module outsend — ce que chacun accepte en entrée, ce qu'il renvoie, son comportement dans le temps, et comment les modules s'enchaînent en pipelines.

Double objectif :

1. **Aider les intégrateurs et les power users** à comprendre ce que fait chaque module et comment le piloter depuis l'UI ou l'API.
2. **Être lisible par un assistant AI** — chaque page est du markdown brut, téléchargeable en masse, exposée via le standard `llms.txt`.

## Comment lire

- **Concepts** — par où commencer. Couvre ce qu'est un *job*, un *pipeline*, une *veille*, plus le cycle de vie et les événements émis.
- **Modules** — une page par module (19 actifs + 4 sur demande). Structure : Objet → Entrées → Sorties → Cycle de vie → Limites → Erreurs.
- **Référence API** — chaque endpoint REST, groupé par domaine.
- **Intégration** — bring-your-own-key (BYOK), MCP server (prévu), `llms.txt`.

## Tout copier en un clic

Le bouton **Copy** en haut à droite de chaque page permet de récupérer :

- La page courante (markdown brut)
- La section courante (toutes les pages de modules par ex.)
- **Toute la documentation** — un seul bundle markdown concaténé, prêt à coller dans Claude, ChatGPT, Cursor, ou tout autre assistant AI.

Index LLM stable à [`/docs/fr/llms.txt`](/docs/fr/llms.txt) et bundle complet à [`/docs/fr/llms-full.txt`](/docs/fr/llms-full.txt) — tous deux suivent le standard [llms.txt](https://llmstxt.org), détecté automatiquement par la plupart des outils AI.

## Périmètre

Cette documentation décrit **ce qu'outsend expose**, pas comment c'est construit en interne. Détails d'implémentation — stack de scraping, infrastructure proxy, sélecteurs DOM, heuristiques de timing, taux de réussite exacts — volontairement omis. Ce ne sont pas des contrats stables et ils n'aident pas à intégrer.

S'il manque quelque chose, écrire à [support@outsend.xyz](mailto:support@outsend.xyz).

## Liens rapides

- [Qu'est-ce qu'outsend](/docs/fr/what-is-outsend)
- [Démarrage rapide](/docs/fr/quickstart)
- [Jobs & cycle de vie](/docs/fr/concepts/jobs-lifecycle)
- [Registre des modules](/docs/fr/concepts/module-registry)
- [Vue d'ensemble API](/docs/fr/api/overview)


<!-- doc: api/auth -->

---
title: Authentification
slug: api/auth
section: API
summary: Émission et révocation de cookies de session, gestion des identifiants, vérification d'email et endpoints RGPD self-service sous /api/auth.
---

# Authentification

L'API d'authentification émet et révoque les cookies de session, gère les identifiants, vérifie la propriété d'email et expose les endpoints RGPD self-service. Toutes les routes sont montées sous `/api/auth` et répondent en JSON sauf mention contraire.

## Cookie de session

Les appels réussis à `signup`, `login` et `password/change` posent un cookie `outsend_session` :

| Attribut | Valeur |
|----------|--------|
| Nom | `outsend_session` |
| TTL | 7 jours (`SESSION_DURATION_DAYS = 7`) |
| `HttpOnly` | true |
| `Secure` | true (production) |
| `SameSite` | `Lax` |
| `Path` | `/` |

Le cookie est un jeton signé lié à une ligne de `sessions`. Révoquer une session (logout, changement de mot de passe, suppression de compte) supprime la ligne côté serveur même si le cookie est rejoué.

## Limites de débit et erreurs

Chaque endpoint applique des fenêtres par IP et par identité (voir [Limites](/docs/fr/concepts/limits)). Le dépassement renvoie `429 Too Many Requests` avec un message en français contenant le délai de retry en secondes.

Toutes les erreurs suivent la forme FastAPI `{ "detail": "<message>" }`. Codes génériques : `400` (payload invalide, jeton expiré, mauvais mot de passe actuel, échec captcha), `401` (identifiants erronés ou session manquante sur routes protégées), `429` (limite de débit). Les `detail` spécifiques sont listés en ligne ci-dessous.

---

## POST /api/auth/signup

Crée un utilisateur, envoie l'email de bienvenue + vérification, et ouvre une session. Sans auth. Limite : 3 / heure / IP.

### Corps de requête

| Champ | Type | Notes |
|-------|------|-------|
| `email` | string (email) | Requis. |
| `password` | string | 8 à 128 caractères, doit contenir une lettre ET un chiffre/symbole. |
| `invitation_code` | string | 1 à 64 caractères. L'alpha est sur invitation. |
| `accept_responsibility` | boolean | Doit valoir `true`. |
| `hcaptcha_token` | string ou null | Requis quand `HCAPTCHA_SECRET` est configuré. |

```json
{
  "email": "ada@example.com",
  "password": "lovelace-1843",
  "invitation_code": "ALPHA-7K2",
  "accept_responsibility": true,
  "hcaptcha_token": "10000000-aaaa-bbbb-cccc-000000000001"
}
```

### Réponse — `200 OK`

```json
{
  "ok": true,
  "user": {
    "id": 42,
    "email": "ada@example.com",
    "is_admin": false,
    "is_active": true,
    "email_verified": false,
    "created_at": "2026-05-27T09:14:00Z"
  }
}
```

Pose le cookie `outsend_session`.

### Erreurs spécifiques

| Code | Detail |
|------|--------|
| `400` | `Captcha invalide. Réessaie.` |
| `400` | `Code invitation invalide` |
| `400` | `Email existe déjà` |

---

## POST /api/auth/login

Valide les identifiants et ouvre une session. Sans auth. Limite : 5 / 15 min / IP et 5 / 15 min / email.

### Corps de requête

| Champ | Type | Notes |
|-------|------|-------|
| `email` | string (email) | Requis. |
| `password` | string | 1 à 128 caractères. |

```json
{ "email": "ada@example.com", "password": "lovelace-1843" }
```

### Réponse — `200 OK`

```json
{ "ok": true, "user": { "id": 42, "email": "ada@example.com", "is_admin": false, "is_active": true, "email_verified": true, "created_at": "2026-05-27T09:14:00Z" } }
```

Pose le cookie `outsend_session`.

### Erreurs spécifiques

| Code | Detail |
|------|--------|
| `401` | `Email ou mot de passe incorrect` |
| `401` | `Compte désactivé` |

---

## POST /api/auth/logout

Révoque la session courante et efface le cookie. Auth optionnelle. Corps vide. Réponse : `200 OK` `{ "ok": true }`.

---

## GET /api/auth/me

Renvoie l'utilisateur authentifié.

```json
{
  "id": 42,
  "email": "ada@example.com",
  "is_admin": false,
  "is_active": true,
  "email_verified": true,
  "created_at": "2026-05-27T09:14:00Z"
}
```

---

## POST /api/auth/password/reset-request

Envoie un lien de réinitialisation à l'email si (et seulement si) il correspond à un utilisateur actif. La réponse est identique dans tous les cas pour prévenir l'énumération de comptes. Sans auth. Limite : 3 / heure / IP et 3 / heure / email (silencieux quand épuisé).

### Corps de requête

```json
{ "email": "ada@example.com" }
```

### Réponse — `200 OK`

```json
{ "ok": true }
```

---

## POST /api/auth/password/reset-confirm

Consomme un jeton de réinitialisation à usage unique et fixe le nouveau mot de passe. Révoque toutes les sessions existantes de l'utilisateur. Sans auth (le jeton fait office d'identifiant).

### Corps de requête

| Champ | Type | Notes |
|-------|------|-------|
| `token` | string | 10 à 256 caractères, livré par email. |
| `new_password` | string | 8 à 128 caractères, lettre + chiffre/symbole. |

```json
{ "token": "eyJ...", "new_password": "babbage-1822" }
```

### Réponse — `200 OK`

```json
{ "ok": true }
```

### Erreurs spécifiques

| Code | Detail |
|------|--------|
| `400` | `Lien invalide ou expiré` |
| `422` | Complexité de mot de passe refusée par le validateur. |

---

## POST /api/auth/password/change

Renouvelle le mot de passe d'un utilisateur connecté. Requiert le mot de passe actuel, révoque les autres sessions, émet un cookie frais. Limite : 5 / heure / utilisateur.

### Corps de requête

| Champ | Type | Notes |
|-------|------|-------|
| `current_password` | string | 1 à 200 caractères. |
| `new_password` | string | 8 à 200 caractères, doit différer de l'actuel. |

```json
{ "current_password": "lovelace-1843", "new_password": "babbage-1822" }
```

### Réponse — `200 OK`

```json
{ "ok": true }
```

Pose un cookie `outsend_session` rafraîchi.

### Erreurs spécifiques

| Code | Detail |
|------|--------|
| `400` | `Mot de passe actuel incorrect` |
| `400` | `Le nouveau mot de passe doit être différent de l'actuel` |

---

## POST /api/auth/email/verify

Consomme un jeton de vérification à usage unique et bascule `email_verified` à `true`. Sans auth.

### Corps de requête

```json
{ "token": "eyJ..." }
```

### Réponse — `200 OK`

```json
{ "ok": true }
```

Erreur spécifique : `400 Lien de vérification invalide ou expiré`.

---

## POST /api/auth/email/resend-verify

Renvoie l'email de vérification à l'utilisateur authentifié. Idempotent si l'adresse est déjà vérifiée. Corps vide. Limite : 3 / heure / utilisateur.

### Réponse — `200 OK`

```json
{ "ok": true }
```

ou, si déjà vérifié :

```json
{ "ok": true, "already_verified": true }
```

---

## DELETE /api/auth/me

Supprime définitivement le compte et tous les enregistrements possédés (jobs, pipelines, surveillances, sessions, jetons). Les fichiers de jobs sur disque sont purgés après le delete DB en cascade. Les fils de feedback sont anonymisés plutôt que supprimés.

### Corps de requête

| Champ | Type | Notes |
|-------|------|-------|
| `confirm_email` | string | Doit égaler l'email de l'utilisateur (insensible à la casse). |

```json
{ "confirm_email": "ada@example.com" }
```

### Réponse — `204 No Content`

Corps vide. Efface le cookie `outsend_session`.

Erreur spécifique : `400 Confirmation email incorrecte`.

---

## GET /api/auth/me/export

Endpoint de portabilité RGPD. Diffuse une archive ZIP contenant tous les enregistrements possédés par l'utilisateur.

### Réponse — `200 OK`

`Content-Type: application/zip`
`Content-Disposition: attachment; filename="outsend-export-<local>-<YYYY-MM-DD>.zip"`

Contenu de l'archive :

| Entrée | Contenu |
|--------|---------|
| `account.json` | Métadonnées du compte, sans secrets. |
| `jobs.json` | Tous les jobs avec métadonnées. |
| `jobs/<job_id>/*` | Sorties CSV/JSON pour chaque job `done`. |
| `pipelines.json` | Définitions de pipelines. |
| `veille.json` | `recurring_scraps` + historique des runs. |
| `manifest.txt` | Résumé lisible. |


<!-- doc: api/feedback -->

---
title: API Feedback
slug: api/feedback
section: API
summary: Chat in-app avec l'admin de la plateforme et point d'entrée pour les demandes d'activation de modules on-demand.
---

# API Feedback

L'API Feedback alimente le chat in-app entre un utilisateur authentifié et l'admin de la plateforme. Elle sert aussi de point d'entrée pour les demandes d'activation de modules on-demand : cliquer "Demander" sur un module stub (email, SMS, WhatsApp, opérateur téléphonique) ouvre un fil de feedback avec un `topic` dédié, qui apparaît dans l'inbox "On demand" du dashboard admin.

Un fil est une conversation stable épinglée à un `topic`. Chaque réponse est une ligne `feedback_message` rattachée à ce fil. L'état de lecture est tracké par rôle (user, admin) afin que chaque côté ne voie que son propre badge non-lu.

Tous les endpoints requièrent un appelant authentifié. Erreurs génériques : `401` (non authentifié), `404` (fil inexistant). Les causes spécifiques sont en ligne.

## Conventions de topic

Le champ `topic` d'un fil est une chaîne libre plafonnée à 64 caractères, mais le produit suit un petit jeu de conventions :

| Valeur de topic          | Signification                                    |
| ------------------------ | ------------------------------------------------ |
| `general`                | Défaut. Chat fourre-tout.                        |
| `feedback`               | Feedback produit générique.                      |
| `bug`                    | Rapport de bug.                                  |
| `feature`                | Demande de fonctionnalité.                       |
| `on_demand_email`        | Demande d'activation du stub campagne email.     |
| `on_demand_sms`          | Demande d'activation du stub campagne SMS.       |
| `on_demand_whatsapp`     | Demande d'activation du stub WhatsApp.           |
| `on_demand_phone_carrier`| Demande d'activation du stub opérateur tél.      |

Tout `topic` correspondant à `on_demand_*` est capté par l'endpoint admin `GET /api/admin/feedback/on-demand`, qui groupe les fils par topic et expose les compteurs ouverts. Les stubs on-demand sont listés dans le registre des modules sous `on_demand` ; un client peut lire le registre et construire `topic = "on_demand_" + slug`.

Le champ plus court `type` (`bug`, `feature`, `other`) est indépendant du topic et ne porte que l'intention grossière pour le tri.

---

## POST /api/feedback/threads

Crée un nouveau fil avec son premier message. Limite : 20 fils par utilisateur par heure.

| Champ          | Type     | Notes                                             |
| -------------- | -------- | ------------------------------------------------- |
| `type`         | string   | `bug`, `feature` ou `other`. Défaut `other`.      |
| `message`      | string   | 3 à 5000 caractères. Corps du premier message.    |
| `topic`        | string   | Optionnel. Défaut `general`. Max 64 caractères.   |

### Requête

```json
POST /api/feedback/threads
{
  "type": "feature",
  "topic": "on_demand_whatsapp",
  "message": "L'envoi de relances WhatsApp sur les leads scrapés serait utile."
}
```

### Réponse — 201 Created

```json
{
  "id": 142,
  "user_id": 7,
  "user_email": "user@example.com",
  "type": "feature",
  "status": "open",
  "created_at": "2026-05-27 10:11:12",
  "last_read_user": "2026-05-27 10:11:12",
  "last_read_admin": null,
  "messages": [
    {
      "id": 991,
      "author_role": "user",
      "author_user_id": 7,
      "message": "L'envoi de relances WhatsApp sur les leads scrapés serait utile.",
      "created_at": "2026-05-27 10:11:12"
    }
  ],
  "preview": "L'envoi de relances WhatsApp sur les leads scrapés serait utile.",
  "last_message_at": "2026-05-27 10:11:12",
  "unread_for_me": 0
}
```

Causes spécifiques : `400` `type` hors de `{bug, feature, other}` ; `422` `message` plus court que 3 ou plus long que 5000 ; `429` plus de 20 fils dans la dernière heure.

---

## POST /api/feedback/threads/{thread_id}/messages

Ajoute une réponse à un fil existant. L'appelant doit posséder le fil, et le fil ne doit pas être `closed`. Poster un message marque aussi le fil comme lu côté user.

### Requête

```json
POST /api/feedback/threads/142/messages
{
  "message": "Pour contexte : le tracking d'opt-out serait aussi nécessaire."
}
```

### Réponse — 201 Created

Renvoie le fil sérialisé complet, identique en forme à la réponse de `POST /threads`, avec le message ajouté inclus.

Causes spécifiques : `400` fil `closed` ; `403` appelant ne possède pas le fil ; `422` message vide ou plus long que 5000.

---

## GET /api/feedback/threads

Liste les fils de l'appelant, les plus récents d'abord. Plafonné à 100 lignes. Chaque entrée embarque la liste complète des messages pour rendre previews et compteurs non-lus sans second aller-retour.

### Réponse — 200 OK

```json
[
  {
    "id": 142,
    "user_id": 7,
    "user_email": "user@example.com",
    "type": "feature",
    "status": "open",
    "created_at": "2026-05-27 10:11:12",
    "last_read_user": "2026-05-27 10:11:12",
    "last_read_admin": null,
    "messages": [ /* ... */ ],
    "preview": "L'envoi de relances WhatsApp...",
    "last_message_at": "2026-05-27 10:11:12",
    "unread_for_me": 0
  }
]
```

Le compteur `unread_for_me` reflète les réponses admin pas encore vues, calculé à partir de `last_read_user`. L'endpoint compagnon `GET /api/feedback/unread` retourne le même nombre agrégé sur tous les fils, prêt à être lié à un badge d'en-tête.


<!-- doc: api/jobs -->

---
title: API Jobs
slug: api/jobs
section: API
summary: Surface unifiée pour toutes les charges exécutées par Outsend — acquisition de sources, enrichissement, vérification, reporting.
---

# API Jobs

L'API Jobs est la surface unifiée pour toutes les charges qu'Outsend exécute pour un tenant : acquisition de sources (`scrap`) et les modules d'enrichissement, vérification et reporting qui opèrent sur les items résultants. Un job est la seule unité facturable.

Voir aussi :

- [Cycle de vie des jobs](/docs/fr/concepts/jobs-lifecycle) — pending → running → done | failed | cancelled | expired
- [États et événements](/docs/fr/concepts/states-and-events) — référence des payloads SSE
- [Limites](/docs/fr/concepts/limits) — quota EF, plafonds par job, rétention

Tous les endpoints requièrent un cookie de session authentifié. Les endpoints qui créent ou mutent des jobs requièrent en plus un utilisateur actif ; `POST /api/jobs` et `POST /api/jobs/resume` exigent aussi un email vérifié. Les routes admin (`/api/admin/*`, `/api/jobs/queue`) ne sont pas documentées ici.

## Conventions

| Élément | Valeur |
|---|---|
| URL de base | `https://outsend.xyz` |
| Auth | Cookie de session (`outsend_session`) |
| Content-Type | `application/json` pour les corps POST |
| Identifiant de job | Chaîne opaque (`job.id`), stable durant la vie du job |
| Horodatages | ISO 8601 UTC |

### L'objet `JobPublic`

Tout endpoint qui retourne un job retourne la même forme :

```json
{
  "id": "j_01HXYZ...",
  "job_type": "scrap",
  "queries": ["dentiste"],
  "zones": ["Paris", "75015"],
  "include_reviews": false,
  "status": "running",
  "grid_points_count": 412,
  "processed_points": 87,
  "results_count": 64,
  "error_count": 0,
  "ef_cost": 0.041,
  "created_at": "2026-05-27T09:12:03Z",
  "started_at": "2026-05-27T09:12:05Z",
  "completed_at": null,
  "expires_at": "2026-06-26T09:12:03Z",
  "error_message": null,
  "output_filename": null,
  "download_available": false,
  "source_job_id": null,
  "email_mode": null,
  "breakdown": { "by_query": {"dentiste": 64}, "by_zone": {"Paris": 64} },
  "dead_queries": [],
  "flagged_tiles_count": 0,
  "total_attempts_count": 87,
  "query_stats": { "dentiste": { "tiles": 87, "with_results": 71 } }
}
```

`status` prend l'une des valeurs `pending | running | done | failed | cancelled | expired`.

### Erreurs

Tous les endpoints renvoient `{"detail": "..."}` (ou `{"detail": {"message": ..., "errors": [...]}}` pour les erreurs de validation). Codes génériques : `401` non authentifié, `403` non autorisé (autre tenant ou email non vérifié), `404` non trouvé, `422` validation Pydantic. Les causes spécifiques sont listées en ligne.

---

## Créer un job (générique)

```
POST /api/jobs
```

Crée un job `scrap` — la charge canonique d'acquisition qui exécute des requêtes sur une grille géographique. Pour toute autre charge, utiliser le raccourci typé décrit plus bas ; passer un champ `type` à `POST /api/jobs` n'est **pas** supporté.

**Corps de requête**

```json
{
  "queries": ["dentiste", "orthodontiste"],
  "zones": ["Paris", "75015", "Lyon 2e"],
  "include_reviews": false
}
```

| Champ | Type | Notes |
|---|---|---|
| `queries` | `string[]` (1..20) | Chaque item ≤ 200 caractères, trimé, dédupliqué |
| `zones` | `string[]` (1..50) | Noms de villes, codes postaux ou arrondissements ; résolus côté serveur |
| `include_reviews` | `boolean` | Si `true`, récupère les derniers avis par POI (augmente le coût EF) |

**Réponse** — `200 OK`, un `JobPublic` en statut `pending`.

Causes spécifiques : `400` parsing de zone échoué / quota EF dépassé / grille vide ; `403` email non vérifié.

---

## Créer un job (raccourci typé)

Chaque module d'enrichissement, vérification et reporting a un endpoint dédié qui accepte les items sur lesquels il opère. Chaque raccourci renvoie un `JobPublic` dont le `job_type` est fixé au slug du module.

```
POST /api/jobs/{type}
```

| `type` | Rôle | Doc module |
|---|---|---|
| `reviews` | Récupérer les derniers avis par POI | [reviews](/docs/fr/modules/reviews) |
| `emails` | Découvrir les emails de contact depuis chaque site | [emails](/docs/fr/modules/emails) |
| `verify-emails` | Vérification anti-bounce (sans VPN) | [verify-emails](/docs/fr/modules/verify-emails) |
| `socials` | Détecter les profils sociaux liés | [socials](/docs/fr/modules/socials) |
| `phones-extra` | Trouver des numéros au-delà du listing Maps | [phones-extra](/docs/fr/modules/phones-extra) |
| `legal-ids` | Extraire SIRET / SIREN depuis le site | [legal-ids](/docs/fr/modules/legal-ids) |
| `legal-mentions` | Parser la page mentions légales (capital, RCS, …) | [legal-mentions](/docs/fr/modules/legal-mentions) |
| `legal-data` | Enrichir via SIRENE / INPI (`api.gouv.fr`) | [legal-data](/docs/fr/modules/legal-data) |
| `pricing` | Extraire les tarifs SaaS / B2B | [pricing](/docs/fr/modules/pricing) |
| `techstack` | Détecter CMS, frameworks, analytics, paiement, CRM | [techstack](/docs/fr/modules/techstack) |
| `pagespeed` | Score via Google PSI API v5 | [pagespeed](/docs/fr/modules/pagespeed) |
| `ads-intelligence` | Profilage marketing/ads (pixels, CMP, retargeting) | [ads-intelligence](/docs/fr/modules/ads-intelligence) |
| `brand-assets` | Logo, favicon, palette, screenshot optionnel | [brand-assets](/docs/fr/modules/brand-assets) |
| `dead-check` | Marquer les sites morts (DNS, parking, default-server, SSL) | [dead-check](/docs/fr/modules/dead-check) |
| `delivery-check` | Test de placement Gmail Inbox / Promotions / Spam | [delivery-check](/docs/fr/modules/delivery-check) |

**Corps de requête (forme partagée par tous les modules par item)**

```json
{
  "items": [
    { "nom": "Cabinet Dupont", "site_web": "https://dupont-dentiste.fr", "ville": "Paris" }
  ],
  "source_job_id": "j_01HXYZ..."
}
```

| Champ | Type | Notes |
|---|---|---|
| `items` | `dict[]` (1..10 000) | Clés spécifiques au module ; généralement un sous-ensemble du CSV d'un job précédent |
| `source_job_id` | `string?` | Chaîne le nouveau job à un précédent, utilisé pour traçabilité et affichage facturation |

**Surcharges spécifiques aux modules**

- `POST /api/jobs/emails` — accepte `mode: "normal" | "deep"` (défaut `normal`).
- `POST /api/jobs/brand-assets` — accepte `capture_screenshot: boolean` (défaut `false`, ~5× plus lent par item quand activé).
- `POST /api/jobs/delivery-check` — ne prend **pas** `items`. Corps :

  ```json
  { "domain": "example.com", "subject_filter": "outsend" }
  ```

**Réponse** — `200 OK`, un `JobPublic` en statut `pending`. Cause additionnelle : `422` si `items` est vide, trop grand ou si des clés requises par le module manquent.

---

## Lister les jobs

```
GET /api/jobs?limit={n}&offset={n}
```

Renvoie les jobs de l'utilisateur authentifié, les plus récents d'abord.

| Param | Type | Défaut | Plage |
|---|---|---|---|
| `limit` | `int` | `100` | borné à `[1, 500]` |
| `offset` | `int` | `0` | `≥ 0` |

**Réponse** — `200 OK`, `JobPublic[]`.

---

## Récupérer un job

```
GET /api/jobs/{id}
```

**Réponse** — `200 OK`, un seul `JobPublic`. Inclut des compteurs live (`processed_points`, `results_count`, `query_stats`, `breakdown`) que le tableau de bord interroge entre les événements SSE.

---

## Suivre la progression en direct (SSE)

```
GET /api/jobs/{id}/stream?since={log_id}
```

Flux Server-Sent Events qui émet les transitions de statut, lignes de log et mises à jour de compteurs au fur et à mesure de l'avancement. Les reconnexions honorent automatiquement `Last-Event-ID` ; le paramètre `since` est un fallback pour clients qui ne parlent pas SSE nativement. La taxonomie d'événements (`status`, `log`, `progress`, `done`, `error`) et les payloads sont documentés dans [États et événements](/docs/fr/concepts/states-and-events).

**En-têtes renvoyés**

```
Content-Type: text/event-stream
Cache-Control: no-cache
X-Accel-Buffering: no
```

---

## Lister les items d'un job

```
GET /api/jobs/{id}/items?offset={n}&limit={n}
```

Renvoie les lignes du CSV de sortie en JSON, pour chaînage vers un job d'enrichissement. Disponible uniquement pour les jobs dont `status == "done"` et dont le `job_type` produit un CSV réutilisable (c.-à-d. ni `delivery_check` ni `viewport_test`).

**Réponse** — `200 OK`

```json
{
  "count": 412,
  "items": [
    { "nom": "Cabinet Dupont", "site_web": "https://...", "telephone": "+33 1 ...", "...": "..." }
  ]
}
```

Causes spécifiques : `400` job non terminé ou job_type sans sortie réutilisable ; `410` CSV expiré ou supprimé.

---

## Télécharger le résultat d'un job

```
GET /api/jobs/{id}/download?format=csv|json|xlsx
```

Télécharge la sortie du job. Le CSV est l'artefact canonique écrit par le worker (UTF-8 BOM, séparateur `;`) ; JSON et XLSX sont dérivés à la volée. Tous les exports passent par un sanitiseur d'injection de formules tableur.

| `format` | Media type | Nom de fichier |
|---|---|---|
| `csv` (défaut) | `text/csv; charset=utf-8` | `{job.output_filename}` |
| `json` | `application/json; charset=utf-8` | `{base}.json` |
| `xlsx` | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` | `{base}.xlsx` |

Causes spécifiques : `400` job encore pending/running ou `format` non supporté ; `410` sortie expirée, manquante, ou job échoué avant la première ligne.

---

## Arrêter un job

```
POST /api/jobs/{id}/cancel
```

Arrête un job `pending` ou `running`. Les résultats déjà extraits sont **conservés** (téléchargeables en CSV partiel et réutilisables). Renvoie `400` si le job est déjà terminal.

Si le job appartient à un pipeline, l'arrêt **met la pipeline en pause** sur cette étape — les étapes suivantes ne sont **pas** lancées automatiquement (idem en cas de crash). Pour poursuivre la chaîne avec les résultats partiels, l'utilisateur déclenche explicitement [`POST /api/pipelines/{id}/nodes/{node_id}/continue`](./pipelines.md) (bouton « Continuer avec les résultats »). Pour arrêter au contraire la pipeline entière, utiliser [`POST /api/pipelines/{id}/cancel`](./pipelines.md).

**Réponse** — `200 OK`, `{"ok": true}`.

---

## Reprendre un job

```
POST /api/jobs/{id}/resume
```

Crée un **nouveau** job qui reprend un `scrap` `cancelled` ou `failed` là où il s'est arrêté. Le nouveau job hérite des queries, zones et CSV partiel de la source ; le worker saute les coordonnées déjà traitées. EF est débité uniquement pour les points restants.

**Réponse** — `200 OK`, un nouveau `JobPublic` (le job de reprise) en statut `pending`. Son `source_job_id` référence l'original.

Causes spécifiques : `400` job source non reprisable (mauvais type, non interrompu, ou déjà entièrement traité) ; `403` email non vérifié.

---

## Supprimer un job

```
DELETE /api/jobs/{id}
```

Supprime définitivement le job et son CSV. Refuse de supprimer un job encore en cours — il faut l'arrêter d'abord.

**Réponse** — `204 No Content`. Cause spécifique : `400` job encore en cours.

---

## Estimer le coût EF

```
POST /api/estimate
```

Calcule le coût EF d'un job `scrap` hypothétique sans le créer. Alimente le compteur de coût live du formulaire de lancement. L'estimation est gratuite et non comptée.

**Corps de requête** — même forme que `POST /api/jobs`, mais `queries` et `zones` peuvent être vides (renvoie `valid: false`).

**Réponse** — `200 OK`, un `JobEstimateResponse` :

```json
{
  "valid": true,
  "grid_points": 412,
  "total_requests": 824,
  "queries_count": 2,
  "ef_cost": 0.041,
  "estimated_duration_seconds": 1380,
  "errors": [],
  "warnings": []
}
```

| Champ | Signification |
|---|---|
| `valid` | `true` ssi `errors` est vide |
| `grid_points` | Tuiles GPS distinctes sur l'union des zones |
| `total_requests` | `grid_points × len(queries)` — ce que le worker appellera réellement |
| `queries_count` | Reflète `len(queries)` pour l'affichage UI |
| `ef_cost` | Unités équivalent France ; voir [Limites](/docs/fr/concepts/limits) |
| `estimated_duration_seconds` | Estimation au mieux du temps horloge |
| `errors` | Bloqueurs durs (hors-quota, zones impossibles à parser, grille vide) |
| `warnings` | Signaux doux (non utilisés actuellement) |

---

## Notes sur les endpoints omis

Les routes suivantes existent mais ne font pas partie de la surface publique :

- `GET /api/jobs/queue` — file globale anonymisée pour le widget public. Sans tenant, périmètre séparé.
- `/api/admin/*` — réservé opérateur.
- `GET /api/jobs/{id}/breakdown`, `GET /api/jobs/{id}/map`, `GET /api/jobs/{id}/output-columns`, `GET /api/jobs/{id}/delivery-result`, `POST /api/jobs/parse-list`, `GET /api/brand-lookup`, `GET /api/brand-assets/{owner}/{filename}`, `GET /api/delivery-check/seeds` — helpers internes UI susceptibles de changer sans préavis.


<!-- doc: api/overview -->

---
title: Vue d'ensemble API
slug: api/overview
section: API
summary: Conventions partagées par tous les endpoints de l'API Outsend — URL de base, authentification, types de contenu, versioning, erreurs.
---

# Vue d'ensemble API

L'API Outsend expose la même surface que l'application web. Le tableau de bord et l'API partagent un backend, un schéma d'authentification et un ensemble d'objets uniques.

## URL de base

```
https://outsend.xyz
```

Les endpoints sous `/api/` renvoient du JSON ou diffusent des événements. L'URL de base est stable durant l'alpha.

## Authentification

Les sessions utilisent un cookie nommé `outsend_session`. Pour l'obtenir, envoyer les identifiants :

```
POST /api/auth/login
Content-Type: application/json

{ "email": "nom@example.com", "password": "..." }
```

La réponse pose `outsend_session` en `HttpOnly`, `Secure`, `SameSite=Lax`. Les requêtes suivantes doivent l'inclure. Les sessions restent valides jusqu'à la déconnexion (`POST /api/auth/logout`) ou expiration. Les requêtes sans cookie valide reçoivent `401` sur les routes protégées.

Des jetons API scopés par workspace sont prévus à la feuille de route ; les sessions par cookie sont actuellement le seul mécanisme supporté.

## Types de contenu

| Surface | Type de contenu | Notes |
|---|---|---|
| Endpoints lecture/écriture | `application/json` | UTF-8, champs en snake_case |
| Flux d'événements | `text/event-stream` | Server-Sent Events |
| Téléchargements | `application/octet-stream` et apparentés | Endpoints terminant par `/download` |
| Exports tabulaires | `text/csv`, `application/json`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` | Sélectionné via `?format=csv|json|xlsx` |

Les endpoints acceptant `format` retournent du JSON par défaut.

## Versioning

L'API est en alpha. Aucun préfixe `/v1/`, aucun header de version — la surface évolue sur place. Les ruptures sont annoncées à l'avance via le changelog et, le cas échéant, par bannières in-app. Les ajouts (nouveaux champs, endpoints, paramètres optionnels) sont livrés sans préavis. Un préfixe versionné sera introduit avant la disponibilité générale.

## Limites de débit

Les endpoints sensibles (authentification, contact, création de jobs) sont protégés par des quotas par route. Le dépassement renvoie `429` avec un en-tête `Retry-After`. Voir [/docs/fr/concepts/limits](/docs/fr/concepts/limits).

## Erreurs

Les échecs renvoient un corps JSON et un code HTTP conventionnel :

```json
{
  "detail": "Message lisible",
  "errors": [
    { "field": "email", "message": "Format invalide" }
  ]
}
```

Le tableau `errors` n'est présent que lorsque l'échec concerne des champs spécifiques.

| Code | Signification |
|---|---|
| 400 | Requête malformée, violation de règle métier |
| 401 | Pas de session, ou session expirée |
| 403 | Authentifié mais non autorisé ; également pour comptes désactivés |
| 404 | Ressource inexistante, ou non visible par l'appelant |
| 422 | Requête bien formée mais échec de validation |
| 429 | Limite de débit atteinte ; réessayer après la valeur du header |
| 5xx | Défaillance côté serveur ; les retries avec backoff sont sûrs |

Considérer tout 5xx comme transitoire et appliquer un backoff exponentiel.

## Groupes d'endpoints

| Groupe | Chemin | Rôle |
|---|---|---|
| Authentification | [/docs/fr/api/auth](/docs/fr/api/auth) | Login, logout, inscription, reset mot de passe, vérification email |
| Jobs | [/docs/fr/api/jobs](/docs/fr/api/jobs) | Créer, lister, inspecter, contrôler et exporter des jobs |
| Pipelines | [/docs/fr/api/pipelines](/docs/fr/api/pipelines) | Composer des workflows multi-étapes et les exécuter |
| Veille | [/docs/fr/api/veille](/docs/fr/api/veille) | Monitoring continu de requêtes et de sources |
| Feedback | [/docs/fr/api/feedback](/docs/fr/api/feedback) | Soumettre du feedback produit et des rapports de bug |
| Registre | [/docs/fr/api/registry](/docs/fr/api/registry) | Découvrir les types de jobs disponibles et leurs paramètres |

## Protocole SSE

Les opérations longues exposent leur progression via Server-Sent Events. Noms d'événements, forme de payload et machine à états sont documentés sur [/docs/fr/concepts/states-and-events](/docs/fr/concepts/states-and-events).


<!-- doc: api/pipelines -->

---
title: API Pipelines
slug: api/pipelines
section: API
summary: Composer et exécuter des DAG d'étapes de scraping, enrichissement et transformation sous /api/pipelines.
---

# API Pipelines

Un pipeline est un graphe orienté acyclique (DAG) de nodes qui enchaîne des étapes de scraping, enrichissement et transformation. Soumettre un pipeline lance les jobs racines de façon synchrone ; les jobs en aval sont engendrés à mesure que chaque prédécesseur atteint `done`.

Tous les endpoints sont sous `/api/pipelines` et requièrent une session authentifiée. Les routes mutantes requièrent en plus un compte actif (non suspendu). Erreurs génériques : `401` pas de session, `403` non propriétaire / compte suspendu, `404` pipeline ou node inconnu — les causes spécifiques sont listées en ligne.

Voir aussi : [Orchestration de pipelines](/docs/fr/concepts/pipeline-orchestration) et [Module filter](/docs/fr/modules/filter).

## Forme du graphe

Le document `definition` décrit le DAG. Les edges sont explicites et référencent des ids de node ; ils ne sont pas inférés d'un champ `inputs` par node.

```json
{
  "nodes": [
    {"id": "n1", "type": "scrap",  "config": {"queries": ["dentist"], "zones": ["Paris"]}, "x": 100, "y": 100},
    {"id": "n2", "type": "emails", "config": {"mode": "normal"}, "x": 320, "y": 100},
    {"id": "n3", "type": "verify", "config": {}, "x": 540, "y": 100}
  ],
  "edges": [
    {"id": "e1", "from": "n1", "to": "n2"},
    {"id": "e2", "from": "n2", "to": "n3"}
  ]
}
```

### Types de node

| Type              | Rôle                                     | Accepte (entrée)  | Produit (sortie)  |
|-------------------|------------------------------------------|-------------------|-------------------|
| `scrap`           | Scrape Google Maps (racine)              | aucune            | `pois`            |
| `import`          | Import CSV/Sheets (racine)               | aucune            | `pois`            |
| `reviews`         | Récupérer les avis des POIs              | `pois_any`        | `reviews`         |
| `emails`          | Découvrir les emails depuis les sites    | `pois_any`        | `pois_email`      |
| `verify`          | Vérification SMTP des emails             | `pois_email`      | `verified`        |
| `socials`         | Découvrir les profils sociaux            | `pois_any`        | `pois`            |
| `dead_check`      | Détecter les POIs inactifs               | `pois_any`        | `pois`            |
| `techstack`       | Détecter la pile tech du site            | `pois_any`        | `pois`            |
| `ads_intelligence`| Détecter les campagnes publicitaires     | `pois_any`        | `pois`            |
| `brand_assets`    | Extraire logo et assets de marque        | `pois_any`        | `pois`            |
| `filter`          | Appliquer un filtre à base de règles     | `any_pois`        | passthrough       |
| `sort`            | Réordonner les lignes par colonne        | `any_pois`        | passthrough       |

`filter` et `sort` préservent le type amont ; la compatibilité de types est résolue en remontant jusqu'au premier ancêtre non-passthrough.

### Règles de validation

Le serveur rejette une définition avec HTTP 400 si l'une des conditions suivantes est vraie :

| Règle                                           | Message d'erreur                                |
|-------------------------------------------------|-------------------------------------------------|
| Liste `nodes` vide                              | `Pipeline vide`                                 |
| Plus de 20 nodes                                | `Trop de nodes (max 20)`                        |
| Id de node en doublon                           | `IDs de nodes en doublon`                       |
| `type` inconnu                                  | `Type de node inconnu : ...`                    |
| Extrémité d'edge référence un node manquant     | `Edge référence un node inexistant`             |
| Boucle (`from == to`)                           | `Edge vers soi-même interdit`                   |
| Type racine branché comme successeur            | `Le node '...' ne peut pas avoir de prédécesseur` |
| Sortie incompatible avec entrée                 | `Connexion X → Y incompatible`                  |
| Node avec plusieurs prédécesseurs (limite MVP)  | `Le node ... a plusieurs prédécesseurs`         |

Les racines doivent être `scrap` ou `import`. Le fan-out (un node alimentant plusieurs successeurs) est autorisé ; le fan-in ne l'est pas.

---

## POST /api/pipelines

Crée un pipeline et lance ses jobs racines.

**Corps de requête**

```json
{
  "name": "Dentistes Paris",
  "definition": { "nodes": [...], "edges": [...] }
}
```

`name` est optionnel (≤ 120 caractères, défaut `"Pipeline"`).

**Réponse 201**

```json
{
  "id": "f1a2…-uuid",
  "status": "running",
  "initial_jobs": ["job_abc", "job_def"]
}
```

Cause spécifique : `400` la définition échoue à une règle de validation, ou la création du job racine échoue. En cas d'échec racine, le pipeline est persisté avec `status = failed`.

---

## GET /api/pipelines

Liste les pipelines de l'appelant (plus récents d'abord, plafonné à 50).

**Réponse 200**

```json
[
  {
    "id": "f1a2…",
    "name": "Dentistes Paris",
    "status": "running",
    "created_at": "2026-05-27 10:14:02",
    "completed_at": null,
    "nodes_count": 3
  }
]
```

`status` prend l'une des valeurs `pending | running | done | failed | cancelled`. `nodes_count` est dérivé de la définition stockée.

---

## GET /api/pipelines/{id}

Retourne un pipeline avec sa définition et les jobs engendrés jusqu'ici.

**Réponse 200**

```json
{
  "id": "f1a2…",
  "user_id": 42,
  "name": "Dentistes Paris",
  "definition": { "nodes": [...], "edges": [...] },
  "status": "running",
  "created_at": "2026-05-27 10:14:02",
  "completed_at": null,
  "progress_pct": 42,
  "jobs": [
    {
      "id": "job_abc",
      "job_type": "scrap",
      "status": "done",
      "pipeline_node_id": "n1",
      "results_count": 187,
      "error_message": null,
      "created_at": "2026-05-27 10:14:02",
      "completed_at": "2026-05-27 10:18:55"
    }
  ],
  "output_job": {
    "id": "job_xyz",
    "job_type": "verify_emails",
    "results_count": 142,
    "status": "done",
    "download_available": true
  }
}
```

`output_job` est le **jeu de données final** du pipeline — la sortie de l'étape la plus en aval ayant réellement produit des lignes (un pipeline filtre/réduit, il n'additionne pas ; `output_job.results_count` correspond donc au compteur affiché, pas à la somme des étapes). On le télécharge via [`GET /api/jobs/{id}/download`](jobs.md#get-apijobsiddownload) avec `output_job.id`, en `csv` / `xlsx` / `json`. Il vaut `null` tant que le pipeline n'a rien produit de téléchargeable, et `download_available` indique si un CSV (final **ou** partiel — donc valable aussi pour un pipeline en cours/arrêté) est encore présent sur disque et non expiré.

---

## PATCH /api/pipelines/{id}

Non implémenté. L'API actuelle n'expose pas de mutation du graphe après création ; cloner le pipeline en relançant `POST /api/pipelines` avec une définition mise à jour. Retourne `405 Method Not Allowed`.

---

## DELETE /api/pipelines/{id}

Non implémenté. Les pipelines sont immuables une fois créés ; la suppression sera ajoutée lorsque la politique de rétention sera définie. Retourne `405 Method Not Allowed`.

---

## POST /api/pipelines/{id}/cancel

Arrête le pipeline **entier** : l'étape en cours est stoppée et les étapes restantes ne sont **pas** lancées. Les résultats partiels déjà extraits restent téléchargeables sur chaque job concerné. À distinguer de l'arrêt d'une seule étape (`POST /api/jobs/{id}/cancel`), qui met simplement la pipeline en pause sur cette étape.

Le pipeline passe en statut `cancelled`. Renvoie `400` si le pipeline est déjà terminal (`done`, `failed`, `cancelled`).

**Réponse** — `200 OK`, `{"ok": true}`.

---

## POST /api/pipelines/{id}/nodes/{node_id}/continue

« Continuer avec les résultats ». Quand une étape de scraping a été **arrêtée** (assez de résultats) ou a **crashé**, la pipeline se met en pause sur cette étape (les suivantes ne démarrent pas automatiquement). Cet endpoint relance la chaîne à partir de cette étape en consommant ses **résultats partiels** : il crée le(s) job(s) de l'étape suivante.

Conditions : le dernier job du node est `cancelled` ou `failed`, et la pipeline n'est pas terminale. Si l'étape n'a produit aucune ligne, la branche est court-circuitée (pas de successeur créé). Renvoie `400` si l'étape n'est pas dans un état poursuivable.

**Réponse** — `200 OK`, `{"ok": true}`.

---

## POST /api/pipelines/{id}/run

Non implémenté. Les pipelines démarrent automatiquement à la création via `POST /api/pipelines` ; aucun endpoint de run séparé. Pour ré-exécuter un graphe, le re-poster comme nouveau pipeline.

---

## GET /api/pipelines/{id}/nodes/{node_id}/input-columns

Inspecte le schéma du CSV qui alimentera un node donné. Utile pour construire des UIs de filtre.

**Comportement.** L'endpoint localise le job prédécesseur le plus récent du node. Si le prédécesseur n'est pas encore `done`, la réponse porte une liste `columns` vide et un code `reason`. Sinon le CSV de sortie est lu (jusqu'à 5000 lignes) et chaque colonne est profilée pour type, taux de remplissage et exemples.

**Réponse 200 — prédécesseur terminé**

```json
{
  "columns": [
    {
      "name": "telephone",
      "type": "phone",
      "fill_rate": 0.92,
      "sample_values": ["+33 1 23 45 67 89", "0612345678"],
      "distinct_count": null
    },
    {
      "name": "categorie",
      "type": "category",
      "fill_rate": 1.0,
      "sample_values": ["dentiste", "orthodontiste"],
      "distinct_count": 4,
      "distinct_values": ["dentiste", "endodontiste", "orthodontiste", "stomatologue"]
    }
  ],
  "row_count": 187,
  "predecessor_job_id": "job_abc"
}
```

`type` prend l'une des valeurs `phone | email | url | number | category | text`. Une colonne est étiquetée `category` uniquement si elle a entre 1 et 200 valeurs non vides distinctes ; sinon elle retombe à `text`. Un verdict typé requiert ≥ 80% des valeurs non vides correspondant au pattern.

**Réponse 200 — pas d'entrée utilisable**

```json
{ "columns": [], "reason": "no_predecessor" }
```

| `reason`          | Signification                                            |
|-------------------|----------------------------------------------------------|
| `no_predecessor`  | Le node est une racine, ou n'a pas encore d'edge entrant.|
| `no_data_yet`     | Le job prédécesseur existe mais n'est pas `done`.        |
| `no_csv_found`    | Le prédécesseur a fini mais aucun CSV n'est sur disque.  |
| `csv_read_error`  | Le fichier CSV n'a pas pu être parsé.                    |

---

## POST /api/pipelines/{id}/nodes/{node_id}/filter-preview

Applique un jeu de règles de filtre en mémoire contre le CSV amont et renvoie le nombre de correspondances plus un petit échantillon. Aucun job n'est créé ; aucun état n'est muté.

Le node cible doit être de type `filter`. Le corps utilise la même forme `rules` que les nodes `filter` persistent dans leur `config.rules` ; les previews sont calculés par la même fonction que le worker utilise à l'exécution, donc le compte fait autorité pour les données inspectées.

**Corps de requête**

```json
{
  "rules": {
    "logic": "AND",
    "conditions": [
      {"column": "fill_rate", "op": ">=", "value": 0.5},
      {"column": "categorie", "op": "in", "value": ["dentiste", "orthodontiste"]}
    ]
  }
}
```

La grammaire exacte des règles est définie par le module filter (voir [Module filter](/docs/fr/modules/filter)).

**Réponse 200**

```json
{
  "total": 187,
  "matched": 73,
  "samples": [
    {"nom": "Cabinet Dupont", "telephone": "0123456789", "categorie": "dentiste"}
  ],
  "predecessor_job_id": "job_abc",
  "fieldnames": ["nom", "telephone", "categorie", "site_web"],
  "capped": false
}
```

`samples` contient jusqu'à 5 lignes correspondantes avec les champs vides retirés. `capped` vaut `true` quand le CSV amont a dépassé la limite preview de 5000 lignes — dans ce cas `total` ne reflète que la fenêtre inspectée, mais le ratio `matched/total` reste représentatif.

Quand le prédécesseur n'est pas prêt, la réponse est la même squelette `{total, matched, samples, reason}` avec tous les compteurs à `0`. Les codes `reason` possibles miroitent l'endpoint input-columns : `no_predecessor`, `no_data_yet`, `no_csv_found`.

Causes spécifiques : `400` node cible n'est pas de type `filter`, ou application de règle a levé une erreur ; `500` CSV non lisible.

---

## Résumé du cycle de vie

1. `POST /api/pipelines` valide le graphe, persiste le pipeline en `running`, et engendre un job par node racine.
2. Quand un job se termine **normalement** (`done`), le worker lit son CSV, transforme les lignes pour le type d'entrée du successeur et crée le job suivant. Une sortie vide court-circuite la branche.
3. Quand un job est **arrêté** (`cancelled`) ou **crashe** (`failed`), la pipeline se met **en pause** sur cette étape : aucune suite automatique. L'utilisateur reprend explicitement via [`POST /api/pipelines/{id}/nodes/{node_id}/continue`](#post-apipelinesidnodesnode_idcontinue) (« Continuer avec les résultats »), qui crée le job suivant à partir du CSV partiel.
4. La pipeline est finalisée en `done` quand toutes les étapes atteignables sont terminales et résolues. Un arrêt global (`POST /api/pipelines/{id}/cancel`) la finalise en `cancelled`. Un job `expired` la finalise en `failed`. Une étape `cancelled`/`failed` non poursuivie ne finalise rien : la pipeline reste `running` (en pause) jusqu'à un « Continuer » ou un arrêt global.


<!-- doc: api/registry -->

---
title: API Registre des modules
slug: api/registry
section: API
summary: Source de vérité unique listant tous les modules exposés par la plateforme — scrapers actifs, stubs on-demand, méta-fonctionnalités, items à venir.
---

# API Registre des modules

Le Registre de modules est la source de vérité unique qui liste tous les modules exposés par la plateforme : scrapers actifs, stubs on-demand, méta-fonctionnalités et items à venir qui collectent encore des votes d'intérêt. Le frontend lit le registre au lieu de coder en dur les slugs de modules, donc ajouter un module ne demande que deux fichiers (`frontend/static/job_types.js` et `app/job_registry.py`).

Voir aussi : [/docs/fr/concepts/module-registry](/docs/fr/concepts/module-registry).

## Forme d'une entrée

Chaque module est décrit par un petit objet que le frontend rend dans les tuiles du tableau de bord, la palette de recherche et les pages tarif.

| Champ          | Type           | Rôle                                                                    |
| -------------- | -------------- | ----------------------------------------------------------------------- |
| `slug`         | string         | Identifiant stable. Utilisé comme job_type, paramètre de route et clé.  |
| `category`     | string         | Bucket de groupe (`sources`, `enrich`, `signals`, `outreach`, `tools`). |
| `label`        | objet          | `{ "fr": "...", "en": "..." }`. Nom d'affichage bilingue.               |
| `needs`        | string[]       | Artefacts amont consommés (ex. `["leads"]`).                            |
| `produces`     | string[]       | Artefacts aval émis (ex. `["emails"]`).                                 |
| `pipelinable`  | boolean        | Le module peut-il être chaîné dans un Pipeline.                         |
| `is_on_demand` | boolean        | Module stub — cliquer activer ouvre un fil de feedback, pas un job.     |
| `coming_soon`  | boolean        | Listé pour le vote d'intérêt seulement. Pas d'exécution backend.        |
| `alpha_unavailable` | boolean   | Construit et listé comme actif, mais gelé pendant l'alpha. Son endpoint de création renvoie `503`. |
| `api_endpoint` | string \| null | Chemin appelé par le tableau de bord pour lancer un run, ou `null`.     |

Un module est au plus l'un de `is_on_demand`, `coming_soon`, `alpha_unavailable`, ou actif. Les modules actifs ont un `api_endpoint` non-null ; les stubs et coming-soon ont `api_endpoint = null`. Un module `alpha_unavailable` se présente comme actif et garde un `api_endpoint` non-null, mais cet endpoint renvoie `503` tant que le gel alpha est en vigueur.

---

## GET /api/modules-registry

Endpoint public. Renvoie le miroir côté serveur du registre JS. La réponse est un objet plat avec un tableau par bucket plus un mapping `feature_pages` qui pointe chaque module actif vers sa page de vente publiée `/features/<slug>` (ou `null` si pas encore écrite).

### Réponse — 200 OK

```json
{
  "active": [
    "ads_intelligence", "brand_assets", "dead_check", "delivery_check",
    "emails", "filter", "import", "legal_data", "legal_ids",
    "legal_mentions", "pagespeed", "phones_extra", "pricing", "reviews",
    "scrap", "socials", "sort", "techstack", "verify_emails",
    "viewport_test"
  ],
  "multi_proxy": [
    "dead_check", "emails", "legal_ids", "legal_mentions", "phones_extra",
    "pricing", "reviews", "scrap", "socials", "techstack"
  ],
  "parallel": [
    "ads_intelligence", "brand_assets", "delivery_check", "filter",
    "import", "legal_data", "pagespeed", "sort", "verify_emails",
    "viewport_test"
  ],
  "on_demand": [
    "email_campaign", "phone_carrier", "sms_campaign", "whatsapp_campaign"
  ],
  "meta": ["pipeline", "veille"],
  "coming_soon": [
    "ai_personalization", "ai_team_members", "bing_places", "campaign",
    "chrome_extension", "crm", "directories", "email_warmup",
    "funding", "hiring", "integrations", "job_changes", "linkedin",
    "mobile_phones", "multichannel", "natural_filter", "pagesjaunes",
    "press_monitoring", "public_api", "review_patterns", "seo_data",
    "tech_adoption", "tracking", "whatsapp", "yelp_tripadvisor"
  ],
  "alpha_unavailable": ["finance"],
  "feature_pages": {
    "scrap": "scraper-google-maps-gratuit-export-csv",
    "emails": "email-finder-pro-rgpd-france",
    "ads_intelligence": null
  }
}
```

L'ensemble `multi_proxy` liste les scrapers qui partagent le pool VPN global — un seul peut tourner à la fois à l'échelle plateforme. Les modules `parallel` utilisent HTTP direct et peuvent tourner en concurrence. Les clients qui planifient des jobs devraient vérifier les deux ensembles pour faire ressortir des avertissements "Sera en file".

---

## GET /api/features

Renvoie l'état d'intérêt de l'appelant plus un compteur global par fonctionnalité coming-soon. Les comptes incluent chaque id de fonctionnalité autorisée, même ceux à zéro vote, afin que le frontend puisse rendre les libellés `Souhaité (N)` sans branche de fallback.

La liste des ids acceptables égale `coming_soon` du registre, plus un petit ensemble legacy (`company`, `monitoring`, `pagespeed`) conservé pour préserver les votes historiques.

### Réponse — 200 OK

```json
{
  "voted": ["linkedin", "funding"],
  "counts": {
    "linkedin": 27,
    "funding": 14,
    "hiring": 6,
    "ai_personalization": 3,
    "directories": 0,
    "press_monitoring": 0
  }
}
```

Cause spécifique : `401` appelant non authentifié.

---

## POST /api/features/{feature_id}/interest

Enregistre un vote d'intérêt pour `feature_id`. L'opération est idempotente — un second appel par le même utilisateur est un no-op. Utiliser `DELETE` sur le même chemin pour retirer le vote.

`feature_id` est validé contre l'allow-list du registre (ids coming-soon plus ids legacy). Les ids inconnus renvoient 404 afin que l'endpoint ne puisse pas servir de KV store écrit-partout.

### Requête

```json
POST /api/features/linkedin/interest
```

Pas de corps. L'utilisateur est identifié par session.

### Réponse — 204 No Content

Corps vide. Re-récupérer `GET /api/features` pour le compteur mis à jour.

Causes spécifiques : `401` non authentifié ; `403` authentifié mais pas actif (invitation en attente) ; `404` `feature_id` hors allow-list du registre.

---

## Liens

- [Concept de registre de modules](/docs/fr/concepts/module-registry)
- [API Feedback](/docs/fr/api/feedback) — utilisée par les stubs on-demand pour faire remonter les demandes d'activation dans le dashboard admin.


<!-- doc: api/veille -->

---
title: API Veille
slug: api/veille
section: API
summary: Monitoring récurrent de scrapes et pipelines, avec buckets de diff et signaux de réputation.
---

# API Veille

L'API Veille gère les jobs de monitoring récurrents. Une *veille* rejoue un scrape source — ou un pipeline entier — à une cadence fixe, puis calcule un diff contre le run précédent pour faire ressortir ce qui a changé.

Voir [Concepts de monitoring Veille](/docs/fr/concepts/veille-monitoring) pour le cycle de vie, l'ordonnancement et le modèle de diff.

Tous les endpoints sont sous `/api/veille` et requièrent une session authentifiée et active. Les réponses sont en JSON. La propriété de ressource est appliquée à chaque requête : un accès cross-user renvoie `404`. Erreurs génériques : `401` (pas de session) et `404` (non trouvé / non propriétaire) ; les causes spécifiques sont en ligne.

## Modèle de ressource

Un objet `Veille` expose les champs suivants :

| Champ                | Type            | Description                                                  |
| -------------------- | --------------- | ------------------------------------------------------------ |
| `id`                 | entier          | Identifiant stable.                                          |
| `name`               | string          | Libellé lisible (2–200 caractères).                          |
| `source_job_id`      | string \| null  | Scrape source rejoué à chaque tick (exclusif avec `source_pipeline_id`). |
| `source_pipeline_id` | string \| null  | Pipeline source rejoué à chaque tick.                        |
| `frequency_days`     | entier          | Cadence en jours, entre `1` et `365`.                        |
| `status`             | string          | `active`, `paused` ou `deleted`.                             |
| `next_run_at`        | string (ISO8601)| Prochaine exécution planifiée.                               |
| `last_run_at`        | string \| null  | Horodatage du dernier run terminé.                           |
| `last_run_job_id`    | string \| null  | Id de job du dernier run.                                    |
| `run_count`          | entier          | Total de runs réussis.                                       |
| `created_at`         | string (ISO8601)| Horodatage de création.                                      |

## Endpoints

### Lister les veilles

`GET /api/veille`

Renvoie les veilles actives et en pause de l'appelant. Les entrées soft-deleted sont exclues.

**Réponse** `200 OK` — `{ "items": [Veille, ...] }`.

### Créer une veille

`POST /api/veille`

Crée un monitor récurrent à partir d'un scrape ou pipeline terminé appartenant à l'appelant. Exactement un de `source_job_id` ou `source_pipeline_id` est requis.

**Corps de requête**

| Champ                | Type    | Requis | Notes                                  |
| -------------------- | ------- | ------ | -------------------------------------- |
| `name`               | string  | oui    | 2–200 caractères.                      |
| `source_job_id`      | string  | un des | 8–64 caractères.                       |
| `source_pipeline_id` | string  | un des | 8–64 caractères.                       |
| `frequency_days`     | entier  | oui    | `1` ≤ valeur ≤ `365`.                  |

```json
{
  "name": "Plombiers Lyon 3",
  "source_job_id": "job_8f2c91a4",
  "frequency_days": 7
}
```

**Réponse** `200 OK` — la veille nouvellement créée.

Cause spécifique : `400` échec de validation (champs source manquants/doubles, source non possédée, source non terminée, fréquence invalide).

### Récupérer une veille

`GET /api/veille/{id}`

Renvoie une veille appartenant à l'appelant. Les entrées soft-deleted renvoient `404`.

### Mettre à jour une veille

`PATCH /api/veille/{id}`

Patche les champs mutables. Les champs omis sont laissés inchangés.

**Corps de requête**

| Champ            | Type    | Notes                                                  |
| ---------------- | ------- | ------------------------------------------------------ |
| `name`           | string  | 2–200 caractères.                                      |
| `frequency_days` | entier  | `1` ≤ valeur ≤ `365`. Reprogramme `next_run_at`.       |
| `status`         | string  | `active`, `paused` ou `deleted`.                       |

```json
{ "status": "paused", "frequency_days": 14 }
```

**Réponse** `200 OK` — la veille mise à jour. Cause spécifique : `400` valeur de champ invalide.

### Supprimer une veille

`DELETE /api/veille/{id}`

Soft-delete de la veille. L'enregistrement est conservé pour audit mais exclu de tous les endpoints de liste et n'est plus planifié.

**Réponse** `200 OK` — `{ "ok": true }`.

## Runs

Un *run* est une exécution unique de la veille plus les statistiques de diff calculées contre le run précédent. Le premier run est un *baseline* (`is_baseline: true`) et n'a pas de compteurs de diff.

### Lister les runs

`GET /api/veille/{id}/runs`

Renvoie l'historique des runs ordonné par `computed_at` descendant.

**Réponse** `200 OK`

```json
{
  "items": [{
    "id": 17,
    "job_id": "job_b71e0d22",
    "prev_job_id": "job_aa44e0f1",
    "is_baseline": false,
    "total_count": 312, "prev_total_count": 305,
    "new_count": 9, "removed_count": 2,
    "modified_count": 24, "unchanged_count": 279,
    "computed_at": "2026-05-27T08:11:04Z",
    "job_status": "done",
    "job_completed_at": "2026-05-27T08:10:48Z"
  }]
}
```

### Récupérer un run

`GET /api/veille/{id}/runs/{run_id}`

Renvoie le run, incluant `samples` — previews plafonnés des lignes dans chaque bucket de diff.

**Réponse** `200 OK`

```json
{
  "id": 17,
  "job_id": "job_b71e0d22",
  "is_baseline": false,
  "new_count": 9,
  "removed_count": 2,
  "modified_count": 24,
  "unchanged_count": 279,
  "total_count": 312,
  "computed_at": "2026-05-27T08:11:04Z",
  "samples": {
    "new": [{ "key": "...", "nom": "..." }],
    "removed": [{ "key": "...", "nom": "..." }],
    "modified": [{
      "key": "...", "nom": "...",
      "before": { "note": "4.3", "nb_avis": 42 },
      "after":  { "note": "3.8", "nb_avis": 51 },
      "changed_fields": ["note", "nb_avis"]
    }]
  }
}
```

## Catégories de signaux

Chaque run non-baseline classe chaque ligne du dataset dans exactement un bucket :

| Catégorie  | Signification                                                                 |
| ---------- | ----------------------------------------------------------------------------- |
| `new`      | Ligne présente dans le run courant, absente du précédent.                     |
| `removed`  | Ligne présente dans le précédent, absente du courant (fermée/retirée).        |
| `modified` | Ligne présente dans les deux runs avec au moins un champ tracké modifié.      |
| `unchanged`| Ligne présente dans les deux runs, identique sur les champs trackés.          |

Les compteurs sont exposés en `new_count`, `removed_count`, `modified_count` et `unchanged_count`. Les tableaux correspondants `samples.{new,removed,modified}` portent des previews plafonnés pour l'UI.

> Le champ `removed` est le bucket fermé/retiré : un enregistrement qui n'est plus listé à la source.

## Signaux de réputation

Les signaux de réputation sont une vue dérivée du bucket `modified` d'un run. Ils isolent les lignes dont la réputation publique a bougé d'une manière critique pour l'outreach — typiquement des listings Google Maps dont la note a baissé ou dont le volume d'avis a explosé entre deux runs.

### Logique de classement (vue haute)

Une ligne modifiée devient un signal quand au moins une condition est vraie :

- **Chute de note** — la note moyenne a baissé d'au moins `0.2` point.
- **Surge d'avis** — le nombre d'avis a augmenté d'au moins `3` depuis le run précédent.

Chaque signal porte un `score` qui classe l'urgence. Les chutes de note plus larges dominent ; les surges d'avis contribuent un boost additif plus petit au-dessus d'un seuil de bruit bas volume. Les signaux sont retournés triés par `score` descendant. La pondération exacte est un détail d'implémentation susceptible d'évoluer ; ne pas dépendre des valeurs absolues, uniquement de l'ordre relatif.

### Lister les signaux

`GET /api/veille/{id}/runs/{run_id}/signals`

**Réponse** `200 OK`

```json
{
  "items": [{
    "nom": "Garage du Centre",
    "adresse": "12 rue Voltaire, 69003 Lyon",
    "telephone": "+33 4 78 00 00 00",
    "site_web": "https://...", "email": "contact@...",
    "lien_google_maps": "https://maps.google.com/...",
    "note_avant": 4.3, "note_apres": 3.8, "delta_note": -0.5,
    "avis_avant": 42, "avis_apres": 51, "delta_avis": 9,
    "score": 12.0
  }],
  "total": 1
}
```

### Exporter les signaux

`GET /api/veille/{id}/runs/{run_id}/signals.{fmt}`

Diffuse la même liste classée comme fichier téléchargeable.

| Format | Media type                                                                | Extension |
| ------ | ------------------------------------------------------------------------- | --------- |
| `csv`  | `text/csv; charset=utf-8`                                                 | `.csv`    |
| `json` | `application/json`                                                        | `.json`   |
| `xlsx` | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`       | `.xlsx`   |

La réponse pose `Content-Disposition: attachment` avec un nom de fichier de la forme `signaux-reputation-veille-{id}-run-{run_id}.{fmt}`.

Cause spécifique : `400` `fmt` non supporté (doit être `csv`, `json`, `xlsx`).


<!-- doc: concepts/ai-spending-caps -->

---
title: Plafonds de dépense IA
slug: concepts/ai-spending-caps
section: Concepts
summary: Plafonds de dépense IA stricts par utilisateur ($/requête, $/jour, $/mois), avec estimation du coût avant l'action et alertes email.
---

Les fonctionnalités IA d'outsend tournent sur **votre propre clé fournisseur** (BYOK) : la facturation se fait au réel, directement chez le fournisseur. Pour qu'un prompt mal calibré ne brûle jamais votre facture, outsend applique des **plafonds de dépense stricts** à chaque requête IA — côté serveur, donc impossibles à contourner.

## Les trois plafonds

| Plafond        | Défaut | Configurable jusqu'à |
|----------------|--------|----------------------|
| Par requête    | 10 $   | 100 $                |
| Par jour       | 10 $   | 100 $                |
| Par mois       | 100 $  | 1 000 $              |

À régler dans **Paramètres → Plafonds de dépense IA**. Les jours et mois sont comptés en UTC.

## Comment ça marche

1. **Estimation avant** — avant une action IA, outsend affiche le coût worst-case (vos tokens d'entrée + le maximum de tokens en sortie) et le budget restant aujourd'hui et ce mois.
2. **Blocage avant dépassement** — si une requête risque de dépasser un plafond, elle est refusée *avant* tout appel au fournisseur. Rien n'est dépensé.
3. **Suivi du coût réel** — après chaque appel, le coût réel (les tokens consommés rapportés par le fournisseur × le prix du modèle) est ajouté à vos totaux du jour et du mois.
4. **Alertes email** — vous recevez un email à 80 % d'un plafond jour/mois, puis lorsqu'un plafond est atteint (IA en pause jusqu'au reset).

## Modèles sans prix connu

Les prix viennent d'un catalogue public de prix de modèles (~2 700 modèles). Si un modèle n'y figure pas (certains endpoints custom ou exotiques), outsend ne peut pas calculer son coût : la requête est **autorisée et tracée, mais non plafonnée**, et l'interface signale le prix comme inconnu. Les modèles courants de chaque fournisseur supporté sont, eux, tarifés.

## Bon à savoir

- Les plafonds sont une **sécurité côté outsend** — la vraie facture reste celle de votre fournisseur, et l'estimation est indicative.
- Les resets sont calendaires : le total du jour se remet à zéro à 00:00 UTC, le total du mois le 1er.
- Augmenter un plafond prend effet immédiatement ; l'IA reprend dès que vous repassez en dessous.


<!-- doc: concepts/jobs-lifecycle -->

---
title: Jobs & cycle de vie
slug: concepts/jobs-lifecycle
section: Concepts
summary: Un job est une unité de travail. Cette page décrit ses états, transitions, événements et la sémantique de reprise.
---

Un **job** est une unité de travail. Chaque module s'exécute sous forme de job. Les jobs sont isolés, observables, reprenables.

## Machine à états

```
   ┌─────────┐   pris par file   ┌─────────┐    succès     ┌──────┐
   │ pending │ ────────────────► │ running │ ────────────► │ done │
   └─────────┘                   └─────────┘               └──────┘
        │                             │
        │       annulation            │    erreur fatale
        ▼                             ▼
   ┌───────────┐                 ┌────────┐
   │ cancelled │                 │ failed │
   └───────────┘                 └────────┘

   done / failed / cancelled  ──── (après 7 jours) ────►  expired
```

| État        | Signification                                                                       |
|-------------|-------------------------------------------------------------------------------------|
| `pending`   | Créé, en attente dans la file FIFO                                                  |
| `running`   | Pris par un worker, en cours d'exécution                                            |
| `done`      | Terminé avec succès, résultats téléchargeables                                      |
| `failed`    | Échec (voir `error_message`)                                                        |
| `cancelled` | Annulé via l'UI ou l'API                                                            |
| `expired`   | Plus de 7 jours depuis l'état terminal — fichiers de résultats purgés               |

Transitions et assignation à la file sont atomiques ; un job n'est jamais pris deux fois.

## Création

```
POST /api/jobs             { "queries": [...], "zones": [...] }   # crée un job scrap
POST /api/jobs/{type}      { ...paramètres module }               # raccourci typé
```

Voir [API Jobs](/docs/fr/api/jobs).

## Observabilité

```
GET /api/jobs/{id}            # statut, compteurs, métadonnées
GET /api/jobs/{id}/stream     # SSE : status / log / done
```

Le flux se ferme à la fin du job. Timeout de sécurité : 6 heures. Payloads des événements : voir [États & événements SSE](/docs/fr/concepts/states-and-events).

## Résultats

```
GET /api/jobs/{id}/download?format=csv|json|xlsx
GET /api/jobs/{id}/items?offset=0&limit=200
```

Les résultats restent **7 jours** après l'état terminal, puis sont purgés. L'enregistrement du job demeure.

## Erreurs & reprises

Un job `failed` expose `error_message` et `error_count` (items en erreur dans le job — un job peut être `done` avec `error_count > 0`).

```
POST /api/jobs/{id}/resume
```

Crée une nouvelle tentative qui repart du dernier item réussi.

## Annulation

```
POST /api/jobs/{id}/cancel    # conserve les résultats partiels
DELETE /api/jobs/{id}         # annule et supprime l'enregistrement
```

## Concurrence

- Jusqu'à **5 jobs simultanés par utilisateur** (au-delà : file d'attente)
- Deux voies : **série** (extraction) et **parallèle** (6 slots : vérification, utilitaires pipeline, `delivery_check`)
- Les jobs sont indépendants — les ré-exécutions n'attendent pas l'original

## La suite

- [États & événements SSE](/docs/fr/concepts/states-and-events)
- [Orchestration pipeline](/docs/fr/concepts/pipeline-orchestration)
- [Limites & quotas](/docs/fr/concepts/limits)


<!-- doc: concepts/limits -->

---
title: Limites & quotas
slug: concepts/limits
section: Concepts
summary: Toutes les limites numériques appliquées par la plateforme, dans un seul tableau.
---

Référence pour la planification de capacité. Global plateforme sauf mention par-utilisateur.

## Jobs

| Limite                             | Valeur          | Portée          |
|------------------------------------|-----------------|-----------------|
| Jobs simultanés par utilisateur    | 5               | par utilisateur |
| Slots worker voie parallèle        | 6               | global plateforme (verify_emails, delivery_check, import, filter, sort) |
| Rétention fichiers résultats       | 7 jours         | par job         |
| Durée max d'un flux SSE            | 6 heures        | par flux        |
| EF max par job                     | 1.0             | par job         |

La voie parallèle est un pool séparé de la voie série utilisée par les modules d'extraction.

## Veille

| Limite             | Valeur     |
|--------------------|------------|
| Fréquence min      | 1 jour     |
| Fréquence max      | 365 jours  |

## Pipelines

| Limite             | Valeur     |
|--------------------|------------|
| Nœuds max          | 20         |
| Inputs max/nœud    | 1 (MVP)    |

## Dépense IA (BYOK)

Plafonds stricts par utilisateur sur les fonctionnalités IA — facturées sur votre propre clé fournisseur — avec alertes email. Configurables dans les Paramètres jusqu'à ×10 le défaut.

| Plafond      | Défaut | Max     | Portée                     |
|--------------|--------|---------|---------------------------|
| Par requête  | 10 $   | 100 $   | par utilisateur           |
| Par jour     | 10 $   | 100 $   | par utilisateur, jour UTC |
| Par mois     | 100 $  | 1 000 $ | par utilisateur, mois UTC |

Une requête qui dépasserait un plafond est bloquée avant tout appel au fournisseur ; un email part à 80 % et quand un plafond est atteint. Voir [Plafonds de dépense IA](/docs/fr/concepts/ai-spending-caps).

## Rate limits auth

Fenêtres par endpoint. Dépassement = `429 Too Many Requests`.

| Endpoint                       | Limite       | Fenêtre                    |
|--------------------------------|--------------|----------------------------|
| Inscription                    | 3 tentatives | par heure, par IP          |
| Connexion                      | 5 tentatives | par 15 min, par IP+email   |
| Demande de réinitialisation    | 3 tentatives | par heure, par IP+email    |
| Changement de mot de passe     | 5 tentatives | par heure, par utilisateur |
| Renvoi vérification email      | 3 tentatives | par heure, par utilisateur |
| Création thread feedback       | 20 tentatives| par heure, par utilisateur |
| Durée de session               | 7 jours      | fenêtre glissante          |

Aucun throttle API global au-delà.

## Spécifiques aux modules

- **[`scrap`](/docs/fr/modules/scrap)** — max 1.0 EF par job
- **[`emails`](/docs/fr/modules/emails)** — modes `normal` et `deep` avec profils EF distincts
- Tous les modules multi-proxy — tableau `items` borné à 1–10000 par requête

## La suite

- [Jobs & cycle de vie](/docs/fr/concepts/jobs-lifecycle)
- [Vue d'ensemble API](/docs/fr/api/overview)


<!-- doc: concepts/module-registry -->

---
title: Registre des modules
slug: concepts/module-registry
section: Concepts
summary: Une source de vérité unique décrit chaque module — ses entrées, sorties, catégorie et son emplacement dans l'UI.
---

Chaque module exposé par outsend est déclaré dans un **registre unique**. Il alimente la grille de modules du dashboard, le sélecteur de nouveau job, l'éditeur de pipeline et le listing landing.

Garanties : un module visible au dashboard a un endpoint (et réciproquement) ; un snapshot lisible par machine est publié ; les catégories sont des indices, tandis que `slug`, `needs` et `produces` sont stables.

## L'endpoint

```
GET /api/modules-registry
```

Renvoie le registre complet en JSON. Chaque entrée :

```json
{
  "slug": "scrap",
  "category": "extraction",
  "label": { "fr": "Scrap Google Maps", "en": "Scrape Google Maps" },
  "needs": null,
  "produces": "poi_list",
  "pipelinable": true,
  "is_on_demand": false,
  "coming_soon": false,
  "api_endpoint": "/api/jobs/scrap"
}
```

| Champ           | Signification                                                            |
|-----------------|--------------------------------------------------------------------------|
| `slug`          | Identifiant stable, utilisé dans URLs et chemins d'API                   |
| `category`      | `extraction` \| `enrichment` \| `intelligence` \| `verification` \| `pipeline` \| `meta` |
| `label`         | Libellés d'affichage par langue                                          |
| `needs`         | Forme d'entrée (`poi_list`, `csv_rows`, …) — `null` si produit à partir de rien |
| `produces`      | Forme de sortie                                                          |
| `pipelinable`   | Utilisable comme nœud d'un pipeline                                      |
| `is_on_demand`  | Si true, pas de backend — déclenche une conversation avec l'équipe       |
| `coming_soon`   | Si true, listé pour visibilité seulement ; intérêt votable               |
| `api_endpoint`  | Raccourci pour démarrer un job de ce type                                |

## Correspondance souple des entrées

`needs` et `produces` décrivent des noms de colonnes *canoniques* (`nom`, `telephone`, `site_web`, `email`, `lien_google_maps`, …). Vous n'avez jamais à formater vos données pour les coller exactement : les entrées sont résolues via une table partagée d'alias acceptés, de sorte que des colonnes nommées `Website`, `url`, `e-mail`, `name` ou `raison sociale` sont mappées vers le bon champ canonique. Les fichiers sans en-tête sont détectés automatiquement et les colonnes déduites de leur contenu.

Chaque job le signale en clair. Chaque exécution renvoie une **`notice`** non bloquante (bannière d'info sur la page du job, ⓘ discret au dashboard) décrivant ce qui a été auto-mappé, deviné ou ignoré — par exemple les lignes écartées faute de site web. Un job n'échoue que lorsqu'une colonne requise est réellement absente (ex : un enrichissement qui a besoin de `site_web` ne la trouve sur aucune ligne), et cette erreur **nomme explicitement les alias acceptés** pour que vous sachiez quel en-tête fournir.

## Catégories

| Catégorie      | Rôle                                                       | Exemples                                                    |
|----------------|------------------------------------------------------------|-------------------------------------------------------------|
| `extraction`   | Produit des données depuis des sources publiques           | [`scrap`](/docs/fr/modules/scrap)                           |
| `enrichment`   | Enrichit les lignes existantes avec de nouveaux champs     | [`emails`](/docs/fr/modules/emails), [`socials`](/docs/fr/modules/socials), [`legal_ids`](/docs/fr/modules/legal_ids) |
| `intelligence` | Calcule des signaux sur les lignes existantes              | [`pricing`](/docs/fr/modules/pricing), [`techstack`](/docs/fr/modules/techstack), [`ads_intelligence`](/docs/fr/modules/ads_intelligence) |
| `verification` | Valide ou score les lignes existantes                      | [`verify_emails`](/docs/fr/modules/verify_emails), [`delivery_check`](/docs/fr/modules/delivery_check) |
| `pipeline`     | Utilitaires d'orchestration                                | [`import`](/docs/fr/modules/import), [`filter`](/docs/fr/modules/filter), [`sort`](/docs/fr/modules/sort) |
| `meta`         | N'est pas un job — décrit pipelines ou veilles             | (aucun endpoint API)                                        |

## Cycle de vie d'un module

1. **Coming soon** — landing uniquement, pas de backend, intérêt votable
2. **On-demand** — listé au dashboard, le CTA ouvre une conversation, exécuté manuellement
3. **Active** — entièrement supporté par un endpoint
4. **Disponible (gelé en alpha)** — construit et présenté comme un module actif sur toutes les surfaces, mais non lançable pendant l'alpha : l'UI affiche un bandeau maintenance avec bouton « Lancer » désactivé, et l'endpoint de création renvoie `503`. Contrairement à *coming soon*, ce n'est pas un placeholder et il ne porte pas de vote d'intérêt — c'est un module fini, retenu uniquement par la capacité serveur de l'alpha.
5. **Deprecated** — toujours appelable mais signalé

Les changements de phase apparaissent dans le registre via `coming_soon`, `is_on_demand`, `alpha_unavailable` et `deprecated_at`.

## Ajouter un module (contributeurs)

Ajouter un module = 2 fichiers dans le codebase : une entrée registre JS (surfaces UI) et une entrée registre Python (API + dispatcher worker). Le runtime branche ensuite le module partout automatiquement.

## La suite

- [Jobs & cycle de vie](/docs/fr/concepts/jobs-lifecycle)
- [Orchestration pipeline](/docs/fr/concepts/pipeline-orchestration)


<!-- doc: concepts/pipeline-orchestration -->

---
title: Orchestration pipeline
slug: concepts/pipeline-orchestration
section: Concepts
summary: Chaîner des modules dans un DAG réutilisable. Chaque bloc consomme la sortie du précédent, sans code de liaison.
---

Un **pipeline** est un graphe orienté acyclique de modules. Chaque nœud est un appel de module ; chaque arête déclare quelle sortie alimente quelle entrée. Le pipeline sauvegarde une recette multi-étapes une fois et la relance à volonté.

Les pipelines supportent aussi la [veille](/docs/fr/concepts/veille-monitoring) : un scrap récurrent est en interne un pipeline planifié.

## Anatomie

```
   ┌──────────┐
   │  scrap   │   queries=["boulangerie"], zones=["Paris"]
   └────┬─────┘
        │ produces: poi_list
        ▼
   ┌──────────┐      ┌──────────┐
   │  emails  │      │ ads_intel│
   └────┬─────┘      └────┬─────┘
        │                  │
        ▼                  ▼
   ┌────────────────────────────┐
   │          filter            │   rules: emails_present=true, ads_score≥30
   └────────────┬───────────────┘
                ▼
            ┌────────┐
            │  sort  │   sort_by=ads_score, desc, top_n=200
            └────────┘
```

Chaque nœud possède :

- **type** — slug du module (voir [registre des modules](/docs/fr/concepts/module-registry))
- **params** — configuration du module, identique à un job autonome
- **inputs** — références au(x) nœud(s) amont
- **id** — identifiant local dans le pipeline

## Règles de chaînage

Une arête est valide uniquement si `produces` du producteur correspond à `needs` du consommateur (formes comme `poi_list`, `enriched_list`, `csv_rows`). L'éditeur vérifie à la conception.

## Limites

| Limite             | Valeur                                |
|--------------------|---------------------------------------|
| Nœuds max          | 20                                    |
| Inputs max/nœud    | 1 (fusion multi-entrées non ouverte)  |
| Profondeur max     | 20                                    |
| Ré-exécutions      | Illimitées                            |

## Exécution

Les pipelines **démarrent auto à la création** — `POST /api/pipelines` met en file le nœud racine, la suite suit à mesure que les prédécesseurs atteignent `done`.

Chaque nœud tourne comme un job normal (même cycle de vie, observabilité, reprises). Le coordinateur avance sur `done`, s'arrête au premier `failed`. Un pipeline échoué peut être repris au nœud fautif. Pour relancer, créer un nouveau pipeline (le graphe est en JSON — copier et re-poster).

## Endpoints

```
POST   /api/pipelines                  # création (démarre auto)
GET    /api/pipelines                  # liste des pipelines utilisateur
GET    /api/pipelines/{id}             # détail + graphe
```

Un pipeline appartient à un seul utilisateur.

### Aperçu filtre

```
POST /api/pipelines/{id}/nodes/{node_id}/filter-preview
```

Exécute un nœud `filter` sur un échantillon de la sortie du prédécesseur, sans lancer tout le pipeline.

## La suite

- [Veille (surveillance)](/docs/fr/concepts/veille-monitoring)
- [`filter`](/docs/fr/modules/filter), [`sort`](/docs/fr/modules/sort), [`import`](/docs/fr/modules/import)


<!-- doc: concepts/scrape-modes -->

---
title: Modes de scrap (Fast / Avancé / Ultra)
slug: concepts/scrape-modes
section: Concepts
summary: Les trois modes du scrap Google Maps règlent la profondeur de subdivision adaptative — donc l'arbitrage entre vitesse, coût (EF) et exhaustivité des contacts.
---

Le scrap Google Maps d'outsend propose **trois modes** qui règlent un seul paramètre : la **profondeur de subdivision adaptative**. Ils arbitrent entre vitesse, coût et exhaustivité.

| Mode | Pour qui | En une phrase |
|------|----------|----------------|
| **Fast** *(défaut)* | La majorité des cas | Rapide, moins de coût, récupère déjà l'essentiel des contacts. |
| **Avancé** | Besoin d'enrichir | Équilibré : plus de contacts dans les zones denses, coût modéré. |
| **Ultra** | Couverture maximale | Subdivise au maximum : recall quasi-exhaustif, plus lent et plus coûteux. |

## Pourquoi trois modes : le cap des 120 résultats

Google Maps **plafonne toute recherche à ~120 résultats** (« vous êtes arrivé au bout de la liste »). Pour aller au-delà, outsend découpe une tuile saturée en 4 sous-tuiles plus zoomées et rescanne chacune (dédup par lien Google Maps). C'est la **subdivision adaptative**.

Mais subdiviser n'a de sens que si la sous-tuile apporte de **nouveaux** contacts : dans une zone peu dense, Google élargit son rayon au-delà de la tuile et renvoie souvent les mêmes 120 fiches → subdiviser = 4× plus de travail pour 0 nouveau lead.

Chaque mode fixe donc un **seuil** : on ne subdivise une tuile saturée que si elle a ramené au moins *N* nouveaux contacts uniques.

| Mode | Seuil (nouveaux uniques requis pour subdiviser) | Effet |
|------|------------------------------------------------|-------|
| **Fast**   | 15 | Ne subdivise que les zones franchement riches → peu de tuiles. |
| **Avancé** | 7  | Subdivise plus volontiers → plus de couverture. |
| **Ultra**  | 1  | Subdivise dès qu'il reste du nouveau → couverture maximale. |

La profondeur de subdivision est bornée (zoom 13 → 17, soit 4 niveaux : une tuile fait alors ~300 m de côté, ≈ 1 bloc urbain), donc même Ultra reste fini.

## Les modes ne divergent que dans les zones denses

Point essentiel : **un mode ne change quelque chose que là où des tuiles saturent** (≥ 120 résultats). 

- **Zone dense** (centre-ville, requête courante comme « plombier » ou « restaurant ») : les tuiles saturent, la subdivision se déclenche → Fast / Avancé / Ultra donnent des volumes de contacts **nettement différents**.
- **Zone peu peuplée** (rural, requête de niche) : rien ne sature, aucune subdivision → **les trois modes donnent exactement le même résultat**. Choisir Ultra ne sert alors à rien (même résultat, même coût).

C'est pour cela que le mode est un choix **par scrap**, pas un réglage global : il dépend de la densité de ce que vous cherchez.

## Coût (EF) et durée

L'**EF** (équivalent-France) est l'unité de coût d'un scrap. La base est simple :

> **1 EF = scraper la France entière, une fois, en mode Fast.**

Une ville ou un département coûtent donc une petite fraction d'EF. Comme les modes plus profonds lancent **beaucoup plus** de requêtes Google Maps (ils re-subdivisent les tuiles saturées), ils coûtent proportionnellement plus :

| Mode | Coût relatif | Durée relative |
|------|:---:|:---:|
| Fast | **×1** (base) | ×1 |
| Avancé | **≈ ×2** | ≈ ×2 |
| Ultra | **≈ ×6** | ≈ ×6 |

Ces facteurs sont des **moyennes mesurées** (ratio de tuiles traitées vs Fast, campagne du 2026-06-05). Le coût réel dépend de la **densité réelle** de la zone :
- **Zone peu peuplée** : rien ne sature → aucune subdivision → les 3 modes coûtent **pareil** (le facteur ne s'applique pas vraiment).
- **Zone dense** : l'écart se creuse (Ultra peut atteindre ×14 en centre-ville très dense).

L'estimation pré-scrap applique ces facteurs (l'EF affiché monte quand vous passez en Avancé/Ultra). En cours de scrap, l'**ETA tient compte** des subdivisions à venir, et le **temps écoulé** est affiché en direct.

## Mesures

> **Méthodologie.** 3 requêtes de densités différentes — « plombier » (clusterise), « pharmacie » (nombreuse et répartie), « cordonnier » (niche) — toutes des catégories qui **affichent un téléphone** (les catégories grand-public type restaurant/coiffeur affichent ~0 tél → faussement filtrées par l'anti-bot, non testables). 3 zones (dense / moyenne / rurale), les 3 modes chacune, **chaque scrap mené à terminaison complète** (aucun timeout). On mesure : contacts uniques, tuiles traitées (≈ coût/requêtes), durée réelle. Le % est exprimé vs Fast.

**Matrice complète (campagne 2026-06-05, « plombier », tout à terminaison)**

| Zone | Densité | Mode | Contacts | Tuiles | Temps | vs Fast | Contacts/tuile |
|------|---------|------|---------:|-------:|------:|--------:|---------------:|
| Lyon 6 km | dense | Fast | 606 | 53 | 50 min | — | 11,4 |
| Lyon 6 km | dense | Avancé | 627 | 89 | 84 min | +3,5 % | 7,0 |
| Lyon 6 km | dense | Ultra | 647 | 193 | 180 min | +6,8 % | 3,4 |
| Tours 10 km | moyenne | Fast | 311 | 14 | 8 min | — | 22,2 |
| Tours 10 km | moyenne | Avancé | 351 | 42 | 20 min | +13 % | 8,4 |
| Tours 10 km | moyenne | Ultra | 377 | 150 | 72 min | +21 % | 2,5 |
| Aurillac 12 km | rurale | Fast | 213 | 19 | 7 min | — | 11,2 |
| Aurillac 12 km | rurale | Avancé | 211 | 23 | 9 min | −1 % | 9,2 |
| Aurillac 12 km | rurale | Ultra | 215 | 83 | 40 min | +1 % | 2,6 |

- **Rural → les 3 modes sont identiques** (213 / 211 / 215). Ultra met 40 min (vs 7 min pour Fast) pour **+2 contacts**. Pousser ne sert à rien quand rien ne sature.
- **Moyenne → Ultra +21 %** vs Fast, mais en **9× le temps** (72 min vs 8 min) ; Avancé +13 % en 2,5×.
- **Dense → Ultra +6,8 %** vs Fast, en **3,6× le temps** (3 h vs 50 min).
- **Efficacité** : Fast est **3 à 9× plus rentable par tuile** (donc par EF/temps) que Ultra dans toutes les zones.

**Deux autres requêtes (« pharmacie » = catégorie dense et nombreuse ; « cordonnier » = niche), gain d'Ultra vs Fast**

| Requête | Lyon (dense) | Tours (moyenne) | Aurillac (rurale) |
|---------|:---:|:---:|:---:|
| plombier (clusterise) | +6,8 % | +21 % | +1 % |
| **pharmacie (nombreuse, répartie)** | **+50 %** | **+44 %** | bruit* |
| cordonnier (niche) | +16 % | +3 % | +12 % |

<small>Détail pharmacie : Lyon Fast 411 / Ultra 617 (36→157 min) ; Tours Fast 253 / Ultra 364 (8→110 min). Cordonnier Lyon Fast 173 / Ultra 200. *Rural pharmacie = bruit : les tuiles ne saturent pas de façon stable (frontière des 120), l'ordre des modes y est aléatoire.</small>

> **Conclusion.** Le gain d'Ultra **n'a pas de valeur unique : de +1 % à +50 % selon la catégorie**. Les catégories **nombreuses et réparties** (pharmacies, commerces réguliers) bénéficient énormément d'Ultra (+44 à +50 % — Fast en rate la moitié à cause du cap des 120). Les catégories qui **se regroupent** (plombier) ou **rares** (cordonnier) n'y gagnent que +1 à +16 %. Dans tous les cas, Ultra coûte **3 à 14× le temps** de Fast, et en rural/faible densité les 3 modes convergent.

## Recommandation

- **Par défaut : Fast.** Meilleur rapport vitesse/coût pour un premier jet et pour les catégories qui se regroupent (artisans, services spécialisés).
- **Ultra quand la cible est dense ET nombreuse** (pharmacies, commerces, agences…) et que vous voulez l'exhaustivité : le gain est réel, jusqu'à **+50 %** de contacts. Acceptez 3 à 14× le temps.
- **Avancé** = compromis intermédiaire.
- **Niche ou zone peu peuplée → Fast**, point : les modes convergent, Ultra ne fait que perdre du temps.

Voir aussi : [Jobs & cycle de vie](concepts/jobs-lifecycle), [Limites & quotas](concepts/limits).


<!-- doc: concepts/states-and-events -->

---
title: États & événements SSE
slug: concepts/states-and-events
section: Concepts
summary: Payloads exacts pour chaque état de job et chaque événement émis sur le flux SSE.
---

Le contrat pour toute intégration contre le flux job — bots, dashboards, alerting, assistants IA.

## États — énumération complète

| Valeur      | Terminal | Fichiers résultats dispo | Reprenable |
|-------------|----------|---------------------------|------------|
| `pending`   | non      | non                       | s/o        |
| `running`   | non      | non                       | s/o        |
| `done`      | oui      | oui (7 jours)             | oui        |
| `failed`    | oui      | partiels                  | oui        |
| `cancelled` | oui      | partiels                  | oui        |
| `expired`   | oui      | non (purgés)              | non        |

Un job `pending` ou `running` ne peut être supprimé, seulement **annulé**.

## Flux SSE

```
GET /api/jobs/{id}/stream
Accept: text/event-stream
```

SSE standard ; chaque événement :

```
event: <name>
data: <json-payload>

```

### Événement `status`

Toutes les **2 secondes** tant que non-terminal, plus une fois à l'état terminal.

```json
{
  "id": "j_abc123",
  "status": "running",
  "processed_points": 412,
  "grid_points_count": 1280,
  "results_count": 387,
  "error_count": 2,
  "download_available": false,
  "query_stats": {
    "bakery": { "found_pct": 92 },
    "dentist": { "found_pct": 78 }
  }
}
```

| Champ                | Type    | Description                                                  |
|----------------------|---------|--------------------------------------------------------------|
| `id`                 | string  | Id du job                                                    |
| `status`             | enum    | Voir tableau ci-dessus                                       |
| `processed_points`   | int     | Items traités                                                |
| `grid_points_count`  | int     | Items planifiés                                              |
| `results_count`      | int     | Lignes de résultats à ce stade                               |
| `error_count`        | int     | Items en échec (le job peut quand même atteindre `done`)     |
| `download_available` | bool    | `true` une fois le fichier prêt                              |
| `query_stats`        | object  | Stats par requête ; dépend du module                         |

### Événement `log`

Émis au fil des nouvelles lignes de log (par lots, sondage interne 0,5 s).

```json
{
  "message": "Picked up 12 POIs in Lyon centre",
  "level": "info",
  "timestamp": "2026-05-27T14:21:08Z"
}
```

`level` ∈ `debug` · `info` · `warn` · `error`.

### Événement `done`

Émis une fois, puis le flux se ferme. Même événement pour `failed` et `cancelled` — vérifier `status`.

```json
{
  "id": "j_abc123",
  "status": "done",
  "results_count": 1820,
  "duration_seconds": 1342
}
```

### Événement `error`

Erreurs au niveau du flux (auth, not-found). Différent d'un job terminé en `failed` (qui arrive via `done` avec `status: "failed"`).

```json
{ "code": "forbidden", "message": "Not your job" }
```

## Intervalles de sondage (sans SSE)

| Endpoint         | Intervalle minimum |
|------------------|--------------------|
| `/api/jobs/{id}` | 2 secondes         |
| `/api/jobs`      | 5 secondes         |

L'état interne se rafraîchit toutes les 2 s ; sonder plus vite n'apporte rien.

## Timeouts

| Élément                                   | Valeur     |
|-------------------------------------------|------------|
| Durée max d'un flux SSE                   | 6 heures   |
| Timeout global d'un job                   | 6 heures   |
| Fenêtre de reconnexion worker idle        | 30 secondes |
| Rétention fichiers résultats après `done` | 7 jours    |

## La suite

- [Jobs & cycle de vie](/docs/fr/concepts/jobs-lifecycle)
- [Limites & quotas](/docs/fr/concepts/limits)


<!-- doc: concepts/veille-monitoring -->

---
title: Veille (surveillance)
slug: concepts/veille-monitoring
section: Concepts
summary: Un scrap récurrent qui compare chaque exécution à la précédente et fait remonter des signaux de réputation.
---

Une **veille** est la réexécution planifiée d'un job ou pipeline existant. Chaque exécution est comparée à la précédente, et les différences sont exposées comme **signaux**.

Une veille est créée à partir d'un **job scrap** existant (la source). Sa requête + zones + paramètres deviennent le modèle, cloné à chaque exécution planifiée.

```
   job source (scrap ponctuel)
        │  enregistré comme veille, fréquence = 7 jours
        ▼
   run 1   ──►   poi_list_v1
        │  7 jours plus tard
        ▼
   run 2   ──►   poi_list_v2
        │  diff(v1, v2)
        ▼
   rapport de changements :
     - nouveaux POIs (ouvertures)
     - POIs fermés (introuvables)
     - POIs modifiés (notes en baisse, contact changé, ...)
```

## Fréquence

Jours, **1**–**365**. L'horaire est volontairement interdit : la donnée prospect n'évolue pas aussi vite, et les rate limits sources ne tiendraient pas. Typique : 7 (hebdo), 30 (mensuel), 90 (trimestriel).

## Signaux

Trois catégories extraites de chaque diff :

- **`new`** — dans la nouvelle exécution, absent avant (concurrents nouvellement ouverts, partenaires, cibles d'acquisition)
- **`closed`** — absent de la nouvelle exécution, présent avant (nettoyage prospection ; signal précoce de fermeture)
- **`modified`** — présent dans les deux, changé :
  - **Delta de note** — chute Google = signal fort « client en difficulté »
  - **Delta de nombre d'avis** — activité en envol ou en stagnation
  - **Delta de contact** — téléphone ou site web changé (souvent un relancement)

Les lignes modifiées sont scorées ; l'endpoint signals les renvoie classées.

## Endpoints

```
GET    /api/veille                              # liste les veilles utilisateur
POST   /api/veille                              # création
PATCH  /api/veille/{id}                         # mise à jour nom, fréquence, statut
DELETE /api/veille/{id}                         # suppression douce
GET    /api/veille/{id}/runs                    # historique des exécutions
GET    /api/veille/{id}/runs/{run_id}           # une exécution + diff
GET    /api/veille/{id}/runs/{run_id}/signals   # signaux filtrés, scorés
```

L'endpoint signals supporte CSV / JSON / XLSX via `?format=…`.

## États

| État     | Signification                                          |
|----------|--------------------------------------------------------|
| `active` | S'exécute selon le planning                            |
| `paused` | Planning suspendu ; exécutions existantes conservées   |
| `deleted`| Supprimé en douce ; données conservées                 |

Une exécution de veille est un job normal — mêmes workers, mêmes quotas. Ne compte dans le plafond de jobs en cours qu'au moment de l'exécution.

## La suite

- [Jobs & cycle de vie](/docs/fr/concepts/jobs-lifecycle)
- [Orchestration pipeline](/docs/fr/concepts/pipeline-orchestration)
- [`scrap`](/docs/fr/modules/scrap)


<!-- doc: integration/byok -->

---
title: BYOK — Bring your own AI key
slug: integration/byok
section: Intégration
summary: Connecter une clé API personnelle de n'importe quel grand fournisseur AI (Anthropic, OpenAI, Gemini, Mistral, Groq, DeepSeek, xAI, ou tout endpoint OpenAI-compatible) et choisir un modèle. Clé du user, quota du user.
---

> **Statut : partiellement live.** Connecter une clé, choisir un fournisseur et sélectionner un modèle sont disponibles dès maintenant dans **Settings → Connecter une IA**, et alimentent les features AI déjà livrées (ex. résumé d'avis Google, génération de pipeline depuis une description). L'assistant intégré plus large décrit ci-dessous reste sur la roadmap.

L'intégration BYOK ("bring your own key") permet au user de coller une clé API AI dans les settings d'outsend et d'utiliser un assistant directement dans l'app — pour configurer des recherches, écrire des règles de filtre, résumer des résultats, construire des pipelines en langage naturel.

## Pourquoi BYOK plutôt qu'un modèle hébergé

- Le spend reste sur le compte du user, facturé directement par le fournisseur AI.
- Pas de médiation côté outsend : l'assistant ne voit que ce que le user accorde.
- Le choix du fournisseur reste au user : Anthropic, OpenAI, ou tout endpoint compatible.

## Fournisseurs supportés

Le fournisseur et le modèle se choisissent dans **Settings → Connecter une IA**. Les modèles sont **détectés en live** depuis l'API du fournisseur — aucune liste figée à maintenir, les nouveaux modèles apparaissent automatiquement à mesure que le fournisseur les publie.

| Fournisseur | Format de clé | Notes |
|-------------|---------------|-------|
| Anthropic (Claude) | `sk-ant-…` | API Messages native |
| OpenAI | `sk-…` | Inclut les modèles de raisonnement (série o, GPT-5) |
| Google (Gemini) | `AIza…` | Endpoint OpenAI-compatible |
| Mistral | — | |
| Groq | `gsk_…` | |
| DeepSeek | `sk-…` | |
| xAI (Grok) | `xai-…` | |
| Tout endpoint OpenAI-compatible | — | Coller une base URL custom (Together, Perplexity, OpenRouter, Ollama / vLLM local, …) |

La clé est stockée chiffrée au repos (Fernet, secret serveur), liée au compte du user, et jamais envoyée hors backend outsend sauf vers le fournisseur choisi. Une estimation de coût indicative s'affiche avant les actions AI — purement indicative (comptage de tokens best-effort face aux tarifs publics connus), elle peut différer de la facturation réelle du fournisseur. La dépense IA est aussi protégée par des **plafonds stricts** — par requête, par jour et par mois — que vous réglez dans les **Paramètres** : une requête qui dépasserait un plafond est bloquée *avant* tout appel au fournisseur, avec des alertes email à 80 % et quand un plafond est atteint. Voir [Plafonds de dépense IA](/docs/fr/concepts/ai-spending-caps).

## Ce que l'assistant peut faire

Mêmes endpoints qu'un user humain — voir [Vue d'ensemble API](/docs/fr/api/overview). Il peut :

- Lire les jobs, pipelines et veilles du user
- Démarrer de nouveaux jobs (avec confirmation explicite sur le coût)
- Composer des pipelines en enchaînant des modules du [registre](/docs/fr/concepts/module-registry)
- Calculer des règles de filtre depuis une description en langage naturel et prévisualiser le résultat

Il ne peut pas :

- Accéder aux données d'autres users
- Modifier billing, paramètres compte, ou codes d'invitation
- Faire quoi que ce soit hors du scope normal de permission du user

## Pourquoi pas juste Claude.ai avec outsend en MCP ?

Les deux options coexisteront :

- **BYOK** — pour les users qui veulent l'assistant **dans outsend.xyz**, avec l'UI qui rend nativement les formulaires de recherche et les tables pendant que le modèle orchestre.
- **[MCP](/docs/fr/integration/mcp)** — pour les users qui veulent piloter outsend depuis leur propre Claude.ai ou Claude Desktop, avec leur abonnement existant.

Les deux patterns sont complémentaires, pas concurrents.

## Pour aller plus loin

- [Intégration MCP](/docs/fr/integration/mcp) — piloter outsend depuis son propre client AI
- [llms.txt](/docs/fr/integration/llms-txt) — pointer un assistant AI vers la doc


<!-- doc: integration/llms-txt -->

---
title: llms.txt — documentation AI-friendly
slug: integration/llms-txt
section: Intégration
summary: Une seule URL expose toute la doc outsend à n'importe quel assistant AI — pas d'auth, pas de scraping, pas de parsing.
---

La doc outsend est publiée au format [llms.txt](https://llmstxt.org). N'importe quel assistant AI — Claude, ChatGPT, Cursor, Perplexity, ou un modèle local — peut ingérer la référence complète en un seul fetch.

## Les deux endpoints

| URL                                                                       | Rôle                                                                                |
|---------------------------------------------------------------------------|-------------------------------------------------------------------------------------|
| [`/docs/fr/llms.txt`](/docs/fr/llms.txt)                                  | Index plat — une ligne par page, avec titre + URL + résumé une ligne                |
| [`/docs/fr/llms-full.txt`](/docs/fr/llms-full.txt)                        | Bundle complet — chaque page concaténée, délimitée par `<!-- doc: <slug> -->`       |

Les deux endpoints renvoient du `text/plain`, sans auth, sans rate limit, sans rendering JS requis.

## Usage depuis un assistant AI

La plupart des clients AI détectent désormais `llms.txt` automatiquement quand un domaine est mentionné. Pour ceux qui ne le font pas, coller l'URL directement :

```
https://outsend.xyz/docs/fr/llms-full.txt
```

Le bundle pèse ~150 KB et tient confortablement dans n'importe quelle fenêtre de contexte moderne.

## Bundles par section

Pour des périmètres plus serrés :

| URL                                              | Contenu                              |
|--------------------------------------------------|--------------------------------------|
| `/docs/fr/_bundle/concepts.txt`                  | Seulement les pages Concepts         |
| `/docs/fr/_bundle/modules.txt`                   | Seulement les pages Modules          |
| `/docs/fr/_bundle/api.txt`                       | Seulement la référence API           |
| `/docs/fr/_bundle/integration.txt`               | Seulement les pages Intégration      |

## Le bouton Copy

Chaque page de cette doc a un bouton **Copy** en haut à droite. Mêmes bundles, mais en un clic vers le presse-papier :

- Copier cette page (markdown brut)
- Copier cette section
- Copier toute la doc

L'action "Copier toute la doc" est le chemin recommandé quand on confie la doc à un assistant AI en interactif.

## Pourquoi ça compte

Les assistants AI deviennent la couche d'intégration entre produits SaaS. Une doc qu'un assistant peut ingérer proprement — sans scraping, sans flow de login, sans parsing HTML — est intégrable ; une qui ne le peut pas, non.

La doc outsend est conçue pour être lisible par un humain, mais sa **première audience** est le LLM qui va rédiger le code d'intégration, écrire le template de prompt, ou diagnostiquer le pipeline mal configuré.

## Pour aller plus loin

- [Vue d'ensemble API](/docs/fr/api/overview) — la surface que l'assistant va appeler
- [MCP](/docs/fr/integration/mcp) — le protocole que l'assistant devrait préférer


<!-- doc: integration/mcp -->

---
title: MCP — Model Context Protocol
slug: integration/mcp
section: Intégration
summary: Piloter outsend depuis son propre Claude.ai, Claude Desktop, ou tout client compatible MCP. Son abonnement, ses tokens.
---

> **Statut : prévu.** Le serveur MCP est sur la roadmap. Cette page décrit le contrat ciblé. Sortie annoncée dans le changelog.

L'intégration MCP expose outsend comme **serveur MCP distant**, branchable par tout client compatible : Claude.ai (custom connectors), Claude Desktop, Claude Code, Cursor, ou tout futur client qui parle le protocole.

Le user se connecte une fois avec son compte outsend, et ensuite le client AI peut lancer des recherches, construire des pipelines, lire des résultats — en utilisant **son propre abonnement LLM** (aucun coût LLM côté outsend).

## Comment ça marchera

1. Le user ouvre les settings de son client MCP (ex. Claude.ai → Settings → Connectors → Add custom connector).
2. Il colle `https://outsend.xyz/mcp` et s'authentifie.
3. Le serveur MCP renvoie la liste des tools disponibles (voir ci-dessous).
4. Le modèle peut appeler ces tools au nom du user ; chaque appel tape l'API outsend en tant que ce user.

## Tools prévus

| Tool                      | Action                                                              |
|---------------------------|---------------------------------------------------------------------|
| `list_jobs`               | Lister les jobs récents du user                                     |
| `get_job`                 | Récupérer status, compteurs, et échantillon de résultats            |
| `create_scrap_job`        | Démarrer une extraction Google Maps                                 |
| `create_enrich_job`       | Démarrer un enrichissement sur un job existant (emails, socials…)   |
| `list_pipelines`          | Lister les pipelines du user                                        |
| `create_pipeline`         | Composer un pipeline depuis une description                         |
| `run_pipeline`            | Exécuter un pipeline sauvegardé                                     |
| `list_veilles`            | Lister les veilles récurrentes                                      |
| `create_veille`           | Enregistrer un job existant comme veille                            |
| `get_signals`             | Récupérer les derniers signaux de réputation d'une veille           |

Chaque tool a un schéma d'arguments calé sur l'[endpoint API](/docs/fr/api/overview) correspondant.

## Périmètre et limites

Le serveur MCP hérite des permissions normales du user :

- Pas d'accès aux données d'autres users.
- Mêmes rate limits que l'API REST.
- Pas de modification du billing, des paramètres compte, ou des codes d'invitation.

## BYOK vs MCP

| Pattern | Où vit le chat                                  | Qui paie les tokens LLM           |
|---------|-------------------------------------------------|-----------------------------------|
| [BYOK](/docs/fr/integration/byok) | Dans outsend.xyz                      | Le user, via une clé API collée   |
| MCP     | Dans le client AI existant du user              | Le user, via son abonnement       |

Les deux patterns coexistent. BYOK si l'assistant doit vivre dans l'UI outsend ; MCP s'il doit vivre là où le user travaille déjà.

## Pour aller plus loin

- [BYOK](/docs/fr/integration/byok) — assistant dans outsend.xyz
- [llms.txt](/docs/fr/integration/llms-txt) — donner accès à la doc à n'importe quel assistant AI


<!-- doc: modules/ads_intelligence -->

---
title: Profil marketing
slug: modules/ads_intelligence
section: Modules
---

# Profil marketing

Le module `ads_intelligence` profile la stack marketing du site de chaque POI et condense les résultats en un score unique de maturité marketing 0–100. Il découpe une liste de prospects en deux segments actionnables : les entreprises qui investissent déjà en acquisition payante et celles encore en premier contact froid.

Les détections croisent la page d'accueil avec des listes de filtres maintenues par la communauté (uBlock Origin, EasyList, EasyPrivacy) plus une table de signatures outsend curatée, couvrant pixels publicitaires, réseaux de retargeting, CMP, CRM marketing et widgets de chat.

## Entrées

Seuls les items avec un `site_web` non vide sont traités.

| Champ           | Type   | Requis | Notes                                    |
|-----------------|--------|--------|------------------------------------------|
| `site_web`      | string | oui    | URL absolue du site du POI               |
| `nom`           | string | non    | Repassé pour reporting                   |
| `place_id`      | string | non    | Sert à recoller à la liste source        |
| `source_job_id` | string | non    | ID d'un job `scrap` amont à chaîner      |

Taille de lot : 1 à 10 000 items par job.

## Sorties

Une ligne par POI traité. Les pixels paid-media et le retargeting pèsent le plus dans le score ; les widgets de chat le moins.

| Colonne           | Type     | Description                                                                 |
|-------------------|----------|-----------------------------------------------------------------------------|
| `ads_score`       | integer  | Score de maturité marketing, 0–100                                          |
| `pixels_detected` | string[] | Pixels publicitaires trouvés sur la page (ex. `meta`, `google_ads`, `tiktok`) |
| `crm_detected`    | string   | CRM marketing identifié, le cas échéant (ex. `hubspot`, `klaviyo`, `brevo`) |
| `chat_widget`     | string   | Solution de chat identifiée, le cas échéant (ex. `intercom`, `crisp`, `drift`) |
| `marketing_tools` | string[] | Autres technologies marketing (CMP, CDP, affiliation, réseaux de retargeting) |

Champs granulaires aussi stockés : `ads_active`, `ads_networks`, `pixel_meta`, `pixel_google_ads`, `cmp_vendor`, `retargeting`, `crm_marketing`, `chat_widgets`.

## Cycle de vie

Cycle de vie standard des jobs outsend ; voir [/docs/fr/concepts/jobs-lifecycle](/docs/fr/concepts/jobs-lifecycle). La progression est reportée par item en unité `sites`.

## Pipeline

| Direction  | Clés                                                                                                              |
|------------|-------------------------------------------------------------------------------------------------------------------|
| `needs`    | `site_web`                                                                                                        |
| `produces` | `ads_active`, `ads_score`, `ads_networks`, `pixel_meta`, `pixel_google_ads`, `cmp_vendor`, `retargeting`, `crm_marketing`, `chat_widgets` |

Tout job amont qui émet `site_web` (typiquement `scrap`) peut alimenter `ads_intelligence`. Le sélecteur de job se positionne par défaut sur le dernier job `scrap` du compte courant.

## Endpoints

### Créer un job

`POST /api/jobs/ads-intelligence`

```json
{
  "items": [
    { "site_web": "https://example.com", "nom": "Example", "place_id": "..." }
  ],
  "source_job_id": "optional-upstream-job-uuid"
}
```

Réponse : document `JobPublic` décrivant le job nouvellement créé (`id`, `status`, `job_type`, `output_filename`, `ef_cost`, timestamps).

| Statut | Quand                                                                  |
|--------|------------------------------------------------------------------------|
| `400`  | Aucun item n'a de `site_web`, ou quota EF par job dépassé              |
| `401`  | Session manquante ou invalide                                          |
| `403`  | Compte inactif                                                         |
| `422`  | Payload non conforme au schéma (ex. `items` vide ou > 10 000)          |

L'état, la progression et les résultats du job se lisent via les endpoints partagés (`GET /api/jobs/{id}`, `GET /api/jobs/{id}/results`, flux SSE).

## Limites

Voir [/docs/fr/concepts/limits](/docs/fr/concepts/limits). Coût EF par item : ~1 / 3 / 3700 EF. Temps mur par item : 0,6 – 6 s.

## Erreurs

| Erreur                                  | Cause                                                          |
|-----------------------------------------|----------------------------------------------------------------|
| `Aucun établissement avec site web`     | Tous les items manquaient de `site_web` après normalisation    |
| `Quota dépassé`                         | Coût EF estimé au-dessus du plafond par job                    |
| Échec de fetch au niveau item           | Enregistré sur la ligne ; le job continue avec l'item suivant  |
| Page d'accueil vide / réponse non-HTML  | Ligne émise avec `ads_score = 0` et détections vides           |

## Pour aller plus loin

Associer `ads_intelligence` aux modules suivants pour enrichir le profil prospect :

- [`techstack`](/docs/fr/modules/techstack) — empreinte complète CMS, framework et hébergement.
- [`pricing`](/docs/fr/modules/pricing) — fait remonter les tarifs visibles et les conditions commerciales.
- [`pagespeed`](/docs/fr/modules/pagespeed) — Core Web Vitals et budget de performance.


<!-- doc: modules/brand_assets -->

---
title: Assets visuels
slug: modules/brand_assets
section: Modules
---

# Assets visuels

Extrait l'identité visuelle de chaque prospect depuis son propre site : logo principal, variantes de logo, favicon, couleur de marque dominante, palette harmonique dérivée du logo. Capture d'écran de la page d'accueil en option. Toutes les images sont ré-hébergées dans le stockage privé de l'appelant, ce qui évite qu'un lien casse si le prospect change de CDN.

Le module est en lecture seule contre le site du prospect — aucune soumission de formulaire, aucune connexion, aucun franchissement d'authentification.

## Inputs

Une ligne par POI. Seul `site_web` est requis ; le reste est transmis en passe-plat.

| Champ      | Type   | Requis | Notes                                                  |
|------------|--------|--------|--------------------------------------------------------|
| `site_web` | string | oui    | URL HTTP(S) du site du prospect.                       |
| `nom`      | string | non    | Nom affiché, exposé dans l'UI.                         |

Un batch accepte 1 à 10 000 lignes. Les lignes sans `site_web` sont écartées avant la mise en file.

Options au niveau du job :

| Option               | Type   | Défaut  | Notes                                                       |
|----------------------|--------|---------|-------------------------------------------------------------|
| `source_job_id`      | string | null    | Job parent dans la chaîne du pipeline.                      |
| `capture_screenshot` | bool   | false   | Ajoute une capture de la page d'accueil. ~5× plus lent.     |

## Outputs

Sortie par ligne. Les URLs locales pointent vers des assets ré-hébergés sous `/api/brand-assets/<owner_user_id>/<sha256>.<ext>` et ne sont servies qu'au propriétaire (ou à un admin).

| Colonne                       | Type    | Notes                                                                       |
|-------------------------------|---------|-----------------------------------------------------------------------------|
| `logo_url`                    | string  | URL source du logo principal trouvée sur le site du prospect.               |
| `logo_local_url`              | string  | Copie ré-hébergée du logo principal, URL stable.                            |
| `logo_source`                 | string  | Origine du logo (par exemple `og:image`, JSON-LD, apple-touch).             |
| `logo_variants_local_urls`    | list    | Variantes ré-hébergées : apple-touch, mask-icon, monochrome, etc.           |
| `favicon_url`                 | string  | URL source du favicon de meilleure qualité détecté.                         |
| `favicon_local_url`           | string  | Copie ré-hébergée du favicon.                                               |
| `brand_color`                 | string  | Couleur de marque dominante au format hex.                                  |
| `brand_color_source`          | string  | Origine de la couleur (meta theme-color, échantillonnage du logo, etc.).    |
| `brand_palette`               | list    | Cinq couleurs hex harmoniques dérivées du logo.                             |
| `screenshot_local_url`        | string  | Capture de la page d'accueil. Renseigné si `capture_screenshot=true`.       |

Les binaires sont stockés sous `data/brand_assets/<user_id>/<sha256>.<ext>`. Extensions autorisées : `svg`, `png`, `jpg`, `jpeg`, `webp`, `gif`, `ico`, `avif`. Chaque asset est haché pour la déduplication entre lignes d'un même propriétaire.

## Cycle de vie

États de job standard — voir [Cycle de vie des jobs](/docs/fr/concepts/jobs-lifecycle). Les erreurs HTTP par ligne ne font jamais échouer le job : une ligne en échec porte `fetch_error` et un `logo_local_url` à null.

## Pipeline

| Needs       | Produces                                                                                                                                                  |
|-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
| `site_web`  | `logo_url`, `logo_local_url`, `logo_variants_local_urls`, `favicon_url`, `favicon_local_url`, `brand_color`, `brand_palette`, `screenshot_local_url`      |

`pipelinable: true`, s'insère après toute étape produisant `site_web` — typiquement un parent `scrap`. `supports_veille: false` : l'identité de marque est traitée comme une extraction one-shot, pas un signal récurrent.

## Endpoints

### Créer un job batch

```
POST /api/jobs/brand-assets
```

Body :

```json
{
  "items": [
    {"nom": "Stripe", "site_web": "https://stripe.com"}
  ],
  "source_job_id": null,
  "capture_screenshot": false
}
```

Retourne une enveloppe `JobPublic`. Authentification : tout utilisateur actif.

### Lookup live mono-domaine

```
GET /api/brand-lookup?domain=<domain>&refresh=<bool>
```

One-shot, aucun job batch créé. Le premier appel sur un domaine donné fait un fetch live (~2–3s) et stocke le résultat dans un cache par utilisateur. Les appels suivants dans les sept jours retournent instantanément le profil mis en cache. `refresh=true` force un re-fetch.

Forme de la réponse :

```json
{
  "domain": "stripe.com",
  "cached": false,
  "cached_at": null,
  "profile": {
    "status": "ok",
    "logo_url": "...",
    "logo_local_url": "...",
    "logo_source": "og:image",
    "logo_variants_local_urls": ["..."],
    "favicon_url": "...",
    "favicon_local_url": "...",
    "brand_color": "#635BFF",
    "brand_color_source": "theme-color",
    "brand_palette": ["#635BFF", "..."],
    "http_status": 200,
    "final_url": "https://stripe.com/",
    "fetch_error": null
  }
}
```

### Servir un asset ré-hébergé

```
GET /api/brand-assets/<owner_user_id>/<sha256>.<ext>
```

Isolation par propriétaire : seul le propriétaire (ou un admin) peut lire les assets du namespace. Les noms de fichiers sont validés par une regex stricte ; les tentatives de path traversal sont rejetées avec `400`.

Pour les quotas et caps globaux, voir [Limites](/docs/fr/concepts/limits). TTL du cache brand-lookup : 7 jours, par utilisateur, par domaine. Le mode screenshot multiplie le coût par ligne par ~5 ; opt-in uniquement.

## Erreurs

| Code | Signification                                                                  |
|------|--------------------------------------------------------------------------------|
| 400  | `Aucun établissement avec site web` — aucune ligne ne porte un `site_web` exploitable. |
| 400  | Domaine invalide sur `/api/brand-lookup`.                                      |
| 400  | Nom de fichier d'asset invalide sur l'endpoint de service.                     |
| 403  | Accès à un asset appartenant à un autre utilisateur.                           |
| 502  | Lookup live en échec côté amont (`Lookup failed: <type>: <message>`).          |

## Pour aller plus loin

- [techstack](/docs/fr/modules/techstack) — détecter le CMS, l'analytics et les frameworks derrière le même `site_web`.
- [ads_intelligence](/docs/fr/modules/ads_intelligence) — révéler l'empreinte d'acquisition payante du prospect en complément de l'identité visuelle.


<!-- doc: modules/dead_check -->

---
title: Vérification fermeture
slug: modules/dead_check
section: Modules
summary: Vérifier si chaque point d'intérêt est toujours en activité, a fermé, ou est incertain — à partir des signaux réels d'abandon sur son site.
---

## Objet

Le module `dead_check` inspecte le site web associé à chaque point d'intérêt (POI) et détermine si l'activité sous-jacente semble vivante, fermée ou incertaine. Il corrèle plusieurs signaux d'abandon sur le même domaine : nom de domaine en expiration, redirection vers une propriété sans rapport (revente ou rebranding), pages de parking déguisées en vrais sites, certificats TLS expirés ou invalides. Les annuaires (Doctolib, Pages Jaunes, Yelp, etc.) sont reconnus comme tels plutôt que catalogués à tort en site personnel.

## Inputs

Une liste de POI, chacun portant au moins un site web. Les entrées sans `site_web` sont filtrées à la soumission.

| Champ | Type | Requis | Description |
|---|---|---|---|
| `items` | array d'objets POI | oui | 1 à 10 000 entrées. Les entrées sans `site_web` sont écartées avant exécution. |
| `source_job_id` | string | non | Identifiant du job amont produisant la liste (typiquement un `scrap`). Sert au lignage dans l'UI et le pipeline. |

Aucun autre paramètre : le module tourne dans un mode unique.

## Outputs

Chaque POI d'entrée est enrichi du verdict de fermeture pour son site. Les colonnes POI d'origine sont conservées et la suivante est ajoutée :

| Colonne | Type | Description |
|---|---|---|
| `site_alive` | `"open"` \| `"closed"` \| `"uncertain"` | Verdict final. `open` = site se comporte comme une présence d'activité, `closed` = signaux convergents d'abandon, `uncertain` = signaux trop minces pour trancher. |

L'unité de progression pendant l'exécution est `sites` ; l'unité de résultat aussi.

## Cycle de vie

États de job standard — voir [Cycle de vie des jobs](/docs/fr/concepts/jobs-lifecycle). Des compteurs partiels sont diffusés en SSE, ce qui permet de consommer les premiers verdicts sans attendre l'export final.

## Pipeline

Pipelinable ; typiquement inséré juste après l'étape produisant la liste, avant tout enrichissement coûteux.

| Slot | Valeur |
|---|---|
| `needs` | `site_web` |
| `produces` | `site_alive` |
| Catégorie | `verify` |
| Amont typique | `scrap` |
| Aval typique | `emails`, `techstack`, `ads_intelligence`, `filter` |

Pattern courant : `scrap` puis `dead_check` puis `filter` (garder `site_alive = "open"`) puis n'importe quel module d'enrichissement — pour ne pas payer de la donnée d'outreach sur des activités fermées.

## Endpoints

Créer un job :

```
POST /api/jobs/dead-check
Content-Type: application/json

{
  "items": [
    { "site_web": "https://example.com", "nom": "Example Co" }
  ],
  "source_job_id": "…"
}
```

Réponse : un objet `JobPublic` avec `id`, `status` et les métadonnées de job standard. Poller `GET /api/jobs/{id}` ou s'abonner au flux SSE pour la progression ; télécharger le CSV final depuis la page de détail du job une fois `status = "done"`.

Pour la surface complète de l'API des jobs (liste, détail, cancel, export, events), voir [API Jobs](/docs/fr/api/jobs). Pour les quotas par compte, voir [Limites](/docs/fr/concepts/limits).

## Erreurs

| HTTP | `detail` | Cause |
|---|---|---|
| 400 | `Aucun établissement avec site web` | Aucun item d'entrée ne porte de champ `site_web`. |
| 400 | `Quota dépassé : …` | Le coût estimé dépasse le quota équivalent-France par job. |
| 401 / 403 | — | Session manquante ou inactive. |

Les erreurs levées après la création du job remontent sur la page de détail et via l'événement SSE `error` ; le job termine en `status = "error"` et les résultats partiels, s'il y en a, restent téléchargeables.

## Pour aller plus loin

- [filter](/docs/fr/modules/filter) — ne garder que les POI dont `site_alive` vaut `open` (ou exclure `closed`) avant d'engager du budget sur l'enrichissement.
- [reviews](/docs/fr/modules/reviews) — pour les POI marqués `uncertain`, les avis récents départagent fortement entre activité en marche et activité dormante.


<!-- doc: modules/delivery_check -->

---
title: Délivrabilité inbox
slug: modules/delivery_check
section: Modules
---

# Délivrabilité inbox

Teste où un message envoyé depuis un domaine donné atterrit réellement. Le module n'envoie rien à la place de l'appelant — le vrai message est envoyé à quinze boîtes seed, et le module remonte où chacune l'a classé : inbox principale, onglet secondaire (Promotions, Social) ou spam.

Le résultat est un instantané de la façon dont une boîte destinataire a traité ce message précis, depuis ce domaine précis, à ce moment précis. Ce n'est ni une simulation, ni un lookup de réputation, ni une inspection d'en-têtes. Le module répond à une seule question : *si ce message est envoyé depuis ce domaine maintenant, où va-t-il ?*

## Inputs

Un job de test prend deux valeurs.

| Champ | Requis | Description |
| --- | --- | --- |
| `domain` | oui | Le domaine d'envoi à tester, en minuscules, sans `@` (par exemple `acme.fr`). Doit contenir un point et faire 3 à 120 caractères. |
| `subject_filter` | non | Sous-chaîne optionnelle comparée aux sujets dans les boîtes seed. Utile pour désambiguïser quand plusieurs tests tournent en parallèle depuis le même domaine. Jusqu'à 120 caractères. |

Le module ne prend pas de liste de destinataires. La délivrabilité inbox est un job standalone — il ne fait pas partie d'un pipeline et ne peut pas consommer la sortie d'un autre job.

## Outputs

Le job écrit une ligne par boîte seed dans `results_delivery.csv`. Quinze boîtes seed sont interrogées ; chaque ligne décrit ce que cette boîte a observé.

| Colonne | Description |
| --- | --- |
| `seed_email` | Adresse de la boîte de test concernée par la ligne. |
| `seed_kind` | Famille de fournisseur de la seed (sert à grouper les résultats par type de boîte). |
| `status` | `received` si le message a été trouvé, sinon un état vide ou en attente. |
| `placement` | Où le message a atterri : `Inbox principal`, `Inbox · <tab>` (par exemple Promotions, Social), `Spam`, ou vide si non reçu. |
| `subject` | Sujet tel qu'observé dans la boîte seed. |
| `received_relative` | Délai lisible entre envoi et observation (par exemple `2 min`). |

L'endpoint de rapport structuré agrège ces lignes en un résumé.

| Champ | Description |
| --- | --- |
| `received` | Nombre de seeds ayant observé le message. |
| `total` | Total de boîtes seed interrogées (15). |
| `missing` | `total - received`. |
| `primary` | Seeds dont le placement est `Inbox principal`. |
| `primary_pct` | Taux d'inbox principale en pourcentage de `received`. |
| `inbox_secondary` | Seeds dont le placement est un onglet inbox non-principal. |
| `promotions` | Seeds dont le placement correspond à Promotions ou Social. |
| `spam` | Seeds dont le placement est `Spam`. |
| `spam_pct` | Taux de spam en pourcentage de `received`. |
| `verdict` | Verdict contextuel — voir ci-dessous. |
| `seeds` | Tableau par seed décrit dans la table précédente. |

L'objet `verdict` porte un jugement en une ligne et une note actionnable.

| `verdict.label` | Quand |
| --- | --- |
| `EXCELLENT` | `primary_pct` ≥ 90. |
| `TRÈS BON` | `primary_pct` ≥ 70. |
| `MOYEN` | `primary_pct` ≥ 50. |
| `MAUVAIS` | `spam_pct` ≥ 50. |
| `INSUFFISANT` | La plupart des messages ont atterri dans des onglets secondaires. |
| `EN ATTENTE` | Rien reçu pour l'instant. |

## Cycle de vie

États de job standard — voir [Cycle de vie des jobs](/docs/fr/concepts/jobs-lifecycle). Le déroulé d'exécution : créer le job, récupérer les seeds via `GET /api/delivery-check/seeds`, envoyer le vrai message aux quinze depuis le domaine testé, attendre que le worker poll jusqu'à ce que toutes les seeds remontent `received` ou qu'un timeout déclenche, puis lire le rapport agrégé.

Le module ne se chaîne pas. Sa sortie n'est pas réutilisable en entrée d'un autre job — la délivrabilité inbox est listée dans le set de jobs non-chaînables aux côtés de `viewport_test`.

## Pipeline

La délivrabilité inbox est `standalone_only`.

- **Needs :** rien. Le job prend une chaîne de domaine, pas une liste d'enregistrements.
- **Produces :** aucune colonne réutilisable. Le CSV existe pour l'export mais n'est pas exposé au graphe pipeline.
- **Pipelinable :** non.
- **Veille :** non supportée.

Si une campagne doit réagir à un résultat de placement, le rapport est consommé via l'API et branché dans une orchestration externe — le module ne nourrira pas directement un autre nœud.

## Endpoints

| Méthode | Chemin | Rôle |
| --- | --- | --- |
| `POST` | `/api/jobs/delivery-check` | Créer un job delivery-check. Body : `{ "domain": "...", "subject_filter": "..." }`. Retourne l'objet job public. |
| `GET` | `/api/delivery-check/seeds` | Lister les quinze adresses seed auxquelles envoyer le message de test. |
| `GET` | `/api/jobs/{job_id}/delivery-result` | Rapport agrégé avec résumé, verdict et lignes par seed. |
| `GET` | `/api/jobs/{job_id}` | Statut de job standard (queued, running, done, failed). |

Tous les endpoints requièrent un utilisateur authentifié et actif. Lire le job d'un autre utilisateur retourne `403`.

Le budget par job est fixé à quinze observations seed ; pas de slider, pas d'override. La délivrabilité inbox ne consomme pas de crédits scraping (`ef_per_item: 0`), même si le quota par utilisateur s'applique encore. Une exécution complète atterrit typiquement entre deux et huit minutes après l'envoi du message seed. Le domaine doit contenir un point et est mis en minuscules en interne. Pour les caps globaux, voir [Limites](/docs/fr/concepts/limits).

## Erreurs

| Statut | Raison |
| --- | --- |
| `400` | `Domaine d'envoi invalide` — le domaine est vide ou ne contient pas de point. |
| `400` | `Quota dépassé` — `MAX_EF_PER_JOB` atteint. La délivrabilité inbox est gratuite en soi, mais le check quota s'applique quand même. |
| `400` | `Pas un job de test de délivrabilité` — `/delivery-result` appelé sur un job dont le type n'est pas `delivery_check`. |
| `403` | Le job appartient à un autre utilisateur. |
| `404` | L'ID de job n'existe pas. |
| `410` | Le CSV du job a expiré et a été supprimé. |

Si le rapport retourne `received: 0` après l'exécution du worker, le message seed n'est jamais arrivé — soit il n'a pas été envoyé, soit il a été bloqué entièrement, soit le domaine est sur une blocklist complète. Renvoyer aux seeds et re-poller avant de conclure.

## Pour aller plus loin

- [Vérification emails](/docs/fr/modules/verify_emails) — nettoyer une liste d'adresses avant envoi, pour que le test seed reflète ce que verra le sous-ensemble délivrable.
- [Ads intelligence](/docs/fr/modules/ads_intelligence) — une fois le placement solide, voir quels concurrents paient pour de la visibilité sur la même audience.


<!-- doc: modules/emails -->

---
title: Emails
slug: modules/emails
section: Modules
summary: Trouve une adresse email exploitable pour chaque point d'intérêt d'une liste existante.
---

## Purpose

Module d'enrichissement : déduit des adresses email depuis le site web de chaque POI. Les boîtes nominatives sont remontées avant les génériques (`info@`, `contact@`, `hello@`). Aucune adresse n'est inventée — vide quand aucun candidat ne qualifie.

## Inputs

Une liste de POI portant chacun au moins un site web. Les deux modes d'exécution diffèrent en couverture vs coût.

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | array of POI objects | yes | 1 à 10 000 entrées. Les entrées sans `site_web` sont filtrées avant l'exécution. |
| `mode` | `"normal"` \| `"deep"` | no, défaut `"normal"` | `normal` exécute l'extraction standard. `deep` exécute un second passage exhaustif et requiert un run `normal` déjà terminé sur la même source. |
| `source_job_id` | string | conditionnel | Requis quand `mode = "deep"`. Doit référencer un job `emails` `done` en mode `normal` sur la même source amont. |

## Outputs

Chaque POI d'entrée est augmenté de jusqu'à deux champs email. Les colonnes POI d'origine sont conservées ; le job ajoute :

| Column | Type | Description |
|---|---|---|
| `email` | string \| null | Meilleure adresse classée pour ce POI. Vide quand aucun candidat ne qualifie. |
| `email_personal` | string \| null | Renseigné quand le meilleur candidat ressemble à une boîte personnelle plutôt qu'à une adresse de rôle générique. |

Le classement est déterministe. Unité de progression : `sites`. Unité de résultat : `emails`.

## Lifecycle

Cycle de vie standard : voir [Jobs & lifecycle](/docs/fr/concepts/jobs-lifecycle).

## Pipeline

| Slot | Value |
|---|---|
| `needs` | `poi_list` (POI avec un champ `site_web`) |
| `produces` | `enriched_list` (POI augmentés de `email`, `email_personal`) |
| Amont typique | `scrap` |
| Aval typique | `verify_emails`, `delivery_check`, `filter` |

Config pipeline par défaut : `{ "mode": "normal" }`. `deep` est conçu comme une relance manuelle sur les POI revenus vides du run normal.

## Endpoints

Création d'un job :

```
POST /api/jobs/emails
Content-Type: application/json

{
  "items": [
    { "site_web": "https://example.com", "nom": "Example Co" }
  ],
  "mode": "normal"
}
```

Réponse : un objet `JobPublic` avec `id`, `status` et les métadonnées standard. Pour la surface API job complète, voir [Jobs API](/docs/fr/api/jobs).

## Limits

Quotas globaux : voir [/docs/fr/concepts/limits](/docs/fr/concepts/limits). Plafonds spécifiques au module :

| Limit | Value |
|---|---|
| Nombre minimum d'items par job | 1 |
| Nombre maximum d'items par job | 10 000 |
| Items retenus | uniquement ceux avec un `site_web` non vide |
| Prérequis mode `deep` | Un job `emails` `normal` `done` sur le même `source_job_id` |

Les items sans site web sont écartés à la normalisation. Si la liste filtrée est vide, le job est rejeté avec `"Aucun établissement avec site web"`.

## Errors

| HTTP | `detail` | Cause |
|---|---|---|
| 400 | `Mode email invalide : ... (attendu: normal | deep)` | `mode` n'est ni `normal` ni `deep`. |
| 400 | `Aucun établissement avec site web` | Aucun item d'entrée ne porte un champ `site_web`. |
| 400 | `Le mode Deep Extract n'est dispo qu'après une extraction normale ...` | `mode = "deep"` soumis sans run normal valide préalable sur la même source. |
| 400 | `Quota dépassé : ...` | Coût estimé supérieur au quota équivalent-France per-job. |
| 401 / 403 | — | Session absente ou inactive. |

Les erreurs levées après création remontent via l'événement SSE `error` ; le job termine en `status = "error"` et les résultats partiels restent téléchargeables.

## What's next

- [verify_emails](/docs/fr/modules/verify-emails) — confirme que chaque adresse est délivrable avant envoi.
- [delivery_check](/docs/fr/modules/delivery-check) — mesure le placement inbox sur un vrai message.
- [filter](/docs/fr/modules/filter) — ne garder que les POI ayant une adresse personnelle, exclure les domaines jetables, ou échantillonner la liste.


<!-- doc: modules/filter -->

---
title: Filtrer
slug: modules/filter
section: Modules
---

## Objectif

Le module `filter` restreint un jeu de données aux lignes qui satisfont un ensemble de règles. Il est interne au pipeline (voir [/docs/fr/concepts/pipeline-orchestration](/docs/fr/concepts/pipeline-orchestration)) : il consomme le CSV produit par un nœud amont et émet un sous-ensemble strict, avec les mêmes colonnes. Aucune nouvelle donnée n'est récupérée et aucune colonne n'est ajoutée. Filtrer tôt économise le budget sur les étapes d'enrichissement coûteuses qui suivent.

## Entrées

Les règles sont lues depuis l'objet `config` du nœud et appliquées ligne par ligne dans un ordre fixe. Chaque clé est optionnelle ; une règle vide est sans effet.

### Règles standard

| Clé | Type | Comportement |
| --- | --- | --- |
| `require_phone` | `bool` | Garde les lignes où `telephone` est non vide. |
| `require_site` | `bool` | Garde les lignes où `site_web` est non vide. |
| `require_email` | `bool` | Garde les lignes où `email` est non vide. |
| `exclude_aggregators` | `bool` | Écarte les lignes dont `site_web` pointe vers un domaine d'agrégateur connu. |
| `alive_only` | `bool` | Garde les lignes dont le `status` de dead-check est `alive` ou `stale`. |
| `has_personal_email` | `bool` | Garde les lignes où au moins une adresse dans `email` est une boîte personnelle (non basée sur un rôle). |
| `rating_min` | `float` | Garde les lignes où `note >= rating_min`. |
| `reviews_min` | `int` | Garde les lignes où `nb_avis >= reviews_min`. |

### Règles avancées

| Clé | Forme | Comportement |
| --- | --- | --- |
| `phone_prefix` | `{ column?, prefixes[], prefix_unparseable_keep? }` | Garde les lignes dont la colonne téléphone commence par l'un des `prefixes` (par ex. `06`, `+33`). Nécessite la bibliothèque `phonenumbers` sur le worker — sinon la règle est journalisée et ignorée. |
| `email_domain` | `{ column?, include[], exclude[], reject_disposable? }` | Garde les lignes dont le domaine d'email est dans `include` (si défini) et pas dans `exclude`. `reject_disposable` écarte les fournisseurs jetables connus. |
| `category` | `{ column, values[] }` | Garde les lignes dont la valeur de `column` est contenue dans `values`. |
| `dedup_column` | `string` | Fusionne les lignes partageant la même valeur sur cette colonne (la première ligne l'emporte). |

### Échantillonnage

| Clé | Type | Comportement |
| --- | --- | --- |
| `sample_type` | `"n" \| "pct" \| ""` | Sélectionne le mode d'échantillonnage appliqué après les règles ci-dessus. |
| `sample_n` | `int` | Garde les `n` premières lignes retenues. |
| `sample_pct` | `0..100` | Garde un pourcentage des lignes retenues. |
| `sample_seed` | `int` | Graine pour un échantillonnage aléatoire reproductible. |

Ordre d'application : drapeaux d'exigence → agrégateurs/alive/note/avis → email personnel → `phone_prefix` → `email_domain` → `category` → `dedup_column` → échantillonnage.

## Sorties

Le module écrit un CSV avec les mêmes colonnes que le nœud amont, contenant uniquement les lignes retenues. Il ne produit pas de nouveaux champs (`needs: []`, `produces: []`, `pipeline_passthrough: true`).

| Champ | Valeur |
| --- | --- |
| `output_filename` | `results_<label>.csv` (même forme qu'amont) |
| `n_items` | Nombre de lignes gardées |
| `progress_unit` | `lignes` |
| `results_unit` | `lignes gardées` |

## Cycle de vie

Cycle de vie de job standard — voir [/docs/fr/concepts/jobs-lifecycle](/docs/fr/concepts/jobs-lifecycle). Les jobs de filtrage tournent dans le pool `parallel`, sont créés par le runner de pipeline, et ne sont exposés ni sur le dashboard ni dans « Nouveau job ».

## Pipeline

| Attribut | Valeur |
| --- | --- |
| `category` | `process` |
| `pipelinable` | `true` |
| `pipeline_passthrough` | `true` |
| `needs` | `[]` (fonctionne sur tout type amont) |
| `produces` | `[]` |
| `hidden_from_new_job` | `true` |
| `hidden_from_dashboard` | `true` |

`filter` accepte tout module amont. L'UI n'expose que les règles avancées dont le champ cible est effectivement présent dans la sortie amont — par exemple, le bloc `phone_prefix` n'est affiché que si un nœud amont produit un champ `phone`.

## Endpoints

`filter` est un type de job interne au pipeline (voir [/docs/fr/concepts/pipeline-orchestration](/docs/fr/concepts/pipeline-orchestration)). Il n'a pas d'endpoint public `POST /api/jobs/filter` : les jobs de filtrage sont créés par le runner de pipeline et configurés via la définition du pipeline.

Deux endpoints sont exposés aux utilisateurs :

### Aperçu de filtre

`POST /api/pipelines/{pipeline_id}/nodes/{node_id}/filter-preview`

Applique un ensemble de règles au CSV du nœud amont en mémoire et renvoie le nombre de lignes qui correspondraient — sans créer de job. Utilisé par l'éditeur pour un retour en direct pendant l'édition des règles.

Requête :

```json
{
  "rules": {
    "require_email": true,
    "phone_prefix": { "column": "telephone", "prefixes": ["06", "+33"] },
    "sample_type": "pct",
    "sample_pct": 25
  }
}
```

Réponse :

| Champ | Type | Notes |
| --- | --- | --- |
| `total` | `int` | Lignes lues depuis le CSV amont. |
| `matched` | `int` | Lignes gardées après les règles. |
| `samples` | `array` | Jusqu'à 5 lignes retenues, colonnes vides retirées. |
| `predecessor_job_id` | `string` | Job dont le CSV a été prévisualisé. |
| `fieldnames` | `string[]` | Colonnes du CSV amont. |
| `capped` | `bool` | `true` si la lecture a atteint la limite de lignes (voir Limites). |
| `reason` | `string` | Présent uniquement quand `total = 0` : `no_predecessor`, `no_data_yet`, ou `no_csv_found`. |

Erreurs : `404` si le pipeline ou le nœud est absent, `403` si l'appelant n'est pas propriétaire du pipeline, `400` si le nœud n'est pas de type `filter`, `400` si les règles sont mal formées.

### Items du job de pipeline

Une fois le pipeline arrivé au nœud de filtrage, le CSV résultant est servi par les endpoints génériques de jobs :

- `GET /api/jobs/{job_id}/items`
- `GET /api/jobs/{job_id}/output-columns`
- `GET /api/jobs/{job_id}/download`

## Limites

Limites globales — voir [/docs/fr/concepts/limits](/docs/fr/concepts/limits). Spécifiques au module :

| Limite | Valeur |
| --- | --- |
| Plafond de lignes d'aperçu | `5000` lignes (`_PREVIEW_ROWS_LIMIT`). Quand le CSV amont dépasse, l'aperçu lit les 5000 premières lignes et positionne `capped: true`. Le job de filtrage complet, à l'exécution, applique les règles à chaque ligne. |
| Dépendance `phone_prefix` | Nécessite le paquet `phonenumbers` sur le worker. S'il manque, la règle est journalisée et ignorée — les autres règles continuent de s'appliquer. |

## Erreurs

| Code | Cause |
| --- | --- |
| `400` | Le nœud référencé par l'aperçu n'est pas un nœud `filter`, ou `rules` n'est pas un objet valide. |
| `403` | Le pipeline n'appartient pas à l'appelant et l'appelant n'est pas admin. |
| `404` | Le pipeline ou le nœud n'existe pas. |
| `500` | Le CSV amont n'a pas pu être lu (fichier corrompu, absent du disque). |

Un job de filtrage ne tombe en échec que si le CSV amont est illisible ; les valeurs de règles invalides sont ramenées à des no-ops plutôt que de lever une erreur.

## Et après

- [Trier](/docs/fr/modules/sort) — ordonner les lignes filtrées et éventuellement garder le top N.
- [Import](/docs/fr/modules/import) — introduire un CSV externe dans un pipeline pour pouvoir le filtrer comme toute autre source.


<!-- doc: modules/import -->

---
title: Import
slug: modules/import
section: Modules
---

## Objectif

Le module `import` introduit des données externes dans outsend en tant que source de pipeline. Il est interne au pipeline — voir [/docs/fr/concepts/pipeline-orchestration](/docs/fr/concepts/pipeline-orchestration) — et produit une liste de POI normalisée que les nœuds d'enrichissement, de vérification ou de traitement en aval peuvent consommer. Contrairement à `scrap`, `import` ne consomme aucun quota d'extraction (coût EF nul).

## Entrées

La configuration du nœud expose un seul discriminateur, `source`, avec trois modes mutuellement exclusifs.

| Champ | Type | Requis | Description |
|---|---|---|---|
| `source` | `"paste"` \| `"url"` \| `"from_job"` | oui | Sélectionne lequel des trois canaux d'entrée ci-dessous s'applique. Vaut `paste` par défaut si omis. |
| `text` | chaîne | si `source = paste` | Contenu CSV brut. Lu uniquement en mode `paste`. |
| `url` | chaîne | si `source = url` | URL publique de tableur. Lue uniquement en mode `url`. |
| `from_job_id` | chaîne | si `source = from_job` | UUID d'un job de scrap existant appartenant à l'appelant. Lu uniquement en mode `from_job`. |

### `paste` — CSV en ligne

La charge utile `text` est parsée comme CSV par la couche de résolution partagée ([`app/column_map.py`](/docs/fr/concepts/module-registry#correspondance-souple-des-entrees)). Le délimiteur est auto-détecté (virgule, point-virgule ou tabulation) ; UTF-8 est attendu, avec UTF-8 BOM et Latin-1 / cp1252 acceptés en repli. Les en-têtes ne sont **pas** obligatoires : les noms de colonnes sont reconnus de façon souple via des alias acceptés (un en-tête `Website`, `url`, `e-mail` ou `raison sociale` est mappé vers la bonne colonne canonique), et un fichier sans en-tête est auto-détecté — ses colonnes sont alors déduites de leur contenu. Dans tous les cas l'import émet une **`notice`** (bannière d'info sur la page du job, ⓘ au dashboard) indiquant ce qui a été auto-mappé, déduit ou ignoré, pour que le mapping ne soit jamais silencieux.

### `url` — tableur public

La charge utile `url` pointe vers un tableur lisible publiquement (forme typique : `https://docs.google.com/spreadsheets/d/.../edit#gid=0`). La feuille doit être partagée en « toute personne ayant le lien peut consulter » — outsend ne s'authentifie pas auprès de fournisseurs tiers. Le contenu récupéré est parsé selon les mêmes règles CSV que `paste`.

### `from_job` — réutilisation d'un scrap récent

La charge utile `from_job_id` référence un job `scrap` antérieur. La référence est validée côté serveur à la création du job :

| Contrainte | Règle |
|---|---|
| Existence | L'ID du job doit correspondre à un job existant. |
| Propriété | L'appelant doit être propriétaire du job source. |
| Type de job | Doit être `scrap`. Les autres types ne peuvent pas être réimportés par ce canal. |
| Disponibilité | Le CSV source doit encore être téléchargeable (`is_download_available`). |
| Fraîcheur | Le job source doit avoir moins de 7 jours. |

Lorsque la validation passe, l'import résultant hérite de toutes les colonnes produites par le scrap source.

## Sorties

`import` produit une liste de POI normalisée, déclarée dans le registre du pipeline avec `output: "pois"` — la même forme que celle émise par `scrap`. Les nœuds en aval qui acceptent `pois_any` (reviews, emails, socials, dead-check, techstack, ads-intelligence, brand-assets) s'enchaînent directement. Les nœuds qui exigent `pois_email` (verify) ne s'enchaînent que si le CSV importé porte déjà une colonne email.

L'ensemble de colonnes est dynamique : il reflète ce que fournit la source. Le registre déclare `needs: []` et `produces: []` pour cette raison — le module est permissif en entrée et propage le schéma d'entrée en sortie.

## Cycle de vie

Cycle de vie de job standard — voir [/docs/fr/concepts/jobs-lifecycle](/docs/fr/concepts/jobs-lifecycle). Le job est rattaché à son pipeline via `pipeline_id` et `pipeline_node_id` et s'exécute dès que le pipeline passe à `running`.

## Pipeline

`import` est un nœud racine. Il n'accepte aucun arc amont. Tout nœud dont l'`input` est `pois_any`, `any_pois` ou `pois_email` (quand le CSV porte des emails) peut être câblé en aval.

| Direction | Types compatibles |
|---|---|
| Amont | aucun — `import` est un `ROOT_TYPE` aux côtés de `scrap` |
| Aval | `reviews`, `emails`, `verify` (avec colonne email), `socials`, `dead_check`, `techstack`, `ads_intelligence`, `brand_assets`, `filter`, `sort` |

Registre : `needs: []`, `produces: []`.

## Endpoints

Le module `import` n'est pas exposé comme endpoint de job autonome — il est interne au pipeline (voir [/docs/fr/concepts/pipeline-orchestration](/docs/fr/concepts/pipeline-orchestration)) et créé uniquement comme racine de pipeline. Deux endpoints adjacents sont utiles lors de l'assemblage d'un import :

| Méthode | Chemin | Rôle |
|---|---|---|
| `POST` | `/api/jobs/parse-list` | Valide l'entrée CSV avant soumission. Accepte soit un JSON `{"text": "..."}`, soit un envoi `multipart/form-data` avec un champ `file`. Renvoie `{count, with_lien_google_maps, with_site_web, sample, items, delimiter}`. |
| `GET` | `/api/jobs/{job_id}/items` | Renvoie les lignes CSV d'un job `scrap` terminé dans une structure adaptée à la réutilisation `from_job`. |

La charge utile du nœud de pipeline suit cette forme :

```json
{
  "type": "import",
  "config": {
    "source": "paste",
    "text": "nom,site_web\n...",
    "url": "",
    "from_job_id": ""
  }
}
```

Exactement un parmi `text`, `url`, `from_job_id` est lu, déterminé par `source`. Les champs inutilisés sont persistés sous forme de chaînes vides.

## Limites

Limites globales — voir [/docs/fr/concepts/limits](/docs/fr/concepts/limits). Spécifiques au module :

| Limite | Valeur |
|---|---|
| Fraîcheur `from_job` | 7 jours. Le job source est rejeté au-delà. |
| Type source `from_job` | `scrap` uniquement. |
| Formats pris en charge | CSV avec délimiteur virgule, point-virgule ou tabulation. Encodages : UTF-8 (préféré), UTF-8 avec BOM, Latin-1 / cp1252 (repli). En-têtes facultatifs — un fichier sans en-tête est auto-détecté et ses colonnes déduites du contenu. |

## Erreurs

| Condition | Surface | Forme du message |
|---|---|---|
| `source` hors de `{paste, url, from_job}` | Création du pipeline | `Source d'import invalide : <value> (attendu: paste \| url \| from_job)` |
| `from_job` sans `from_job_id` | Création du pipeline | `Source 'from_job' : aucun job sélectionné` |
| `from_job_id` inconnu | Création du pipeline | `Job source introuvable : <id>` |
| Source `from_job` non détenue par l'appelant | Création du pipeline | `Job source non autorisé pour cet utilisateur` |
| Source `from_job` n'étant pas un scrap | Création du pipeline | `Seuls les scraps Gmaps peuvent être importés via 'from_job'` |
| CSV source `from_job` indisponible | Création du pipeline | `Le CSV du job source n'est pas (ou plus) disponible` |
| Source `from_job` de plus de 7 jours | Création du pipeline | `Le job source a plus de 7 jours — relancez un scrap ou collez le CSV.` |
| Charge utile paste vide | `parse-list` | HTTP 400, `Aucun texte fourni` |
| Échec de parsing CSV | `parse-list` | HTTP 400, `CSV invalide: <detail>` |
| Zéro ligne parsée | `parse-list` | HTTP 400, `Aucune ligne lue dans le CSV` |
| Envoi multipart sans fichier | `parse-list` | HTTP 400, `Aucun fichier fourni` |
| URL injoignable ou réponse non CSV | Exécution du pipeline | Le job d'import passe à `failed` ; le message nomme la source injoignable. |
| Tableur privé (page de connexion renvoyée au lieu du CSV) | Exécution du pipeline | L'import **échoue franchement** avec une explication au lieu de réussir silencieusement — le contenu était du HTML (page de connexion), pas du CSV. Partagez la feuille en « toute personne ayant le lien peut consulter ». |
| Vide, en-tête seul, ou rien d'exploitable | Exécution du pipeline / `parse-list` | L'import **échoue avec une explication** (aucune ligne exploitable) plutôt que d'annoncer un faux succès. |

## Et après

| Module | Usage |
|---|---|
| [filter](/docs/fr/modules/filter) | Restreindre la liste importée par des prédicats de colonnes avant de payer l'enrichissement en aval. |
| [sort](/docs/fr/modules/sort) | Ordonner la liste importée — utile combiné à des limites de lignes dans les étapes ultérieures. |


<!-- doc: modules/legal_data -->

---
title: Données légales FR
slug: modules/legal_data
section: Modules
---

Le module `legal_data` enrichit une liste de POI avec les données officielles des sources légales publiques françaises. Pour chaque ligne d'entrée, le module interroge `api.gouv.fr` (SIRENE, INPI, RNCS) et complète la réponse avec les annonces légales BODACC et les extraits publics Infogreffe. Le résultat est un profil structuré rattaché à chaque entreprise : forme juridique, capital, dirigeants enregistrés, code NAF, tranche d'effectif, finances clés, et un statut de lead consolidé.

Le module est en lecture seule : aucun identifiant requis, aucune facturation par les sources amont, aucune entreprise contactée dans le cadre de la recherche.

> **Aucun site web requis.** Contrairement à [`legal_ids`](/docs/fr/modules/legal_ids) qui lit les identifiants sur un site web, ce module recherche chaque ligne par **nom + adresse** dans SIRENE et renvoie **aussi le SIRET/SIREN**. C'est le bon choix quand votre liste n'a pas de colonne site web — par exemple un scrap Google Maps avec seulement des noms et des liens Maps.

## Objectif

Les listes de prospection B2B françaises démarrent généralement avec un nom, une adresse, parfois un site. `legal_data` transforme chaque ligne en fiche entreprise qualifiée à partir des seuls registres publics.

Cas d'usage typiques :

- Filtrer une liste scrapée par capital, tranche d'effectif ou code NAF avant prise de contact.
- Détecter les entités mortes ou insolvables (`bodacc_procedure_collective`) et les écarter d'une séquence.
- Identifier les sociétés à événements légaux récents (augmentation de capital, changement de dirigeant, changement d'adresse) comme signaux d'opportunité.
- Récupérer le nom des dirigeants pour personnaliser un premier email.

## Entrées

`legal_data` est un module d'enrichissement : il consomme une liste de POI existante, il n'en produit pas. L'entrée attendue est un `poi_list`, typiquement la sortie d'un job de découverte.

| Champ          | Requis | Notes                                                          |
| -------------- | ------ | -------------------------------------------------------------- |
| `nom`          | oui    | Raison sociale, utilisée pour le rapprochement fuzzy.          |
| `siren`        | non    | Si présent, utilisé pour un match exact (préféré).             |
| `code_postal`  | non    | Désambiguïse les rapprochements fuzzy.                         |
| `lat`, `lon`   | non    | Repli géographique quand nom et SIREN échouent.                |

La résolution suit trois niveaux, dans l'ordre :

1. Recherche exacte par SIREN quand l'identifiant est fourni.
2. Rapprochement fuzzy sur `nom` + `code_postal`.
3. Repli géographique sur coordonnées dans un petit rayon.

Une ligne qui ne se résout à aucun niveau est renvoyée avec des colonnes d'enrichissement vides et un code d'erreur (voir Erreurs).

## Sorties

Chaque ligne d'entrée est augmentée des colonnes suivantes. Les valeurs vides sont préservées en chaînes vides — le module ne fabrique jamais de valeur.

| Colonne           | Type    | Description                                                       |
| ----------------- | ------- | ----------------------------------------------------------------- |
| `legal_form`      | string  | Forme juridique (SAS, SARL, SA, EI, association, etc.).           |
| `capital`         | number  | Capital social enregistré en EUR.                                 |
| `founding_date`   | date    | Date d'immatriculation au registre.                               |
| `executives`      | list    | Dirigeants nommés avec rôle (Président, Gérant, DG).              |
| `financials`      | object  | Dernier CA et résultat net disponibles, avec l'exercice fiscal.   |
| `naf_code`        | string  | Code d'activité NAF/APE à cinq caractères.                        |
| `employees_range` | string  | Tranche d'effectif INSEE (ex. `10-19`, `100-199`).                |

Un `lead_status` consolidé est également renvoyé, prenant une des quatre valeurs : `mort`, `alerte`, `opportunite`, `actif`. Il encode la combinaison de l'état administratif, des signaux BODACC et de la récence des événements légaux.

## Cycle de vie

Cycle de job standard — voir [Cycle de vie des jobs](/docs/fr/concepts/jobs-lifecycle). La progression est reportée par établissement traité. Le job est idempotent à l'échelle d'une session : ré-exécuter sur la même liste d'entrée donne les mêmes colonnes enrichies, aux mises à jour amont près.

## Pipeline

```
needs:     poi_list
produces:  enriched_list
```

`legal_data` consomme un `poi_list` et émet un `enriched_list` portant les lignes d'origine plus les colonnes décrites dans Sorties. La liste enrichie peut elle-même être consommée par des modules d'enrichissement en aval (`legal_mentions`, `legal_ids`, etc.).

## Endpoints

### Créer un job

```
POST /api/jobs/legal-data
```

Corps de requête :

```json
{
  "items": [
    { "nom": "Boulangerie Martin", "code_postal": "75011" },
    { "siren": "552120222" }
  ],
  "source_job_id": "job_01HXYZ..."
}
```

Soit `items`, soit `source_job_id` doit être fourni. Quand `source_job_id` référence un job de découverte terminé, ses lignes sont utilisées comme entrée directement.

Réponse : une ressource `Job` avec `id`, `type`, `status`, et champs de progression.

### Récupérer un job

```
GET /api/jobs/{job_id}
```

Renvoie l'état courant, les compteurs de progression et — quand `done` — l'URL de téléchargement du CSV enrichi.

### Lister les jobs

```
GET /api/jobs?type=legal_data
```

Maximum **5 000 lignes par job**. Les listes plus grandes doivent être découpées côté client. Quotas globaux et limites de débit : voir [Limites](/docs/fr/concepts/limits).

Les chiffres financiers dépendent du dépôt de comptes par la société (environ 60 % des PME françaises). Les noms de dirigeants reflètent le dernier dépôt ; les changements récents peuvent mettre quelques semaines à se propager.

## Erreurs

Les erreurs ligne sont reportées dans une colonne `error` sur la sortie enrichie. Les erreurs job font passer le job en `failed`.

| Code                     | Portée | Signification                                                |
| ------------------------ | ------ | ------------------------------------------------------------ |
| `not_found`              | ligne  | Aucun match SIRENE pour le nom et le code postal fournis.    |
| `foreign_business`       | ligne  | Établissement non immatriculé en France.                     |
| `ambiguous_match`        | ligne  | Plusieurs candidats à score égal ; aucun sélectionné.        |
| `source_unavailable`     | job    | Une ou plusieurs sources publiques amont sont injoignables.  |
| `quota_exceeded`         | job    | Quota d'usage équitable journalier atteint ; réessayer demain. |
| `invalid_input`          | job    | Liste d'entrée vide ou champs requis manquants.              |

Un échec `source_unavailable` préserve toutes les lignes déjà enrichies avant la coupure. Le job peut être resoumis avec les lignes restantes une fois la source amont rétablie.

## Et après

- [`legal_ids`](/docs/fr/modules/legal_ids) — détecter SIREN et SIRET directement sur un site d'entreprise, avec validation Luhn. Prérequis utile quand les lignes d'entrée n'ont pas de `siren`.
- [`legal_mentions`](/docs/fr/modules/legal_mentions) — analyser la page mentions légales d'un site pour extraire raison sociale, capital, RCS, adresse postale et numéro de TVA. Complète `legal_data` quand les dépôts au registre sont rares.


<!-- doc: modules/legal_ids -->

---
title: Identifiants entreprise
slug: modules/legal_ids
section: Modules
---

# Identifiants entreprise

Le module `legal_ids` extrait les identifiants d'entreprises françaises depuis une liste de POI déjà dotés d'un site web. Pour chaque site, le module localise et valide le **SIRET** (14 chiffres) et le **SIREN** (9 chiffres), et enregistre l'URL où l'identifiant a été trouvé. La somme de contrôle Luhn est appliquée à chaque candidat : les numéros de téléphone à neuf chiffres sont rejetés avant la sortie.

Ce module est le point d'entrée standard du pipeline legal-data : une fois un SIREN vérifié attaché à un item, des modules en aval comme `legal_data` peuvent interroger les registres officiels sans étape de rapprochement par nom.

> **Site web requis.** Ce module lit le SIRET/SIREN dans les **mentions légales du site web** de chaque établissement : chaque ligne doit donc avoir une colonne `site_web`. Si votre liste n'a que des noms ou des liens Google Maps (sans site web), utilisez plutôt [Données société](/docs/fr/modules/legal_data) — il renvoie le même SIRET/SIREN en recherchant le **nom** dans l'annuaire SIRENE, sans site web.

## Objectif

- Rattacher un identifiant d'entreprise française faisant autorité (SIREN/SIRET) à chaque POI.
- Conserver la provenance : chaque identifiant est accompagné de l'URL d'extraction.
- Fournir une clé propre et dédoublonnée pour l'enrichissement ultérieur (`legal_data`, `legal_mentions`).

## Entrées

Le module consomme une `enriched_list` de POI. Le champ minimal requis sur chaque item est `site_web` ; les items sans site sont filtrés à la création du job et comptés comme ignorés.

| Champ      | Type   | Requis | Notes                                              |
| ---------- | ------ | ------ | -------------------------------------------------- |
| `site_web` | string | oui    | Domaine racine ou URL quelconque du site cible.    |
| `nom`      | string | non    | Transmis tel quel en sortie pour le contexte.      |
| `adresse`  | string | non    | Transmis tel quel en sortie pour le contexte.      |

Une liste de POI est typiquement produite par le module `scrap`, mais toute `enriched_list` portant `site_web` est acceptée.

## Sorties

Chaque item d'entrée est retourné avec trois nouveaux champs. Les autres champs d'entrée sont transmis tels quels.

| Colonne             | Type   | Description                                                                   |
| ------------------- | ------ | ----------------------------------------------------------------------------- |
| `siren`             | string | Identifiant à 9 chiffres, validé Luhn. Vide si non trouvé.                    |
| `siret`             | string | Identifiant d'établissement à 14 chiffres, validé Luhn. Vide si non trouvé.   |
| `siret_source_url`  | string | URL de la page d'extraction. Vide si non trouvé.                              |

Quand seul un SIREN est détecté, `siret` reste vide et les modules en aval peuvent opérer sur le SIREN seul. Les autres attributs de société — forme juridique, n° RCS, code NAF, effectif, dirigeants, finances — relèvent de `legal_data`.

## Cycle de vie

Cycle de job standard — voir [Cycle de vie des jobs](/docs/fr/concepts/jobs-lifecycle). Les échecs sur des items individuels n'arrêtent pas le job : la ligne de sortie correspondante a simplement les champs `siren`/`siret` vides, et le compteur `errors` suit le nombre d'items terminés sans identifiant.

## Pipeline

```
needs:    poi_list
produces: enriched_list
```

`legal_ids` est rangé dans la catégorie `enrich`. Chaînes typiques :

- `scrap` → `legal_ids` → `legal_data`
- `scrap` → `legal_ids` → `legal_mentions`

## Endpoints

### Créer un job

```
POST /api/jobs/legal-ids
```

Corps :

| Champ            | Type                | Requis | Description                                                                        |
| ---------------- | ------------------- | ------ | ---------------------------------------------------------------------------------- |
| `items`          | tableau de POI      | oui    | Liste d'entrée. Chaque item doit porter `site_web`.                                |
| `source_job_id`  | string (UUID)       | non    | Quand on enchaîne depuis un job précédent, ID du job amont pour la traçabilité.    |

Réponse : objet `Job` standard, incluant `id`, `status`, `output_filename`, et l'estimation de coût en unités équivalent-France.

Le job créé est ensuite piloté par les endpoints habituels (`GET /api/jobs/{id}`, `GET /api/jobs/{id}/download`, etc.) partagés par tous les modules.

Quotas globaux et plafonds par job : voir [Limites](/docs/fr/concepts/limits).

## Erreurs

| Situation                                  | Comportement                                                                       |
| ------------------------------------------ | ---------------------------------------------------------------------------------- |
| Item sans `site_web`                       | Écarté avant démarrage. Si aucun item ne reste, le job est rejeté.                 |
| Site joignable, aucun identifiant trouvé   | Item terminé avec `siren`/`siret` vides. Comptabilisé dans le total d'erreurs.     |
| POI non immatriculé (pas de SIREN/SIRET)   | Idem : aucun identifiant inventé ; sorties vides.                                  |
| Entreprise étrangère                       | Idem : seuls les identifiants français sont reconnus.                              |
| Candidat échouant à la validation Luhn     | Écarté silencieusement ; aucun faux positif écrit en sortie.                       |
| Aucun item avec site web                   | Le job échoue avec un message explicite — ex. `0 ligne sur 120 a un site web (votre liste ne contient que des noms, des liens Google Maps et des téléphones)` — et recommande [`legal_data`](/docs/fr/modules/legal_data) pour obtenir le SIRET/SIREN par le nom. |

## Et après

- [Données entreprise](/docs/fr/modules/legal_data) — depuis un SIREN, récupère le dossier officiel complet : forme juridique, n° RCS, code NAF, effectif, dirigeants, finances.
- [Mentions légales](/docs/fr/modules/legal_mentions) — extrait le bloc de mentions légales (éditeur, hébergeur, contact) depuis les mêmes sites.


<!-- doc: modules/legal_mentions -->

---
title: Mentions légales
slug: modules/legal_mentions
section: Modules
---

# Mentions légales

Le module `legal_mentions` localise la page mentions légales (aussi *Impressum*) sur le site de chaque POI et en extrait le contenu structuré. Il s'exécute comme étape d'enrichissement sur une liste de POI existante et renvoie une ligne par site d'entrée, qu'une page légale ait été trouvée ou non.

## Objectif

La plupart des workflows de due-diligence B2B reposent sur quelques faits publiés uniquement sur le site de l'entreprise : raison sociale, dirigeant, capital social, hébergeur. Le module fait remonter ces faits à l'échelle de la liste, pour qu'une campagne ou un audit en aval puisse filtrer, segmenter et recouper sans visites manuelles.

Usages typiques :

- Qualifier une liste de prospects par proxies de taille (capital, forme juridique).
- Rapprocher un nom commercial de l'entité immatriculée avant prise de contact.
- Construire un index de dirigeants pour personnaliser les messages.
- Auditer les hébergeurs sur un secteur.

Le module n'invente jamais de valeur. Un champ vide signifie que l'information n'a pas pu être localisée sur la page cible.

## Entrées

Le job consomme une liste d'items POI. Chaque item doit porter une URL de site ; les items sans URL sont écartés à la validation.

| Champ           | Type   | Requis | Notes                                                       |
| --------------- | ------ | ------ | ----------------------------------------------------------- |
| `site_web`      | string | oui    | URL racine du site de l'établissement.                      |
| `name`          | string | non    | Transmis en sortie pour le rapprochement.                   |
| `source_job_id` | string | non    | ID d'un job `scrap` amont pour hériter les items.           |

Soumettre entre 1 et 10 000 items par job. Les items sont normalisés et dédoublonnés avant exécution.

## Sorties

Une ligne est produite par site d'entrée. Colonnes :

| Colonne           | Type   | Description                                                                  |
| ----------------- | ------ | ---------------------------------------------------------------------------- |
| `raison_sociale`  | string | Raison sociale telle qu'apparaissant sur la page mentions légales.           |
| `forme_juridique` | string | Forme juridique (SAS, SARL, SA, EI, etc.).                                   |
| `capital_social`  | string | Capital social déclaré, dans la devise indiquée sur la page.                 |
| `rcs`             | string | Mention RCS (ville + identifiant).                                           |
| `adresse_postale` | string | Adresse postale du siège.                                                    |
| `dirigeant`       | string | Directeur de publication ou représentant légal, quand indiqué.               |
| `tva_intracom`    | string | Numéro de TVA intracommunautaire, validé au format FR quand présent.         |

Les cellules vides indiquent que le champ n'était pas présent sur la page analysée — le module n'invente jamais de valeur. La sortie est livrée en CSV avec les colonnes d'entrée.

## Cycle de vie

Cycle de job standard — voir [Cycle de vie des jobs](/docs/fr/concepts/jobs-lifecycle). La progression est reportée par site ; les sorties partielles sont préservées en cas d'annulation ou d'échec en cours d'exécution.

## Pipeline

Le module est une étape d'enrichissement. Il s'insère dans le pipeline de liste standard :

```yaml
needs: [site_web]
produces: [raison_sociale, forme_juridique, capital_social, rcs, adresse_postale, dirigeant, tva_intracom]
```

Une chaîne typique ressemble à `scrap` → `legal_mentions` → `legal_data`. La source peut être sélectionnée en téléversant directement les items ou en référençant un job `scrap` récent via `source_job_id`.

## Endpoints

Tous les endpoints requièrent un utilisateur authentifié et actif.

| Méthode | Chemin                        | Corps                             | Renvoie      |
| ------- | ----------------------------- | --------------------------------- | ------------ |
| POST    | `/api/jobs/legal-mentions`    | `{ items: [...], source_job_id }` | `JobPublic`  |
| GET     | `/api/jobs/{id}`              | —                                 | `JobPublic`  |
| GET     | `/api/jobs/{id}/output`       | —                                 | flux CSV     |
| POST    | `/api/jobs/{id}/cancel`       | —                                 | `JobPublic`  |

L'endpoint de création valide le quota en amont et renvoie `400` avec un message descriptif en cas d'échec. Items par job : 1 à 10 000. Quotas globaux : voir [Limites](/docs/fr/concepts/limits).

## Erreurs

Deux issues remontent en lignes vides plutôt qu'en échec de job, car attendues à l'échelle de la liste :

| Condition                       | Comportement                                                              |
| ------------------------------- | ------------------------------------------------------------------------- |
| Aucune page légale trouvée      | Ligne renvoyée avec chaque champ légal vide.                              |
| Site hors-ligne                 | Ligne renvoyée tous champs vides ; le site est marqué injoignable.        |

Les échecs au niveau job (`status = failed`) sont réservés aux conditions non récupérables comme une entrée invalide ou une erreur quota. Le message d'erreur est exposé sur l'enregistrement du job.

## Et après

- [legal_ids](/docs/fr/modules/legal_ids) — détecter SIREN/SIRET sur le même ensemble de sites.
- [legal_data](/docs/fr/modules/legal_data) — enrichir chaque identifiant avec les données officielles d'entreprise.


<!-- doc: modules/on-demand/email_campaign -->

---
title: Campagnes email
slug: modules/on-demand/email_campaign
section: Modules · sur demande
summary: Campagnes de cold email opérées par l'équipe outsend pour le compte du client. Pas self-serve.
---

## Objet

Le module `email_campaign` propose des campagnes de prospection email construites et opérées par l'équipe outsend. La délivrabilité de cold email se joue sur trop de signaux (warm-up, IP, réputation, séquences, suivi des plaintes) pour exposer un bouton "envoyer" en self-serve à ce stade.

## Comment en faire la demande

Aucun endpoint backend. Deux chemins équivalents :

- **Dashboard** — la carte du module ouvre un fil dans le chat feedback avec le topic `on_demand_email`.
- **API** — `POST /api/feedback/threads` avec `topic: "on_demand_email"` (voir [Feedback API](/docs/fr/api/feedback)).

L'équipe répond, cadre le besoin, et propose un plan.

## Ce qui est livré

- Liste de destinataires vérifiée (déduplication + check délivrabilité)
- Séquences d'envoi rédigées en accord avec le client
- Personnalisation par lead (variables tirées des modules outsend en amont)
- Caps de fréquence + opt-out
- Réponses centralisées dans le dashboard outsend
- Rapport délivrabilité + taux de réponse

## Pourquoi sur demande

Cold email à l'échelle = piège à délivrabilité ouvert. Mauvaise séquence, mauvais domaine, mauvais timing → blacklist quasi-permanente. Tant qu'outsend ne propose pas l'infra warm-up + monitoring complète en self-serve, c'est l'équipe qui opère pour garantir le résultat.

## Tarification

Sur devis. Le périmètre détermine le coût (volume, niveau de personnalisation, durée de séquence).

## Pour aller plus loin

- [Campagnes SMS](/docs/fr/modules/on-demand/sms_campaign)
- [Campagnes WhatsApp](/docs/fr/modules/on-demand/whatsapp_campaign)


<!-- doc: modules/on-demand/phone_carrier -->

---
title: Détection opérateur téléphonique
slug: modules/on-demand/phone_carrier
section: Modules · sur demande
summary: Identifie l'opérateur réel de chaque numéro mobile — portabilité incluse — pour le routage SMS, la dédup et la segmentation.
---

# Détection opérateur téléphonique

Qualifie l'opérateur d'une liste de numéros mobiles — Orange, SFR, Bouygues, Free, MVNO — en tenant compte de la portabilité. Utile avant un envoi SMS à grande échelle, pour dédoublonner un CRM, ou segmenter par opérateur.

## Deux moyens de l'utiliser

- **Outil public** — instantané, gratuit, sans inscription, sans limite de batch : [`/c-est-quel-operateur`](/c-est-quel-operateur). Retourne l'opérateur attributaire ARCEP par numéro avec son nom, son SIRET, son siège et sa date de déclaration. Voir [Lookup opérateur](/docs/fr/modules/operator_lookup).
- **Batch portabilité live** — ce module. Ajoute l'opérateur *actuel* après portabilité pour une liste de numéros, avec cache. Sur demande pendant l'alpha.

## Entrées

| Champ | Type | Requis | Notes |
|---|---|---|---|
| `items` | tableau d'objets | oui | Chaque élément doit contenir au moins `phone` (E.164 ou 10 chiffres). De 1 à 10 000 éléments par batch. |
| `source_job_id` | string | non | ID du job amont pour la lineage. |

## Sorties

Chaque ligne en entrée est renvoyée enrichie.

| Colonne | Type | Description |
|---|---|---|
| `carrier_name` | string | Opérateur actuel après portabilité (nom commercial). |
| `carrier_original` | string | Opérateur attributaire ARCEP de la tranche. |
| `is_ported` | bool | `true` si l'opérateur actuel diffère de l'attributaire. |
| `is_reachable` | bool | Numéro actif sur le réseau au moment du lookup. |
| `line_type` | string | `mobile`, `fixed_line`, `fixed_or_mobile` ou `other`. |

Un cache persistant rend tout re-run gratuit pour toi : seuls les premiers lookups consomment un slot.

## Cycle de vie

Cycle de vie standard — voir [Jobs & cycle de vie](/docs/fr/concepts/jobs-lifecycle).

## Limites

- **Sur demande pendant l'alpha** — pas encore d'endpoint create en self-service ; on l'active pour toi. Pour des lookups en libre service illimités, utilise l'outil public ARCEP.
- Numéros français uniquement. Les numéros internationaux renvoient `error: "not_french_number"` par ligne.
- L'enrichissement live est best-effort. Quand il n'est pas disponible, la ligne tombe sur l'opérateur attributaire ARCEP.

## Pourquoi sur demande

On ajuste le débit et la concurrence selon le volume client. Écris-nous via [Contact](/contact), on cale la cadence avec toi.


<!-- doc: modules/on-demand/sms_campaign -->

---
title: Campagnes SMS
slug: modules/on-demand/sms_campaign
section: Modules · sur demande
summary: Campagnes de prospection SMS opérées par l'équipe outsend.
---

## Objet

Le module `sms_campaign` propose des campagnes de prospection SMS construites et opérées par l'équipe outsend. Validation des numéros, conformité opérateur, gestion des opt-outs, le SMS impose des contraintes que self-serve n'absorbe pas proprement aujourd'hui.

## Comment en faire la demande

Aucun endpoint backend. Deux chemins :

- **Dashboard** — la carte ouvre un fil chat avec le topic `on_demand_sms`.
- **API** — `POST /api/feedback/threads` avec `topic: "on_demand_sms"` (voir [Feedback API](/docs/fr/api/feedback)).

## Ce qui est livré

- Numéros vérifiés (HLR + détection ligne mobile vs fixe)
- Conformité RGPD : recueil consentement validé
- Messages personnalisés par lead
- Caps de fréquence + opt-out STOP
- Réponses remontées dans le dashboard
- Rapport délivrabilité + taux d'opt-out

## Pourquoi sur demande

Partenariats opérateurs, validation expéditeur, facturation au volume — pas de bouton à exposer tant que le contrat n'est pas standardisé côté outsend.

## Tarification

Sur devis. Le volume + le niveau de personnalisation déterminent le coût.

## Pour aller plus loin

- [Campagnes email](/docs/fr/modules/on-demand/email_campaign)
- [Campagnes WhatsApp](/docs/fr/modules/on-demand/whatsapp_campaign)


<!-- doc: modules/on-demand/whatsapp_campaign -->

---
title: Campagnes WhatsApp
slug: modules/on-demand/whatsapp_campaign
section: Modules · sur demande
summary: Campagnes de prospection WhatsApp opérées par l'équipe outsend.
---

## Objet

Le module `whatsapp_campaign` propose des campagnes WhatsApp construites et opérées par l'équipe outsend. WhatsApp Business impose ses propres règles (templates pré-approuvés, opt-in explicite, fenêtres 24h) — pas de bouton self-serve à ce stade.

## Comment en faire la demande

Aucun endpoint backend. Deux chemins :

- **Dashboard** — la carte ouvre un fil chat avec le topic `on_demand_whatsapp`.
- **API** — `POST /api/feedback/threads` avec `topic: "on_demand_whatsapp"` (voir [Feedback API](/docs/fr/api/feedback)).

## Ce qui est livré

- Numéros vérifiés (mobile uniquement)
- Templates pré-approuvés WhatsApp Business
- Personnalisation par lead dans le respect des contraintes Meta
- Gestion des opt-outs + caps de fréquence
- Réponses remontées dans le dashboard
- Rapport de délivrabilité

## Pourquoi sur demande

Politique Meta stricte : un template mal formé = ban du numéro émetteur. Tant qu'outsend ne propose pas un studio template + workflow de validation Meta en self-serve, c'est l'équipe qui opère.

## Tarification

Sur devis. Coût Meta par conversation + setup outsend.

## Pour aller plus loin

- [Campagnes email](/docs/fr/modules/on-demand/email_campaign)
- [Campagnes SMS](/docs/fr/modules/on-demand/sms_campaign)


<!-- doc: modules/pagespeed -->

---
title: PageSpeed
slug: modules/pagespeed
section: Modules
---

# PageSpeed

Lance un audit officiel Google PageSpeed Insights sur le site de chaque prospect. La sortie classe la liste par qualité de site, expose les performeurs les plus faibles, et fait remonter un angle de pitch concret : un site lent ou cassé est une amélioration à proposer.

Le module ne crawle jamais un site directement. La mesure est déléguée à Google, ce qui garde le signal comparable d'un prospect à l'autre.

## Entrées

Le job accepte un tableau de dictionnaires POI. Seul `site_web` est réellement utilisé ; tout autre champ est repassé tel quel à la sortie.

| Champ | Type | Requis | Notes |
|---|---|---|---|
| `items` | `list[dict]` | oui | 1 à 10 000 POI. Les lignes sans `site_web` sont conservées et marquées. |
| `source_job_id` | `string` | non | UUID du job amont (typiquement un scrap Google Maps). |

```json
{
  "nom": "Studio Atlas",
  "adresse": "12 rue de Rivoli, 75001 Paris",
  "site_web": "https://studio-atlas.fr"
}
```

## Sorties

Une ligne par POI d'entrée. Les cellules vides signalent que PSI n'a pas pu scorer l'URL (voir Erreurs).

| Colonne | Type | Description |
|---|---|---|
| `perf_score_mobile` | int 0-100 | Score de performance Lighthouse, profil mobile. |
| `perf_score_desktop` | int 0-100 | Score de performance Lighthouse, profil desktop. |
| `lcp_ms` | int | Largest Contentful Paint en millisecondes. Bon < 2500. |
| `cls` | float | Cumulative Layout Shift. Bon < 0.1. |
| `accessibility_score` | int 0-100 | Score d'accessibilité Lighthouse. |
| `seo_score` | int 0-100 | Score SEO Lighthouse. |
| `suggestions[]` | list[string] | Audits Lighthouse en échec, prêts à citer dans un message d'outreach. |

L'export CSV porte aussi `best_practices_score`, `fcp_ms`, `tbt_ms` et `inp_ms` pour exhaustivité.

## Cycle de vie

Cycle de vie standard des jobs outsend ; voir [/docs/fr/concepts/jobs-lifecycle](/docs/fr/concepts/jobs-lifecycle). La progression est reportée en `sites` ; le compteur de résultats en `audits`.

## Pipeline

```
needs:     site_web
produces:  perf_score, accessibility_score, seo_score,
           best_practices_score, lcp, cls, inp
```

PageSpeed est un module `check` : il consomme une liste et retourne la même liste enrichie. Schéma typique : partir d'un job `scrap`, puis lancer `pagespeed` sur les POI résultants.

## Endpoints

### Créer un job

```
POST /api/jobs/pagespeed
Content-Type: application/json
```

```json
{
  "items": [
    { "nom": "Studio Atlas", "site_web": "https://studio-atlas.fr" }
  ],
  "source_job_id": "8b1f...-uuid"
}
```

Réponse : enveloppe `JobPublic` portant l'UUID du job, son statut et le coût EF réservé pour le suivi.

### Lire un job

```
GET  /api/jobs/{job_id}
GET  /api/jobs/{job_id}/results
GET  /api/jobs/{job_id}/export.csv
```

L'export CSV est disponible une fois le job en `completed`.

## Limites

Voir [/docs/fr/concepts/limits](/docs/fr/concepts/limits). L'amont est l'offre gratuite de Google PSI v5 (une URL par requête) ; les pics au-dessus du quota par clé sont reprogrammés dans le job plutôt qu'échoués.

## Erreurs

| Condition | Comportement |
|---|---|
| POI sans `site_web` | Ligne conservée, colonnes d'audit vides, `suggestions[]` réduit à une entrée explicative unique. |
| URL injoignable ou réponse non-HTML | Ligne conservée, scores vides, erreur notée sur la ligne. |
| Quota PSI épuisé | Les URL touchées sont remises en file dans le job ; si le quota reste épuisé la ligne est marquée failed et le reste continue. |
| Site bloque le fetcher PSI | Ligne marquée failed avec le code d'erreur amont ; le job reste sain. |
| `items` vide | `400 Bad Request`, aucun job créé. |
| `PAGESPEED_API_KEY` absente côté serveur | Job créé mais bascule immédiatement en `failed`. |

Une ligne en échec ne bloque jamais le job : le contrat est « chaque POI d'entrée reçoit une ligne de sortie, scorée ou expliquée ».

## Pour aller plus loin

- [`techstack`](/docs/fr/modules/techstack) — détecte le CMS, l'analytics et les frameworks derrière chaque site. Un score PageSpeed faible combiné à une stack connue pour être lente donne un angle plus tranchant que chaque signal seul.
- [`ads_intelligence`](/docs/fr/modules/ads_intelligence) — vérifie si le prospect investit activement en publicité. Payer du trafic qui atterrit sur une page lente est le pitch à plus forte conviction que ce module rend possible.


<!-- doc: modules/phone_info -->

---
title: Informations sur le numéro
slug: modules/phone_info
section: Modules
summary: Enrichit une liste de numéros de téléphone avec opérateur, type de ligne, portabilité et métadonnées opérateur — registre officiel ARCEP plus vérification live de portabilité.
---

# Informations sur le numéro

Le module `phone_info` prend une liste de numéros de téléphone et renvoie une ligne enrichie par numéro. Pour chaque numéro français, il identifie l'opérateur attributaire de la tranche selon l'**ARCEP** (Orange, SFR, Bouygues, Free, MVNO), avec son nom commercial, son SIRET, son siège, son RCS et sa date de déclaration ARCEP. Quand c'est disponible, il renvoie aussi l'opérateur actuel après portabilité et un indicateur de joignabilité.

Module d'enrichissement pipelinable : à chaîner après un job de discovery, un import, ou toute liste qui transporte une colonne téléphone.

## Entrées

Une liste d'items, chacun portant au moins un champ téléphone. Les autres colonnes sont préservées telles quelles.

| Champ | Requis | Notes |
|---|---|---|
| `phone` (ou `telephone`, `phone_number`, `numero`, `number`) | oui | Numéro français ou international. Accepte espaces, `+`, `00` et 10 chiffres bruts. |
| `nom` (ou `name`) | non | Repris en sortie pour l'affichage. |
| toute autre colonne | non | Préservée à l'identique. |

Taille batch : 1 à 10 000 items par job.

Options du job :

| Option | Défaut | Notes |
|---|---|---|
| `live_mode` | `"cache_only"` | `"cache_only"` lit seulement le cache de portabilité existant. `"with_live"` tente une vérification live pour les mobiles français pas encore en cache. |
| `source_job_id` | aucune | ID du job amont pour la lineage dans les pipelines. |

## Sorties

Chaque ligne en entrée est renvoyée enrichie des colonnes ci-dessous.

| Colonne | Type | Description |
|---|---|---|
| `phone_e164` | string | Format international canonique. |
| `phone_national` | string | Format national lisible. |
| `phone_country` | string | ISO 3166-1 alpha-2. |
| `phone_line_type` | string | `mobile`, `fixed_line`, `fixed_or_mobile`, `other`. |
| `phone_carrier_original` | string | Opérateur attributaire de la tranche ARCEP. |
| `phone_operator_siret` | string | SIRET de l'opérateur d'origine. |
| `phone_operator_rcs` | string | Ville RCS. |
| `phone_operator_address` | string | Adresse du siège. |
| `phone_operator_registered_since` | string | Date de déclaration ARCEP de l'opérateur. |
| `phone_tranche_attribution_date` | string | Date d'attribution de la tranche. |
| `phone_territory` | string | Métropole, La Réunion, Mayotte, etc. |
| `phone_carrier_current` | string | Opérateur actuel après portabilité (quand disponible). |
| `phone_is_ported` | string | `yes`, `no`, `unknown`. |
| `phone_is_reachable` | string | `yes`, `no`, `unknown`. |
| `phone_is_valid` | string | `yes`, `no`. |
| `phone_status` | string | `ok`, `not_french`, `invalid`, `no_match`. |

## Pipeline

```yaml
needs:    telephone
produces: phone_e164, phone_carrier_original, phone_carrier_current, phone_is_ported, ...
```

Chaînes typiques :

```
scrap → phone_info → filter (par opérateur) → sms_campaign
import → phone_info → enrichissement emails …
```

## Endpoints

### `POST /api/jobs/phone-info`

Crée un nouveau job phone-info à partir d'une liste d'items.

**Corps**

| Champ | Type | Requis | Description |
|---|---|---|---|
| `items` | array<object> | oui | 1 à 10 000 éléments. Chacun doit porter un champ téléphone. |
| `live_mode` | string | non | `"cache_only"` (défaut) ou `"with_live"`. |
| `source_job_id` | string (uuid) | non | ID du job amont en pipeline. |

**Réponse**

Enveloppe `JobPublic` standard.

**Exemple**

```http
POST /api/jobs/phone-info
Content-Type: application/json

{
  "items": [
    { "nom": "Acme",  "phone": "+33612345678" },
    { "nom": "Beta",  "phone": "0142868828"  }
  ],
  "live_mode": "cache_only"
}
```

## Sources de données

- **MAJNUM** — tranches attribuées à chaque opérateur ([Open data ARCEP](https://www.data.gouv.fr/datasets/ressources-en-numerotation-telephonique))
- **Identifiants CE** — nom commercial, SIRET, RCS, siège et date de déclaration ([Open data ARCEP](https://www.data.gouv.fr/datasets/identifiants-de-communications-electroniques))
- Un cron hebdo rafraîchit la copie locale après chaque collège ARCEP.


<!-- doc: modules/phones_extra -->

---
title: Téléphones supplémentaires
slug: modules/phones_extra
section: Modules
---

# Téléphones supplémentaires

Le module `phones_extra` va au-delà de l'unique numéro de standard renvoyé par une fiche cartographique typique et fait remonter les canaux vocaux supplémentaires qu'une entreprise expose sur son propre site : lignes directes, mobiles, services commerciaux, hotlines support, et fax résiduels.

## Objectif

Les sources de découverte publient un numéro canonique par implantation. Les organisations réelles en publient plusieurs : homepage, landing pages, bios d'équipe, mentions légales. `phones_extra` lit les pages publiques de chaque site rattaché à un POI, extrait tous les jetons de forme téléphonique, les valide via la bibliothèque `phonenumbers` de Google, les normalise en E.164 et les dédoublonne par rapport au numéro principal déjà connu.

## Entrées

Le module opère sur une liste de POI enrichie — généralement issue d'une étape de découverte préalable.

| Champ        | Requis | Notes                                                    |
|--------------|--------|----------------------------------------------------------|
| `site_web`   | oui    | Les POI sans site sont filtrés à la soumission.          |
| `name`       | non    | Sert au libellé de sortie et à l'audit trail.            |
| `phone`      | non    | Quand présent, sert de référence pour le dédoublonnage.  |
| `address`    | non    | Aide la détection de pays sur formats ambigus.           |

Les items sans `site_web` sont silencieusement écartés ; si la liste filtrée est vide, la requête est rejetée avec une erreur de validation.

## Sorties

Chaque POI d'entrée est retourné avec jusqu'à trois champs téléphoniques supplémentaires. Une chaîne vide indique que le module a tourné mais n'a rien trouvé pour ce type.

| Colonne           | Type   | Description                                                        |
|-------------------|--------|--------------------------------------------------------------------|
| `phone_secondary` | string | Ligne fixe additionnelle distincte du numéro principal, E.164.     |
| `mobile`          | string | Ligne mobile détectée via le plan de numérotation national, E.164. |
| `fax`             | string | Numéro de fax quand explicitement étiqueté sur la page, E.164.     |

Tous les numéros sont validés et normalisés. Ce qui échoue à la validation est écarté plutôt que rendu sous forme d'estimation.

## Cycle de vie

Cycle de job standard — voir [Cycle de vie des jobs](/docs/fr/concepts/jobs-lifecycle). La progression est reportée en `sites` et le volume final en `numéros`.

## Pipeline

`phones_extra` est un module d'**enrichissement** : il augmente une liste de POI existante, il n'en génère pas.

```yaml
needs:    poi_list
produces: enriched_list
```

Chaîne typique :

```
discovery → phones_extra → verify_emails → filter → campaign
```

## Endpoints

### `POST /api/jobs/phones-extra`

Crée un job de téléphones supplémentaires à partir d'une liste de POI.

**Corps**

| Champ           | Type           | Requis | Description                                                |
|-----------------|----------------|--------|------------------------------------------------------------|
| `items`         | array<object>  | oui    | POI à enrichir, chacun portant au moins `site_web`.        |
| `source_job_id` | string (uuid)  | non    | ID du job parent quand on enchaîne depuis une exécution.   |

**Réponse**

Retourne l'enveloppe `JobPublic` standard (`id`, `status`, `job_type`, `output_filename`, coût quota, timestamps).

**Exemple**

```http
POST /api/jobs/phones-extra
Content-Type: application/json

{
  "source_job_id": "f3c2…",
  "items": [
    { "name": "Acme SAS", "site_web": "https://acme.example", "phone": "+33123456789" },
    { "name": "Beta Co",  "site_web": "https://beta.example" }
  ]
}
```

```json
{
  "id": "9a7b…",
  "status": "pending",
  "job_type": "phones_extra",
  "output_filename": "telephones-extra-2-sites.xlsx"
}
```

Quotas globaux et plafonds par job : voir [Limites](/docs/fr/concepts/limits).

## Erreurs

| Condition                                       | Réponse                                      |
|-------------------------------------------------|----------------------------------------------|
| Aucun item ne porte de `site_web`               | `400` — *Aucun établissement avec site web*. |
| Coût estimé au-dessus du quota par job          | `400` — quota dépassé, avec dépassement chiffré. |
| Quota de compte épuisé                          | `400` — échec du contrôle quota avant insertion. |
| Corps malformé (`items` manquant, mauvais types) | `422` — erreur de validation de requête.    |

Les erreurs runtime sur des sites individuels n'interrompent pas le job : le POI concerné est enregistré avec des champs téléphoniques extras vides et le worker poursuit.

## Et après

- [Vérification d'emails](/docs/fr/modules/verify_emails) — apparier les lignes directes fraîchement trouvées avec des boîtes délivrables.
- [Filter](/docs/fr/modules/filter) — segmenter la liste enrichie par présence de mobile, indicatif pays, ou toute combinaison des nouveaux champs.


<!-- doc: modules/pricing -->

---
title: Tarifs
slug: modules/pricing
section: Modules
---

# Tarifs

Extrait les grilles tarifaires publiées sur le site web de chaque point d'intérêt. Le module parcourt une cascade de sources structurées (JSON-LD, Microdata, Open Graph, routes tarifaires dédiées, repli sur la page d'accueil) et retourne un montant normalisé, une devise et une période de facturation pour chaque site résolu.

C'est une étape d'enrichissement, pas de découverte. Elle attend une liste préalable de POI avec un `site_web` résolu — typiquement la sortie d'un job `scrap`.

## Entrées

Les items sans `site_web` sont silencieusement écartés à la validation.

| Champ              | Type   | Requis | Notes                                              |
| ------------------ | ------ | ------ | -------------------------------------------------- |
| `items`            | array  | oui    | 1 à 10 000 points d'intérêt                        |
| `items[].site_web` | string | oui    | URL absolue du site principal du fournisseur       |
| `source_job_id`    | string | non    | ID du job amont ayant produit la liste             |

## Sorties

Les lignes sans signal sont conservées et marquées `price_confidence = low` afin de préserver la cardinalité d'entrée.

| Colonne            | Type    | Description                                                                            |
| ------------------ | ------- | -------------------------------------------------------------------------------------- |
| `price_amount`     | number  | Tarif publié le plus bas visible chez le fournisseur, en valeur numérique              |
| `price_currency`   | string  | Code ISO-4217 de la devise, typiquement `EUR` ou `USD`                                 |
| `price_period`     | string  | Période de facturation associée au montant : `month`, `year`, `one_time` ou `unknown`  |
| `price_confidence` | string  | Confiance d'extraction : `high`, `medium` ou `low`                                     |

## Cycle de vie

Cycle de vie standard des jobs outsend ; voir [/docs/fr/concepts/jobs-lifecycle](/docs/fr/concepts/jobs-lifecycle). Les jobs `pricing` sont sérialisés avec les autres jobs réseau intensifs du même compte.

## Pipeline

```
needs:    [site_web]
produces: [price_amount, price_currency, price_period, price_confidence]
```

Chaîne typique : `scrap -> pricing -> filter("price_amount >= 1000")`.

## Endpoints

| Méthode | Chemin                    | Rôle                                       |
| ------- | ------------------------- | ------------------------------------------ |
| `POST`  | `/api/jobs/pricing`       | Créer un job de tarifs                     |
| `GET`   | `/api/jobs`               | Lister les jobs de l'appelant              |
| `GET`   | `/api/jobs/{id}`          | Lire un job et sa progression              |
| `GET`   | `/api/jobs/{id}/download` | Télécharger les résultats en JSON ou CSV   |
| `POST`  | `/api/jobs/{id}/cancel`   | Arrêter un job en cours                    |

### Créer un job

```http
POST /api/jobs/pricing
Content-Type: application/json

{
  "items": [
    { "site_web": "https://example-saas.com" },
    { "site_web": "https://another-vendor.io" }
  ],
  "source_job_id": "job_01HX..."
}
```

## Limites

Voir [/docs/fr/concepts/limits](/docs/fr/concepts/limits). Un seul job `pricing` concurrent par compte.

## Erreurs

Issue par item plutôt qu'échec du job entier.

| Condition                  | Comportement                                                              |
| -------------------------- | ------------------------------------------------------------------------- |
| Aucune page tarifs trouvée | Ligne renvoyée avec `price_amount` vide et `price_confidence = low`. Le job termine en `done`. |
| Mur de connexion           | Ligne renvoyée avec `price_amount` vide et `price_confidence = low`.      |

Les erreurs au niveau du job — payload invalide, entrée vide après filtrage, quota dépassé — apparaissent en `400` depuis `POST /api/jobs/pricing` avec un message `JobValidationError`.

## Pour aller plus loin

- [Stack technique](/docs/fr/modules/techstack) — détecte les technologies derrière les mêmes sites pour croiser prix et profil de build.
- [Profil marketing](/docs/fr/modules/ads_intelligence) — repère parmi les fournisseurs tarifés ceux qui investissent activement en acquisition payante.


<!-- doc: modules/reviews -->

---
title: Avis
slug: modules/reviews
section: Modules
summary: Module d'enrichissement qui extrait le flux complet d'avis Google pour chaque point d'intérêt d'une liste.
---

## Purpose

Module d'enrichissement : transforme une liste de POI (avec lien Google Maps) en flux à plat d'avis — auteur, note, date, texte, drapeau de réponse propriétaire. Typiquement chaîné après `scrap`.

## Inputs

Corps JSON avec une liste d'items POI. Chaque item doit porter un lien Google Maps ; les autres colonnes sont conservées comme contexte mais ignorées pour l'extraction.

| Field           | Type     | Required | Description                                                                  |
| --------------- | -------- | -------- | ---------------------------------------------------------------------------- |
| `items`         | `list`   | yes      | Lignes POI. Entre 1 et 10000 entrées par job.                                |
| `source_job_id` | `string` | no       | UUID du job amont (typiquement un job `scrap`). Utilisé pour la traçabilité. |

Chaque entrée d'`items` est un objet. La seule clé requise est `lien_google_maps`. Les autres clés sont propagées inchangées et rattachées à chaque ligne d'avis produite.

| Item key            | Type     | Required | Notes                                                       |
| ------------------- | -------- | -------- | ----------------------------------------------------------- |
| `lien_google_maps`  | `string` | yes      | URL canonique Google Maps du POI. Les items sans ce champ sont rejetés à la validation. |
| `nom`               | `string` | no       | Nom de l'établissement, propagé à chaque ligne d'avis.      |
| `adresse`           | `string` | no       | Adresse postale, propagée.                                  |
| `telephone`         | `string` | no       | Propagé.                                                    |
| `site_web`          | `string` | no       | Propagé.                                                    |

Exemple de requête :

```json
{
  "source_job_id": "9d2f8e0a-1c4b-4f7e-a2b9-3d6a5e10c8f1",
  "items": [
    {
      "nom": "Boulangerie Centrale",
      "adresse": "12 rue de la Paix, 75002 Paris",
      "lien_google_maps": "https://www.google.com/maps/place/..."
    },
    {
      "nom": "Garage Dupont",
      "lien_google_maps": "https://www.google.com/maps/place/..."
    }
  ]
}
```

## Outputs

Une ligne par avis (pas par POI). Le contexte POI est dupliqué sur chaque ligne.

| Column              | Type      | Description                                                       |
| ------------------- | --------- | ----------------------------------------------------------------- |
| `nom`               | `string`  | Nom de l'établissement (depuis l'entrée).                         |
| `adresse`           | `string`  | Adresse de l'établissement (depuis l'entrée).                     |
| `lien_google_maps`  | `string`  | URL POI source.                                                   |
| `reviewer_name`     | `string`  | Nom public de l'auteur de l'avis.                                 |
| `rating`            | `integer` | Note en étoiles, 1–5.                                             |
| `date`              | `string`  | Date relative telle que publiée par Google (ex. "il y a 2 mois"). |
| `review_text`       | `string`  | Corps de l'avis.                                                  |
| `owner_replied`     | `boolean` | `true` quand le propriétaire a posté une réponse publique.        |
| `owner_reply_text`  | `string`  | Corps de la réponse du propriétaire, vide sinon.                  |

Deux formats d'export : CSV (UTF-8, séparateur virgule, quoting RFC 4180) et XLSX. Le CSV est canonique.

## Lifecycle

Cycle de vie standard : voir [Jobs & lifecycle](/docs/fr/concepts/jobs-lifecycle).

## Pipeline

| Slot          | Value                                          |
| ------------- | ---------------------------------------------- |
| `category`    | `enrich`                                       |
| `needs`       | `poi_list` (nécessite `lien_google_maps`)      |
| `produces`    | `reviews_list`, `owner_replied`                |

Amont : [`scrap`](/docs/fr/modules/scrap), ou tout import avec colonne `lien_google_maps` valide. Aval : typiquement [`filter`](/docs/fr/modules/filter) et [`sort`](/docs/fr/modules/sort) pour restreindre par note, réponse propriétaire, ou récence.

## Endpoints

Spécifique au module :

```
POST /api/jobs/reviews
```

Corps : `ReviewsJobCreateRequest` (voir Inputs). Retourne le job créé en `pending`.

Endpoints job génériques :

| Method | Path                          | Purpose                          |
| ------ | ----------------------------- | -------------------------------- |
| GET    | `/api/jobs/{job_id}`          | Récupère l'état et les métadonnées du job. |
| GET    | `/api/jobs/{job_id}/events`   | Flux SSE des événements de progression. |
| GET    | `/api/jobs/{job_id}/download` | Téléchargement du CSV/XLSX produit. |
| POST   | `/api/jobs/{job_id}/cancel`   | Demande d'annulation.            |

## Limits

Quotas globaux : voir [/docs/fr/concepts/limits](/docs/fr/concepts/limits). Le module `reviews` consomme environ `0.4 / 3700` EF par POI. Bornes payload : 1 à 10000 items par job. Pas de plafond côté client sur le nombre d'avis par POI.

## Errors

| Condition                                | Outcome                                                                              |
| ---------------------------------------- | ------------------------------------------------------------------------------------ |
| Aucun item ne porte de `lien_google_maps`     | La création échoue avec HTTP 400 et message `Aucun établissement valide`.       |
| Coût estimé supérieur au quota per-job        | La création échoue avec HTTP 400 et un message explicite `Quota dépassé`.       |
| POI sans avis publics                         | Le POI est traité ; zéro ligne émise pour lui. Le job réussit malgré tout.      |
| Source temporairement indisponible pour un POI | Ce POI est sauté et remonté dans le résumé du job ; les autres POI continuent. |
| Source injoignable sur l'ensemble du run      | Le job termine en `failed` avec l'erreur amont remontée sur le job.             |

## What's next

- [Module Scrap](/docs/fr/modules/scrap) — producteur canonique amont de listes POI.
- [Module Filter](/docs/fr/modules/filter) — restreindre le flux d'avis par note, récence ou réponse propriétaire.
- [Jobs lifecycle](/docs/fr/concepts/jobs-lifecycle) — états, événements et sémantique d'annulation.


<!-- doc: modules/scrap -->

---
title: Scrap (Google Maps)
slug: modules/scrap
section: Modules
summary: Module source qui extrait des fiches Google Maps pour un ensemble de requêtes sur une ou plusieurs zones géographiques.
---

## Purpose

Module source : exécute chaque requête sur chaque point de grille couvrant les zones demandées et retourne un CSV à plat d'établissements Google Maps (nom, contact, localisation, note).

## Inputs

| Field | Type | Required | Description |
|---|---|---|---|
| `queries` | `string[]` (1–20) | yes | Termes recherchés sur Google Maps. Chaque requête est trimée et plafonnée à 200 caractères. |
| `zones` | `string[]` (1–50) | yes | Zones géographiques. Accepte codes INSEE, codes département, noms de région, ou `"France"`. Chaque zone est résolue en grille de points côté serveur. |
| `include_reviews` | `bool` | no | Conservé pour compatibilité ascendante. Ne chaîne pas un job reviews — utiliser le module `reviews` à la place. Défaut `false`. |

Corps de requête :

```json
{
  "queries": ["plombier", "chauffagiste"],
  "zones": ["75", "92"],
  "include_reviews": false
}
```

Requêtes Google Maps effectives = `len(queries) × grid_points(zones)`. Rejeté à la soumission si coût supérieur au plafond per-job EF.

## Outputs

Fichier résultat : CSV UTF-8, séparateur point-virgule, BOM (compatible Excel). Même jeu de données disponible en trois formats via l'endpoint de téléchargement.

| Column | Type | Description |
|---|---|---|
| `nom` | string | Nom de l'établissement affiché sur Google Maps. |
| `site_web` | string | URL du site web public si renseignée. |
| `telephone` | string | Numéro de téléphone tel que listé. |
| `adresse` | string | Adresse postale. |
| `rating` | float | Note moyenne (0.0–5.0). |
| `reviews_count` | int | Nombre d'avis publics. |
| `category` | string | Catégorie principale Google Maps. |
| `lien_google_maps` | string | URL canonique Google Maps de la fiche. |
| `aggregator_flag` | bool | Vrai si la fiche ressemble à un annuaire/agrégateur plutôt qu'à un établissement final. |
| `query` | string | Requête source qui a produit la ligne. |
| `lat`, `lon` | float | Point de grille auquel la ligne a été collectée. |

Formats : `csv` (original), `json`, `xlsx`. Choisi via `?format=` sur l'endpoint de téléchargement.

## Lifecycle

Cycle de vie standard : voir [Jobs & lifecycle](/docs/fr/concepts/jobs-lifecycle). Pendant l'exécution, l'événement SSE `status` transporte une charge `query_stats` de forme `{ "<query>": { "tiles": int, "with_results": int } }`, mise à jour en temps réel pour exposer le taux de succès par requête.

## Pipeline

| Field | Value |
|---|---|
| `needs` | `null` (module source — aucun CSV d'entrée requis) |
| `produces` | `poi_list` |

Modules typiques chaînés en aval d'un `scrap` :

- [`emails`](/docs/fr/modules/emails) — recherche les emails pro et personnels depuis `site_web`.
- [`socials`](/docs/fr/modules/socials) — extrait les comptes réseaux sociaux depuis `site_web`.
- [`legal_ids`](/docs/fr/modules/legal_ids) — extrait SIREN/SIRET depuis le site de l'établissement (page mentions légales).
- [`reviews`](/docs/fr/modules/reviews) — collecte les fils d'avis complets depuis `lien_google_maps`.
- [`techstack`](/docs/fr/modules/techstack), [`dead_check`](/docs/fr/modules/dead_check), [`brand_assets`](/docs/fr/modules/brand_assets), [`ads_intelligence`](/docs/fr/modules/ads_intelligence) — enrichissements au niveau site web, indexés sur `site_web`.

## Endpoints

Endpoint dédié :

```
POST /api/jobs
Content-Type: application/json

{
  "queries": ["plombier"],
  "zones": ["75"],
  "include_reviews": false
}
```

Endpoint générique (équivalent — même payload, `job_type` déduit de la forme) :

```
POST /api/jobs
Content-Type: application/json

{
  "job_type": "scrap",
  "queries": ["plombier"],
  "zones": ["75"]
}
```

Les deux réponses retournent l'objet `JobPublic` créé, incluant `id`, `status`, `grid_points_count`, `ef_cost` et `output_filename`.

Téléchargement :

```
GET /api/jobs/{job_id}/download?format=csv|json|xlsx
```

## Limits

Quotas globaux de la plateforme : voir [/docs/fr/concepts/limits](/docs/fr/concepts/limits). Plafonds spécifiques au module :

| Limit | Value |
|---|---|
| Nombre maximum de requêtes par job | 20 |
| Nombre maximum de zones par job | 50 |
| Longueur maximum d'une requête | 200 caractères |
| Coût maximum par job | `1.0` équivalent-France (EF) |
| Vérification email | Requise sur le compte avant création d'un job `scrap`. |

## Errors

| Scenario | HTTP | Resolution |
|---|---|---|
| Zone non reconnue | 400 | Inspecter le tableau `errors` dans le corps de réponse ; utiliser codes INSEE/département ou `"France"`. |
| Aucun point de grille résolu | 400 | L'ensemble des zones est vide après résolution — élargir la sélection. |
| Quota EF dépassé | 400 | Réduire le nombre de requêtes ou rétrécir les zones jusqu'à EF estimé ≤ 1.0. |
| Email non vérifié | 403 | Vérifier l'email du compte avant de créer un job `scrap`. |
| Aucun worker disponible | Le job reste en `pending` jusqu'à libération du pool multi-proxy partagé. Un seul job multi-proxy tourne à la fois sur l'ensemble de la plateforme. |
| Job échoué en cours | Un CSV partiel est conservé. Un `POST /api/jobs/{id}/resume` crée un job de relance qui saute les points de grille déjà traités et n'est facturé que sur le reliquat. |
| Téléchargement expiré | 410 | Les fichiers résultats ont une fenêtre de rétention — relancer le job ou chaîner depuis une source fraîche. |

Les requêtes refusées par Google Maps remontent dans `dead_queries` sur l'objet job.

## What's next

- [Jobs lifecycle](/docs/fr/concepts/jobs-lifecycle)
- [Pipelines](/docs/fr/concepts/pipelines)
- [Module `emails`](/docs/fr/modules/emails)


<!-- doc: modules/socials -->

---
title: Réseaux sociaux
slug: modules/socials
section: Modules
summary: Module d'enrichissement qui attache les URLs de profils sociaux publics à chaque point d'intérêt portant un site web.
---

## Purpose

Module d'enrichissement : attache les URLs de profils sociaux publics (opérés par l'entité elle-même) à chaque POI portant un site web. Les liens parasites — boutons de partage, annuaires tiers, agrégateurs d'avis — sont écartés. Ne découvre pas d'entités, ne vérifie pas la propriété, n'accède à aucun contenu authentifié.

## Inputs

Corps JSON avec deux champs.

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | array of objects | yes | Entre 1 et 10 000 points d'intérêt. Chaque item doit porter un champ `site_web`. Les items sans site web sont filtrés avant la mise en file. |
| `source_job_id` | string | no | Identifiant d'un job amont dont la sortie alimente celui-ci. Sert à chaîner les modules dans un pipeline. |

Forme minimale d'un item :

```json
{
  "name": "Studio Atlas",
  "site_web": "https://studio-atlas.example"
}
```

Toute clé additionnelle sur les items d'entrée est conservée inchangée aux côtés des colonnes sociales.

## Outputs

Chaque item d'entrée est retourné avec les mêmes champs d'identification plus une colonne par réseau. Une colonne est laissée vide quand aucun profil n'est trouvé.

| Column | Type | Description |
|---|---|---|
| `social_facebook` | string | URL canonique de la page Facebook. |
| `social_instagram` | string | URL canonique du profil Instagram. |
| `social_linkedin` | string | URL canonique de la page entreprise ou du profil LinkedIn. |
| `social_twitter` | string | URL canonique du profil X (ex-Twitter). |
| `social_tiktok` | string | URL canonique du profil TikTok. |
| `social_youtube` | string | URL canonique de la chaîne YouTube. |

## Lifecycle

Cycle de vie standard : voir [Jobs & lifecycle](/docs/fr/concepts/jobs-lifecycle).

## Pipeline

| Property | Value |
|---|---|
| Category | enrich |
| Needs | `site_web` |
| Produces | `social_facebook`, `social_instagram`, `social_linkedin`, `social_twitter`, `social_tiktok`, `social_youtube` |
| Pipelinable | yes |
| Supports continuous monitoring | no |

Chaîne typique : `scrap` → `socials` → outreach. `source_job_id` relie le run à son parent.

## Endpoints

### Création d'un job socials

```
POST /api/jobs/socials
```

Le corps de requête correspond à la table `Inputs`. Réponse : une ressource `Job` avec identifiant, statut en file, et coût EF estimé.

```json
{
  "items": [
    { "name": "Studio Atlas", "site_web": "https://studio-atlas.example" },
    { "name": "Atelier Nord",  "site_web": "https://atelier-nord.example" }
  ],
  "source_job_id": "b1f2c3d4-..."
}
```

Une réponse réussie retourne :

```json
{
  "id": "f9e8d7c6-...",
  "job_type": "socials",
  "status": "pending",
  "items_count": 2,
  "ef_cost": 0.0011
}
```

### Lire l'état, suivre la progression, télécharger les résultats

Endpoints job standard sans changement :

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/api/jobs/{id}` | Instantané de l'état du job. |
| `GET` | `/api/jobs/{id}/events` | Flux server-sent events pour les mises à jour de progression. |
| `GET` | `/api/jobs/{id}/results` | Liste enrichie, JSON ou CSV. |

## Limits

Quotas globaux : voir [/docs/fr/concepts/limits](/docs/fr/concepts/limits). Plafonds spécifiques au module :

| Limit | Value |
|---|---|
| Items par job | 1 à 10 000 |
| Champ requis par item | `site_web` |

Les items sans `site_web` sont écartés à la validation. Si aucun item ne reste, le job est rejeté.

## Errors

Enveloppe d'erreur HTTP standard.

| Status | Code | Condition |
|---|---|---|
| 400 | `validation_error` | Le payload échoue la validation de schéma (`items` manquant, plus de 10 000 entrées, JSON malformé). |
| 400 | `no_eligible_items` | Aucun item soumis ne porte un `site_web` exploitable. |
| 400 | `quota_exceeded` | Le coût estimé dépasse le plafond du compte. Le corps de réponse porte l'estimation et le plafond. |
| 401 | `unauthenticated` | La requête n'a pas de session valide. |
| 403 | `inactive_account` | Le compte n'est pas actif. |
| 429 | `rate_limited` | Trop de créations de jobs dans une fenêtre courte. |

Les échecs par item ne font jamais échouer le job : colonnes vides pour cet item, remontées dans le résumé du job.

## What's next

- [Jobs lifecycle](/docs/fr/concepts/jobs-lifecycle) pour les transitions d'état et payloads d'événements.
- [Pipelines](/docs/fr/concepts/pipelines) pour chaîner `socials` avec des modules amont et aval.
- [Emails](/docs/fr/modules/emails) pour attacher des emails de contact à la même liste.
- [Tech stack](/docs/fr/modules/techstack) pour profiler la technologie derrière chaque site web.


<!-- doc: modules/sort -->

---
title: Trier
slug: modules/sort
section: Modules
---

## Objectif

Réordonner les lignes produites par une étape antérieure du pipeline selon une colonne choisie, en ordre croissant ou décroissant, et tronquer éventuellement le résultat aux N premières lignes. Sort est interne au pipeline (voir [/docs/fr/concepts/pipeline-orchestration](/docs/fr/concepts/pipeline-orchestration)) : il consomme la sortie du nœud prédécesseur et émet les mêmes colonnes dans un nouvel ordre. Un usage courant : ordonner une liste fraîchement scrapée par `completeness` décroissant et garder les 200 premières avant de transmettre le résultat à une étape de recherche d'emails ou de prospection. Sort n'ajoute, ne retire ni ne réécrit jamais de colonnes — la troncature est le seul changement de contenu qu'il puisse appliquer.

## Entrées

La configuration est attachée au nœud de pipeline. Il n'y a pas de corps de requête autonome.

| Champ       | Type                | Requis | Défaut         | Description                                                       |
|-------------|---------------------|--------|----------------|-------------------------------------------------------------------|
| `sort_by`   | chaîne (enum)       | oui    | `completeness` | Colonne servant de clé de tri.                                    |
| `direction` | `"asc"` \| `"desc"` | oui    | `desc`         | Sens du tri.                                                      |
| `top_n`     | entier \| `null`    | non    | `null`         | Garder uniquement les `top_n` premières lignes après tri. Min `1`. |

Valeurs acceptées pour `sort_by` :

| Valeur          | Signification                                                       |
|-----------------|---------------------------------------------------------------------|
| `completeness`  | Taux global de remplissage des champs d'enrichissement d'une ligne. |
| `note`          | Note en étoiles de l'établissement (Google Maps).                    |
| `nb_avis`       | Nombre d'avis sur l'établissement.                                  |
| `email_quality` | Score de qualité de l'email extrait (personnel > rôle).             |

`top_n` doit être un entier positif ou `null`. Une valeur `null` conserve toutes les lignes.

## Sorties

Même schéma que le nœud prédécesseur — sort est déclaré `passthrough` dans le graphe du pipeline. Le nœud aval voit les mêmes colonnes qu'il aurait vues sans l'étape de tri, simplement dans un ordre différent et éventuellement avec moins de lignes.

| Propriété          | Comportement                                                                |
|--------------------|------------------------------------------------------------------------------|
| Colonnes           | Identiques à l'entrée, octet pour octet.                                     |
| Ordre des lignes   | Déterminé par `sort_by` et `direction`.                                     |
| Nombre de lignes   | `min(input_count, top_n)` si `top_n` est défini, sinon égal à l'entrée.     |
| Type de pipeline   | Identique à la source amont (résolu transitivement à travers sort/filter).   |

## Cycle de vie

Cycle de vie de job standard — voir [/docs/fr/concepts/jobs-lifecycle](/docs/fr/concepts/jobs-lifecycle). Une étape de tri est créée automatiquement par le runner de pipeline lorsque le prédécesseur atteint `done`, et est traitée comme une étape structurelle de pipeline plutôt que comme une action facturable.

## Pipeline

| Propriété                | Valeur                       |
|--------------------------|------------------------------|
| Catégorie                | `process`                    |
| Pipelinable              | oui                          |
| Needs                    | aucun (accepte toute entrée) |
| Produces                 | aucun (sortie passthrough)   |
| Type d'entrée pipeline   | `any_pois`                   |
| Type de sortie pipeline  | `passthrough`                |

Comme le type de sortie est `passthrough`, le type effectif en aval est hérité du prédécesseur non-passthrough le plus proche. Un tri placé après `scrap` expose le même contrat aval que `scrap` exposerait seul.

## Endpoints

Sort n'a pas d'endpoint REST public — il est interne au pipeline (voir [/docs/fr/concepts/pipeline-orchestration](/docs/fr/concepts/pipeline-orchestration)) et créé exclusivement par le runner de pipeline lorsque le nœud prédécesseur termine, via l'aide interne `create_pipeline_internal_job(job_type="sort", …)`.

Pour utiliser sort, le définir comme un nœud dans un pipeline créé via l'API pipelines :

| Méthode | Chemin                        | Rôle                                              |
|---------|-------------------------------|---------------------------------------------------|
| POST    | `/api/pipelines`              | Créer un pipeline contenant un nœud `sort`.       |
| GET     | `/api/pipelines/{id}`         | Inspecter la configuration et les statuts.        |

Une entrée de nœud pour sort ressemble à :

```json
{
  "type": "sort",
  "config": {
    "sort_by": "completeness",
    "direction": "desc",
    "top_n": 200
  }
}
```

Le runner lit `config` à l'exécution et émet le CSV trié dans le répertoire de job du nœud.

## Limites

Limites globales — voir [/docs/fr/concepts/limits](/docs/fr/concepts/limits). Sort n'est pas facturé (coût quota `0`), tourne dans le pool parallèle standard, et sa taille d'entrée maximale est bornée par la sortie du prédécesseur, pas par sort lui-même.

## Erreurs

| Condition                              | Résultat                                                                       |
|----------------------------------------|--------------------------------------------------------------------------------|
| `sort_by` référence une colonne inconnue | Le nœud passe à `failed` ; les nœuds aval restent `pending`.                |
| `direction` n'est pas `asc` ou `desc`  | Le nœud passe à `failed` avec une erreur de validation.                        |
| `top_n` vaut `0` ou est négatif        | Rejeté à la création du pipeline ; l'API renvoie `400`.                        |
| Entrée vide                            | Le nœud termine en `done` avec un CSV de sortie vide.                          |
| Prédécesseur n'ayant pas atteint `done` | Sort reste `pending` ; il n'est jamais planifié tant que le parent n'a pas fini. |

## Et après

- [Filtrer](/docs/fr/modules/filter) — écarter les lignes ne correspondant pas à une règle avant, ou après, le tri.
- [Import](/docs/fr/modules/import) — introduire un CSV externe dans un pipeline pour pouvoir le trier.


<!-- doc: modules/techstack -->

---
title: Stack technique
slug: modules/techstack
section: Modules
---

# Stack technique

Détecte les technologies qui alimentent le site de chaque prospect — CMS, frameworks JavaScript, suites analytics, processeurs de paiement, hébergement et CDN — et retourne une ligne structurée par site.

Cas d'usage typiques :

- Qualifier les prospects par maturité (build sur mesure vs constructeur drag-and-drop).
- Filtrer par signal d'achat (analytics payant déjà en place, paiement par carte déjà actif).
- Router les leads vers la bonne offre selon la plateforme exploitée.

## Entrées

Les items sans `site_web` résolu sont écartés avant facturation.

| Champ              | Type   | Requis | Notes                                          |
| ------------------ | ------ | ------ | ---------------------------------------------- |
| `items`            | array  | oui    | 1 à 10 000 lignes de POI                       |
| `items[].site_web` | string | oui    | URL HTTP(S) du site à empreinter               |
| `source_job_id`    | string | non    | UUID d'un job amont à chaîner                  |

## Sorties

Une ligne enrichie par item d'entrée. La détection est best-effort : chaque colonne peut être `null` quand le signal est absent ou ambigu.

| Colonne           | Type            | Description                                                                                  |
| ----------------- | --------------- | -------------------------------------------------------------------------------------------- |
| `tech_cms`        | string \| null  | Système de gestion de contenu ou constructeur principal (ex. `wordpress`, `shopify`, `webflow`). |
| `tech_analytics`  | string \| null  | Produits analytics détectés (ex. `ga4`, `matomo`, `plausible`).                              |
| `tech_ads_pixels` | string \| null  | Pixels publicitaires détectés (ex. `meta`, `google_ads`, `linkedin`, `tiktok`).              |

Le rapport complet par site — hiérarchie à trois niveaux, signaux business, métadonnées techniques — est disponible sur la page de détail du job ; le CSV expose les signaux à plat ci-dessus pour le filtrage et le branchement de pipeline.

## Cycle de vie

Cycle de vie standard des jobs outsend ; voir [/docs/fr/concepts/jobs-lifecycle](/docs/fr/concepts/jobs-lifecycle). La progression est reportée par site, en unité `sites`.

## Pipeline

```
needs:    [site_web]
produces: [tech_cms, tech_analytics, tech_ads_pixels]
```

Tout module amont qui émet `site_web` — `scrap` étant la source canonique — peut alimenter `techstack`.

## Endpoints

### Créer un job

```
POST /api/jobs/techstack
```

```json
{
  "items": [
    { "site_web": "https://example.com" },
    { "site_web": "https://another.example" }
  ],
  "source_job_id": "8b3e…optional"
}
```

Retourne le job créé avec son `id` et son statut initial `pending`.

### Inspecter un job

```
GET /api/jobs/{job_id}
```

### Suivre la progression

```
GET /api/jobs/{job_id}/stream
```

Événements server-sent, un par site traité plus les transitions de statut terminal.

### Télécharger les résultats

```
GET /api/jobs/{job_id}/download
```

Retourne la liste enrichie. Chaque ligne porte les champs POI d'origine plus les colonnes documentées dans [Sorties](#sorties).

## Limites

Voir [/docs/fr/concepts/limits](/docs/fr/concepts/limits) pour les limites globales. Le schéma d'URL doit être `http://` ou `https://`. Un job avec zéro item valide après filtrage de `site_web` est rejeté en `400`.

## Erreurs

| HTTP | Code / message                                  | Quand                                                          |
| ---- | ----------------------------------------------- | -------------------------------------------------------------- |
| 400  | `Aucun établissement avec site web`             | Aucun item du payload n'a de `site_web` exploitable.           |
| 400  | `Quota dépassé`                                 | Le coût EF du job dépasse `MAX_EF_PER_JOB`.                    |
| 400  | Erreur de validation                            | Forme du payload invalide (taille, champs manquants, types).   |

Les erreurs sont renvoyées en JSON avec un champ `detail`. Une fois le job en cours, les échecs par item apparaissent dans la ligne de résultat (colonnes vides) plutôt qu'en erreur HTTP.

## Pour aller plus loin

La sortie `techstack` se compose naturellement avec :

- [`pricing`](/docs/fr/modules/pricing) — extrait les tarifs publiés et les plans depuis les mêmes sites.
- [`ads_intelligence`](/docs/fr/modules/ads_intelligence) — profile la maturité marketing (pixels, retargeting, CMP, CRM).
- [`pagespeed`](/docs/fr/modules/pagespeed) — mesure la performance réelle et les Core Web Vitals.


<!-- doc: modules/verify_emails -->

---
title: Vérification emails
slug: modules/verify_emails
section: Modules
---

# Vérification emails

Le module `verify_emails` valide la délivrabilité d'une liste d'adresses email avant l'envoi d'une campagne. Il vérifie la syntaxe, résout les enregistrements MX, ouvre une sonde contre le serveur récepteur, et signale les adresses jetables ou en forme de boîte générique de fonction.

Il s'exécute après une étape d'enrichissement ayant produit des emails, ou contre une liste importée. Le job est parallèle : il ne consomme pas de slot sur la file multi-proxy et peut tourner en même temps que des jobs d'extraction.

Les domaines jetables et alias sont détectés, y compris les fournisseurs modernes (Apple, DuckDuckGo, ProtonMail) que des outils similaires rejettent à tort. Les domaines catch-all sont remontés comme cas où la délivrabilité ne peut être garantie.

## Inputs

| Champ         | Requis | Source                                              |
|---------------|--------|-----------------------------------------------------|
| `email`       | oui    | issu d'un job `emails` précédent, ou importé        |
| `nom`         | non    | transmis en passe-plat vers la sortie               |
| `telephone`   | non    | transmis en passe-plat                              |
| `site_web`    | non    | transmis en passe-plat                              |

`needs: ['email']`. Les items sans `@` sont écartés à la création du job. La déduplication se fait sur l'adresse en minuscules. Le job accepte entre `1` et `10000` items par appel.

`source_job_id` est optionnel et pointe vers le job `emails` dont la sortie est vérifiée. L'UI expose ce sélecteur en `from_jobs_of_type: 'emails'`.

## Outputs

Le job produit un rapport de vérification. Chaque ligne porte l'adresse vérifiée, le verdict, et un passe-plat des champs d'identification de l'entrée.

| Colonne         | Type   | Signification                                                                                            |
|-----------------|--------|---------------------------------------------------------------------------------------------------------|
| `email`         | string | Adresse en minuscules telle que soumise                                                                  |
| `status`        | string | Verdict de délivrabilité (voir valeurs ci-dessous)                                                       |
| `category`      | string | Comment le verdict a été obtenu : `smtp`, `syntax`, `disposable`, `suspect`, `big_provider`, `no_mx`, `error` |
| `reason`        | string | Explication lisible du verdict                                                                           |
| `suggested_fix` | string | Correction suggérée en cas de typo évidente, si détectée (optionnel)                                     |
| `smtp_code`     | string | Code de réponse SMTP brut de la sonde, si un check SMTP a eu lieu                                        |
| `catch_all`     | string | `yes` / `no` / `unknown` — le domaine accepte-t-il n'importe quelle adresse                              |
| `nom`           | string | Transmis depuis l'entrée                                                                                 |
| `telephone`     | string | Transmis depuis l'entrée                                                                                 |
| `site_web`      | string | Transmis depuis l'entrée                                                                                 |

`status` prend l'une des valeurs :

| Valeur            | Signification                                                                              |
|-------------------|-------------------------------------------------------------------------------------------|
| `valid`           | Le serveur récepteur a accepté l'adresse — délivrable                                      |
| `valid_catch_all` | Accepté, mais le domaine est catch-all : l'acceptation n'est pas une garantie              |
| `invalid`         | Le serveur a rejeté l'adresse — ne pas envoyer                                             |
| `greylisted`      | Différé temporairement par le serveur ; réessayable plus tard                             |
| `unknown`         | Indéterminable (timeout, sonde bloquée…)                                                   |
| `filtered`        | Rejeté avant l'étape SMTP — syntaxe, jetable, rôle/suspect, ou pas de MX (voir `category`) |
| `skipped`         | Gros fournisseur gratuit (Gmail, Outlook…) qui rejette les sondes ; considéré délivrable   |

Les colonnes de signal (`status`, `category`) sont déclarées dans le registre des modules sous `produces`. Ce sont les colonnes sur lesquelles les campagnes et les nœuds `filter` / `sort` aval peuvent brancher.

## Cycle de vie

États de job standard — voir [Cycle de vie des jobs](/docs/fr/concepts/jobs-lifecycle). La progression est rapportée par email (`progress_unit: 'emails'`).

## Pipeline

Le module déclare le contrat suivant :

| Propriété      | Valeur                              |
|----------------|-------------------------------------|
| `needs`        | `email`                             |
| `produces`     | `status`, `category`   |
| `category`     | `verify`                            |
| `pipelinable`  | `true`                              |
| `supports_veille` | `false`                          |

Dans un pipeline, `verify_emails` accepte tout nœud amont qui émet `email` (typiquement `emails` ou `import`). Sa sortie `verified` peut alimenter un nœud `filter` ou `sort` en aval — filtrez sur `status` pour ne garder que les lignes délivrables (ex. `status` ∈ `valid`, `valid_catch_all`). Les nœuds d'enrichissement ne peuvent pas s'exécuter après `verify_emails` : le rapport de vérif ne porte pas les colonnes POI complètes qu'ils requièrent.

## Endpoints

### Créer un job

```
POST /api/jobs/verify-emails
```

Body :

```json
{
  "items": [
    { "email": "alex@example.com", "nom": "Alex", "site_web": "https://example.com" },
    { "email": "contact@example.org" }
  ],
  "source_job_id": "f3c2…"
}
```

`source_job_id` est optionnel. `items` est requis, avec au moins un enregistrement et au plus `10000`.

Réponse : `JobPublic` (l'enveloppe de job standard).

### Lire un job

Les endpoints de job standard s'appliquent :

```
GET  /api/jobs/{id}
GET  /api/jobs/{id}/events     # flux SSE
GET  /api/jobs/{id}/download   # CSV
```

Pour les caps par job et par compte, voir [Limites](/docs/fr/concepts/limits). Le débit est limité à environ cinq vérifications par seconde pour que l'IP sortante ne soit pas flaggée par les fournisseurs mail. Concurrence : le job tourne sur le pool de workers parallèle ; un `verify_emails` ne bloque jamais un scraping et n'est jamais bloqué par lui.

## Erreurs

| Code | Condition                                                                                                          |
|------|--------------------------------------------------------------------------------------------------------------------|
| 400  | `Aucun email valide dans la liste` — `items` vide, toutes les entrées sans `@`, ou toutes en doublon               |
| 400  | `Quota dépassé` — coût estimé supérieur à `MAX_EF_PER_JOB`                                                         |
| 401  | L'appelant n'est pas un utilisateur actif                                                                          |
| 422  | Le payload ne correspond pas à `VerifyEmailsJobCreateRequest`                                                      |

Les échecs par item (timeout MX, sonde SMTP refusée, etc.) ne font pas échouer le job. La ligne est écrite avec `status = unknown` et le job avance.

## Pour aller plus loin

- [delivery_check](/docs/fr/modules/delivery_check) — confirme que le serveur récepteur a réellement accepté une livraison de test, au-delà du handshake SMTP.
- [filter](/docs/fr/modules/filter) — ne garder que les lignes délivrables en filtrant sur `status` (`valid` / `valid_catch_all`), puis passer le résultat à une campagne ou un export.


<!-- doc: quickstart -->

---
title: Démarrage rapide
slug: quickstart
section: Démarrer
summary: De l'inscription au premier CSV exporté en moins de cinq minutes.
---

Le chemin le plus court d'un compte frais à une liste de prospects exploitable.

## 1. Obtenir un accès

outsend est en **alpha sur invitation**. Demander l'accès sur [outsend.xyz/demander-acces](https://outsend.xyz/demander-acces). Une fois approuvé, un code d'invitation arrive par email.

## 2. S'inscrire

Sur [outsend.xyz/signup](https://outsend.xyz/signup), le formulaire demande :

- Email
- Mot de passe (8 caractères min, au moins une lettre et un chiffre ou symbole)
- Le code d'invitation (`XXXX-XXXX-XXXX`)

Création immédiate. Un email de vérification est envoyé mais ne bloque pas l'usage.

## 3. Lancer un premier scrap

Depuis le dashboard, **New job → Scrap (Google Maps)**.

Remplir :

- **Queries** — quoi chercher, ex. `boulangerie`, `dentiste`, `cabinet comptable`. Plusieurs requêtes en chips.
- **Zones** — régions FR, départements, ou villes. Plusieurs zones supportées.
- **Include reviews** — active si le texte des avis doit être extrait (plus lent, plus riche).

Clic sur **Run**. Le job apparaît dans le dashboard avec un flux de logs en direct.

## 4. Suivre l'exécution

Ouvrir la page détail du job. La barre de status passe par `pending` → `running` → `done`. Les logs streament en temps réel via SSE. Voir [Jobs & cycle de vie](/docs/fr/concepts/jobs-lifecycle) pour la state machine complète.

Durées typiques :

- Petite requête, une seule ville : quelques minutes
- Scrap multi-régions avec avis : dizaines de minutes à quelques heures

## 5. Enrichir

Une fois le scrap fini, **Add module** sur la page détail enchaîne un enrichissement. Chaînages classiques :

- **Emails** — trouver les adresses email de chaque POI
- **Socials** — trouver les profils LinkedIn, Instagram, Facebook
- **Ads intelligence** — scorer chaque POI selon sa maturité marketing (signal premium : budget disponible)

Chaque enrichissement tourne comme un job séparé, partageant la liste de POI du job parent comme entrée.

## 6. Exporter

Sur tout job `done`, **Download** au format CSV, JSON ou XLSX. Les fichiers sont gardés **7 jours**, puis purgés.

## 7. (Optionnel) Construire un pipeline

Pour rejouer le même enchaînement, le construire une fois en **pipeline** : drag-and-drop des blocs, connecter, sauver. Le pipeline peut être relancé à la demande ou enregistré comme [veille](/docs/fr/concepts/veille-monitoring).

## Pour aller plus loin

- [Jobs & cycle de vie](/docs/fr/concepts/jobs-lifecycle) — comment un job passe de la création au résultat
- [Registre des modules](/docs/fr/concepts/module-registry) — liste complète, par catégories
- [Référence API](/docs/fr/api/overview) — tout piloter par programme


<!-- doc: what-is-outsend -->

---
title: Qu'est-ce qu'outsend
slug: what-is-outsend
section: Démarrer
summary: Un processeur de données de prospection B2B — extraire de Google Maps, enrichir, vérifier, orchestrer, surveiller.
---

outsend est un **processeur de données pour la prospection B2B**. À partir d'une requête et d'une zone, il produit une liste de prospects qualifiés exploitables, puis la maintient à jour dans le temps.

Trois couches :

## 1. Modules d'extraction

Tirent les données de sources publiques. Le module central : [`scrap`](/docs/fr/modules/scrap) (annonces Google Maps). Autour, les modules d'enrichissement par POI : [`reviews`](/docs/fr/modules/reviews), [`emails`](/docs/fr/modules/emails), [`socials`](/docs/fr/modules/socials), [`phones_extra`](/docs/fr/modules/phones_extra), [`legal_ids`](/docs/fr/modules/legal_ids), [`legal_mentions`](/docs/fr/modules/legal_mentions), [`legal_data`](/docs/fr/modules/legal_data).

## 2. Modules d'intelligence

Calculent des signaux sur une liste existante : [`pricing`](/docs/fr/modules/pricing), [`techstack`](/docs/fr/modules/techstack), [`pagespeed`](/docs/fr/modules/pagespeed), [`ads_intelligence`](/docs/fr/modules/ads_intelligence), [`brand_assets`](/docs/fr/modules/brand_assets), [`dead_check`](/docs/fr/modules/dead_check). Transforment une liste plate en quelque chose de segmentable.

## 3. Pipeline & veille

N'extraient rien — orchestrent : [`import`](/docs/fr/modules/import), [`filter`](/docs/fr/modules/filter), [`sort`](/docs/fr/modules/sort), plus vérification ([`verify_emails`](/docs/fr/modules/verify_emails), [`delivery_check`](/docs/fr/modules/delivery_check)).

Chaînés ensemble, ils forment un **pipeline** — un DAG éditable visuellement. Un pipeline peut tourner une fois, ou être enregistré comme **veille** qui rejoue à intervalle régulier et rapporte le delta avec le run précédent.

## Modèle mental

```
Requête + zone
     │
     ▼
 [scrap]  ──►  Points d'intérêt (POI)
     │
     ▼
 [emails] [socials] [legal_ids] ...   ──►  POI enrichis
     │
     ▼
 [filter] [sort]                       ──►  Liste curated
     │
     ▼
 Export (CSV / JSON / XLSX)
```

La même forme, enregistrée comme [veille](/docs/fr/concepts/veille-monitoring), rejoue tous les N jours et fait un diff avec le run précédent — surfaçant les nouveaux établissements, les fermetures et les évolutions de réputation comme des signaux.

## Ce qu'outsend n'est pas

- **Pas un CRM.** Les exports vont *vers* un CRM. outsend garde le CRM propre en filtrant en amont.
- **Pas un outil de cold email.** Les modules de campagne ([`email_campaign`](/docs/fr/modules/on-demand/email_campaign), [`sms_campaign`](/docs/fr/modules/on-demand/sms_campaign)) sont sur demande : l'équipe construit l'envoi plutôt que d'exposer un piège à délivrabilité.
- **Pas une base de contacts.** Chaque recherche tourne en direct. Pas de listes pré-construites obsolètes.