> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.aviz.co/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Automatiser les invitations depuis votre SI RH / CRM

## Principe

Le mécanisme **Copy Invite** permet à votre SI RH / CRM de déclencher automatiquement
l'envoi d'une invitation Aviz (témoignage ou avis) à un collaborateur, simplement
en envoyant un email via votre infrastructure existante.

Aucune API REST à appeler, aucune authentification à gérer : il suffit d'envoyer
un email correctement formaté.

## Prérequis

* Disposer d'une campagne de type **"Copy Invite"** active
* Être en mesure d'envoyer des emails depuis votre SI RH / CRM sur des évènements

## Adresse email dédiée

Chaque campagne Copy Invite possède une adresse email unique, au format :

```
avis.{slug-projet}.{identifiant-campagne}@invit.aviz.co
```

**Exemple :**
```
avis.acme.7bhgoq@invit.aviz.co
```

Cette adresse vous est affichée à la création de votre invitation ou communiquée par votre référent.

## Format de l'email à envoyer

### Champs obligatoires

| Champ | Valeur attendue |
| ---- |
| **To** | L'adresse dédiée de la campagne (`avis.acme.7bhgoq@invit.aviz.co`) |
| **Corps du message** | Doit contenir le bloc JSON `[@aviz ... @aviz]` (voir ci-dessous) |

> L'adresse dédiée doit être placée dans le champ **To** (ou **Bcc**).
> Le champ **From** doit être une adresse préalablement déclarée comme expéditeur autorisé sur la campagne (voir section [Sécurité](#sécurité--expéditeurs-autorisés)).

### Bloc de données JSON

Le corps du message (text/plain) doit contenir le bloc suivant, qui peut être
placé n'importe où dans le texte :

```
[@aviz
{
  "recipientFirstName": "Guillaume",
  "recipientLastName": "Dubois",
  "recipientEmail": "guillaume.dubois@acme.fr",
  "recipientTitle": "Commercial",
  "recipientLocation": "Lyon",
  "recipientLanguage": "fr",
  "fromName": "Marc Dupuis",
  "fromEmail": "m.dupuis@acme.fr",
  "fromTitle": "DRH"
}
@aviz]
```

### Description des champs

| Champ | Obligatoire | Description |
| ---- |
| `recipientFirstName` | ✅ | Prénom du collaborateur à inviter |
| `recipientLastName` | ✅ | Nom du collaborateur à inviter |
| `recipientEmail` | ✅ | Adresse email du collaborateur à inviter |
| `recipientTitle` | ❌ | Intitulé du poste du collaborateur |
| `recipientLocation` | ❌ | Lieu / site du collaborateur |
| `recipientLanguage` | ❌ | Langue de l'invitation (`fr`, `en`, `de`, `es`, `it`, `nl`, `pt`). Par défaut : langue configurée sur le projet |
| `fromName` | ❌ | Nom de l'expéditeur affiché dans l'invitation (si la campagne est configurée en mode expéditeur personnalisé) |
| `fromEmail` | ❌ | Email de l'expéditeur affiché |
| `fromTitle` | ❌ | Titre / fonction de l'expéditeur affiché |

## Sécurité — expéditeurs autorisés

Pour des raisons de sécurité, **le système n'accepte les invitations que si l'adresse email de l'expéditeur (`From`) figure dans la liste blanche définie sur la campagne**.

Si cette liste est absente ou vide, toutes les invitations sont **silencieusement ignorées**.

> **⚠️ Action requise pour finaliser le paramétrage :**
> Communiquez à votre référent la (ou les) adresse(s) email que votre SI RH utilisera comme expéditeur. Sans cette étape, aucune invitation ne sera traitée.

> Exemple : `trigger@mon-entreprise.fr`

## Comportement du système

1. L'email est reçu et analysé par Aviz
2. Le collaborateur est créé automatiquement dans la base s'il n'existe pas encore
3. Il est ajouté à la file d'invitation de la campagne
4. L'invitation lui est envoyée selon le délai configuré à nous communiquer :
* **Délai 0** : envoi immédiat
* **Délai ≥ 1 jour** : envoi le lendemain ou plus selon la configuration
5. Un même collaborateur ne peut pas être invité deux fois dans un délai de 3 mois
   sur la même campagne

## Codes de retour

| Réponse | Signification |
| ---- |
| `"Invit received and processed from software"` | Email traité avec succès |
| `"error : json not valid"` | Le bloc JSON est malformé |
| `"error : json not complete, must have first name, last name and email"` | Un champ obligatoire est manquant ou vide |
| `"error : recipientEmail is not a valid email address"` | L'email du destinataire n'est pas valide |

## Exemple complet

```
From:    trigger@acme.fr          ← doit être déclaré comme expéditeur autorisé
To:      avis.acme.7bhgoq@invit.aviz.co
Subject: Nouvelle recrue

[@aviz
{
  "recipientFirstName": "Sophie",
  "recipientLastName": "Martin",
  "recipientEmail": "s.martin@acme.fr",
  "recipientTitle": "Chargée de recrutement",
  "recipientLocation": "Paris",
  "recipientLanguage": "fr"
}
@aviz]
```

## Conseils d'intégration

* Le corps peut contenir d'autre texte avant et après le bloc `[@aviz ... @aviz]` :
  seul le contenu entre les balises est analysé
* Le champ `From` peut être une adresse technique (ex. `noreply@acme.fr`) ou
  nominative selon vos préférences
* En cas d'erreur de format JSON, vérifiez que votre template ne génère pas de
  caractères spéciaux non échappés dans les valeurs (guillemets, retours à la ligne)