# Qu'est ce que l'API Engagement ?

**L'API Engagement est un service public numérique qui permet aux plateformes d'engagement associatives, publiques et privées de mettre en commun leurs missions.**

## À quoi sert l'API Engagement ?

L'API Engagement permet au plus grand nombre d'accéder aux opportunités d'engagement en simplifiant le partage et la diffusion de missions de bénévolat et de volontariat.

Avec cette technologie, les points de rencontres sont multipliés : les annonces de missions de bénévolat / volontariat sont accessibles aux bons endroits, c'est-à-dire là où les personnes qui souhaitent s'engager se trouvent : sites de mairies, applications, plateformes d'engagement, etc. L'API Engagement permet ainsi :

* Côté annonceur, de publier des missions afin de démultiplier la visibilité de celles-ci afin d'augmenter le nombre de personnes qui candidatent aux actions.
* Côté diffuseur, d'exposer son audience à des missions de bénévolat et de volontariat sur son site internet en propre.

L'API Engagement propose également à ses utilisateurs un **tableau de bord pour tracker les clics et candidatures générés via ses outils**. Ainsi, chaque acteur (annonceur ou diffuseur) est capable d'identifier l'impact de ses actions.

<figure><img src="https://2489729786-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG18aCd8mNuBlmkXXgR3Q%2Fuploads%2FkP6Xoa3qBcG4CnG6ToVf%2Fimage.png?alt=media&amp;token=6d53a768-af3d-4938-8b65-d37d7f1a5fa3" alt=""><figcaption><p>Tableau de Bord API mis à disposition des annonceurs et des diffuseurs</p></figcaption></figure>


# À qui s'adresse l'API Engagement ?

Définition des termes "Annonceur" et "Diffuseur"

L'API Engagement est un outil qui permet de connecter les acteurs de l'engagement. En intégrant API Engagement, ces acteurs vont jouer l'un de ces rôles (ou les deux) :&#x20;

* le rôle d'"Annonceur",&#x20;
* le rôle de "Diffuseur"

### Qu'est ce qu'un "Annonceur" ?

Un annonceur est un acteur qui intègre l'API Engagement pour partager des missions d'engagement pour lesquelles il souhaite recruter des bénévoles et/ou des volontaires.

### Pourquoi partager mes missions en tant qu'Annonceur ?

* Les annonceurs partagent leurs missions grâce à l'API Engagement car ils ont un **besoin de recruter** des **bénévoles** ou des **volontaires**.
* Avec l'API Engagement, l'Annonceur augmente la visibilité de ses missions en les exposant à des milliers de personnes grâce notamment au second type d'acteur : les diffuseurs qui vont rediriger vers le site de l’annonceur.

### Qu'est-ce qu'un "Diffuseur" ?&#x20;

Un diffuseur est un acteur qui va, grâce à l'API Engagement, diffuser des missions d'engagement auprès de son audience.

### **Pourquoi diffuser des missions en tant que "Diffuseur" ?**

* Les diffuseurs de l'API Engagement choisissent de promouvoir l'engagement et **proposent à leur public** de participer aux missions de bénévolat ou de volontariat proposées par les annonceurs.
* C'est pour eux une manière d'engager l'audience de leur site internet à s'engager auprès d'associations ou d'organismes d'accueil dans de multiples domaines : santé, sport, solidarité, écologie par exemple.
* Les Diffuseurs ont 3 possibilités pour promouvoir l'engagement en diffusant plus de 40 000 missions de bénévolat et de volontariat (cf. [Les différents moyens de diffusion](/diffuser-des-missions/diffuser-des-missions-dengagement-sur-mon-site))


# Comment devenir partenaire ?

Une équipe engagée se tient à votre disposition pour vous accompagner à rejoindre le réseau des acteurs connectés en faveur de l’engagement. Pour devenir partenaire de l'API Engagement, il suffit d'une simple prise de contact via notre formulaire de demande d'informations. &#x20;

{% embed url="<https://api-engagement.beta.gouv.fr/#contact>" %}


# Les étapes à suivre pour partager des missions d'engagement à l'API Engagement

* **Étape 0** : **Devenir partenaire de l'API Engagement**

  Contactez l'équipe de l'API Engagement via [cette page](https://api-engagement.beta.gouv.fr/#contact).

* **Étape 1 : Mettre ses missions à disposition de l'API Engagement** \
  Deux options :
  * via un flux XML (cf. Méthode 1 : [Création d'un flux XML](/annoncer-des-missions/creation-dun-flux-xml/methode-1-creation-dun-flux-xml)) ;
  * via l'API (cf. Méthode 2 : [Création de missions par API](/annoncer-des-missions/creation-dun-flux-xml/methode-2-creation-de-missions-par-api))

* **Étape 2 : Mettre en place le suivi des candidatures**

  Deux cas de figure selon votre dispositif :

  * Cas n°1 : [Votre site internet recueille lui-même les candidatures](/annoncer-des-missions/tracking-des-candidatures/cas-n-1-votre-site-internet-recueille-lui-meme-les-candidatures) (formulaire ou parcours utilisateur avec création de compte) : ajoutez le script de suivi des candidatures sur votre site.
  * Cas n°2 : [Votre site internet ne permet pas de recueillir les candidatures](/annoncer-des-missions/tracking-des-candidatures/cas-n-2-votre-site-internet-ne-permet-pas-de-recueillir-les-candidatures) (pas de formulaire ni de parcours d'inscription) : utilisez la connexion avec Démarches Numériques pour créer un formulaire d'inscription ; les candidatures seront trackées via cette connexion.

\
À l'issue de l'étape 2, vos missions peuvent être diffusées auprès du réseau de 300+ diffuseurs de l'API Engagement. Les bénévoles et volontaires seront alors redirigés sur votre site pour effectuer leur candidature.


# Étape 1 : mettre ses missions à disposition de l'API Engagement

Cette partie de la documentation est à destination de votre responsable informatique : elle présente les critères nécessaires pour créer votre flux XML ou partager des missions par API

## Accès et prérequis

Cette étape nécessite de disposer d’un **compte API Engagement déjà créé**.

Si ce n’est pas encore le cas, vous pouvez [contacter l'équipe API Engagement](https://api-engagement.beta.gouv.fr/#contact) afin de :

* créer votre compte,
* obtenir vos **identifiants d’accès**.

## Méthodes d’intégration disponibles

Il existe deux méthodes d'intégration pour partager ses missions d'engagement à l'API Engagement :&#x20;

Deux méthodes d’intégration sont proposées pour partager vos missions d’engagement :

* **Méthode 1 :** [création d'un flux XML](/annoncer-des-missions/creation-dun-flux-xml/methode-1-creation-dun-flux-xml)\
  Génération et mise à disposition d’un flux structuré contenant vos missions.
* **Méthode 2 :** [API](/annoncer-des-missions/creation-dun-flux-xml/methode-2-creation-de-missions-par-api)\
  Création et gestion des missions directement via l’API (création, modification, suppression).


# Méthode 1 : création d'un flux XML

Cette partie de la documentation est à destination de votre responsable informatique : elle présente les critères nécessaires pour créer votre flux XML, c’est-à-dire l’envoi d’informations vers l’API

## Introduction

Pour importer vos missions, vous devez mettre à disposition un flux XML. L'API actualise sa base de données de manière autonome en analysant le flux XML toutes les 3 heures.

Les partenaires annonceurs doivent mettre à disposition un flux XML qui sera récupéré **toutes les** **3 heures** par l’API Engagement afin de mettre à jour les missions qu’elle a en base de données.

Ce flux est accessible via un **lien public** qui renvoie un fichier XML. Pour télécharger ce flux, le processus est le suivant:

```javascript
 const xml = await fetch("<https://www.partenaire.fr/mes-missions.xml>", { headers }).then((response) => response.text());
```

Si cette commande ne permet pas d'avoir vos missions, alors le lien fourni est **mal configuré**.


# Format du flux XML

## 1. Architecture du fichier XML

```xml
<?xml version="1.0" encoding="UTF-8"?>
<source>
   <publisher>Example Job Site</publisher>
   <publisherurl><http://www.examplemissionsite.com></publisherurl>
   <lastBuildDate>Fri, 10 March 2020 22:49:39 GMT</lastBuildDate>
   <mission>
      <title><![CDATA[Sales Executive]]></title>
      <clientId><![CDATA[32132143]]></clientId>
			{...}
      <organizationFullAddress><![CDATA[55 Rue du Faubourg Saint-Honoré 75008 Paris]]></organizationFullAddress>
   </mission>
    [...]
</source>
```

## 2. Règles de fonctionnement du flux

Le flux XML doit contenir **l’ensemble des missions actives**.

### Synchronisation avec l’API Engagement

* Toute mission présente dans le flux et absente de l’API → **est créée**
* Toute mission présente dans le flux et déjà existante → **est mise à jour**
* Toute mission absente du flux mais existante dans l’API → **est supprimée**

👉 Le flux agit donc comme une **source de vérité complète** (logique de synchronisation totale)

### Contraintes de format

* Le flux doit respecter le **modèle de données de l’API Engagement**
* Le fichier doit être encodé en **UTF-8**
* Les champs textuels doivent être encapsulés dans des balises **CDATA**
* Une mission = une balise `<mission>`
* Les champs multiples doivent être structurés en **sous-balises XML** (et non en texte concaténé)

## 3. Exemple de fichier XML avec encodage UTF-8

```xml
<?xml version="1.0" encoding="UTF-8"?>
<source>
  <publisher>Example Job Site</publisher>
  <publisherurl>http://www.examplemissionsite.com</publisherurl>
  <lastBuildDate>Fri, 10 March 2020 22:49:39 GMT</lastBuildDate>

  <mission>
    <title><![CDATA[Sales Executive]]></title>
    <clientId><![CDATA[32132143]]></clientId>

    <description><![CDATA[
      Do you have 1-3 years of experience (...) sign up !
    ]]></description>

    <applicationUrl><![CDATA[https://www.urltomymission.org]]></applicationUrl>

    <postedAt><![CDATA[2005-12-10T22:49:39.000Z]]></postedAt>
    <startAt><![CDATA[2005-12-10T22:49:39.000Z]]></startAt>
    <endAt><![CDATA[2005-12-20T22:49:39.000Z]]></endAt>

    <addresses>
      <address>
        <street><![CDATA[46 Rue Saint-Antoine]]></street>
        <postalCode><![CDATA[75004]]></postalCode>
        <city><![CDATA[Paris]]></city>
        <departmentCode><![CDATA[75]]></departmentCode>
        <departmentName><![CDATA[Paris]]></departmentName>
        <region><![CDATA[Île-de-France]]></region>
        <country><![CDATA[France]]></country>
      </address>

      <address>
        <street><![CDATA[Quai de Loire]]></street>
        <postalCode><![CDATA[45000]]></postalCode>
        <city><![CDATA[Orléans]]></city>
        <departmentCode><![CDATA[45]]></departmentCode>
        <departmentName><![CDATA[Loiret]]></departmentName>
        <region><![CDATA[Centre-Val de Loire]]></region>
        <country><![CDATA[France]]></country>
      </address>
    </addresses>

    <places><![CDATA[2]]></places>

    <activities>
      <activity><![CDATA[logistique]]></activity>
    </activities>

    <remote><![CDATA[full]]></remote>
    <domain><![CDATA[environnement]]></domain>

    <tags>
      <tag><![CDATA[environnement]]></tag>
      <tag><![CDATA[écologie]]></tag>
    </tags>

    <image><![CDATA[https://monurl.com/1.jpg]]></image>

    <organizationName><![CDATA[Big ABC Corporation]]></organizationName>
    <organizationRNA><![CDATA[W922000733]]></organizationRNA>
    <organizationSiren><![CDATA[332737394]]></organizationSiren>
    <organizationUrl><![CDATA[https://www.organizationname.com]]></organizationUrl>
    <organizationClientId><![CDATA[123312321]]></organizationClientId>
    <organizationType><![CDATA[Association déclarée]]></organizationType>
    <organizationFullAddress><![CDATA[55 Rue du Faubourg Saint-Honoré 75008 Paris]]></organizationFullAddress>
    <organizationStatusJuridique><![CDATA[Association]]></organizationStatusJuridique>

    <compensationAmount><![CDATA[100]]></compensationAmount>
    <compensationUnit><![CDATA[day]]></compensationUnit>
    <compensationType><![CDATA[net]]></compensationType>

  </mission>
</source>
```


# Liste des champs à inclure dans le flux XML

### ℹ️ Source de vérité

> La définition complète des champs (types, contraintes, enums) est disponible dans la documentation API :\
> → API Référence – [Créer / Mettre à jour une mission](/api-reference/mission-mission/creer-mettre-a-jour)

## 1. Informations principales de la mission

| Champ XML      | Champ API      | Obligatoire | Description                                                                                                      |
| -------------- | -------------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
| clientId       | clientId       | ✅           | Identifiant unique de la mission dans votre système d'information (immuable)                                     |
| title          | title          | ✅           | Titre de la mission                                                                                              |
| description    | description    | ✅           | Description complète de la mission. Texte brut ou HTML acceptés, stockés tels quels.                             |
| applicationUrl | applicationUrl | ✅           | URL de la page où l'utilisateur sera redirigé pour candidater (URL de la page présentant la mission)             |
| image          | image          | ❌           | URL de l'image de la mission. Si absent, l'API Engagement utilise une image de sa bibliothèque selon le domaine. |
| metadata       | metadata       | ❌           | Métadonnées libres associées à la mission.                                                                       |

## 2. Classification de la mission

| Champ XML     | Champ API  | Obligatoire | Description                                                                                    |
| ------------- | ---------- | ----------- | ---------------------------------------------------------------------------------------------- |
| domain        | domain     | ✅           | Domaine d'action de la mission.                                                                |
| activities\[] | activities | ❌           | Activité(s) principale(s) de la mission.                                                       |
| tags\[]       | tags       | ❌           | Mots-clés personnalisés pour taguer la mission. Chaque élément du tableau est un tag distinct. |

## 3. Public & compétences

| Champ XML       | Champ API    | Obligatoire | Description                                                                                                                                |
| --------------- | ------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| audience\[]     | audience     | ❌           | Les bénéficiaires de la mission — à qui la mission s'adresse, le public auquel sera confronté la personne qui s'engage.                    |
| requirements\[] | requirements | ❌           | Pré-requis relatifs à la mission.                                                                                                          |
| softSkills\[]   | softSkills   | ❌           | Les compétences générales requises pour la mission. Ce champ ne repose pas sur un référentiel de compétence structuré.                     |
| romeSkills\[]   | romeSkills   | ❌           | Code OGR Macro du ROME 4.0. Ce champ repose sur le référentiel "Arborescence simplifiée des compétences" (section "Arborescence du ROME"). |

## 4. Modalités de la mission

| Champ XML | Champ API | Obligatoire | Description                                                                                                                                                                               |
| --------- | --------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| remote    | remote    | ❌           | Disponibilité en distanciel.                                                                                                                                                              |
| schedule  | schedule  | ❌           | Rythme de la mission (texte libre)                                                                                                                                                        |
| startAt   | startAt   | ❌           | Date de début de la mission souhaitée. Format ISO 8601.                                                                                                                                   |
| endAt     | endAt     | ❌           | Date de fin de la mission souhaitée. Format ISO 8601.                                                                                                                                     |
| postedAt  | postedAt  | ❌           | Date de première publication de la mission. Format ISO 8601.                                                                                                                              |
| places    | places    | ❌           | Nombre de places disponibles pour la mission. Ce nombre doit être mis à jour dès qu'il évolue dans votre système afin que l'API Engagement dispose toujours de la donnée la plus récente. |

## 5. Indemnisation

| Champ XML          | Champ API          | Obligatoire | Description                                                         |
| ------------------ | ------------------ | ----------- | ------------------------------------------------------------------- |
| compensationAmount | compensationAmount | ❌           | Montant de l'indemnisation perçue par le bénévole ou le volontaire. |
| compensationUnit   | compensationUnit   | ❌           | Période de l'indemnisation pour le montant fourni.                  |
| compensationType   | compensationType   | ❌           | Type d'indemnisation.                                               |

## 6. Accessibilité & conditions

| Champ XML                 | Champ API                 | Obligatoire | Description                                          |
| ------------------------- | ------------------------- | ----------- | ---------------------------------------------------- |
| openToMinors              | openToMinors              | ❌           | Mission ouverte aux mineurs.                         |
| reducedMobilityAccessible | reducedMobilityAccessible | ❌           | Mission accessible aux personnes à mobilité réduite. |
| closeToTransport          | closeToTransport          | ❌           | Mission proche des transports en commun.             |

## 7. Localisation de la mission

| Champ XML    | Champ API | Obligatoire | Description                                                                                                                                                                                                                  |
| ------------ | --------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| addresses\[] | addresses | ✅           | Ensemble des localisations où se déroule la mission. Si la mission se tient dans plusieurs lieux, renseignez autant d'objets que de localisations. Pour une mission en lieu unique, le tableau ne contient qu'un seul objet. |

#### Détail d’un objet `address`

| Champ XML      | Champ API                | Description                                                                                                  |
| -------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------ |
| street         | addresses.street         | Rue où la mission se déroule                                                                                 |
| postalCode     | addresses.postalCode     | Code postal du lieu où la mission se déroule                                                                 |
| city           | addresses.city           | Ville où la mission se déroule                                                                               |
| departmentCode | addresses.departmentCode | Département où la mission se déroule                                                                         |
| departmentName | addresses.departmentName | Nom du département où la mission se déroule                                                                  |
| region         | addresses.region         | Nom de la région où la mission se déroule                                                                    |
| country        | addresses.country        | Nom du pays où la mission se déroule. La mission doit avoir le code du pays au format **ISO 3166-1 alpha-2** |

## 8. Typologie de mission

| Champ XML | Champ API | Obligatoire | Description                  |
| --------- | --------- | ----------- | ---------------------------- |
| type      | type      | ✅           | Type de mission d'engagement |

## 9. Organisation

| Champ XML                    | Champ API                   | Obligatoire | Description                                                                                                                          |
| ---------------------------- | --------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| organizationClientId         | organizationClientId        | ❌           | Identifiant de l'organisation dans votre système. L'organisation désigne l'entité qui accueille le bénévole ou le volontaire.        |
| organizationName             | organizationName            | ⚠️          | Nom de l'organisation. Requis si un autre champ organization\* est renseigné.                                                        |
| organizationDescription      | organizationDescription     | ❌           | Description de l'organisation.                                                                                                       |
| organizationUrl              | organizationUrl             | ❌           | Lien de l'organisation (ex. page de présentation sur votre site).                                                                    |
| organizationType             | organizationType            | ❌           | Type de l'organisation.                                                                                                              |
| organizationLogo             | organizationLogo            | ❌           | URL de l'image de l'organisation.                                                                                                    |
| organizationRNA              | organizationRNA             | ❌           | Numéro RNA de l'organisation. Uniquement valable pour les organisations de type association.                                         |
| organizationSiren            | organizationSiren           | ❌           | SIREN de l'organisation.                                                                                                             |
| organizationSiret            | organizationSiret           | ❌           | SIRET de l'organisation.                                                                                                             |
| organizationFullAddress      | organizationFullAddress     | ❌           | Adresse de l'organisation. Pas de format strict attendu (contrairement à l'adresse de la mission).                                   |
| organizationPostCode         | organizationPostCode        | ❌           | Code postal de l'organisation.                                                                                                       |
| organizationCity             | organizationCity            | ❌           | Ville de l'organisation.                                                                                                             |
| organizationDepartmentCode   | organizationDepartmentCode  | ❌           | Code du département de l'organisation.                                                                                               |
| organizationDepartmentName   | organizationDepartmentName  | ❌           | Nom du département de l'organisation.                                                                                                |
| organizationStatusJuridique  | organizationStatusJuridique | ❌           | Statut juridique de l'organisation.                                                                                                  |
| organizationBeneficiaries\[] | organizationBeneficiaries   | ❌           | Bénéficiaires de l'organisation.                                                                                                     |
| organizationActions\[]       | organizationActions         | ❌           | Principales actions menées par l'organisation.                                                                                       |
| organizationReseaux\[]       | organizationReseaux         | ❌           | Réseau de l'organisation. Ce champ sert à renseigner les organisations ayant des antennes locales et dépendant d'un réseau national. |


# Dépreciée - Liste des champs à inclure dans le flux XML

## Champs principaux

| Nom du champs    | Type     | Description                                                                   |
| ---------------- | -------- | ----------------------------------------------------------------------------- |
| `clientId`       | `String` | Identifiant de la mission. <mark style="color:red;">**Requis**</mark>         |
| `title`          | `String` | Titre de votre mission. <mark style="color:red;">**Requis**</mark>            |
| `applicationUrl` | `String` | Lien de candidature de la mission. <mark style="color:red;">**Requis**</mark> |
| `postedAt`       | `Date`   | Date à laquelle la mission a été postée. Défaut `now()`                       |
| `startAt`        | `Date`   | Date de début de la mission. Défaut `now()`                                   |
| `endAt`          | `Date`   | Date de fin de la mission                                                     |

## Caractéristiques de la mission

<table><thead><tr><th width="296">Nom du champs</th><th width="119">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>description</code></td><td><code>String</code></td><td>La description de votre mission, peut contenir des balises HTML. <mark style="color:red;"><strong>Requis</strong></mark></td></tr><tr><td><code>domain</code></td><td><code>String</code></td><td><p>Domaine de la mission.</p><p></p><p><strong>1 valeur possible parmi :</strong></p><p><code>"environnement"</code>,</p><p><code>"solidarite-insertion"</code>,</p><p><code>"prevention-protection"</code>,</p><p><code>"sante"</code>,</p><p><code>"culture-loisirs"</code>,</p><p><code>"education"</code>,</p><p><code>"emploi"</code>,</p><p><code>"sport"</code>,</p><p><code>"humanitaire"</code>, </p><p><code>"animaux"</code>,</p><p><code>"vivre-ensemble"</code>,</p><p><code>"memoire-et-citoyennete"</code>,</p><p><code>"benevolat-competences"</code>, ou <code>"autre"</code></p></td></tr><tr><td><code>activity</code></td><td><code>String</code></td><td><p>Activité de la mission.</p><p></p><p><strong>1 valeur possible parmi :</strong><br><code>"accueil-de-public"</code>,<br><code>"aide-psychologique"</code>,<br><code>"activites-manuelles"</code>,<br><code>"alphabetisation"</code>,<br><code>"animation"</code>,<br><code>"Animation, Valorisation"</code>,<br><code>"art"</code>,<br><code>"autre"</code>,<br><code>"bricolage"</code>,<br><code>"collecte"</code>,<br><code>"communication"</code>,<br><code>"comptabilite-finance"</code>,<br><code>"conseil"</code>,<br><code>"distribution"</code>,<br><code>"documentation-traduction"</code>,<br><code>"ecoute-permanence"</code>,</p><p><code>"encadrement-d-equipes"</code> ,</p><p><code>"enseignement-formation"</code>,</p><p><code>"gestion-de-projets"</code>,<br><code>"gestion-recherche-des-partenariats"</code>,<br><code>"informatique"</code>,<br><code>"jardinage"</code>,<br><code>"juridique"</code>,<br><code>"logistique"</code>,<br><code>"lutte-contre-isolement"</code>,<br><code>"Médiation, Information"</code>,<br><code>"mentorat-parrainage"</code>,<br><code>"mission-internationale"</code>,<br><code>"Préservation, Patrimoine"</code>,<br><code>"Prévention, Sensibilisation"</code>,<br><code>"ramassage-dechets"</code>,<br><code>"recrutement"</code>,<br><code>"responsabilites-associatives"</code>,<br><code>"sante-soins"</code>,<br><code>"Secours, Aide"</code>,<br><code>"secourisme"</code>,<br><code>"sensibilisation"</code>,<br><code>"soins-animaux"</code>,<br><code>"Soutien, Accompagnement"</code>,<br><code>"soutien-scolaire"</code>,<br><code>"sport"</code>,<br><code>"taches-administratives"</code>,<br><code>"Transmission, Pédagogie"</code>,<br><code>"visites"</code></p></td></tr><tr><td><code>schedule</code></td><td><code>String</code></td><td>Rythme de la mission.<br><br><strong>Exemple</strong> : "1 demi-journée par semaine"</td></tr><tr><td><code>places</code></td><td><code>Number</code></td><td>Nombre de places disposnibles pour la mission<br>Défaut <code>1</code></td></tr><tr><td><code>remote</code></td><td><code>String</code></td><td><p>Mission disponible en distanciel.</p><p></p><p><strong>Valeurs possibles:</strong></p><p><code>"possible"</code>, <code>"full"</code> ou <code>"no"</code></p></td></tr><tr><td><code>image</code></td><td><code>String</code></td><td>Lien url de l'image de la mission. Si vous n'en fournissez pas, l'API Engagement utilisera l'une des images de sa bibliothèque en fonction du domaine.</td></tr><tr><td><code>audience</code></td><td><code>String[]</code></td><td>Les bénéficiaires de la mission / à qui la mission s'adresse.<br>Exemple 1: <code>"Tous publics"</code><br>Exemple 2: <code>"Jeunes, Adultes"</code></td></tr><tr><td><code>softSkills</code></td><td><code>String[]</code></td><td>Les compétences générales requises pour la mission<br>Exemple : <code>"Écoute active, Communication orale"</code></td></tr><tr><td><code>romeSkills</code></td><td><code>String[]</code></td><td>Codes métiers (référentiel ROME 4.0) </td></tr><tr><td><code>requirements</code></td><td><code>String[]</code></td><td>Pré-requis relatifs à la mission</td></tr><tr><td><code>reducedMobilityAccessible</code></td><td><code>String</code></td><td><p>Mission accessible pour les personnes à mobilité réduite. </p><p></p><p><strong>Valeurs possibles:</strong></p><p><code>"yes"</code> ou <code>"no"</code></p></td></tr><tr><td><code>closeToTransport</code></td><td><code>String</code></td><td><p>Mission proche des transports en commun.</p><p></p><p><strong>Valeurs possibles:</strong></p><p><code>"yes"</code> ou <code>"no"</code></p></td></tr><tr><td><code>openToMinors</code></td><td><code>String</code></td><td><p>Mission ouverte aux mineurs.</p><p> </p><p><strong>Valeurs possibles:</strong></p><p><code>"yes"</code> ou <code>"no"</code></p></td></tr><tr><td><code>tags</code></td><td><code>String[]</code></td><td>Ce champs permet de tagguer vos missions avec un, ou plusieurs mots-clés personnalisés séparés par une virgule, dans l’API.<br><br>Exemple 1: <code>"Ecologie"</code><br>Exemple 2: <code>"Ecologie, Sport, Solidarité"</code></td></tr><tr><td><code>priority</code></td><td><code>String</code></td><td>Priorité de la mission</td></tr><tr><td><code>metadata</code></td><td><code>String</code></td><td>Métadata de la mission</td></tr></tbody></table>

## Champs géographiques de la mission

Il s’agit de l’ensemble des localisations où se déroulent la mission.

Si vos missions se tiennent dans plusieurs lieux alors vous pouvez renseigner ces localisations dans le champs `addresses` qui est un tableau d'objects contenant le détail géographique de chaque mission.

Si vos missions ne se tiennent dans un lieu unique, vous ne renseignez qu'une seule adresse dans le tableau `addresses`.

*Exemple d'une mission avec une adresse unique*

```xml
<addresses>
  <address>
    <street><![CDATA[10 rue de la Paix]]></street>
    <postalCode><![CDATA[75001]]></postalCode>
    <city><![CDATA[Paris]]></city>
    <departmentCode><![CDATA[75]]></departmentCode>
    <departmentName><![CDATA[Paris]]></departmentName>
    <region><![CDATA[Centre-Val de Loire]]></region>
    <country><![CDATA[FR]]></country>
    <location>
      <lat><![CDATA[47.8951]]></lat>
      <lon><![CDATA[1.9108]]></lon>
    </location>
  </address>
</addresses>
```

*Exemple d'une mission avec plusieurs addresses*

```xml
<addresses>
  <address>
    <street><![CDATA[10 rue de la Paix]]></street>
    <postalCode><![CDATA[75001]]></postalCode>
    <city><![CDATA[Paris]]></city>
    <departmentCode><![CDATA[75]]></departmentCode>
    <departmentName><![CDATA[Paris]]></departmentName>
    <region><![CDATA[Centre-Val de Loire]]></region>
    <country><![CDATA[FR]]></country>
    <location>
      <lat><![CDATA[47.8951]]></lat>
      <lon><![CDATA[1.9108]]></lon>
    </location>
  </address>
  
  <address>
    <street><![CDATA[Port de Loire]]></street>
    <postalCode><![CDATA[45110]]></postalCode>
    <city><![CDATA[Châteauneuf-sur-Loire]]></city>
    <departmentCode><![CDATA[45]]></departmentCode>
    <departmentName><![CDATA[Loiret]]></departmentName>
    <region><![CDATA[Île-de-France]]></region>
    <country><![CDATA[FR]]></country>
    <location>
      <lat><![CDATA[48.8698]]></lat>
      <lon><![CDATA[2.3322]]></lon>
    </location>
  </address>
  
  <address>
    <street><![CDATA[20 rue Victor Hugo]]></street>
    <postalCode><![CDATA[59000]]></postalCode>
    <city><![CDATA[Lille]]></city>
    <departmentCode><![CDATA[59]]></departmentCode>
    <departmentName><![CDATA[Nord]]></departmentName>
    <region><![CDATA[Hauts-de-France]]></region>
    <country><![CDATA[FR]]></country>
  </address>
</addresses>
```

| Nom du champ | Type        | Description                                                                                                                                                    |
| ------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `addresses`  | `Address[]` | <p>Tableau des adresses où se déroule la mission. Chaque objet représente une adresse distincte.<br><br><br>Veuillez vous référer au tableau ci-dessous ⬇️</p> |

Une adresse se compose des champs suivants :&#x20;

<table><thead><tr><th width="209">Nom du champ</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>street</code></td><td><code>String</code></td><td>Rue où se déroule la mission.<br><br>Exemple: <code>46 Rue Saint-Antoine</code></td></tr><tr><td><code>postalCode</code></td><td><code>String</code></td><td>Code postal où se déroule la mission<br><br>Exemple: <code>75004</code></td></tr><tr><td><code>city</code></td><td><code>String</code></td><td>Ville où se déroule la mission<br><br>Exemple: <code>Paris</code> </td></tr><tr><td><code>departmentCode</code></td><td><code>String</code></td><td>Numéro de département où se déroule la mission.<br><br>Exemple: <code>75</code></td></tr><tr><td><code>departmentName</code></td><td><code>String</code></td><td>Nom du département où se déroule la mission</td></tr><tr><td><code>region</code></td><td><code>String</code></td><td>Région où se déroule la mission</td></tr><tr><td><code>country</code></td><td><code>String</code></td><td><a href="https://fr.wikipedia.org/wiki/ISO_3166-1">Code ISO 2</a> du pays de la mission<br>Défaut <code>FR</code></td></tr><tr><td><code>location</code></td><td><code>{lat:number;lon:number}</code></td><td>Composé de <code>lat</code> et <code>lon</code> de type <code>Number</code> représentant la latitude et longitude de l'adresse de la mission<br><br>Si la longitude et la latitude ne sont pas fournies ou sont incorrectes, l'API utilise l'<a href="https://adresse.data.gouv.fr/api-doc/adresse">api-adresse</a> pour obtenir ces valeurs. La mission est géolocalisée si au moins l'un des champs suivants est renseigné : <code>adresse</code>, <code>ville</code> ou <code>code postal</code>.</td></tr></tbody></table>

## Champs de l'organisation ou de la structure d'accueil

<table><thead><tr><th width="291">Nom du champ</th><th width="156">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>organizationName</code></td><td><code>String</code></td><td>Nom de l'organisation de la mission</td></tr><tr><td><code>organizationRNA</code></td><td><code>String</code></td><td>RNA de l'organisation de la mission <mark style="color:red;"><strong>Requis (ou organizationSiren)</strong></mark></td></tr><tr><td><code>organizationSiren</code></td><td><code>String</code></td><td>Siren de l'organisation de la mission <mark style="color:red;"><strong>Requis (ou organizationRNA)</strong></mark></td></tr><tr><td><code>organizationUrl</code></td><td><code>String</code></td><td><p>Lien de l'organisation de la mission. </p><p>Il peut s'agir de la page de présentation de l'organisation sur votre site par exemple.</p></td></tr><tr><td><code>organizationLogo</code></td><td><code>String</code></td><td>Lien de l'image de l'organisation de la mission</td></tr><tr><td><code>organizationDescription</code></td><td><code>String</code></td><td>Description de l'organisation de la mission</td></tr><tr><td><code>organizationClientId</code></td><td><code>String</code></td><td>Identifiant de l'organisation de la mission</td></tr><tr><td><code>organizationStatusJuridique</code></td><td><code>String</code></td><td>Statut juridique de l'organisation de la mission</td></tr><tr><td><code>organizationType</code></td><td><code>String</code></td><td>Type de l'organisation de la mission<br>Exemple 1: <code>"Association déclarée"</code><br>Exemple 2: <code>"Association internationale"</code></td></tr><tr><td><code>organizationActions</code></td><td><code>String[]</code></td><td>Actions de l'organisation de la mission<br>Exemple : <code>"Animation, Valorisation, Préservation"</code></td></tr><tr><td><code>organizationFullAddress</code></td><td><code>String</code></td><td>Adresse de l'organisation de la mission</td></tr><tr><td><code>organizationPostCode</code></td><td><code>String</code></td><td>Code postal de l'organisation de la mission</td></tr><tr><td><code>organizationCity</code></td><td><code>String</code></td><td>Ville de l'organisation de la mission</td></tr><tr><td><code>organizationBeneficiaries</code></td><td><code>String[]</code></td><td>Bénéficiaires de l'organisation de la mission</td></tr><tr><td><code>organizationReseaux</code></td><td><code>String[]</code></td><td>Réseau de l'organisation de la mission</td></tr></tbody></table>

## Champs d'indemnisation

<table><thead><tr><th width="291">Nom du champ</th><th width="156">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>compensationAmount</code></td><td><code>Number</code></td><td>Montant de l'indemnisation</td></tr><tr><td><code>compensationUnit</code></td><td><code>String</code></td><td><p>Période de l'indemnisation pour le montant fourni<br><br><strong>Valeurs possibles:</strong></p><p><code>"hour"</code>, <code>"day"</code>, <code>"month"</code>, <code>"year"</code></p></td></tr><tr><td><code>compensationType</code></td><td><code>String</code></td><td><p>Type d'indemnisation (brute ou nette). <br><br><strong>Valeurs possibles:</strong></p><p><code>"gross"</code>, <code>"net"</code></p></td></tr></tbody></table>

**Exemple :**&#x20;

Pour une indemnisation de 10 € brut de l'heure, renseignez :&#x20;

* `compensationAmount`: `10`
* `compensationUnit`: `"hour"`
* `compensationType`: `"gross"`


# Conditions d'utilisation du flux XML

{% hint style="danger" %}
Votre flux sera désactivé et vos offres de missions seront supprimées de nos résultats de recherche sans préavis si vous ne respectez pas les conditions suivantes:
{% endhint %}

* L'URL que vous fournissez doit être un **lien ouvert au public de manière permanente**
* **Vous ne devez pas exiger** de l'utilisateur qu'il se connecte pour afficher la description des missions
* Toutes les missions fournies dans votre flux XML doivent **être uniques** à votre site web
* Vous ne devez pas inclure les emplois d'autres plateformes dans votre flux XML
* Vous ne devez pas inclure des missions expirées ou fermées dans votre flux XML


# Méthode 2 : création de missions par API

Cette partie de la documentation est à destination de votre responsable informatique : elle redirige vers la documentation technique de l'API permettant de créer, modifier et supprimer des missions.

## Introduction

Pour importer vos missions, vous pouvez utiliser l’API Engagement afin de **créer, modifier et supprimer des missions d’engagement** de manière automatisée.

La documentation technique destinée aux développeurs est accessible dans la section **API Référence** :

* [Créer / modifier une mission](/api-reference/mission-mission/creer-mettre-a-jour)
* [Supprimer une mission](/api-reference/mission-mission/supprimer)

⚠️ **Attention** :\
Cette méthode d’intégration offre un haut niveau de contrôle et de sécurité, mais elle nécessite :

* une **maintenance régulière**,
* une **rigueur technique importante** de la part de l’intégrateur.


# Étape 2 : Mettre en place le suivi des candidatures

Si vous recevez du trafic de l'API Engagement, vous devez nous **transmettre les informations** des candidatures générées et des comptes créés (inscriptions). Deux cas de figure selon votre dispositif :

## [Cas n°1](/annoncer-des-missions/tracking-des-candidatures/cas-n-1-votre-site-internet-recueille-lui-meme-les-candidatures) : Votre site internet recueille lui-même les candidatures **(**&#x66;ormulaire ou parcours utilisateur avec création de compte)

Ajoutez le script de suivi des candidatures sur votre site. Vous avez **deux options** pour le faire :

* 1\. [En utilisant une balise sur votre site en en déclenchant des commandes](/annoncer-des-missions/tracking-des-candidatures/cas-n-1-votre-site-internet-recueille-lui-meme-les-candidatures/rajout-de-la-balise-et-des-commandes-de-tracking-par-le-tag-implementation-simple-et-conseillee) *- Implémentation simple et conseillée*
* 2\. [En effectuant un appel à l'API ](/annoncer-des-missions/tracking-des-candidatures/cas-n-1-votre-site-internet-recueille-lui-meme-les-candidatures/tracking-de-lactivite-par-api-implementation-manuelle)- *Implémentation manuelle*

## [Cas n°2](/annoncer-des-missions/tracking-des-candidatures/cas-n-2-votre-site-internet-ne-permet-pas-de-recueillir-les-candidatures) : Votre site internet ne permet pas de recueillir les candidatures (pas de formulaire ni de parcours d'inscription)

Utilisez la connexion avec Démarches Numériques pour créer un formulaire d'inscription ; les candidatures seront trackées via cette connexion.


# Quelles sont les étapes du parcours de l'engagement que l'API Engagement traque ?

Sur la partie droite, dans le cadre vert (Site Annonceur A), l'API traque plusieurs étapes du parcours de l'engagement grâce à l'exécution de commandes sur le site de l'annonceur (vous). L'API peut ainsi donner des statistiques consolidées à ses partenaires :

* **sur le nombre de candidatures pour une mission donnée**. Cette candidature peut soit venir (1) d'une diffusion "directe" de la mission sur un site diffuseur ou (2) d'une diffusion "indirecte" via une campagne (ou lien tracké) suite à une campagne email
* **sur le nombre d'inscriptions (ou de création de comptes) sur le site annonceur** (en précisant de quelle mission provient cette inscription)

<figure><img src="https://2489729786-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG18aCd8mNuBlmkXXgR3Q%2Fuploads%2FseVN2nqjl5ELtPAD60hn%2FTracking%20API%20Engagement%20-%20Frame%202%20(4).jpg?alt=media&amp;token=0bb144e6-420b-4a59-8d7a-0b353e0ec3f0" alt=""><figcaption></figcaption></figure>


# Cas n°1 :  Votre site internet recueille lui-même les candidatures

## Les étapes à suivre

1. Ajoutez le script de suivi des candidatures sur votre site. Vous avez **deux options** pour le faire :
   1. [En utilisant une balise sur votre site en en déclenchant des commandes](/annoncer-des-missions/tracking-des-candidatures/cas-n-1-votre-site-internet-recueille-lui-meme-les-candidatures/rajout-de-la-balise-et-des-commandes-de-tracking-par-le-tag-implementation-simple-et-conseillee) *- Implémentation simple et conseillée*
   2. [En effectuant un appel à l'API ](/annoncer-des-missions/tracking-des-candidatures/cas-n-1-votre-site-internet-recueille-lui-meme-les-candidatures/tracking-de-lactivite-par-api-implementation-manuelle)- *Implémentation manuelle*
2. [Tester votre intégration grâce à l'extension Chrome](/annoncer-des-missions/tracking-des-candidatures/cas-n-1-votre-site-internet-recueille-lui-meme-les-candidatures/tester-votre-integration-grace-a-lextension-chrome)


# Introduction : comment fonctionne le tracking de l'API Engagement ?

Le tracking repose sur une chaîne en trois étapes :

1. **URL trackée** : l'utilisateur arrive sur votre site via un lien fourni par l’API Engagement au site diffuseur, qui contient un paramètre `?apiengagement_id=…`.
2. **Cookie déposé** : le JSTag lit ce paramètre et dépose un cookie `apiengagement` (valable 30 jours).
3. **Événement déclenché** : quand votre code appelle `trackApplication` / `trackAccount`, l'appel vers API Engagement ne part **que si le cookie est présent**.

Sans cookie, `trackApplication()` et `trackAccount()` ne font rien : aucune erreur, aucune requête réseau. C'est le problème le plus courant lors des tests de l'intégration ; Si vous ouvrez directement votre page sans passer par une URL trackée, aucun cookie n'est posé, donc rien n'est envoyé. Cela ne signifie pas que votre code est incorrect.

### Le cookie `apiengagement`

| Attribut        | Valeur                                                             |
| --------------- | ------------------------------------------------------------------ |
| Nom             | `apiengagement`                                                    |
| Valeur          | l'identifiant de clic (`apiengagement_id`) reçu dans l'URL trackée |
| Durée de vie    | 30 jours                                                           |
| Domaine         | votre domaine (`www.exemple.fr` → `.exemple.fr`)                   |
| Path / SameSite | `/` · `Lax` · `Secure`                                             |
| Posé par        | le JSTag, dès qu'il détecte `?apiengagement_id=…` dans l'URL       |

Le cookie fait le lien entre le clic d'origine et la candidature. Tant qu'il est présent (jusqu'à 30 jours après le clic), `trackApplication` / `trackAccount` enverront l'événement.


# Rajout de la balise et des commandes de tracking par le tag (Implémentation simple et conseillée)

Le tag est un moyen simple de suivre les activités de votre implémentation. Le tag de l'API Engagement" est un script JavaScript permettant de mesurer l'impact des redirections de l'API Engagement.

## 1. Rajouter la balise "API Engagement" sur votre site&#x20;

La Balise API Engagement, doit être ajoutée en haut de la balise `<head>` et avant tout autre script ou balise CSS.&#x20;

```html
<script>
(function (i, s, o, g, r, a, m) {
i["ApiEngagementObject"] = r; (i[r] = i[r] || function () { (i[r].q = i[r].q || []).push(arguments); }), (i[r].l = 1 * new Date()); (a = s.createElement(o)), (m = s.getElementsByTagName(o)[0]); a.async = 1; a.src = g; m.parentNode.insertBefore(a, m);
})(window, document, "script", "https://app.api-engagement.beta.gouv.fr/jstag.js", "apieng");
apieng("config", "votre-id-de-partenaire");
</script>
```

Ce script effectue **trois actions** principales :&#x20;

1. **Crée un élément** `<script>` pour démarrer le téléchargement asynchrone de la bibliothèque JavaScript jstag.js depuis <https://app.api-engagement.beta.gouv.fr/jstag.js>
2. **Initialise une fonction** globale apieng (appelée "file d'attente de commandes apieng()") permettant de planifier l'exécution des commandes une fois la bibliothèque jstag.js chargée et prête à être utilisée
3. **Ajoute la commande `apieng()`** à la variable `window` qui permet d'accéder à toutes les fonctionnalités de tracking de l'API Engagement.

## 2. Comment mesurer une candidature ?

Lorsqu'une candidature est validée sur votre site dans le cadre d'une redirection, il faut exécuter la commande suivante :&#x20;

```html
window.apieng && window.apieng("trackApplication", clientId)
```

⚠️ Par défaut, il est fortement conseillé d'ajouter, si connu, l'**identifiant** **de la mission pour laquelle cette candidature est associée** (`clientId` = votre identifiant de mission utilisé dans le flux XML)**.** Informer le clientId pour laquelle il y a eu une candidature permet à l’API de fournir des statistiques poussées.

NB : Si vous ne l'avez pas, ne l’indiquez pas dans la commande. La commande de **comptage d'une candidature** sera la suivante :&#x20;

```html
window.apieng && window.apieng("trackApplication")
```

#### Paramètres additionnels

**Identifiant client**

Vous pouvez ajouter un identifiant client permettant de modifier le statut de la candidature a posteriori (voir [documentation API](/api-reference/tracking-activity/qualifier) `/v2/activity`).

```
window.apieng && window.apieng("trackApplication", clientId, {
  clientEventId: "evt_12345",
})
```

**Custom attributes**

Vous pouvez également ajouter des paramètres supplémentaires, au format JSON, qui vous permettraient de qualifier la candidature, de façon suivante :&#x20;

```
window.apieng && window.apieng("trackApplication", clientId, { 
    customAttributes: {candidateAge: 22, candidatePostalCode: "89140"}
})
```

Ces paramètres sont bien sûr cumulables :&#x20;

```
window.apieng && window.apieng("trackApplication", undefined, {
  clientEventId: "evt_12345",
  customAttributes: { candidateAge: 22 }
})
```

## 3. Comment mesurer une création de compte ?

Lorsqu'un compte utilisateur est créé sur votre site suite à une redirection, il faut exécuter la commande suivante :&#x20;

```html
window.apieng && window.apieng("trackAccount", clientId)
```

⚠️ Par défaut, il est fortement conseillé d'ajouter, si connu, **l'identifiant**  **de la mission pour laquelle cette création de compte est associée** (`clientId` = votre identifiant de mission utilisé dans le flux XML). Informer le clientId pour laquelle il y a eu une création de compte permet à l’API de fournir des statistiques poussées :

NB: Si vous ne l'avez pas, ne l’indiquez pas dans la commande. La commande de **comptage d'une création de compte** sera la suivante :

```html
window.apieng && window.apieng("trackAccount")
```

## 4. Quand effectuer ces commandes ?

Les commandes de création de compte et de création d'une candidature sont à effectuer lorsque vous êtes sûr que cet évènement est arrivé.&#x20;

Par exemple pour une création de compte avec un fonctionnement front-back, cette commande est à déclencher lorsque le backend a confirmé la création du compte en base.

## 5. Où retrouver ces commandes ?

Vous pouvez trouver cette commande sur votre **espace partenaire** dans la partie [**Paramètres &#x20;*****>  Tracking des événements***](https://app.api-engagement.beta.gouv.fr/settings/tracking)

<figure><img src="https://2489729786-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG18aCd8mNuBlmkXXgR3Q%2Fuploads%2FAjEHnsdDggyyl7S3gB17%2Fimage.png?alt=media&amp;token=e31d1172-0647-40ef-9425-4dbd43188d82" alt=""><figcaption></figcaption></figure>


# Tracking de l'activité par API (Implémentation manuelle)

Vous pouvez également envoyer les informations de candidatures ou de création de compte manuellement, en suivant le ce guide :&#x20;

## Redirection

Les redirections provenant de l'API contiennent **un attribut unique dans les paramètres de requête**, `apiengagement_id`. Cet attribut correspond à **l'identifiant de la redirection** qui a amené l'utilisateur sur votre site. Exemple de lien suite à une redirection:

```html
https://www.jeveuxaider.gouv.fr/?apiengagement_id=60a8e60ef959740741fa6616
```

Le tag de l'API Engagement **permet de récupérer cette valeur** et de la stocker dans les cookies sous le nom `apiengagement`. Cependant, si vous n'intégrez pas le script, il est important de **récupérer cette valeur et de l'utiliser pour suivre** une candidature ou une création de compte. Cela peut se faire en utilisant le `localStorage`, par exemple.

## 1. Créer une candidature ou une création de compte

<mark style="color:green;">`POST`</mark> `https://api.api-engagement.beta.gouv.fr/v2/activity`

Lorsqu'une candidature ou une création de compte est détectée chez vous, cette route permet de créer une entrée de statEvent (candidature, création de compte) sans passer par notre SDK en front, mais directement en API

#### Headers

<table><thead><tr><th width="182">Name</th><th width="126">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>x-api-key</code> <mark style="color:red;">Requis</mark></td><td><code>string</code></td><td>La clé API <strong>nécessaire à l’authentification</strong>. Les données disponibles sont définies en fonction de votre clé API.</td></tr></tbody></table>

#### Body

| Name              | Type                                                         | Description                                                                                                                                                                                                                                               |
| ----------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clickId`         | string - <mark style="background-color:red;">Required</mark> | Id de la redirection associée à la création de compte correspondant à la valeur comprise dans `apiengagement_id`                                                                                                                                          |
| `type`            | `apply` ou `account`                                         | Type de l'activité à enregistrer: `apply` pour une candidature, `account` pour une création de compte. Par défaut : <mark style="color:blue;">`apply`</mark>                                                                                              |
| `missionClientId` | string                                                       | Id de la mission pour laquelle une création de compte est identifié (correspondant aux `clientId` dans le [flux XML](/annoncer-des-missions/creation-dun-flux-xml/methode-1-creation-dun-flux-xml/depreciee-liste-des-champs-a-inclure-dans-le-flux-xml)) |
| `tag`             | string                                                       | Tag de la création de compte                                                                                                                                                                                                                              |

#### **Response**

{% tabs %}
{% tab title="200" %}

```json
/** Call with the body set to
* missionClientId = "4321"
* clickId = "click_id"
* tag = "les-meilleurs-missions"
* type = "account"
*/
{
    "ok": true,
    "data": {
        "_id": "activity_id",
        "clikcId": "click_id",
        "missionId": "87654321-431-4321-210987654321",
        "missionClientId": "4321",
        "missionDomain": "education",
        "missionTitle": "Le titre de ma mission",
        "missionPostalCode": "33440",
        "missionDepartmentName": "Gironde",
        "missionOrganizationName": "Mon asso preferee",
        "missionOrganizationId": "xxxx",
        "toPublisherId": "mon_identifiant",
        "fromPublisherId": "identifiant_partenaire",
        "tag": "les-meilleurs-missions",
        "host": "https://xxx.yyy.fr",
        "created_at": "2024-03-13T13:00:00.000Z",
        "source": "publisher",
        "type": "account",
        "status" : "PENDING",
    }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "ok": false,
    "code": "INVALID_BODY",
    "error": [
        {
            "expected": "string",
            "code": "invalid_type",
            "path": [
                "clickId"
            ],
            "message": "Invalid input: expected string, received undefined"
        }
    ]
}
```

{% endtab %}

{% tab title="404" %}

```json
{
    "ok": false,
    "code": "NOT_FOUND",
    "message": "Mission not found"
}
// Ou
{
    "ok": false,
    "code": "NOT_FOUND",
    "message": "Mission not found"
}
```

{% endtab %}
{% endtabs %}

## 2. Mettre à jour le statut de la candidature

<mark style="color:blue;">`PUT`</mark> `https://api.api-engagement.beta.gouv.fr/v2/activity/:id`

Il est possible de mettre à jour le statut d'une candidature ou d'une création de compte afin de suivre l'avancement du candidat

#### Headers

<table><thead><tr><th width="182">Name</th><th width="126">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>x-api-key</code> <mark style="color:red;">Requis</mark></td><td><code>string</code></td><td>La clé API <strong>nécessaire à l’authentification</strong>. Les données disponibles sont définies en fonction de votre clé API.</td></tr></tbody></table>

#### **Params**

| Name  | Value                                                  |
| ----- | ------------------------------------------------------ |
| `:id` | Identifiant de la candidature ou de création de compte |

#### **Body**

| Name     | Type                                                           | Description                                                                                                                                                           |
| -------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status` | `PENDING`, `VALIDATED`, `CANCELED`, `REFUSED` ou `CARRIED_OUT` | Statut de la candidature ou création du compte. <mark style="color:blue;">Défaut à</mark> <mark style="color:blue;"></mark><mark style="color:blue;">`PENDING`</mark> |

#### **Response**

{% tabs %}
{% tab title="200" %}

```json
/** Call with the body set to
* status = "VALIDATED"
*/
{
    "ok": true,
    "data": {
        "_id": "activity_id",
        "clickId": "click_id",
        "missionId": "87654321-431-4321-210987654321",
        "missionClientId": "4321",
        "missionDomain": "education",
        "missionTitle": "Le titre de ma mission",
        "missionPostalCode": "33440",
        "missionDepartmentName": "Gironde",
        "missionOrganizationName": "Mon asso preferee",
        "missionOrganizationId": "xxxx",
        "toPublisherId": "mon_identifiant",
        "fromPublisherId": "identifiant_parteanire",
        "tag": "les-meilleurs-missions",
        "host": "https://xxx.yyy.fr",
        "created_at": "2024-03-13T13:00:00.000Z",
        "source": "publisher",
        "type": "account",
        "status" : "VALIDATED",
    }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "ok": false,
    "code": "INVALID_BODY",
    "error": [
        {
            "code": "invalid_value",
            "values": [
                "PENDING",
                "VALIDATED",
                "CANCELED",
                "REFUSED",
                "CARRIED_OUT"
            ],
            "path": [
                "status"
            ],
            "message": "Invalid option: expected one of \"PENDING\"|\"VALIDATED\"|\"CANCELED\"|\"REFUSED\"|\"CARRIED_OUT\""
        }
    ]
}
```

{% endtab %}

{% tab title="404" %}

```json
{
    "ok": false,
    "code": "NOT_FOUND",
    "message": "Activity not found"
}
```

{% endtab %}
{% endtabs %}


# Tester votre intégration grâce à l'extension Chrome

L'extension Chrome « API Engagement Tag Assistant » rend chaque étape visible (script détecté, cookie posé, événements envoyés).

**Installer l'extension** (elle n'est pas publiée sur le Chrome Web Store) :

1. Télécharger `chrome-extension.zip` mis à disposition par l'équipe de l'API Engagement : <https://app.api-engagement.beta.gouv.fr/chrome-extension.zip>
2. Dézipper l'archive.
3. Ouvrir `chrome://extensions`, activer le **Mode développeur** (en haut à droite).
4. Cliquer **Charger l'extension non empaquetée** et sélectionner le dossier dézippé.

**Recette de test :**

1. Obtenez une **URL trackée** auprès de l'équipe API Engagement (ou utilisez un lien de diffusion existant). Cela peut être fait en demandant directement à votre chargé·e de déploiement avec qui vous êtes en contact, ou directement via l’adresse contact <api-engagement@beta.gouv.fr>. Cette URL doit contenir `?apiengagement_id=…`.
2. Ouvrez votre page via cette URL. Dans l'extension, vérifiez que le JSTag est détecté, que votre ID partenaire est affiché, et que le cookie `apiengagement` est posé.
3. Déclenchez l'événement : un `trackApplication` (`/r/apply`) doit apparaître dans l'extension avec un statut 200 et les paramètres `view`, `mission`, `publisher`.
4. Recoupez avec la page « Événements temps réel » de votre espace partenaire : <https://app.api-engagement.beta.gouv.fr/settings/real-time>

<figure><img src="https://2489729786-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG18aCd8mNuBlmkXXgR3Q%2Fuploads%2F7PmeMlTZnlRX1rIrzLYF%2Fimage.png?alt=media&amp;token=25fbe628-ef5e-410c-b73d-40ef0d4dfc13" alt=""><figcaption></figcaption></figure>


# Dépannage

| Symptôme                                          | Cause probable                                                  | Solution                                                                                  |
| ------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Aucune requête ne part lors de `trackApplication` | Cookie absent : la page n'a pas été ouverte via une URL trackée | Ouvrez la page via une URL trackée (`?apiengagement_id=…`) puis réessayez                 |
| Requête en erreur **400**                         | `publisher` (config) ou `mission` invalide                      | Vérifiez le Publisher ID dans `config` et l'identifiant de mission                        |
| JSTag non détecté par l'extension                 | Script absent, mal placé, ou bloqué                             | Placez le script en tête de `<head>` ; vérifiez l'absence de blocage (CSP, ad-blocker)    |
| Comportement différent du script officiel         | Version auto-hébergée obsolète                                  | Vérifiez la version de votre `jstag.js` auto-hébergé, ou repassez à la version officielle |


# Cas n°2 : Votre site internet ne permet pas de recueillir les candidatures

L’intégration avec Démarches Numériques ne nécessite pas l’installation du JSTag ni l’intervention d’un prestataire web.

Pour les organisations utilisant Démarches Numériques, une seule modification est nécessaire dans chaque formulaire : créer une annotation privée appelée exactement **“Identifiant de la redirection”.**

L’équipe API Engagement se charge ensuite de configurer le suivi et de mettre à jour les liens de destination.

### **Ce que vous devez faire**

Pour chaque formulaire Démarches Numériques utilisé pour recueillir des candidatures :

1. ouvrez la page de configuration du formulaire dans Démarches Numériques ;
2. ajoutez une annotation privée ;
3. nommez-la exactement "Identifiant de la redirection" ;
4. publiez la nouvelle version du formulaire ;
5. transmettez l’URL publique de la démarche à l’équipe API Engagement.

### **Étape 1 : Ajouter l’annotation privée**

Dans la configuration de votre démarche, créez une nouvelle **annotation privée**.

Utilisez exactement le libellé suivant : "Identifiant de la redirection". Le libellé doit être strictement identique. Conservez les espaces et l’orthographe indiqués. Le rapprochement automatique repose sur le nom de ce champ.

L’annotation doit rester privée afin :

* qu’elle ne soit pas visible par la personne candidate ;
* qu’elle ne puisse pas être modifiée ou supprimée pendant le dépôt du dossier par le candidat sur Démarches Numériques ;
* que l’API Engagement puisse y inscrire automatiquement l’identifiant de la redirection.

Vous n’avez aucune valeur à saisir dans cette annotation. Elle sera remplie automatiquement lorsqu’une personne accédera à la démarche depuis une offre diffusée par l’API Engagement.

### **Étape 2 : Transmettre l’URL de la démarche**

Envoyez à la personne chargée de votre déploiement :

* l’URL publique du formulaire Démarches Numériques ;
* la confirmation que l’annotation privée a été créée ;
* la liste des formulaires concernés si vous en utilisez plusieurs.

Ne transmettez pas l’URL de la page d’administration. L’équipe API Engagement a besoin du lien utilisé par les personnes candidates pour accéder à la démarche.

### **Étape 3 : Attendre la confirmation d’activation**

À réception de ces éléments, l’équipe API Engagement :

* associe la démarche à votre compte API Engagement ;
* configure le suivi des dossiers déposés ;
* met à jour les campagnes de diffusion existantes lorsque cela est nécessaire ;
* réalise un test du parcours.

Attendez la confirmation de l’équipe avant de considérer l’intégration comme opérationnelle.

### **Checklist Démarches Numériques**

Votre intervention est terminée lorsque :

* l’annotation privée a été créée ;
* elle porte exactement le nom Identifiant de la redirection ;
* elle est présente dans chaque formulaire Démarches Numériques concerné ;
* l’URL publique de chaque démarche a été transmise ;
* l’équipe API Engagement a confirmé l’activation.


# Modération des missions partagées

Les missions reçues par l'API Engagement sont soumises à une (double) modération :&#x20;

* Une première modération effectuée par l'API Engagement elle-même. [En savoir plus](/annoncer-des-missions/la-moderation-des-missions/moderation-api-engagement).
* Une seconde modération par les partenaires diffuseurs de l'API Engagement (notamment jeveuxaider.gouv.fr). [En savoir plus](/annoncer-des-missions/la-moderation-des-missions/moderation-des-partenaires-diffuseur).


# Modération API Engagement

L'API Engagement applique une modération aux missions afin de garantir **un niveau de qualité** optimal dans le flux proposé à nos partenaires. Toute mission récupérée par l'API se voit attribuer un statut :  `ACCEPTED` si elle répond aux **critères de qualité requis**, et `REFUSED` si elle ne respecte pas ces critères. **En cas de refus** par l'API, la mission en question ne sera pas diffusée auprès de nos partenaires.

Les règles de modération sont fixes et concernent les champs suivants :&#x20;

<table><thead><tr><th width="206">Champs concernés</th><th>Règles</th></tr></thead><tbody><tr><td><code>title</code></td><td>La mission doit avoir un titre, qui ne comporte pas de problème d'encodage (caractère spéciaux) et doit être <strong>composé d'au moins 2 mots</strong></td></tr><tr><td><code>clientId</code></td><td>La mission doit avoir un <code>clientId</code></td></tr><tr><td><code>description</code></td><td>La mission doit avoir une description, qui ne comporte pas de problème d’encodage (caractère spéciaux). Pas de nombre minimum de caractères.</td></tr><tr><td><code>applicationUrl</code></td><td>La mission doit avoir un <strong>lien de candidature</strong></td></tr><tr><td><code>country</code></td><td>La mission doit avoir le code du pays au format <strong>ISO 3166-1 alpha-2</strong></td></tr><tr><td><code>domain</code></td><td>La mission doit avoir un champ "domain" qui correspond à <strong>l'une des valeurs répertoriées</strong> dans la liste de constantes définies pour "domain" (cf. <a href="broken://pages/umUMiPkFufg3XWgEIR56#caracteristiques-de-la-mission">Modèle de données d'une mission</a>)</td></tr><tr><td><code>remote</code></td><td>La mission doit avoir un champ "remote" qui correspond à <strong>l'une des valeurs répertoriées</strong> dans la liste de constantes définies pour "remote" (cf. <a href="broken://pages/umUMiPkFufg3XWgEIR56#caracteristiques-de-la-mission">Modèle de données d'une mission</a>)</td></tr><tr><td><code>places</code></td><td>La mission doit avoir un champ "places" et le nombre de places disponible doit être <strong>d'au moins 1</strong></td></tr></tbody></table>


# Modération des partenaires "diffuseur"

Certains diffuseurs de l'API Engagement pratique une modération supplémentaire pour les missions qu'il récupèrent via l'API avant de les diffuser sur leur plateforme.

Dans ce cas, des champs supplémentaires sont ajoutés aux missions afin de connaître le statut de la modération. Tous ces champs suivent le format `moderation_{identifiant_du_diffuseur}_{champs}` comme suit et sont accessible par API avec la route [Broken mention](broken://pages/-M_jv6oFRGaxS_l56Ogy):&#x20;

<table><thead><tr><th width="297">Nom du champ</th><th width="119">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>moderation_{id}_status</code></td><td><code>String</code></td><td><p>Statut de la modération parmi ces valeurs <span data-gb-custom-inline data-tag="emoji" data-code="1f44d">👍</span></p><ul><li><code>ACCEPTED</code>: mission acceptée</li><li><code>REFUSED</code>: mission refusée</li><li><code>PENDING</code>: mission en attente de modération</li><li><code>ONGOING</code>: mission en cours de modération</li></ul></td></tr><tr><td><code>moderation_{id}_comment</code></td><td><code>String</code></td><td>Motif du refus si la mission est refusée</td></tr><tr><td><code>moderation_{id}_title</code></td><td><code>String</code></td><td>Si le titre est modifié, nouveau titre choisi par le partenaire</td></tr></tbody></table>

Ces informations sont également visibles dans le dashboard "Partager des Missions" > Flux de Mission

<figure><img src="https://2489729786-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG18aCd8mNuBlmkXXgR3Q%2Fuploads%2FAURxWYlhRx8iX1dqd1rl%2Fimage.png?alt=media&amp;token=0f2e6ef9-00f9-4bd9-a9f6-57b3f02543e2" alt=""><figcaption></figcaption></figure>

### Exemple de moderation

```json
// Mission refusée
{
    "title": "La meilleure mission de bénévolat",
    "startAt": "2012-12-21T00:00:00.000Z"
    ...
    "moderation_5f5931496c7ea5xxxxxxxxxx_comment": "La mission est refusée car la date de création est trop ancienne (> 6 mois)",
    "moderation_5f5931496c7ea5xxxxxxxxxx_status": "REFUSED",
    "moderation_5f5931496c7ea5xxxxxxxxxx_title": ""
}
// Mission acceptée
{
        "title": "La meilleure mission de bénévolat",
    ...
    "moderation_5f5931496c7eaxxxxxxxxxxx_comment": "",
    "moderation_5f5931496c7eaxxxxxxxxxxx_status": "ACCEPTED",
    "moderation_5f5931496c7eaxxxxxxxxxxx_title": "L'une des meilleures mission de bénévolat"
}
```


# Diffuser des missions d'engagement sur mon site

Missions d'engagement = Missions de bénévolat et/ou volontariat

## Plusieurs méthodes pour diffuser des missions d'engagement

Il existe trois méthodes pour diffuser plus de 40 000 missions de bénévolat et de volontariat. Cela peut se faire :

* [Par API](/diffuser-des-missions/diffuser-des-missions-dengagement-sur-mon-site/diffuser-des-missions-par-api)
* [Via le widget](/diffuser-des-missions/diffuser-des-missions-dengagement-sur-mon-site/diffuser-des-missions-par-widget)
* [Via des campagnes avec des liens dits "trackés" ](/diffuser-des-missions/diffuser-des-missions-dengagement-sur-mon-site/diffuser-des-missions-par-lien-tracke)

## Quelle méthode d'intégration choisir ?

Les solutions de diffusion ont été développées pour répondre aux besoins de tous, que le diffuseur dispose de compétences techniques avancées ou non, d'un temps limité pour l'intégration ou d'un besoin de personnalisation du parcours utilisateur.

| Type d'intégration recommandée                                                                                                           | Contexte diffuseur                                                                                                                                                              | Compatibilité                       |
| ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| [API](/diffuser-des-missions/diffuser-des-missions-dengagement-sur-mon-site/diffuser-des-missions-par-api)                               | <ul><li>Je dispose de capacité de développement (interne ou externe).</li><li>Besoin du personnalisation du parcours utilisateur et des informations affichées.</li></ul>       | Site / Application mobile           |
| [Widget](/diffuser-des-missions/diffuser-des-missions-dengagement-sur-mon-site/diffuser-des-missions-par-widget)                         | <ul><li>Je dispose de capacité de développement très limité.</li><li>Je souhaite présenter un catalogue de missions sur mon site.</li></ul>                                     | Site / Application mobile (webview) |
| [Campagnes / Liens Trackés](/diffuser-des-missions/diffuser-des-missions-dengagement-sur-mon-site/diffuser-des-missions-par-lien-tracke) | <ul><li>Je dispose de capacité de développement très limité.</li><li>Je souhaite renvoyer mes visiteur vers le site annonceur sans présenter de catalogue de mission.</li></ul> | Site / Application mobile           |


# Diffuser des missions par API

## Étape 1 : créer une clé API dans le tableau de bord

Votre clé API est disponible directement dans votre compte API Engagement : vous la générez vous-même, sans avoir à la demander à quelqu'un ni à la recevoir par e-mail.

**Si vous avez déjà un compte**

1. Connectez-vous au tableau de bord API Engagement.
2. Allez dans **Diffuser des missions > Flux par API**.
3. Cliquez sur **Générer ma clé API** (ou **Régénérer** si vous en aviez déjà une), puis copiez-la.

<figure><img src="https://2489729786-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG18aCd8mNuBlmkXXgR3Q%2Fuploads%2FZqNikSIGgmRMYbibV5h5%2Fimage.png?alt=media&amp;token=b9e6d011-913a-4965-8557-1fee96df8c93" alt=""><figcaption></figcaption></figure>

**Si vous n'avez pas encore de compte**

{% hint style="danger" %}
**Cette étape nécessite l'aide d'un chargé de déploiement** avec qui vous êtes en contact. Cette personne pourra générer cette clé pour vous.
{% endhint %}

Rapprochez-vous de votre chargé de déploiement : il crée votre compte diffuseur, active l'accès API et vous envoie une invitation. Vous recevez alors un e-mail pour définir votre mot de passe, puis vous suivez les 3 étapes ci-dessus.

> **Bon à savoir.** Votre clé donne accès aux données de missions et à vos statistiques de diffusion (clics, candidatures). Elle ne doit jamais circuler par e-mail ou par messagerie, y compris avec l'équipe API Engagement : personne n'a besoin de vous la transmettre, ni de vous la demander. En cas de doute sur sa confidentialité, régénérez-la depuis cette même page, l'ancienne clé est immédiatement désactivée.

## Étape 2 : récupérer les missions

L'**endpoint /mission permet de récupérer les missions** qui vous sont disponibles. [Voir la documentation](/api-reference/mission-mission/recuperer).

## Étape 3 : formater le visuel des missions récupérées via l'API sur votre site

#### Page 1 : Présenter une liste de mission d'engagement sur une page dédiée sur votre site

L'utilisateur accède à la liste des missions **récupérées via l'API Engagement** sur votre plateforme. Exemple d'implémentation

{% hint style="success" %}
*Exemple d'intégration*

* *Cette page propose des filtres  (comme la localisation, la date de début, la durée de la mission, le domaine (le thème), et le type d'engagement (bénévolat ou volontariat)*
* *Cette page propose également la liste des missions que vous diffusez avec les informations clés (titre de la mission, nom de la structure d'accueil, adresse d'exécution de la mission, domaine, type d'engagement). Pour rappel,* [*le modèle de données de missions récupérables est disponible ici*](/diffuser-des-missions/modele-de-donnees-dune-mission-dengagement)*.*
  {% endhint %}

<figure><img src="https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG18aCd8mNuBlmkXXgR3Q%2Fuploads%2FtPt5UamOZ1KQ99sS4YdL%2Fimage.png?alt=media&#x26;token=3c1b5c77-d6dc-4d2d-94cf-684f402ac9bb" alt=""><figcaption><p>Page "liste de missions"</p></figcaption></figure>

**Page 2** : En cliquant sur une carte "mission", l'utilisateur peut alors consulter le détail des missions de bénévolat ou de volontariat avant de cliquer sur le **bouton d'action** que vous aurez ajouté à cette page.

L'utilisateur est alors **redirigé** sur le site de l'annonceur de la mission et peut proposer sa candidature.

<figure><img src="https://2489729786-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG18aCd8mNuBlmkXXgR3Q%2Fuploads%2F8c4VBbb6HboXNlpV1Hk8%2Fimage.png?alt=media&amp;token=cdb9c291-8702-4262-bf48-f0ca5de135f6" alt=""><figcaption><p>Exemple de page de détail de mission</p></figcaption></figure>

NB : Retrouvez plus d'informations sur notre site vitrine 👇🏻

{% embed url="<https://api-engagement.beta.gouv.fr/diffuser-les-missions-de-partenaires/#api>" %}

## Étape 4 : Paramétrer le tracking des diffusions de missions

{% hint style="danger" %}
Cette étape est obligatoire pour pourvoir diffuser les missions de l'API Engagement.

Cet [article](/diffuser-des-missions/tracking-des-candidatures) décrit comment mettre en place le tracking obligatoire des vues que vous générerez sur votre site / application.
{% endhint %}


# Diffuser des missions par widget

Vous pouvez afficher des missions de l'API sur votre site web en quelques heures

## Qu'est-ce que le widget API Engagement ?

Le widget permet d'afficher les missions de l'API sur un site web via un iframe (comme les cartes Google Maps sur les sites).

Vous pouvez choisir entre deux formats de widget pour assurer une intégration optimisée sur votre site web. Votre widget peut prendre la forme d'une **page de résultats de missions** ou se présenter plus discrètement dans un **carrousel de missions.**

### Widget - Page de résultats

<figure><img src="https://2489729786-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG18aCd8mNuBlmkXXgR3Q%2Fuploads%2FSdeUvWm7TS53kqgZJowD%2Fimage.png?alt=media&amp;token=cfb5dc82-b520-400d-825a-3f4ab1d95c21" alt=""><figcaption></figcaption></figure>

### Widget - Carrousel de missions

<figure><img src="https://2489729786-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG18aCd8mNuBlmkXXgR3Q%2Fuploads%2FjPQ5BQh5a69luqms2C3B%2Fimage.png?alt=media&amp;token=801f0f5f-93a0-4b2b-b045-e9f5e47cb966" alt=""><figcaption></figcaption></figure>

## Comment intégrer le widget sur votre site web ?

Pour intégrer le widget, vous devez récupérer le code du widget qui se trouve dans le tableau de bord API [Diffuser des missions > Widgets de missions](https://app.api-engagement.beta.gouv.fr/broadcast/widgets).

<figure><img src="https://2489729786-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG18aCd8mNuBlmkXXgR3Q%2Fuploads%2FFWqe3cD6dS1NFohX66VE%2Fimage.png?alt=media&amp;token=ddfc11ae-4342-41e5-a11d-46e252fb1e59" alt=""><figcaption></figcaption></figure>

**Vous trouverez le lien du widget à intégrer en bas de page**

<figure><img src="https://2489729786-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG18aCd8mNuBlmkXXgR3Q%2Fuploads%2FhBTw5QfYIpJOkpQ8xApX%2Fimage.png?alt=media&amp;token=091518dd-769b-4cf1-a5c3-898394aabe4e" alt=""><figcaption></figcaption></figure>

***Important** : ce script est conçu pour garantir une intégration optimisée sur votre site web. Le code est de la forme suivant&#x65;**.***

```html
<iframe border="0" frameborder="0" style="display:block; width:100%;" loading="lazy" allowfullscreen allow="geolocation" src="https://xxx.api-engagement.beta.gouv.fr?widget=xxxxxxxxx"></iframe>

```

Après avoir intégré le widget sur votre site, l'utilisateur voit l'ensemble des missions disponibles. Il pourra alors **cliquer sur une mission** présente dans le widget et sera renvoyé vers le site de l'Annonceur où il pourra candidater.

## Pour une intégration réussie

Vous pouvez trouver toutes les bonnes pratiques pour maximiser l'engagement autour de votre widget API Engagement ici :&#x20;

{% embed url="<https://api-engagement.beta.gouv.fr/integration-des-widgets/>" %}

## Pour aller plus loin

Vous pouvez retrouver toutes les **informations** concernant les **moyens de diffusion** ici :&#x20;

{% embed url="<https://api-engagement.beta.gouv.fr/diffuser-les-missions-de-partenaires/#widget>" %}


# Diffuser des missions par lien tracké

La diffusion des missions de l'API Engagement par ou lien tracké (ou campagne), est la manière la plus simple et rapide d'intégrer l'API Engagement à votre site web.

## Étape 1 : intégrer un lien tracké

* Il suffit simplement d'intégrer le lien tracké généré par les équipes de l'API Engagement **sur votre support (site web, newsletter, QR code, etc).**
* Le lien prend la forme suivante :&#x20;

```
https://api.api-engagement.beta.gouv.fr/r/campaign/65f86ba2073727e7638dd9d8
```

{% hint style="success" %}
*Exemple d'intégration : sur messervicesetudiants, l'utilisateur voit l'image ou le bouton sur votre site.*
{% endhint %}

<figure><img src="https://2489729786-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG18aCd8mNuBlmkXXgR3Q%2Fuploads%2FK5Rx3iXrjJfp7csRpSnc%2Fimage.png?alt=media&amp;token=a746cacd-6244-4366-8ede-70d76d6cd739" alt=""><figcaption></figcaption></figure>

## Étape 2 : Paramétrer le tracking des liens de campagnes

{% hint style="danger" %}
Cette étape est obligatoire pour pourvoir diffuser les missions de l'API Engagement

Cet [article](/diffuser-des-missions/tracking-des-candidatures) décrit comment mettre en place le tracking obligatoire des vues que vous générerez sur votre site / application.
{% endhint %}

## Pour aller plus loin

Vous pouvez retrouver toutes les **informations** concernant les **moyens de diffusion** ici :&#x20;

{% embed url="<https://api-engagement.beta.gouv.fr/diffuser-les-missions-de-partenaires/#campagne>" %}


# Modèle de données d'une mission d'engagement

Cette page décrit le modèle de données d'une mission récupérée via l'API Engagement

## Introduction

Les missions retournées par l’API respectent le **modèle de données standard de l’API Engagement**, identique à celui utilisé pour la création et la mise à jour des missions.

👉 La définition complète des champs (types, contraintes, valeurs possibles) est disponible dans la documentation de référence :\
→ API Référence – [Créer / Mettre à jour une mission](/api-reference/mission-mission/creer-mettre-a-jour)

\
👉 Pour les modalités de récupération des missions (filtres, pagination, requêtes), consultez :\
→ API Référence – [Récupérer des missions](/api-reference/mission-mission/recuperer)

## Structure des missions retournées

### 1. Informations principales de la mission

| Champ XML      | Champ API      | Obligatoire | Description                                                                                                      |
| -------------- | -------------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
| clientId       | clientId       | ✅           | Identifiant unique de la mission dans votre système d'information (immuable)                                     |
| title          | title          | ✅           | Titre de la mission                                                                                              |
| description    | description    | ✅           | Description complète de la mission. Texte brut ou HTML acceptés, stockés tels quels.                             |
| applicationUrl | applicationUrl | ✅           | URL de la page où l'utilisateur sera redirigé pour candidater (URL de la page présentant la mission)             |
| image          | image          | ❌           | URL de l'image de la mission. Si absent, l'API Engagement utilise une image de sa bibliothèque selon le domaine. |
| metadata       | metadata       | ❌           | Métadonnées libres associées à la mission.                                                                       |

### 2. Classification de la mission

| Champ XML     | Champ API  | Obligatoire | Description                                                                                    |
| ------------- | ---------- | ----------- | ---------------------------------------------------------------------------------------------- |
| domain        | domain     | ✅           | Domaine d'action de la mission.                                                                |
| activities\[] | activities | ❌           | Activité(s) principale(s) de la mission.                                                       |
| tags\[]       | tags       | ❌           | Mots-clés personnalisés pour taguer la mission. Chaque élément du tableau est un tag distinct. |

### 3. Public & compétences

| Champ XML       | Champ API    | Obligatoire | Description                                                                                                                                |
| --------------- | ------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| audience\[]     | audience     | ❌           | Les bénéficiaires de la mission — à qui la mission s'adresse, le public auquel sera confronté la personne qui s'engage.                    |
| requirements\[] | requirements | ❌           | Pré-requis relatifs à la mission.                                                                                                          |
| softSkills\[]   | softSkills   | ❌           | Les compétences générales requises pour la mission. Ce champ ne repose pas sur un référentiel de compétence structuré.                     |
| romeSkills\[]   | romeSkills   | ❌           | Code OGR Macro du ROME 4.0. Ce champ repose sur le référentiel "Arborescence simplifiée des compétences" (section "Arborescence du ROME"). |

### 4. Modalités de la mission

| Champ XML | Champ API | Obligatoire | Description                                                                                                                                                                               |
| --------- | --------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| remote    | remote    | ❌           | Disponibilité en distanciel.                                                                                                                                                              |
| schedule  | schedule  | ❌           | Rythme de la mission (texte libre)                                                                                                                                                        |
| startAt   | startAt   | ❌           | Date de début de la mission souhaitée. Format ISO 8601.                                                                                                                                   |
| endAt     | endAt     | ❌           | Date de fin de la mission souhaitée. Format ISO 8601.                                                                                                                                     |
| postedAt  | postedAt  | ❌           | Date de première publication de la mission. Format ISO 8601.                                                                                                                              |
| places    | places    | ❌           | Nombre de places disponibles pour la mission. Ce nombre doit être mis à jour dès qu'il évolue dans votre système afin que l'API Engagement dispose toujours de la donnée la plus récente. |

### 5. Indemnisation

| Champ XML          | Champ API          | Obligatoire | Description                                                         |
| ------------------ | ------------------ | ----------- | ------------------------------------------------------------------- |
| compensationAmount | compensationAmount | ❌           | Montant de l'indemnisation perçue par le bénévole ou le volontaire. |
| compensationUnit   | compensationUnit   | ❌           | Période de l'indemnisation pour le montant fourni.                  |
| compensationType   | compensationType   | ❌           | Type d'indemnisation.                                               |

### 6. Accessibilité & conditions

| Champ XML                 | Champ API                 | Obligatoire | Description                                          |
| ------------------------- | ------------------------- | ----------- | ---------------------------------------------------- |
| openToMinors              | openToMinors              | ❌           | Mission ouverte aux mineurs.                         |
| reducedMobilityAccessible | reducedMobilityAccessible | ❌           | Mission accessible aux personnes à mobilité réduite. |
| closeToTransport          | closeToTransport          | ❌           | Mission proche des transports en commun.             |

### 7. Localisation de la mission

| Champ XML    | Champ API | Obligatoire | Description                                                                                                                                                                                                                  |
| ------------ | --------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| addresses\[] | addresses | ✅           | Ensemble des localisations où se déroule la mission. Si la mission se tient dans plusieurs lieux, renseignez autant d'objets que de localisations. Pour une mission en lieu unique, le tableau ne contient qu'un seul objet. |

#### Détail d’un objet `address`

| Champ XML      | Champ API                | Description                                  |
| -------------- | ------------------------ | -------------------------------------------- |
| street         | addresses.street         | Rue où la mission se déroule                 |
| postalCode     | addresses.postalCode     | Code postal du lieu où la mission se déroule |
| city           | addresses.city           | Ville où la mission se déroule               |
| departmentCode | addresses.departmentCode | Ville où la mission se déroule               |
| departmentName | addresses.departmentName | Nom du département où la mission se déroule  |
| region         | addresses.region         | Nom de la région où la mission se déroule    |
| country        | addresses.country        | Nom du pays où la mission se déroule         |

### 8. Typologie de mission

| Champ XML | Champ API | Obligatoire | Description                  |
| --------- | --------- | ----------- | ---------------------------- |
| type      | type      | ✅           | Type de mission d'engagement |

### 9. Organisation

| Champ XML                    | Champ API                   | Obligatoire | Description                                                                                                                          |
| ---------------------------- | --------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| organizationClientId         | organizationClientId        | ❌           | Identifiant de l'organisation dans votre système. L'organisation désigne l'entité qui accueille le bénévole ou le volontaire.        |
| organizationName             | organizationName            | ⚠️          | Nom de l'organisation. Requis si un autre champ organization\* est renseigné.                                                        |
| organizationDescription      | organizationDescription     | ❌           | Description de l'organisation.                                                                                                       |
| organizationUrl              | organizationUrl             | ❌           | Lien de l'organisation (ex. page de présentation sur votre site).                                                                    |
| organizationType             | organizationType            | ❌           | Type de l'organisation.                                                                                                              |
| organizationLogo             | organizationLogo            | ❌           | URL de l'image de l'organisation.                                                                                                    |
| organizationRNA              | organizationRNA             | ❌           | Numéro RNA de l'organisation. Uniquement valable pour les organisations de type association.                                         |
| organizationSiren            | organizationSiren           | ❌           | SIREN de l'organisation.                                                                                                             |
| organizationSiret            | organizationSiret           | ❌           | SIRET de l'organisation.                                                                                                             |
| organizationFullAddress      | organizationFullAddress     | ❌           | Adresse de l'organisation. Pas de format strict attendu (contrairement à l'adresse de la mission).                                   |
| organizationPostCode         | organizationPostCode        | ❌           | Code postal de l'organisation.                                                                                                       |
| organizationCity             | organizationCity            | ❌           | Ville de l'organisation.                                                                                                             |
| organizationDepartmentCode   | organizationDepartmentCode  | ❌           | Code du département de l'organisation.                                                                                               |
| organizationDepartmentName   | organizationDepartmentName  | ❌           | Nom du département de l'organisation.                                                                                                |
| organizationStatusJuridique  | organizationStatusJuridique | ❌           | Statut juridique de l'organisation.                                                                                                  |
| organizationBeneficiaries\[] | organizationBeneficiaries   | ❌           | Bénéficiaires de l'organisation.                                                                                                     |
| organizationActions\[]       | organizationActions         | ❌           | Principales actions menées par l'organisation.                                                                                       |
| organizationReseaux\[]       | organizationReseaux         | ❌           | Réseau de l'organisation. Ce champ sert à renseigner les organisations ayant des antennes locales et dépendant d'un réseau national. |


# Déprécié -  Modèle de données d'une mission d'engagement

Cette page décrit le modèle de données d'une mission récupérée via l'API Engagement

## Structure des missions retournées

Les missions retournées respectent le **modèle de données standard de l’API Engagement**.

👉 [Voir : documentation "Récupérer des missions"](/api-reference/mission-mission/recuperer)

## Champs principaux

| Nom du champs    | Type     | Description                                                                   |
| ---------------- | -------- | ----------------------------------------------------------------------------- |
| `title`          | `String` | Titre de votre mission. <mark style="color:red;">**Requis**</mark>            |
| `clientId`       | `String` | Identifiant de la mission. <mark style="color:red;">**Requis**</mark>         |
| `applicationUrl` | `String` | Lien de candidature de la mission. <mark style="color:red;">**Requis**</mark> |
| `postedAt`       | `Date`   | Date à laquelle la mission a été postée. Défaut `now()`                       |
| `startAt`        | `Date`   | Date de début de la mission. Défaut `now()`                                   |
| `endAt`          | `Date`   | Date de fin de la mission                                                     |

## Caractéristiques de la mission

<table><thead><tr><th width="255.2265625">Nom du champs</th><th width="182.7073974609375">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>description</code></td><td><code>String</code></td><td>La description de votre mission, peut contenir des balises HTML. <mark style="color:red;"><strong>Requis</strong></mark></td></tr><tr><td><code>type</code></td><td><code>String</code></td><td>Le type de la mission. <br><br><strong>Valeurs possibles :</strong> <code>"benevolat"</code> <code>"volontariat-service-civique</code></td></tr><tr><td><code>domain</code> </td><td><code>String</code></td><td><p>Domaine de la mission.</p><p></p><p><strong>1 valeurs possible parmi :</strong></p><p><code>"environnement",</code></p><p><code>"solidarite-insertion",</code></p><p><code>"prevention-protection",</code></p><p><code>"sante",</code></p><p><code>"culture-loisirs",</code></p><p><code>"education",</code></p><p><code>"emploi",</code></p><p><code>"sport",</code></p><p><code>"humanitaire",</code></p><p><code>"animaux",</code></p><p><code>"vivre-ensemble",</code></p><p><code>"autre",</code></p><p><code>"memoire-et-citoyennete", ou</code></p><p><code>"benevolat-competences"</code></p></td></tr><tr><td><code>activity</code></td><td><code>String</code></td><td><p>Activités de la mission.</p><p></p><p><strong>1 valeur possible parmi :</strong><br><code>"accueil-de-public"</code>,<br><code>"aide-psychologique"</code>,<br><code>"activites-manuelles"</code>,<br><code>"alphabetisation"</code>,<br><code>"animation"</code>,<br><code>"Animation, Valorisation"</code>,<br><code>"art"</code>,<br><code>"autre"</code>,<br><code>"bricolage"</code>,<br><code>"collecte"</code>,<br><code>"communication"</code>,<br><code>"comptabilite-finance"</code>,<br><code>"conseil"</code>,<br><code>"distribution"</code>,<br><code>"documentation-traduction"</code>,<br><code>"ecoute-permanence"</code>,</p><p><code>"encadrement-d-equipes"</code> ,</p><p><code>"enseignement-formation"</code>,</p><p><code>"gestion-de-projets"</code>,<br><code>"gestion-recherche-des-partenariats"</code>,<br><code>"informatique"</code>,<br><code>"jardinage"</code>,<br><code>"juridique"</code>,<br><code>"logistique"</code>,<br><code>"lutte-contre-isolement"</code>,<br><code>"Médiation, Information"</code>,<br><code>"mentorat-parrainage"</code>,<br><code>"mission-internationale"</code>,<br><code>"Préservation, Patrimoine"</code>,<br><code>"Prévention, Sensibilisation"</code>,<br><code>"ramassage-dechets"</code>,<br><code>"recrutement"</code>,<br><code>"responsabilites-associatives</code>,<br><code>"sante-soins"</code>,<br><code>"Secours, Aide"</code>,<br><code>"secourisme"</code>,<br><code>"sensibilisation"</code>,<br><code>"soins-animaux"</code>,<br><code>"Soutien, Accompagnement"</code>,<br><code>"soutien-scolaire"</code>,<br><code>"sport"</code>,<br><code>"taches-administratives"</code>,<br><code>"Transmission, Pédagogie"</code>,<br><code>"visites"</code></p></td></tr><tr><td><code>domainLogo</code></td><td><code>String</code></td><td>Lien url utilisable sur votre site pour illustrer la mission.</td></tr><tr><td><code>schedule</code></td><td><code>String</code></td><td>Rythme de la mission.<br><br><strong>Exemple</strong> : "1 demi-journée par semaine"</td></tr><tr><td><code>audience</code></td><td><code>String[]</code></td><td>Les bénéficiaires de la mission</td></tr><tr><td><code>softSkills</code></td><td><code>String[]</code></td><td>Les compétences générales requises pour la mission</td></tr><tr><td><code>remote</code></td><td><code>String</code></td><td><p>Mission disponible en distanciel.</p><p></p><p><strong>Valeurs possibles:</strong></p><p><code>"possible"</code>, <code>"full"</code> ou <code>"no"</code></p></td></tr><tr><td><code>reducedMobilityAccessible</code></td><td><code>String</code></td><td><p>Mission accessible pour les personnes à mobilité réduite. </p><p></p><p><strong>Valeurs possibles:</strong></p><p><code>"yes"</code> ou <code>"no"</code></p></td></tr><tr><td><code>closeToTransport</code></td><td><code>String</code></td><td><p>Mission proche des transports en commun.</p><p></p><p><strong>Valeurs possibles:</strong></p><p><code>"yes"</code> ou <code>"no"</code></p></td></tr><tr><td><code>openToMinors</code></td><td><code>String</code></td><td><p>Mission ouverte aux mineurs.</p><p> </p><p><strong>Valeurs possibles:</strong></p><p><code>"yes"</code> ou <code>"no"</code></p></td></tr><tr><td><code>priority</code></td><td><code>String</code></td><td>Priorité de la mission</td></tr><tr><td><code>tags</code></td><td><code>String[]</code></td><td>Ce champs permet de tagguer vos missions avec un, ou plusieurs mots-clés personnalisés séparés par une virgule, dans l’API.<br><br>Exemple 1: <code>"Ecologie"</code><br>Exemple 2: <code>"Ecologie, Sport, Solidarité"</code></td></tr><tr><td><code>metadata</code></td><td><code>String</code></td><td>Métadata de la mission</td></tr><tr><td><code>places</code></td><td><code>Number</code></td><td>Nombre de places de la mission</td></tr></tbody></table>

## Champs géographiques de la mission

Il s’agit de l’ensemble des localisations où se déroulent la mission :&#x20;

* Si les missions se tiennent dans plusieurs lieux alors ces localisations se trouveront dans le champs `addresses` qui est un tableau d'objects contenant le détail géographique de chaque mission.
* Si vos missions ne se tiennent dans un lieu unique, vous ne renseignez qu'une seule adresse dans le tableau `addresses`.
* Dans le cas o**ù la mission n'a aucune adresse (cas notamment des missions à distance /remote), ce tableau sera vide.**

*Exemple d'une mission avec une adresse unique*

```json
{
  "addresses": [
    {
      "street": "10 rue de la Paix",
      "city": "Paris",
      "postalCode": "75001",
      "departmentName": "Paris",
      "departmentCode": "75",
      "region": "Île-de-France",
      "country": "FR",
      "location": {
        "lat": 48.8698,
        "lon": 2.3322
      },
      "_id": "67b5d2814870a4e36c06edde"
    }
  ]
}
```

*Exemple d'une mission avec plusieurs adresses*

```json
{
  "addresses": [
    {
      "street": "10 rue de la Paix",
      "city": "Paris",
      "postalCode": "75001",
      "departmentName": "Paris",
      "departmentCode": "75",
      "region": "Île-de-France",
      "country": "FR",
      "location": {
        "lat": 48.8698,
        "lon": 2.3322
      },
      "_id": "67b5d2814870a4e36c06edde"
    },
    {
      "street": "20 rue Victor Hugo",
      "city": "Lille",
      "postalCode": "59000",
      "departmentName": "Nord",
      "departmentCode": "59",
      "region": "Hauts-de-France",
      "country": "FR",
      "location": {
        "lat": 50.6292,
        "lon": 3.0573
      },
      "_id": "67b5d2814870a4e36c06ede0"
    }
  ]
}
```

| Nom du champ | Type               | Description                                                                                                                                                      |
| ------------ | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| addresses    | `Array of Address` | <p>Tableau des adresses où se déroulent la mission. Chaque objet représente une adresse distincte.<br><br><br>Veuillez vous référer au tableau ci-dessous ⬇️</p> |

Une adresse se compose des champs suivants :&#x20;

| Nom du champs    | Type     | Description                                                                                                 |
| ---------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `street`         | `String` | <p>Rue où se déroule la mission.<br><br>Exemple: <code>46 Rue Saint-Antoine</code></p>                      |
| `city`           | `String` | <p>Ville où se déroule la mission<br><br>Exemple: <code>Paris</code> </p>                                   |
| `postalCode`     | `String` | <p>Code postal où se déroule la mission<br><br>Exemple: <code>75004</code></p>                              |
| `departmentCode` | `String` | <p>Numéro de département où se déroule la mission.<br><br>Exemple: <code>75</code></p>                      |
| `departmentName` | `String` | Nom du département où se déroule la mission                                                                 |
| `region`         | `String` | Région où se déroule la mission                                                                             |
| `location`       | `Object` | Composé de `lat` et `lon` de type `Number` représentant la latitude et longitude de l'adresse de la mission |

## Champs de l'organisation ou de la structure d'accueil

<table><thead><tr><th width="291">Nom du champs</th><th width="156">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>organizationName</code></td><td><code>String</code></td><td>Nom de l'organisation de la mission</td></tr><tr><td><code>organizationRNA</code></td><td><code>String</code></td><td>RNA de l'organisation de la mission <mark style="color:red;"><strong>Requis (ou organizationSiren)</strong></mark></td></tr><tr><td><code>organizationSiren</code></td><td><code>String</code></td><td>Siren de l'organisation de la mission <mark style="color:red;"><strong>Requis (ou organizationRNA)</strong></mark></td></tr><tr><td><code>organizationUrl</code></td><td><code>String</code></td><td>Lien de l'organisation de la mission</td></tr><tr><td><code>organizationLogo</code></td><td><code>String</code></td><td>Lien de l'image de l'organisation de la mission</td></tr><tr><td><code>organizationDescription</code></td><td><code>String</code></td><td>Description de l'organisation de la mission</td></tr><tr><td><code>organizationClientId</code></td><td><code>String</code></td><td>Identifiant de l'organisation de la mission</td></tr><tr><td><code>organizationStatusJuridique</code></td><td><code>String</code></td><td>Statut juridique de l'organisation de la mission</td></tr><tr><td><code>organizationType</code></td><td><code>String</code></td><td>Type de l'organisation de la mission</td></tr><tr><td><code>organizationActions</code></td><td><code>String[]</code></td><td>Actions de l'organisation de la mission</td></tr><tr><td><code>organizationFullAddress</code></td><td><code>String</code></td><td>Adresse de l'organisation de la mission</td></tr><tr><td><code>organizationPostCode</code></td><td><code>String</code></td><td>Code postal de l'organisation de la mission</td></tr><tr><td><code>organizationCity</code></td><td><code>String</code></td><td>Ville de l'organisation de la mission</td></tr><tr><td><code>organizationBeneficiaries</code></td><td><code>String[]</code></td><td>Bénéficiaires de l'organisation de la mission</td></tr><tr><td><code>organizationReseaux</code></td><td><code>String[]</code></td><td>Réseau de l'organisation de la mission</td></tr></tbody></table>

## Champs d'indemnisation

<table><thead><tr><th width="291">Nom du champ</th><th width="156">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>compensationAmount</code></td><td><code>Number</code></td><td>Montant de l'indemnisation</td></tr><tr><td><code>compensationUnit</code></td><td><code>String</code></td><td><p>Période d'indemnisation pour le montant fourni<br><br><strong>Valeurs possibles:</strong></p><p><code>"hour"</code>, <code>"day"</code>, <code>"month"</code>, <code>"year"</code></p></td></tr><tr><td><code>compensationType</code></td><td><code>String</code></td><td><p>Type d'indemnisation (brute ou nette). <br><br><strong>Valeurs possibles:</strong></p><p><code>"gross"</code>, <code>"net"</code></p></td></tr></tbody></table>

**Exemple :**&#x20;

Pour une indemnisation de 10 € brut de l'heure, renseignez :&#x20;

* `compensationAmount`: `10`
* `compensationUnit`: `"hour"`
* `compensationType`: `"gross"`

## Champs vérifiés et ajoutés par l'API Engagement

1. L'API Engagement les champs suivants pour chaque mission reçue :

| Nom du champs     | Type      | Description                                                                   |
| ----------------- | --------- | ----------------------------------------------------------------------------- |
| `createdAt`       | `Date`    | Date de création de la mission dans l’API                                     |
| `deletedAt`       | `Date`    | <p>Date à laquelle la mission à été effacée. <br>Défaut <code>null</code></p> |
| `deleted`         | `Boolean` | Si la mission est effacée. Défaut `false`                                     |
| `descriptionHtml` | `String`  | Description originale contenant possiblement des balises HTML                 |
| `duration`        | `String`  | Durée de la mission, soit la difference entre `startAt` et `endAt`            |
| `_id`             | `String`  | Identifiant de la mission                                                     |
| `lastSyncAt`      | `Date`    | Date de début de la dernière mise à jour du flux                              |
| `publisherId`     | `String`  | Id du partenaire (vous) annonceur de la mission                               |
| `publisherName`   | `String`  | Nom du partenaire (vous) annonceur de la mission                              |
| `publisherUrl`    | `String`  | URL du partenaire (vous) annonceur de la mission                              |
| `publisherLogo`   | `String`  | Logo du partenaire (vous) annonceur de la mission                             |
| `statusCode`      | `String`  | Statut de modération de la mission.`“ACCEPTED”`ou `“REFUSED”`                 |
| `statusComment`   | `String`  | Commentaire du statut de la modération                                        |
| `updatedAt`       | `Date`    | Date de création de la dernière mise à jour de la mission                     |

2. L'API Engagement vérifie les références des organisations lors de l'import des missions des partenaires annonceurs afin de garantir l'exactitude des données.&#x20;

Ce processus repose sur une **base de données interne** d'organisations, mise à jour mensuellement avec les données officielles de **l'INSEE** ainsi que sur un appel vers **l'API Data Subvention pour validation externe** si nécessaire.

L'API Engagement tente d'associer le RNA ou SIRET fourni par le partenaire annonceur avec une organisation existante dans la **base de données interne**. En cas d'absence de correspondance interne, l'API Engagement interroge **l'API Data Subvention** pour valider les informations de l'organisation. si une correspondance est trouvée et validée, **l'organisation est créée dans la base interne avec les informations validées**.

<table><thead><tr><th width="347">Nom du champs</th><th width="133">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>organizationVerificationStatus</code></td><td><code>String</code></td><td>Statut de la vérification de l'organisation.</td></tr><tr><td><code>organizationRNAVerified</code></td><td><code>String</code></td><td>Numéro RNA de l'organisation vérifié</td></tr><tr><td><code>organizationSiretVerified</code></td><td><code>String</code></td><td>Numéro SIRET de l'organisation vérifié</td></tr><tr><td><code>organizationSirenVerified</code></td><td><code>String</code></td><td>Numéro SIREN de l'organisation vérifié</td></tr><tr><td><code>organizationNameVerified</code></td><td><code>String</code></td><td>Nom de l'organisation vérifié</td></tr></tbody></table>

## Modération des partenaires "diffuseur"

Certains diffuseurs de l'API Engagement pratique une modération supplémentaire pour les missions qu'il récupèrent via l'API avant de les diffuser sur leur plateforme.

Dans ce cas, des champs supplémentaires sont ajoutés aux missions afin de connaître le statut de la modération. Tous ces champs suivent le format `moderation_{identifiant_du_diffuseur}_{champs}` comme suit et sont accessible par API avec la route [Broken mention](broken://pages/-M_jv6oFRGaxS_l56Ogy):&#x20;

<table><thead><tr><th width="297">Nom du champ</th><th width="119">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>moderation_{id}_status</code></td><td><code>String</code></td><td><p>Statut de la modération parmi ces valeurs <span data-gb-custom-inline data-tag="emoji" data-code="1f44d">👍</span></p><ul><li><code>ACCEPTED</code>: mission acceptée</li><li><code>REFUSED</code>: mission refusée</li><li><code>PENDING</code>: mission en attente de modération</li><li><code>ONGOING</code>: mission en cours de modération</li></ul></td></tr><tr><td><code>moderation_{id}_comment</code></td><td><code>String</code></td><td>Motif du refus si la mission est refusée</td></tr><tr><td><code>moderation_{id}_title</code></td><td><code>String</code></td><td>Si le titre est modifié, nouveau titre choisi par le partenaire</td></tr></tbody></table>

Ces informations sont également visibles dans le dashboard "Partager des Missions" > Flux de Mission

<figure><img src="https://2489729786-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG18aCd8mNuBlmkXXgR3Q%2Fuploads%2FAURxWYlhRx8iX1dqd1rl%2Fimage.png?alt=media&amp;token=0f2e6ef9-00f9-4bd9-a9f6-57b3f02543e2" alt=""><figcaption></figcaption></figure>

### Exemple de modération

```json
// Mission refusée
{
    "title": "La meilleure mission de bénévolat",
    "startAt": "2012-12-21T00:00:00.000Z"
    ...
    "moderation_5f5931496c7ea5xxxxxxxxxx_comment": "La mission est refusée car la date de création est trop ancienne (> 6 mois)",
    "moderation_5f5931496c7ea5xxxxxxxxxx_status": "REFUSED",
    "moderation_5f5931496c7ea5xxxxxxxxxx_title": ""
}
// Mission acceptée
{
        "title": "La meilleure mission de bénévolat",
    ...
    "moderation_5f5931496c7eaxxxxxxxxxxx_comment": "",
    "moderation_5f5931496c7eaxxxxxxxxxxx_status": "ACCEPTED",
    "moderation_5f5931496c7eaxxxxxxxxxxx_title": "L'une des meilleures mission de bénévolat"
}
```


# Partager les données de diffusion sur mon site à l'API Engagement

{% hint style="danger" %}
Cette section ne s'adresse qu'aux **diffuseurs ayant choisi l'intégration par API et/ou par lien tracké**.
{% endhint %}

## Introduction : étapes du parcours de l'engagement trackés par l'API

* Sur la partie gauche, dans le cadre bleu (Site diffuseur B, vous), &#x6C;**'API traque les impressions**.
* Sur la partie droite, dans le cadre vert (Site annonceur A), l'API traque plusieurs étapes du parcours de l'engagement. L'API peut ainsi donner des statistiques consolidées à ses partenaires :
  * **sur le nombre de candidatures pour une mission donnée**.&#x20;
  * **sur le nombre d'inscriptions (ou de création de comptes) sur le site annonceur**

<figure><img src="https://2489729786-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG18aCd8mNuBlmkXXgR3Q%2Fuploads%2FhkGH8U3sTK8RbHKcxNLX%2FTracking%20API%20Engagement%20-%20Frame%202%20(2)%20(1).jpg?alt=media&amp;token=281df51e-2abf-4415-b1b0-b8ba2fcd8fe8" alt=""><figcaption></figcaption></figure>

## Les données à partager en tant que diffuseur à l'API Engagement

{% hint style="warning" %}
L'API Engagement recueille obligatoirement les données de diffusion suivantes de la part de ses partenaires diffuseurs.
{% endhint %}

### Pourquoi partager des données de diffusion à l'API Engagement ?&#x20;

* L'API Engagement met à disposition un stock de missions d'engagement à ses partenaires diffuseurs. En contrepartie, celle-ci demande de renvoyer l'information des informations de missions non diffusées ou diffusées ' dans le stock mis à disposition et les raisons de cette non diffusion.
* L'API Engagement permet à ses partenaires annonceurs d'accéder à des statistiques de diffusion. Pour effectuer un rapport complet sur les statistiques de diffusion

### Quelles sont les données à partager à l'API Engagement en tant que diffuseur ?

* Les [données de missions non diffusées par le partenaire diffuseur](/diffuser-des-missions/tracking-des-candidatures/missions-non-diffusees-sur-mon-site) (concerne uniquement les diffuseurs ayant choisi l'intégration API) : le diffuseur doit partager les données de missions qu'il ne diffusent pas et la raison.
* Les [données d'impressions (vues)](/diffuser-des-missions/tracking-des-candidatures/partager-vos-statistiques-de-diffusions-impressions-a-lapi-engagement) pour les missions diffusées ou les liens de campagnes dits "trackés".


# Missions non diffusées sur mon site

{% hint style="danger" %}
Rappel : Cette section ne s'adresse qu'aux **diffuseurs ayant choisi l'intégration par API**.
{% endhint %}

Il est possible que certaines des missions présentes dans le flux API ne correspondent pas à vos critères pour être diffusées ; et que vous choissisez de ne pas les diffuser sur votre application. Cette information doit être partagée à l'API Engagement.&#x20;

## Étape 1 : Création d'une route "feedback" *(à réaliser par l'équipe API Engagement)*

* Le chargé de déploiement avec qui vous êtes en contact se charge d'ouvrir et **configurer la route** (création de l’endpoint dans l’environnement adéquat) 
* Cette route sera de la forme **`/v2/{nomPartenaire}/feedback`**

*NB : Les données d'authenfication restent les mêmes que pour accéder aux données de missions.*

## Étape 2 : Envoyer l'information des missions non diffusées

### `GET /v2/{nom}/feedback`

#### Header

| **Champs**  | **Type** | **Description**  | **Example**                              |
| ----------- | -------- | ---------------- | ---------------------------------------- |
| `x-api-key` | String   | Clef API fournie | xxxxxxxx\_xxxx\_xxxx\_xxxx\_xxxxxxxxxxxx |

#### Body

***

| **Champs**                                                                             | **Type** | Requis | **Description**                                                          |
| -------------------------------------------------------------------------------------- | -------- | ------ | ------------------------------------------------------------------------ |
| `missionId`                                                                            | String   | oui    | ID de l'annonce                                                          |
| `status`                                                                               | String   | oui    | `ACCEPTED`  en cas d’ajout réussi                                        |
| `PENDING`  en cas de début de traitement de la mission (optionnel)                     |          |        |                                                                          |
| `DELETED` en cas de suppression réussie                                                |          |        |                                                                          |
| `REFUSED` en cas de refus de la mission (accompagné de la raison dans le champs `note` |          |        |                                                                          |
| `url`                                                                                  | String   | non    | Url de l'annonce                                                         |
| `comment`                                                                              | String   | non    | Détails de refus de la mission. Obligatoires pour les statuts `REFUSED`. |

#### Exemples

Accepted

```jsx
{
	"missionId": "5f6b4b86596993ec582f92d1", 
	"status": "ACCEPTED",
	"url": "<https://www.jobteaser.com/en/job-offers/xxx-ma-mission>"
}
```

Refused

```jsx
{
	"missionId": "5f6b4b86596993ec582f92d1", 
	"status": "REFUSED",
	"comment": "La mission ne possede pas de code postal"
}
```

#### Responses

**Status 200**

```jsx
{
	"ok": true
}
```

**Status 400**

```jsx
{
    "ok": false,
    "code": "INVALID_BODY",
    "message": {
        "issues": [
            {
                "code": "invalid_type",
                "expected": "string",
                "received": "undefined",
                "path": [
                    "missionId"
                ],
                "message": "Required"
            }
        ],
        "name": "ZodError"
    }
}
```

**Status 401**

```jsx
Unauthorized
```

**Status 404**

```jsx
{
    "ok": false,
    "code": "NOT_FOUND",
    "message": "Mission not found"
}
```


# Partager vos statistiques de diffusions (impressions) à l'API Engagement

{% hint style="danger" %}
Rappel : Cette section ne s'adresse qu'aux **diffuseurs ayant choisi l'intégration par API et/ou par lien tracké**.
{% endhint %}

## Qu'est ce qu'une impression ?

L'API Engagement appelle impression, la vue d'une page de mission (ou d'un élément portant un lien tracké comme par exemple un bouton ou une bannière dans le cadre d'une campagne) par un utilisateur sur votre site/appli.

{% hint style="info" %}
Pour que l'API comptabilise une impression, il faut que la mission ou l'élément portant un lien tracké API soit visualisé au moins 1,5 seconde par l'internaute.
{% endhint %}

## Pourquoi l'API Engagement tracke les impressions (de missions ou d'éléments portant un lien tracké) ?

L'API Engagement permet aux annonceurs et diffuseurs de faciliter l'engagement en France en mettant à disposition d'outils facilitant la mise en relation entre bénévoles/volontaires et organisations. Pour rendre compte de la performance de cette mise en relation et afin de fournir à ses partenaires annonceurs et diffuseurs des statistiques poussées, l'API demande de **transmettre ces informations d'impressions** :&#x20;

* les diffuseurs peuvent ainsi valoriser leur impact en mesurant combien de fois une mission ou une campagne (via un lien tracké) a été exposée à ses visiteurs.&#x20;
* les annonceurs peuvent comprendre où ont été diffusées leurs missions et quel est le niveau d'attractivité de leur offre par rapport aux redirections (clics) et candidatures reçues.

## Quelles sont les impressions que l'API tracke ?

* Toutes les missions de bénévolat et volontariat diffusées par API.
* Les liens trackés qui seront cliqués sur votre site ou application (exemples : des boutons ou des images figurant sur votre site). ⚠️ **En revanche, les liens trackés placés dans des emails ne peuvent pas faire l'objet d'un tracking d'impressions.**

## Comment envoyer ces informations à l'API Engagement ?

* Il existe deux manières d'envoyer les informations d'impressions à l'API Engagement :&#x20;
  * [Par envoi de fichier csv](/diffuser-des-missions/tracking-des-candidatures/partager-vos-statistiques-de-diffusions-impressions-a-lapi-engagement/par-envoi-de-fichier-csv.).
  * [Par la mise en place d'un tag et l'installation d'un script](/diffuser-des-missions/tracking-des-candidatures/partager-vos-statistiques-de-diffusions-impressions-a-lapi-engagement/par-la-mise-en-place-dun-tag-ou-pixel-sur-votre-site) sur votre site.


# Par envoi de fichier csv.

Il est possible d'envoyer un fichier csv. une fois par semaine avec la liste des missions difffuées et le nombre d'impressions associées sur une période donnée.

### Modalités d'envoi

* **Rythme d'envoi du fichier** : une fois par semaine
* **Informations devant figurer dans le mail** : les dates couvertes par la mission (exemple export mission du 17/01 au 23/01) et un fichier au format csv (voir ci-dessous pour la structure du fichier)
* **Email de destination** : à demander au chargé de déploiement (cette adresse sera de la forme {nomPartenaire}@api-engagement-dev.fr)

### Structure du fichier&#x20;

* `clientId` est l'identifiant de la mission
* Date de début de diffusion : *dernière date de diffusion de la mission*
* Date de fin de diffusion : *vide si la mission est toujours diffusée sur votre site*
* Première date de diffusion : *première date à laquelle la mission a été diffusée sur votre site*
* Titre de la mission
* Nombre de jours de diffusion pendant la période : *Nombre de jours pendant laquelle la mission a été diffusée sur votre site durant la période*
* Nombre d'impressions : le nombre d'impressions réalisées par la mission sur la période couverte

*Exemple de structure de fichier*

<table><thead><tr><th width="201">clientId</th><th width="175">Date de début de diffusion</th><th width="152">Date de fin de diffusion</th><th width="175">Première date de diffusion</th><th width="237">Titre de la missions</th><th width="313">Nombre de jours de diffusion pendant la période</th><th width="180">Nombre d'impressions</th></tr></thead><tbody><tr><td>672e6e2673fbd982c1036c49</td><td>2025-01-06</td><td></td><td>2025-01-06</td><td>Bénévolat - J'apporte un soutien bénévole en comptabilité</td><td>6</td><td>45</td></tr><tr><td>6778969273fbd982c1d03e4d</td><td>2025-01-05</td><td>2025-01-09</td><td>2025-01-05</td><td>Bénévolat - Je participe à la promotion d’un festival / événement</td><td>5</td><td>40</td></tr><tr><td>6778969273fbd982c1d03e4a</td><td>2025-01-05</td><td>2025-01-09</td><td>2025-01-05</td><td>Bénévolat - J’accompagne des projets de communication</td><td>5</td><td>38</td></tr><tr><td>6778969273fbd982c1d03e4c</td><td>2025-01-05</td><td>2025-01-09</td><td>2025-01-05</td><td>Bénévolat - Je deviens secrétaire général bénévole d’une association</td><td>5</td><td>33</td></tr><tr><td>6703bad373fbd982c100f6ba</td><td>2025-01-05</td><td>2025-01-08</td><td>2025-01-05</td><td>Bénévolat - J'anime des ateliers informatiques à la maison d'arrêt de LIMOGES</td><td>4</td><td>30</td></tr><tr><td>631f12e2c2737205f0f6bc7a</td><td>2025-01-05</td><td>2025-01-12</td><td>2025-01-05</td><td>Bénévolat - J'accompagne une personne ou une famille sans-abri hébergée par L'Ouvre Porte</td><td>7</td><td>29</td></tr><tr><td>6778969273fbd982c1d03e49</td><td>2025-01-05</td><td>2025-01-09</td><td>2025-01-05</td><td>Bénévolat - J’interviens en tant que gestionnaire administratif bénévole</td><td>5</td><td>29</td></tr><tr><td>677993b273fbd982c1d96336</td><td>2025-01-05</td><td>2025-01-09</td><td>2025-01-05</td><td>Bénévolat - Je favorise l'apprentissage de la langue française</td><td>5</td><td>28</td></tr><tr><td>67632a3973fbd982c121a3b2</td><td>2025-01-06</td><td>2025-01-09</td><td>2024-12-19</td><td>Bénévolat - Je donne des cours de FLE et Alphabétisation au CHU</td><td>4</td><td>27</td></tr><tr><td>6737a8b173fbd982c173f119</td><td>2025-01-05</td><td>2025-01-08</td><td>2025-01-05</td><td>Bénévolat - J'accompagne des jeunes en grande exclusion à répéter et organiser des représentations d'un spectacle théâtre</td><td>4</td><td>26</td></tr><tr><td>654d764dfbb78a08126db23c</td><td>2025-01-06</td><td>2025-01-09</td><td>2025-01-06</td><td>Bénévolat - J'apporte mon aide en tant que maquilleur bénévole H/F</td><td>4</td><td>26</td></tr><tr><td>659be78422c936452de17eeb</td><td>2025-01-06</td><td>2025-01-09</td><td>2025-01-06</td><td>Bénévolat - Je donne des cours d'informatique aux exilés hébergés à Perpignan</td><td>4</td><td>23</td></tr><tr><td>6778423e73fbd982c1cd9a86</td><td>2025-01-04</td><td></td><td>2025-01-04</td><td>Bénévolat - Je mène le diagnostic et la mise à niveau RGPD de l'association</td><td>7</td><td>23</td></tr><tr><td>652837db2dd0679786674213</td><td>2025-01-05</td><td>2025-01-08</td><td>2025-01-05</td><td>Bénévolat - Je deviens chef scout auprès des enfants et des jeunes</td><td>4</td><td>23</td></tr><tr><td>65728a72ff8b2fd6bfc32f85</td><td>2025-01-06</td><td>2025-01-09</td><td>2024-12-25</td><td>Bénévolat - J’accompagne des projets de communication</td><td>4</td><td>23</td></tr><tr><td>676d61d173fbd982c177e6be</td><td>2024-12-27</td><td></td><td>2024-12-27</td><td>Bénévolat - Je deviens photographe pour les Rencontres Internationales de la Classe Dehors</td><td>7</td><td>22</td></tr><tr><td>6703bb4273fbd982c10119c4</td><td>2025-01-04</td><td>2025-01-12</td><td>2025-01-04</td><td>Bénévolat - Je rends visite à une personne âgée en maison de retraite ou un patient à l'hôpital</td><td>7</td><td>22</td></tr><tr><td>65784f0be5c3ee69e1fc01b9</td><td>2025-01-05</td><td>2025-01-06</td><td>2025-01-05</td><td>Bénévolat - Je démarche des producteurs locaux</td><td>2</td><td>21</td></tr><tr><td>6703bb3c73fbd982c100fd93</td><td>2024-11-22</td><td></td><td>2024-11-06</td><td>Bénévolat - Je m'engage comme super héros et princesses auprès des enfants hospitalisées ou en situation de handicap</td><td>7</td><td>20</td></tr><tr><td>6778423f73fbd982c1cd9a8f</td><td>2025-01-04</td><td>2025-01-08</td><td>2025-01-04</td><td>Bénévolat - Je m'engage comme coach pour encadrer une équipe de rugby LGBT</td><td>4</td><td>20</td></tr><tr><td>6703bad473fbd982c100fa7e</td><td>2025-01-06</td><td>2025-01-09</td><td>2025-01-06</td><td>Bénévolat - J'assure les permanences d'accueil des réfugiés en binôme 2 à 3 heures par semaine</td><td>4</td><td>20</td></tr><tr><td>6703bad073fbd982c100eaa7</td><td>2024-12-28</td><td>2025-01-09</td><td>2024-12-28</td><td>Bénévolat - J'apporte mon aide en tant que journaliste/rédacteur.rice</td><td>5</td><td>20</td></tr></tbody></table>


# Par la mise en place d'un tag (ou pixel) sur votre site

Cet article explique comment mesurer les impressions et envoyer l'information à l'API Engagement de manière automatique.

## Étape 1 : Rajouter la balise "API Engagement" sur votre site&#x20;

La Balise API Engagement, doit être ajoutée en haut de la balise `<head>` et avant tout autre script ou balise CSS.&#x20;

```html
<script>
(function (i, s, o, g, r, a, m) {
i["ApiEngagementObject"] = r; (i[r] = i[r] || function () { (i[r].q = i[r].q || []).push(arguments); }), (i[r].l = 1 * new Date()); (a = s.createElement(o)), (m = s.getElementsByTagName(o)[0]); a.async = 1; a.src = g; m.parentNode.insertBefore(a, m);
})(window, document, "script", "https://app.api-engagement.beta.gouv.fr/jstag.js", "apieng");
apieng("config", "votre-id-de-partenaire");
</script>
```

Ce script effectue **trois actions** principales :&#x20;

1. **Crée un élément** `<script>` pour démarrer le téléchargement asynchrone de la bibliothèque JavaScript jstag.js depuis <https://app.api-engagement.beta.gouv.fr/jstag.js>
2. **Initialise une fonction** globale apieng (appelée "file d'attente de commandes apieng()") permettant de planifier l'exécution des commandes une fois la bibliothèque jstag.js chargée et prête à être utilisée
3. **Ajoute la commande `apieng()`** à la varaiable `window` qui permet d'accéder à toutes les fonctionnalités de tracking de l'API Engagement.

## Étape 2 : S'assurer que le lien de redirection de l'API est visible sur le bouton (ou la bannière)

* Pour le vérifier, il vous suffit de faire clic droit, puis "Inspecter". Dans la console, vous devez voir un lien dans la balise de type \<a href="[https://api.api-engagement.beta.gouv.fr/r/.......">](https://api.api-engagement.beta.gouv.fr/r/.......">) \</a>
* Si ce lien est visible, alors il n'y a rien de plus à faire et l'API pourra tracker les impressions.

⚠️ S'il n'est pas possible de mettre le lien visible tel que mentionné ci-dessus, consultez l'[alternative expliquée ci-dessous](#altenative-tracking-des-impressions-par-le-pixel-utilisable-dans-le-contexte-de-la-diffusion-de-miss) :&#x20;

<figure><img src="https://2489729786-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG18aCd8mNuBlmkXXgR3Q%2Fuploads%2FM1pkKERmaXOi5nRGnVAk%2Fimage.png?alt=media&amp;token=62a2b4d4-715f-4acf-9706-380a02b41f72" alt=""><figcaption><p>Exemple de lien de redirection visible pour une diffusion par API</p></figcaption></figure>

<figure><img src="https://2489729786-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG18aCd8mNuBlmkXXgR3Q%2Fuploads%2FKfQYYaw8riuSvjzFIsCB%2Fimage.png?alt=media&amp;token=9757c57b-18fa-4f5f-b6d0-fbd33870647c" alt=""><figcaption><p>Exemple de lien de redirection visible pour une diffusion par lien tracké</p></figcaption></figure>

## Alternative : Tracking des impressions par le pixel (utilisable dans le contexte de la diffusion de missions par API ou pour les liens trackés)

* **Le rajout de la balise décrite en (1.) reste requis.** Cependant, si l'implémentation décrite en (2.) ne convient pas, alors il est possible de tracker les impressions via la méthode du pixel.
* Sur le bouton (ou la bannière) qui sert à rediriger les utilisateurs vers la page cible (de l'annonceur), vous devez ajouter une balise \<span> de la forme suivante :

```
<span name="tracker_counter" data-id="mission_id" /> 
```

où `tracker_counter` n’est pas à changer (c’est avec ce nom que le script retrouve le tracker) et `mission_id` est l’identifiant que l’API fournit de la mission.


# Identifier l’origine d’une redirection à l’aide de tags

{% hint style="info" %}
Cette page s'adresse exclusivement aux **diffuseurs qui distribuent des missions d'engagement sur plusieurs plateformes ou applications** en utilisant une source unique de récupération des missions via une seule clé API dédiée.
{% endhint %}

### Introduction

Habituellement, une redirection provient directement du site du diffuseur, ce qui signifie qu'elle hérite automatiquement de cette origine. Cependant, il peut arriver qu’un diffuseur dispose de plusieurs plateformes de diffusion. Dans ce contexte, l’API Engagement offre la possibilité d’ajouter des tags aux redirections. Cette fonctionnalité permet de distinguer facilement l’origine de chaque redirection et ainsi d’optimiser le suivi (tracking) des performances sur les différentes plateformes.

### Préambule : récupération des missions

Les missions fournies par l’API Engagement peuvent être récupérées en suivant [les routes indiquées dans la documentation](broken://pages/-MFVTjXZI4cjR4v4MZs2). Une fois récupérées, les missions sont présentées dans le [format décrit ci-dessous](/diffuser-des-missions/modele-de-donnees-dune-mission-dengagement).

```jsx
{
    "_id": "id_mission",
    "publisherId": "id_annonceur",
    "publisherName": "xxx",
    "publisherUrl": "xxx",
    "publisherLogo": "xxx",
    "lastSyncAt": "2021-12-11T16:33:43.807Z",
    "applicationUrl": "<https://api.api-engagement.beta.gouv.fr/r/id_mission/id_annonceur>",
    "statusCode": "ACCEPTED",
    "statusComment": "",
    "clientId": "xxx",
    "title": "Mon titre",
    "description": "Ma description",
		[...]
    "createdAt": "2025-13-32T25:70:00.000Z",
    "updatedAt": "2025-13-32T25:70:00.000Z"
}
```

### Modification de l'**`applicationUrl`** sur votre site de diffusion

Pour ajouter un ou plusieurs tags à des redirections, ce qui permet ensuite de les distinguer en fonction du site source, il suffit de modifier le **`applicationUrl`** envoyé dans la mission.

#### Ajout d'un seul tag

Pour cela, vous devez simplement ajouter un paramètre de recherche dans l’URL (**URL search parameter**) appelé **`tags`**. Cela permettra d’identifier et de suivre plus facilement les redirections en fonction des tags définis.&#x20;

```jsx
"applicationUrl": "<https://api.api-engagement.beta.gouv.fr/r/id_mission/id_annonceur?tags=mon-tag>",
```

Cela aurait pour effet, de notre côté, d’enregistrer la redirection de la manière suivante :

```jsx
{
    "_id":"id_de_la_redirection",
    "type": "click",
    "tags": ["pixel"],
    "missionId": "id_mission",
    "fromPublisherId": "votre_id",
    "fromPublisherName": "Votre Nom",
    "toPublisherId": "id_annonceur",
    "toPublisherName": "Je suis annonceur",
    [...]
    "tags": ["mon-tag"]
}
```

#### Ajout de plusieurs tags

Pour ajouter **plusieurs tag**, il suffit de les séparer par une virgule comme ceci:

```jsx
"applicationUrl": "<https://api.api-engagement.beta.gouv.fr/r/id_mission/id_annonceur?tags=tag1,tag2,tag3>",
```

Cela aurait pour effet, de notre côté, d’enregistrer la redirection de la manière suivante :

```jsx
{
    "_id":"id_de_la_redirection",
    "type": "click",
    "tags": ["pixel"],
    "missionId": "id_mission",
    "fromPublisherId": "votre_id",
    "fromPublisherName": "Votre Nom",
    "toPublisherId": "id_annonceur",
    "toPublisherName": "Je suis annonceur",
    [...]
    "tags": ["tag1","tag2","tag3"]
}
```


# /association

L'API association facilite la recherche, la consultation et la mise à jour de la base des établissements liés aux associations. Une association contient un ou plusieurs établissements.

## Rechercher des établissements

<mark style="color:green;">`POST`</mark> `https://api.api-engagement.beta.gouv.fr/v1/association/search`

Retourne les établissements via le nom de l'établissement.

#### Headers

***

<table><thead><tr><th width="176">Name</th><th width="102">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>apikey</code> <mark style="color:red;">requis</mark></td><td><code>string</code></td><td>La clé API <strong>nécessaire à l’authentification</strong>. Les données disponibles sont définies en fonction de votre clé API.</td></tr></tbody></table>

#### Request Body

***

<table><thead><tr><th>Name</th><th width="216">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>name</code></td><td><code>string</code></td><td>Nom de l'association recherchée</td></tr><tr><td><code>minScore</code></td><td><code>number</code></td><td>Score de correspondance minimal attendu </td></tr><tr><td><code>city</code></td><td><code>string</code></td><td>Ville de l'association</td></tr><tr><td><code>size</code></td><td><code>number</code></td><td>Nombre de résultats maximum retournés</td></tr></tbody></table>

{% tabs %}
{% tab title="200 OK" %}

```
{
  "ok": true,
  "data": [
    {
      "_id": "5f97ec98ab4bb01cb31de652",
      "rna": "W061001494",
      "name": "A DEMI-MOT",
      "regime": "loi1901",
      "theme": "Culture",
      "famille": "culture, pratiques d'activités artistiques, culturelles ",
      "est_etablissement_secondaire": false,
      "coordonnees": {
        "adresse": {
          "nom_complet": "5 Rue de la Laïta 44400 Rezé",
          "nom": "5 Rue de la Laïta",
          "code_postal": "44400",
          "code_insee": "44143",
          "rue": "Rue de la Laïta",
          "numero": "5",
          "commune": "Rezé",
          "commune_ancienne": "",
          "contexte": "44, Loire-Atlantique, Pays de la Loire",
          "departement_numero": "44",
          "departement": "Loire-Atlantique",
          "region": "Pays de la Loire",
          "type": "housenumber"
        },
        "telephone": [],
        "courriel": []
      },
      "objet": "promotion des échanges culturels et mélange entre différentes expressions artistiques (conte musique théâtre)",
      "score": 22.872053
    },
    {
      "_id": "5f9bed4d1087da3c1bae6cda",
      "rna": "W442016188",
      "name": "L'IMAGE A UN SENS",
      "regime": "loi1901",
      "theme": "Culture",
      "famille": "culture, pratiques d'activités artistiques, culturelles ",
      "est_etablissement_secondaire": false,
      "coordonnees": {
        "adresse": {
          "nom_complet": "29 Rue Etienne Lemerle 44400 Rezé",
          "nom": "29 Rue Etienne Lemerle",
          "code_postal": "44400",
          "code_insee": "44143",
          "rue": "Rue Etienne Lemerle",
          "numero": "29",
          "commune": "Rezé",
          "commune_ancienne": "",
          "contexte": "44, Loire-Atlantique, Pays de la Loire",
          "departement_numero": "44",
          "departement": "Loire-Atlantique",
          "region": "Pays de la Loire",
          "type": "housenumber"
        },
        "telephone": [
          "0683527271"
        ],
        "courriel": []
      },
      "objet": "soutenir, créer et produire des films cinéma (courts-métrages, documentaires, etc.) pour favoriser et encourager une culture de l'image pour tous",
      "score": 22.577662
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Mettre à jour un établissement

<mark style="color:orange;">`PUT`</mark> `https://api.api-engagement.beta.gouv.fr/v1/association/:idRna/etablissement/:id`

Enrichit les données d'un établissement au sein d'une association. Ces modifications permettent de mettre à jour un établissement sans modifier tous les établissement de l'association à laquelle il appartient. La modification de la description d'un établissement n'aura pas d'impact sur la description des autres établissement. Pour mettre à jour la description de toute une association, utiliser la route décrite plus bas.

#### Path Parameters

<table><thead><tr><th>Name</th><th width="140">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td><code>string</code></td><td>Identifiant de l'établissement</td></tr><tr><td><code>idRna</code></td><td><code>string</code></td><td>Identifiant de l'association.</td></tr></tbody></table>

#### Headers

<table><thead><tr><th width="191">Name</th><th width="135">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>apikey</code> <mark style="color:red;">requis</mark></td><td><code>string</code></td><td>La clé API <strong>nécessaire à l’authentification</strong>. Les données disponibles sont définies en fonction de votre clé API.</td></tr></tbody></table>

#### Request Body

<table><thead><tr><th width="264">Name</th><th width="107">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>facebook</code></td><td><code>string</code></td><td>URL facebook</td></tr><tr><td><code>linkedin</code></td><td><code>string</code></td><td>URL linkedin</td></tr><tr><td><code>logo</code></td><td><code>string</code></td><td>URL vers l'image du logo</td></tr><tr><td><code>url</code></td><td><code>string</code></td><td>Site web</td></tr><tr><td><code>twitter</code></td><td><code>string</code></td><td>URL twitter</td></tr><tr><td><code>description</code></td><td><code>string</code></td><td>description de l'établissement</td></tr><tr><td><code>publics_beneficiaires</code></td><td><code>array</code></td><td>Publics visés. Exemple : "Tous publics"</td></tr><tr><td><code>statut_juridique</code></td><td><code>string</code></td><td>Statut juridique</td></tr><tr><td><code>coordonnees</code></td><td><code>string</code></td><td>Objet représentant les coordonnées à destination du public de l'association. L'adresse respecte le format de l'API adresse. Exemple : <br><code>"coordonnees": {</code> <br>  <code>"adresse": {</code> <br>    <code>"nom_complet": "29 Rue Etienne Lemerle 44400 Rezé",</code> <br>    <code>"nom": "29 Rue Etienne Lemerle",</code> <br>    <code>"code_postal": "44400",</code> <br>    <code>"code_insee": "44143",</code><br>    <code>"rue": "Rue Etienne Lemerle",</code> <br>    <code>"numero": "29",</code> <br>    <code>"commune": "Rezé",</code> <br>    <code>"commune_ancienne": "",</code> <br>    <code>"contexte": "44, Loire-Atlantique, Pays de la Loire",</code> <br>    <code>"departement_numero": "44",</code> <br>    <code>"departement": "Loire-Atlantique",</code> <br>    <code>"region": "Pays de la Loire",</code> <br>    <code>"type": "housenumber"</code> <br>  <code>},</code> <br>  <code>"telephone": [ "0683527271" ],</code> <br>  <code>"courriel": []</code> <br><code>}</code></td></tr><tr><td><code>domaines</code></td><td><code>array</code></td><td>Liste des domaines de l'association (ex: "Protection de la nature", "Mémoire et citoyenneté")</td></tr><tr><td><code>donation</code></td><td><code>string</code></td><td>URL pour les dons à l'association</td></tr></tbody></table>

{% tabs %}
{% tab title="200 " %}

```
{
  "ok": true,
  "data": {
    "_id": "5f97eddeab4bb01cb31df22a",
    "rna": "W061003010",
    "name": "CENTRE EUROPEEN DE FORMATION AUX METIERS DU SPORT ET DE L'ANIMATION (CEFAMS)",
    "regime": "loi1901",
    "theme": "Sport",
    "famille": "Sports, activités de plein air ",
    "domaines": [
      "test"
    ],
    "statut_juridique": "test",
    "publics_beneficiaires": [
      "test"
    ],
    "est_etablissement_secondaire": false,
    "coordonnees": {
      "adresse": {
        "location": {
          "lon": 6.944482,
          "lat": 43.643349
        },
        "nom_complet": "50 Route de Cannes 06130 Grasse",
        "nom": "50 Route de Cannes",
        "code_postal": "06130",
        "code_insee": "06069",
        "rue": "Route de Cannes",
        "numero": "50",
        "commune": "Grasse",
        "commune_ancienne": "",
        "contexte": "06, Alpes-Maritimes, Provence-Alpes-Côte d'Azur",
        "departement_numero": "06",
        "departement": "Alpes-Maritimes",
        "region": "Provence-Alpes-Côte d'Azur",
        "type": "housenumber"
      },
      "telephone": [
        "0102030405"
      ],
      "courriel": [
        "test@example.org"
      ]
    },
    "objet": "formation et préformation aux métiers de la forme et aux métiers du sport de mettre en place des actions d'aménagement du temps de travail scolaire et périscolaires dans le secteur des aps",
    "description": "hello desc",
    "logo": "http://logo.fr",
    "twitter": "http://donation.fr",
    "donation": "http://donation.fr/df"
  }
}
```

{% endtab %}
{% endtabs %}

## Mettre à jour une association

<mark style="color:orange;">`PUT`</mark> `https://api.api-engagement.beta.gouv.fr/v1/association/:idRna`

Enrichir les données d'une association via son identifiant RNA. Ces modifications seront appliquées **sur tous les établissements**.

#### Path Parameters

| Name    | Type     | Description |
| ------- | -------- | ----------- |
| `idRna` | `string` | ID RNA      |

#### Headers

| Name                                            | Type     | Description                                     |
| ----------------------------------------------- | -------- | ----------------------------------------------- |
| `apikey` <mark style="color:red;">requis</mark> | `string` | La clé API **nécessaire à l’authentification**. |

#### Request Body

<table><thead><tr><th width="267">Name</th><th width="108">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>coordonnees</code></td><td><code>object</code></td><td>Objet représentant les coordonnées à destination du public de l'association. L'adresse respecte le format de l'API adresse.<br>Exemple :<br><code>"coordonnees": {</code> <br>  <code>"adresse": {</code> <br>    <code>"nom_complet": "29 Rue Etienne Lemerle 44400 Rezé",</code> <br>    <code>"nom": "29 Rue Etienne Lemerle",</code> <br>    <code>"code_postal": "44400",</code><br>    <code>"code_insee": "44143",</code> <br>    <code>"rue": "Rue Etienne Lemerle",</code> <br>    <code>"numero": "29", "commune": "Rezé",</code> <br>    <code>"commune_ancienne": "",</code> <br>    <code>"contexte": "44, Loire-Atlantique, Pays de la Loire",</code> <br>    <code>"departement_numero": "44",</code> <br>    <code>"departement": "Loire-Atlantique",</code> <br>    <code>"region": "Pays de la Loire",</code> <br>    <code>"type": "housenumber"</code> <br>  <code>},</code> <br>  <code>"telephone": [ "0683527271" ],</code> <br>  <code>"courriel": []</code> <br><code>}</code></td></tr><tr><td><code>donation</code></td><td><code>string</code></td><td>URL pour les dons à l'association</td></tr><tr><td><code>domaines</code></td><td><code>array</code></td><td>Liste des domaines de l'association (ex: "Protection de la nature", "Mémoire et citoyenneté")</td></tr><tr><td><code>statut_juridique</code></td><td><code>string</code></td><td>Statut juridique</td></tr><tr><td><code>publics_beneficiaires</code></td><td><code>array</code></td><td>Publics visés (ex: "Tous publics")</td></tr><tr><td><code>description</code></td><td><code>string</code></td><td>Description de l'association</td></tr><tr><td><code>url</code></td><td><code>string</code></td><td>URL du site de l'association</td></tr><tr><td><code>facebook</code></td><td><code>string</code></td><td>URL facebook de l'association</td></tr><tr><td><code>twitter</code></td><td><code>string</code></td><td>URL twitter de l'association</td></tr><tr><td><code>linkedin</code></td><td><code>string</code></td><td>URL linkedin de l'association</td></tr><tr><td><code>logo</code></td><td><code>string</code></td><td>URL du logo (JPEG, PNG) de l'association</td></tr></tbody></table>

{% tabs %}
{% tab title="200 OK" %}

```
{
  "ok": true,
  "data": {
    "rna": "W061003010",
    "name": "CENTRE EUROPEEN DE FORMATION AUX METIERS...",
    "regime": "loi1901",
    "theme": "Sport",
    "famille": "Sports, activités de plein air ",
    "domaines": [
      "test"
    ],
    "statut_juridique": "test",
    "publics_beneficiaires": [
      "test"
    ],
    "coordonnees": {
      "adresse_siege": {
        "num_voie": "50",
        "code_type_voie": "RTE",
        "type_voie": "route",
        "code_type_voie_insee": "RTE",
        "voie": "de Cannes",
        "cp": "06130",
        "commune": "Grasse"
      },
      "adresse_publique": {
        "latitude_longitude": {
          "lat": 43.6438108,
          "lon": 6.9427333
        },
        "voie": "50 route de Cannes",
        "cp": "06130",
        "commune": "Grasse",
        "departement": "75"
      },
      "telephone": "0102030405",
      "courriel": "test@example.org"
    },
    "objet": "formation et préformation aux métiers de la...",
    "logo": "http://logo.fr"
  }
}
```

{% endtab %}

{% tab title="400 Bad Request" %}

```
{
  "ok": false,
  "code": "INVALID_PARAMS"
}
```

{% endtab %}

{% tab title="404 Not Found" %}

```
{
  "ok": false,
  "code": "NOT_FOUND"
}
```

{% endtab %}
{% endtabs %}

## Liste des établissement d'une association

<mark style="color:blue;">`GET`</mark> `https://api.api-engagement.beta.gouv.fr/v1/association/:idRna`

Lister les établissements d'une association

#### Path Parameters

| Name    | Type     | Description |
| ------- | -------- | ----------- |
| `idRna` | `string` | ID RNA      |

#### Headers

<table><thead><tr><th width="191">Name</th><th width="138">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>apikey</code> <mark style="color:red;">requis</mark></td><td><code>string</code></td><td>La clé API <strong>nécessaire à l’authentification</strong>.</td></tr></tbody></table>

{% tabs %}
{% tab title="200 OK" %}

```
{
  "ok": true,
  "data": [
    {
      "_id": "5f9bed4d1087da3c1bae6cda",
      "rna": "W442016188",
      "name": "L'IMAGE A UN SENS",
      "regime": "loi1901",
      "theme": "Culture",
      "famille": "culture, pratiques d'activités artistiques, culturelles ",
      "est_etablissement_secondaire": false,
      "coordonnees": {
        "adresse": {
          "location": {
            "lon": -1.563556,
            "lat": 47.187578
          },
          "nom_complet": "29 Rue Etienne Lemerle 44400 Rezé",
          "nom": "29 Rue Etienne Lemerle",
          "code_postal": "44400",
          "code_insee": "44143",
          "rue": "Rue Etienne Lemerle",
          "numero": "29",
          "commune": "Rezé",
          "commune_ancienne": "",
          "contexte": "44, Loire-Atlantique, Pays de la Loire",
          "departement_numero": "44",
          "departement": "Loire-Atlantique",
          "region": "Pays de la Loire",
          "type": "housenumber"
        },
        "telephone": [
          "0683527271"
        ],
        "courriel": []
      },
      "objet": "soutenir, créer et produire des films cinéma (courts-métrages, documentaires, etc.) pour favoriser et encourager une culture de l'image pour tous"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Obtenir un établissement

<mark style="color:blue;">`GET`</mark> `https://api.api-engagement.beta.gouv.fr/v1/association/:idRna/etablissement/:id`

Obtenir les infos sur un établissement en particulier

#### Path Parameters

| Name    | Type     | Description                    |
| ------- | -------- | ------------------------------ |
| `idRna` | `string` | Identifiant de l'association   |
| `id`    | `string` | Identifiant de l'établissement |

#### Headers

<table><thead><tr><th width="185">Name</th><th width="108">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>apikey</code> <mark style="color:red;">requis</mark></td><td><code>string</code></td><td>La clé API <strong>nécessaire à l’authentification</strong>.</td></tr></tbody></table>

{% tabs %}
{% tab title="200 OK" %}

```
{
  "ok": true,
  "data": {
    "_id": "5f974d1e37e975042c8a8434",
    "rna": "W011001103",
    "name": "LA PLATE-FORME - COMITE DE PROMOTION DE LA REGION D'AMBERIEU EN BUGEY POUR L'IMPLANTATION D'UNE PLATE-FORME DE FERROUTAGE",
    "regime": "loi1901",
    "theme": "Economie et développement local",
    "famille": "représentation, promotion et défense d'intérêts économiques ",
    "est_etablissement_secondaire": false,
    "coordonnees": {
      "adresse": {
        "location": {
          "lon": 5.36516,
          "lat": 45.959083
        },
        "nom_complet": "Ambérieu-en-Bugey",
        "nom": "Ambérieu-en-Bugey",
        "code_postal": "01500",
        "code_insee": "01004",
        "rue": "",
        "numero": "",
        "commune": "Ambérieu-en-Bugey",
        "commune_ancienne": "",
        "contexte": "01, Ain, Auvergne-Rhône-Alpes",
        "departement_numero": "01",
        "departement": "Ain",
        "region": "Auvergne-Rhône-Alpes",
        "type": "municipality"
      },
      "telephone": [],
      "courriel": []
    },
    "objet": "comité de promotion de la région d'Ambérieu en Bugey pour l'implantation d'une plate-forme de ferroutage ; échange et diffusion d'informations, promotion et valorisation des atouts locaux, soutien à la multimodalité"
  }
}
```

{% endtab %}
{% endtabs %}

## Liste des champs d'un établissement

Les différentes routes renvoient les informations suivantes (elles peuvent être manquantes quand elles ne sont pas renseignées)

| `_id`                   | Identifiant de l'établissement                                                                |
| ----------------------- | --------------------------------------------------------------------------------------------- |
| `rna`                   | Identifiant RNA                                                                               |
| `name`                  | Nom de l'association                                                                          |
| `regime`                | Exemple : "loi1901"                                                                           |
| `theme`                 | Exemple : "Sport", "Environnement et patrimoine", "Loisirs et vie sociale"                    |
| `famille`               | Exemple : "préservation du patrimoine", "Sports, activités de plein air"                      |
| `commune`               | Exemple: "Nantes", "Paris"                                                                    |
| `objet`                 | Objet de l'association (texte descriptif)                                                     |
| `coordonnees`           | (Objet) Coordonnées de l'association (voir exemples au dessus)                                |
| `logo`                  | URL vers le logo de l'association (PNG, JPEG)                                                 |
| `url`                   | URL vers le site de l'association                                                             |
| `linkedin`              | URL vers la page linkedIn de l'association                                                    |
| `facebook`              | URL vers la page facebook de l'association                                                    |
| `twitter`               | URL vers la page twitter de l'association                                                     |
| `donation`              | URL vers le site de donation                                                                  |
| `domaines`              | Liste des domaines de l'association (ex: "Protection de la nature", "Mémoire et citoyenneté") |
| `publics_beneficiaires` | Publics visés (ex: "Tous publics")                                                            |
| `statut_juridique`      | Statut juridique                                                                              |
| `description`           | Description de l'association                                                                  |
| `score`                 | Score (uniquement dans le cas d'une recherche)                                                |


# Éléments de design "Vignettes" par domaine de mission

L'API Engagement met à disposition une bibliothèque d'images, pouvant être utilisées pour la diffusion de missions d'engagement via API sur votre site.

*<mark style="background-color:blue;">Bibliothèque d'images disponible fin février 2025</mark>*

NB : Dans la bibliothèque, les images sont numérotées de 1 à 8 suivant les domaines de missions. Veillez à faire correspondre les images et leurs thématiques en cas d'utilisation.

1. Éducation
2. Santé
3. Environnement
4. Solidarité et Insertion
5. Sport
6. Mémoire et Citoyenneté
7. Coopération Internationale
8. Culture et Loisirs


# Traitement des données utilisateurs

⚠️ **La demande de consentement n'est pas nécessaire pour le tracker de l'API Engagement** ⚠️

Le but du script de tracking de candidature de l'API Engagement est de suivre la performance des redirections. Elle se fait sans collecter de données personnelles ou d'informations personnellement identifiables (PII) tout en respectant la vie privée des visiteurs du site.

Voici ci-dessous les éléments qui permettent de le justifier :

## Ce que nous collectons et dans quel but nous l'utilisons

Nous ne suivons pas les personnes sur leurs appareils ni sur les sites web ou applications qu'ils visitent. Toutes les données sont isolées sur 30 jours, pour un seul site web et un seul appareil. Il n'y a aucun moyen de savoir si la même personne visite un même site à partir de plusieurs appareils, ou si elle visite un autre site web.

Le but est de mesurer le nombre de redirections et le nombre de candidatures associées.

Nous stockons un identifiant qui contient le site web de départ, le site web d'arrivée et la mission.&#x20;

\
Ce que dit la loi&#x20;
-----------------------

Afin de se limiter à ce qui est strictement nécessaire à la fourniture du service et être ainsi exemptés de consentement conformément à l’article 82 de la loi Informatique et Libertés, ces traceurs doivent:

* ✅ avoir une finalité strictement limitée à la seule mesure de l’audience du site ou de l’application (mesure des performances, détection de problèmes de navigation, optimisation des performances techniques ou de son ergonomie, estimation de la puissance des serveurs nécessaires, analyse des contenus consulté), pour le compte exclusif de l’éditeur.&#x20;
* ✅ servir à produire des données statistiques anonymes uniquement.

\
**À l’inverse, pour être exemptés de consentement, ces traceurs ne doivent pas :**

* ✅ conduire à un recoupement des données avec d’autres traitements ou à ce que les données soient transmises à des tiers; \
  *Note de l'API Engagement : Nous nous interdisons de partager les statistiques fines de redirections qui permettraient de regrouper les informations*
* ✅ ne pas permettre le suivi global de la navigation de la personne utilisant différentes applications ou naviguant sur différents sites web.&#x20;

  *Note de l'API Engagement : Nous ne trackons QUE sur le site qui reçoit le trafic et pas sur le site qui transfère le trafic . Nous ne trackons PAS les mêmes personnes sur plusieurs sites. Le cookie est limité au site où le script est installé.*

Toute solution utilisant un même identifiant à travers plusieurs sites (via par exemple des cookies déposés sur un domaine tiers chargé par plusieurs sites) pour croiser, dédoubler ou mesurer un taux de couverture (« reach ») unifié d’un contenu est exclue.&#x20;

## Les recommandations de la CNIL&#x20;

Afin de mettre en place des solutions respectueuses des droits des personnes, la CNIL recommande également que :

* ✅ **les utilisateurs soient informés** de la mise en œuvre de ces traceurs, par exemple via la politique de confidentialité du site ou de l’application mobile ;
* ✅ **la durée de vie des traceurs soit limitée** à une durée permettant une comparaison pertinente des audiences dans le temps, comme c’est le cas d’une durée de treize mois, et qu’elle ne soit pas prorogée automatiquement lors des nouvelles visites ;
* ✅ les informations collectées par l’intermédiaire de ces traceurs soient conservées pour une **durée maximale de vingt-cinq mois** ; les durées de vie et de conservation ci-dessus mentionnées fassent l’objet d’un **réexamen périodique** afin d’être limitées au strict nécessaire.
* Un sous-traitant peut fournir un service de mesure d’audience comparatif à de multiples éditeurs si :&#x20;

  ✅ les données sont collectées, traitées et stockées de manière indépendante pour chaque éditeur ;

  ✅ et que les traceurs sont **totalement indépendants les uns des autres et de tout autre traceur**.&#x20;

Sources : \
<https://www.cnil.fr/fr/cookies-solutions-pour-les-outils-de-mesure-daudience><https://www.cnil.fr/fr/cookies-et-traceurs-que-dit-la-loi>\
<https://beta.gouv.fr/suivi/>\
<https://www.cnil.fr/fr/cookies-solutions-pour-les-outils-de-mesure-daudience>

Vous pouvez également visiter notre **page présentant notre** [**politique de confidentialité**](https://api-engagement.beta.gouv.fr/politique-de-confidentialite/) pour en savoir plus.


# Introduction

Présentation de l'API Engagement et de ses cas d'usage

L'API Engagement permet aux organisations partenaires de **publier et diffuser des missions bénévoles et civiques** sur la plateforme [api.api-engagement.beta.gouv.fr](https://api.api-engagement.beta.gouv.fr).

## À qui s'adresse cette API ?

L'API s'adresse à deux types de partenaires :

**Partenaires annonceurs** — organisations qui créent et gèrent des missions bénévoles. Ils utilisent l'API pour :

* Publier et mettre à jour leurs missions
* Supprimer des missions expirées
* Suivre l'engagement généré (clics, candidatures)

**Partenaires diffuseurs** — plateformes qui affichent des missions issues de l'API Engagement à leurs utilisateurs. Ils utilisent l'API pour :

* Rechercher et filtrer des missions par localisation, domaine, organisation
* Récupérer le détail d'une mission
* Consulter les organisations et les partenaires disponibles

## URL de base

### Production

```
https://api.api-engagement.beta.gouv.fr
```

### Bac à sable

Un environnement bac à sable est disponible pour vous permettre de tester votre intégration avec des jeux de données de test. Rapprochez-vous de votre chargé de déploiement pour en demander l'accès.

```
https://api.bac-a-sable.api-engagement.beta.gouv.fr
```

Toutes les requêtes doivent utiliser HTTPS.

## Spec OpenAPI

La spécification complète de l'API est disponible au format OpenAPI 3.0 :

```
https://raw.githubusercontent.com/betagouv/api-engagement/main/api/docs/openapi.yaml
```

Vous pouvez l'importer directement dans [Postman](https://learning.postman.com/docs/integrations/available-integrations/working-with-openAPI/), [Insomnia](https://docs.insomnia.rest/insomnia/import-export-data) ou tout autre client HTTP compatible OpenAPI.

## Authentification

Tous les endpoints nécessitent une clé API. Consultez la section [Authentification](/api-reference/authentification) pour les détails.


# Authentification

Comment utiliser votre clé API pour authentifier vos requêtes

L'API Engagement utilise des **clés API** pour authentifier les requêtes. Chaque partenaire dispose d'une clé unique associée à son compte.

## Utilisation

Transmettez votre clé API dans le header HTTP `x-api-key` à chaque requête :

```http
GET /v0/mission HTTP/1.1
Host: api.api-engagement.beta.gouv.fr
x-api-key: votre-clé-api
```

Exemple avec cURL :

```bash
curl https://api.api-engagement.beta.gouv.fr/v0/mission \
  -H "x-api-key: votre-clé-api"
```

## Obtenir une clé API

> **La création d'une clé API nécessite l'aide d'un chargé de déploiement** avec qui vous êtes en contact. Cette personne pourra générer cette clé pour vous depuis le tableau de bord.

Une fois obtenue, votre clé est consultable et gérable depuis votre tableau de bord partenaire.

## Sécurité

Votre clé API confère un accès complet à votre compte partenaire. Prenez les précautions suivantes :

* Ne partagez jamais votre clé dans un dépôt Git public
* Ne l'exposez pas dans du code côté client (JavaScript navigateur, application mobile)
* Stockez-la dans une variable d'environnement côté serveur
* En cas de compromission, contactez votre chargé de déploiement pour la renouveler

## Réponse en cas d'erreur

Si la clé est absente ou invalide, l'API retourne :

```http
HTTP/1.1 401 Unauthorized
```

```json
{
  "ok": false,
  "code": "UNAUTHORIZED",
  "message": "Unauthorized"
}
```


# Erreurs

Format des erreurs et liste des codes retournés par l'API

## Format standard

Toutes les erreurs retournent un objet JSON avec la structure suivante :

```json
{
  "ok": false,
  "code": "ERROR_CODE",
  "message": "Description lisible de l'erreur"
}
```

## Codes d'erreur

| Code                      | HTTP | Description                                                                        |
| ------------------------- | ---- | ---------------------------------------------------------------------------------- |
| `INVALID_BODY`            | 400  | Corps de requête invalide — champ manquant, mauvais type ou valeur hors contrainte |
| `INVALID_PARAMS`          | 400  | Paramètre de chemin invalide (ex. : identifiant mal formé)                         |
| `INVALID_QUERY`           | 400  | Paramètre de query invalide                                                        |
| `NOT_FOUND`               | 404  | Ressource introuvable                                                              |
| `RESSOURCE_ALREADY_EXIST` | 409  | Conflit — une mission avec ce `clientId` existe déjà                               |
| `NO_PARTNER`              | 400  | Aucun partenaire diffuseur configuré pour cette clé API                            |
| `UNAUTHORIZED`            | 401  | Clé API absente ou invalide                                                        |
| `TOO_MANY_REQUESTS`       | 429  | Limite de débit atteinte                                                           |

## Limite de débit (rate limiting)

L'API autorise **600 requêtes par fenêtre de 60 secondes**, identifiées par votre clé API.

En cas de dépassement, l'API retourne un `429 Too Many Requests`. Les headers de réponse indiquent l'état de votre quota :

| Header                  | Description                                          |
| ----------------------- | ---------------------------------------------------- |
| `X-RateLimit-Limit`     | Nombre maximum de requêtes autorisées sur la fenêtre |
| `X-RateLimit-Remaining` | Requêtes restantes sur la fenêtre en cours           |
| `X-RateLimit-Reset`     | Timestamp Unix de réinitialisation du compteur       |

## Erreurs de validation

Pour les erreurs `INVALID_BODY`, le champ `message` précise le ou les champs en cause :

```json
{
  "ok": false,
  "code": "INVALID_BODY",
  "message": "\"title\" is required"
}
```


# Mock offline

Mock local de l'API publique pour les recettes partenaires hors internet

Une archive Mockoon est disponible pour les partenaires qui doivent tester leur integration dans un environnement deconnecte d'internet.

Elle contient un mock local de l'API publique, les fichiers necessaires au lancement Docker, un smoke test et la specification OpenAPI.

## Telechargement

La derniere archive est publiee avec les releases GitHub :

```
https://github.com/betagouv/api-engagement/releases/latest/download/api-engagement-latest.tar.gz
```

Chaque release conserve son propre artefact. Le nom de fichier reste donc stable pour faciliter le telechargement de la derniere version.

## Contrat API

Le contrat detaille des endpoints, schemas et erreurs reste documente dans cette documentation et dans la specification OpenAPI :

```
https://raw.githubusercontent.com/betagouv/api-engagement/main/api/docs/openapi.yaml
```

L'archive inclut egalement ce fichier sous `mockoon/docs/openapi.yaml`.

## Installation

Les instructions d'installation offline sont dans le README inclus dans l'archive.


# Créer / mettre à jour une mission

Crée une nouvelle mission ou met à jour une mission existante via son identifiant client.

{% openapi src="/files/8nuP0Yp800kRTnhVUcMa" path="/v2/mission" method="post" expanded="true" %}
[openapi.yaml](https://852608284-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FubkRP59ZFCzK5T16bZo1%2Fuploads%2Fgit-blob-26a88e25a079e0899ab8f6c916244cec2aef5121%2Fopenapi.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/8nuP0Yp800kRTnhVUcMa" path="/v2/mission/{clientId}" method="put" expanded="true" %}
[openapi.yaml](https://852608284-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FubkRP59ZFCzK5T16bZo1%2Fuploads%2Fgit-blob-26a88e25a079e0899ab8f6c916244cec2aef5121%2Fopenapi.yaml?alt=media)
{% endopenapi %}


# Supprimer une mission

Supprime une mission à partir de son identifiant client.

{% openapi src="/files/8nuP0Yp800kRTnhVUcMa" path="/v2/mission/{clientId}" method="delete" expanded="true" %}
[openapi.yaml](https://852608284-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FubkRP59ZFCzK5T16bZo1%2Fuploads%2Fgit-blob-26a88e25a079e0899ab8f6c916244cec2aef5121%2Fopenapi.yaml?alt=media)
{% endopenapi %}


# Récupérer des missions

Récupérer toutes les missions de vos partenaires avec des filtres précis.

{% openapi src="/files/8nuP0Yp800kRTnhVUcMa" path="/v0/mission" method="get" expanded="true" %}
[openapi.yaml](https://852608284-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FubkRP59ZFCzK5T16bZo1%2Fuploads%2Fgit-blob-26a88e25a079e0899ab8f6c916244cec2aef5121%2Fopenapi.yaml?alt=media)
{% endopenapi %}


# Rechercher dans les missions

Rechercher dans les missions de vos partenaires avec des filtres précis. A noter que vous récupérez des facets sur certains champs.

{% openapi src="/files/8nuP0Yp800kRTnhVUcMa" path="/v0/mission/search" method="get" expanded="true" %}
[openapi.yaml](https://852608284-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FubkRP59ZFCzK5T16bZo1%2Fuploads%2Fgit-blob-26a88e25a079e0899ab8f6c916244cec2aef5121%2Fopenapi.yaml?alt=media)
{% endopenapi %}


# Récupérer une mission par identifiant

Récupère le détail d'une mission à partir de son identifiant unique.

{% openapi src="/files/8nuP0Yp800kRTnhVUcMa" path="/v0/mission/{id}" method="get" expanded="true" %}
[openapi.yaml](https://852608284-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FubkRP59ZFCzK5T16bZo1%2Fuploads%2Fgit-blob-26a88e25a079e0899ab8f6c916244cec2aef5121%2Fopenapi.yaml?alt=media)
{% endopenapi %}


# Récupérer vos missions

Récupérer l’ensemble de vos missions disponibles via l’API Engagement.

{% openapi src="/files/8nuP0Yp800kRTnhVUcMa" path="/v0/mymission" method="get" expanded="true" %}
[openapi.yaml](https://852608284-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FubkRP59ZFCzK5T16bZo1%2Fuploads%2Fgit-blob-26a88e25a079e0899ab8f6c916244cec2aef5121%2Fopenapi.yaml?alt=media)
{% endopenapi %}


# Récupérer votre mission par identifiant

Récupérer les données de la mission correspondant à l’identifiant fourni en paramètre, avec un champ "stats" indiquant le nombre de candidatures et de redirections générées.

{% openapi src="/files/8nuP0Yp800kRTnhVUcMa" path="/v0/mymission/{clientId}" method="get" expanded="true" %}
[openapi.yaml](https://852608284-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FubkRP59ZFCzK5T16bZo1%2Fuploads%2Fgit-blob-26a88e25a079e0899ab8f6c916244cec2aef5121%2Fopenapi.yaml?alt=media)
{% endopenapi %}


# Récupérer les statistiques d'une mission

Récupérer uniquement les statistiques d’une mission, incluant le nombre de candidatures et de redirections, sans inclure les données de la mission.

{% openapi src="/files/8nuP0Yp800kRTnhVUcMa" path="/v0/mymission/{clientId}/stats" method="get" expanded="true" %}
[openapi.yaml](https://852608284-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FubkRP59ZFCzK5T16bZo1%2Fuploads%2Fgit-blob-26a88e25a079e0899ab8f6c916244cec2aef5121%2Fopenapi.yaml?alt=media)
{% endopenapi %}


# Qualifier une candidature

Déclare ou met à jour une activité (impression, clic, candidature) associée à une mission.

{% openapi src="/files/8nuP0Yp800kRTnhVUcMa" path="/v2/activity" method="post" expanded="true" %}
[openapi.yaml](https://852608284-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FubkRP59ZFCzK5T16bZo1%2Fuploads%2Fgit-blob-26a88e25a079e0899ab8f6c916244cec2aef5121%2Fopenapi.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/8nuP0Yp800kRTnhVUcMa" path="/v2/activity/{id}" method="put" expanded="true" %}
[openapi.yaml](https://852608284-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FubkRP59ZFCzK5T16bZo1%2Fuploads%2Fgit-blob-26a88e25a079e0899ab8f6c916244cec2aef5121%2Fopenapi.yaml?alt=media)
{% endopenapi %}


# Récupérer la liste des partenaires diffuseurs

Récupérer la liste de l'ensemble des partenaires qui diffusent vos missions et redirigent du traffic vers votre site.

{% openapi src="/files/8nuP0Yp800kRTnhVUcMa" path="/v0/publisher" method="get" expanded="true" %}
[openapi.yaml](https://852608284-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FubkRP59ZFCzK5T16bZo1%2Fuploads%2Fgit-blob-26a88e25a079e0899ab8f6c916244cec2aef5121%2Fopenapi.yaml?alt=media)
{% endopenapi %}


# Récupérer un partenaire diffuseur

Récupère les informations détaillées d'un partenaire diffuseur à partir de son identifiant.

{% openapi src="/files/8nuP0Yp800kRTnhVUcMa" path="/v0/publisher/{id}" method="get" expanded="true" %}
[openapi.yaml](https://852608284-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FubkRP59ZFCzK5T16bZo1%2Fuploads%2Fgit-blob-26a88e25a079e0899ab8f6c916244cec2aef5121%2Fopenapi.yaml?alt=media)
{% endopenapi %}


# Comprendre les règles de diffusion

Comprendre le fonctionnement des règles de diffusion entre annonceurs et diffuseurs.

## Le principe

En tant que **partenaire annonceur**, vos missions sont diffusées vers les **partenaires diffuseurs** associés à votre compte. Par défaut, **toutes vos missions sont diffusées vers tous vos diffuseurs**.

Les règles de diffusion vous permettent de restreindre ce comportement : pour chaque diffuseur, vous pouvez définir des conditions que vos missions doivent respecter pour lui être diffusées.

```mermaid
flowchart LR
    A["Annonceur<br/>(vos missions)"] --> API["API Engagement<br/>(évaluation des règles)"]
    API -->|"aucune règle"| D1["Diffuseur A<br/>reçoit toutes vos missions"]
    API -->|"type is_not benevolat"| D2["Diffuseur B<br/>reçoit uniquement vos missions<br/>qui ne sont pas du bénévolat"]
    API -->|"parentOrganizations<br/>does_not_contain Marine nationale"| D3["Diffuseur C<br/>ne reçoit pas les missions<br/>du réseau Marine nationale"]
```

Les règles s'appliquent au moment où le diffuseur récupère les missions via l'API : une mission qui ne respecte pas les règles n'apparaît tout simplement pas dans ses résultats.

## Anatomie d'une règle

Une règle de diffusion compare un **champ** de la mission à une **valeur**, via un **opérateur** :

```json
{
  "publisherIds": ["5f5931496c7ea514150a818f"],
  "field": "type",
  "operator": "is_not",
  "value": "benevolat"
}
```

Cette règle se lit : « Diffuseur les missions à ce diffuseur (`5f5931496c7ea514150a818f`) qui `ne sont pas` de `type` `benevolat` ».

### Combinaison des règles

Lorsque plusieurs règles sont configurées pour un même diffuseur, une mission doit **toutes** les satisfaire pour être diffusée (combinaison en `ET`) :

```mermaid
flowchart TD
    M["Mission de l'annonceur"] --> R1{"Règle 1<br/>satisfaite ?"}
    R1 -->|non| KO["Mission non diffusée<br/>vers ce diffuseur"]
    R1 -->|oui| R2{"Règle 2<br/>satisfaite ?"}
    R2 -->|non| KO
    R2 -->|oui| OK["Mission diffusée<br/>vers ce diffuseur"]
```

Les règles sont définies **par diffuseur** : une règle créée pour le diffuseur A n'a aucun effet sur le diffuseur B. Le endpoint de création accepte cependant plusieurs `publisherIds` pour appliquer la même règle à plusieurs diffuseurs en un seul appel.

## Les champs disponibles (`field`)

| Champ                                       | Description                                                                                                     | Exemple de valeur                          |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `type`                                      | Type de la mission                                                                                              | `benevolat`, `volontariat_service_civique` |
| `publisherOrganizationId`                   | Identifiant API Engagement de l'organisation porteuse de la mission                                             | `9b1c2d3e-4f56-7890-abcd-ef0123456789`     |
| `publisherOrganization.clientId`            | Identifiant de l'organisation dans **votre** système (celui que vous transmettez à la création de vos missions) | `12345`                                    |
| `publisherOrganization.parentOrganizations` | Réseaux / organisations parentes de l'organisation porteuse (champ **tableau**)                                 | `Marine nationale`                         |

## Les opérateurs (`operator`)

| Opérateur          | La mission est diffusée si…                                  |
| ------------------ | ------------------------------------------------------------ |
| `is`               | le champ est égal à la valeur                                |
| `is_not`           | le champ est différent de la valeur                          |
| `contains`         | le champ contient la valeur (insensible à la casse)          |
| `does_not_contain` | le champ ne contient pas la valeur (insensible à la casse)   |
| `starts_with`      | le champ commence par la valeur (insensible à la casse)      |
| `is_greater_than`  | le champ est strictement supérieur à la valeur               |
| `is_less_than`     | le champ est strictement inférieur à la valeur               |
| `exists`           | le champ est renseigné (la valeur fournie est ignorée)       |
| `does_not_exist`   | le champ n'est pas renseigné (la valeur fournie est ignorée) |

{% hint style="info" %}
**Cas particulier des champs tableau** (`publisherOrganization.parentOrganizations`) : `is` et `contains` testent la **présence exacte** de la valeur dans le tableau (insensible à la casse), `is_not` et `does_not_contain` testent son absence. Il n'y a pas de correspondance par sous-chaîne : `does_not_contain "Marine"` n'exclut pas une mission dont le réseau est `Marine nationale`.
{% endhint %}

## Vérifier si une valeur est diffusée (`field` / `value` et le booléen `diffuse`)

Le endpoint [Lister les règles de diffusion](/api-reference/regles-de-diffusion-diffusion-rule/liste) accepte deux paramètres de requête optionnels, `field` et `value`, à fournir **ensemble** (les deux ou aucun, sinon l'API renvoie une erreur `400`).

Lorsqu'ils sont fournis, chaque diffuseur retourné est annoté d'un booléen `diffuse` qui répond à la question : **« ce diffuseur diffuserait-il une mission portant cette valeur sur ce champ ? »**

```
GET /v0/diffusion-rule?field=publisherOrganization.parentOrganizations&value=Marine nationale
```

```json
{
  "ok": true,
  "total": 2,
  "data": [
    {
      "id": "5f5931496c7ea514150a818f",
      "name": "Diffuseur A",
      "rules": [],
      "diffuse": true
    },
    {
      "id": "60a1b2c3d4e5f6789abc0001",
      "name": "Diffuseur B",
      "rules": [
        {
          "id": "9b1c2d3e-4f56-7890-abcd-ef0123456789",
          "field": "publisherOrganization.parentOrganizations",
          "fieldType": "string",
          "operator": "does_not_contain",
          "value": "Marine nationale"
        }
      ],
      "diffuse": false
    }
  ]
}
```

Le calcul de `diffuse` ne considère que les **règles d'exclusion** portant sur le champ demandé :

* `is_not` : `diffuse` vaut `false` si la valeur recherchée est égale à la valeur de la règle ;
* `does_not_contain` : `diffuse` vaut `false` si la valeur de la règle est contenue dans la valeur recherchée (présence exacte pour les champs tableau) ;
* `does_not_exist` : `diffuse` vaut `false` dès qu'une valeur est recherchée sur ce champ.

Les comparaisons sont insensibles à la casse. S'il n'existe aucune règle d'exclusion sur ce champ pour le diffuseur, `diffuse` vaut `true`.

## Exemples de règles courantes

**Ne pas diffuser les missions de bénévolat vers un diffuseur :**

```json
{ "publisherIds": ["..."], "field": "type", "operator": "is_not", "value": "benevolat" }
```

**Ne diffuser que les missions d'une organisation précise :**

```json
{ "publisherIds": ["..."], "field": "publisherOrganizationId", "operator": "is", "value": "9b1c2d3e-..." }
```

**Exclure les missions d'un réseau (organisations parentes) :**

```json
{ "publisherIds": ["..."], "field": "publisherOrganization.parentOrganizations", "operator": "does_not_contain", "value": "Marine nationale" }
```


# Lister les règles de diffusion

Récupère, pour chacun de vos diffuseurs, les règles de diffusion configurées.

Retourne la liste de vos partenaires diffuseurs, chacun accompagné des règles de diffusion que vous avez configurées pour lui. Un diffuseur sans règle reçoit toutes vos missions (voir [Comprendre les règles de diffusion](/api-reference/regles-de-diffusion-diffusion-rule/diffusion)).

## Paramètres de requête

| Paramètre | Obligatoire | Description                                                                                                                                                                                       |
| --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `field`   | non         | Champ sur lequel évaluer la diffusion : `type`, `publisherOrganizationId`, `publisherOrganization.clientId` ou `publisherOrganization.parentOrganizations`. À fournir conjointement avec `value`. |
| `value`   | non         | Valeur recherchée sur le champ `field`. À fournir conjointement avec `field`.                                                                                                                     |

`field` et `value` vont par paire : fournir l'un sans l'autre renvoie une erreur `400`. Lorsqu'ils sont présents, chaque diffuseur est annoté d'un booléen `diffuse` indiquant s'il diffuserait une mission portant cette valeur sur ce champ — `false` si une de ses règles d'exclusion (`is_not`, `does_not_contain`, `does_not_exist`) sur ce champ exclut la valeur, `true` sinon. Le détail du calcul est décrit dans [Comprendre les règles de diffusion](/api-reference/regles-de-diffusion-diffusion-rule/diffusion).

Exemple — savoir quels diffuseurs excluent le réseau « Marine nationale » :

```
GET /v0/diffusion-rule?field=publisherOrganization.parentOrganizations&value=Marine nationale
```

{% openapi src="/files/8nuP0Yp800kRTnhVUcMa" path="/v0/diffusion-rule" method="get" expanded="true" %}
[openapi.yaml](https://852608284-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FubkRP59ZFCzK5T16bZo1%2Fuploads%2Fgit-blob-26a88e25a079e0899ab8f6c916244cec2aef5121%2Fopenapi.yaml?alt=media)
{% endopenapi %}


# Créer une règle de diffusion

Crée une règle de diffusion appliquée à un ou plusieurs de vos diffuseurs.

Crée une règle de diffusion pour un ou plusieurs de vos partenaires diffuseurs. Une fois la règle créée, seules vos missions qui la satisfont (ainsi que toutes les autres règles déjà configurées pour ce diffuseur) lui sont diffusées. Le fonctionnement général et la liste complète des champs et opérateurs sont décrits dans [Comprendre les règles de diffusion](/api-reference/regles-de-diffusion-diffusion-rule/diffusion).

Vous pouvez récupérer la liste de vos diffuseurs via [Récupérer la liste des partenaires diffuseurs](/api-reference/diffuseur-publisher/liste).

## Corps de la requête

| Champ          | Obligatoire | Description                                                                                                                                                                                                   |
| -------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `publisherIds` | oui         | Identifiants des diffuseurs auxquels appliquer la règle. Seuls les diffuseurs effectivement associés à votre compte sont pris en compte ; si aucun identifiant ne correspond, l'API renvoie une erreur `403`. |
| `field`        | oui         | Champ de la mission évalué par la règle : `type`, `publisherOrganizationId`, `publisherOrganization.clientId` ou `publisherOrganization.parentOrganizations`.                                                 |
| `operator`     | oui         | Opérateur de comparaison : `is`, `is_not`, `contains`, `does_not_contain`, `starts_with`, `is_greater_than`, `is_less_than`, `exists`, `does_not_exist`.                                                      |
| `value`        | oui         | Valeur comparée au champ de la mission (ignorée pour `exists` et `does_not_exist`, mais à fournir tout de même).                                                                                              |
| `fieldType`    | non         | Type de la valeur évaluée (`string` par défaut).                                                                                                                                                              |

Une règle est créée par diffuseur : la réponse contient autant d'entrées que de diffuseurs concernés, chacune avec son propre `id` (à utiliser pour la [suppression](/api-reference/regles-de-diffusion-diffusion-rule/supprimer)).

L'opération est idempotente : si une règle identique (même `field`, `value`, `operator` et `fieldType`) existe déjà pour un diffuseur, la règle existante est retournée plutôt que dupliquée. En revanche, si une règle existe déjà pour le même `field` et la même `value` mais avec un opérateur différent, l'API renvoie une erreur `409`.

Exemple — exclure les missions du réseau « Marine nationale » chez deux diffuseurs :

```json
{
  "publisherIds": ["5f5931496c7ea514150a818f", "60a1b2c3d4e5f6789abc0001"],
  "field": "publisherOrganization.parentOrganizations",
  "operator": "does_not_contain",
  "value": "Marine nationale"
}
```

{% openapi src="/files/8nuP0Yp800kRTnhVUcMa" path="/v0/diffusion-rule" method="post" expanded="true" %}
[openapi.yaml](https://852608284-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FubkRP59ZFCzK5T16bZo1%2Fuploads%2Fgit-blob-26a88e25a079e0899ab8f6c916244cec2aef5121%2Fopenapi.yaml?alt=media)
{% endopenapi %}


# Supprimer une règle de diffusion

Supprime une règle de diffusion rattachée à votre compte annonceur.

Supprime une règle de diffusion que vous avez configurée. Le diffuseur concerné recevra à nouveau les missions que cette règle excluait (sous réserve des autres règles encore en place).

L'identifiant attendu est le `id` de la règle, tel que retourné par la [liste](/api-reference/regles-de-diffusion-diffusion-rule/liste) ou la [création](/api-reference/regles-de-diffusion-diffusion-rule/creer). Seules les règles rattachées à votre compte annonceur peuvent être supprimées : tenter de supprimer la règle d'un autre annonceur renvoie une erreur `403`.

{% openapi src="/files/8nuP0Yp800kRTnhVUcMa" path="/v0/diffusion-rule/{id}" method="delete" expanded="true" %}
[openapi.yaml](https://852608284-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FubkRP59ZFCzK5T16bZo1%2Fuploads%2Fgit-blob-26a88e25a079e0899ab8f6c916244cec2aef5121%2Fopenapi.yaml?alt=media)
{% endopenapi %}


# Récupérer les organisations

Récupérer les informations d'une organisation depuis la base de données centralisée alimentée par l'INSEE et data-subvention, incluant des informations légales sur l'organisation (dont RNA, SIRET).

{% openapi src="/files/8nuP0Yp800kRTnhVUcMa" path="/v0/organization" method="get" expanded="true" %}
[openapi.yaml](https://852608284-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FubkRP59ZFCzK5T16bZo1%2Fuploads%2Fgit-blob-26a88e25a079e0899ab8f6c916244cec2aef5121%2Fopenapi.yaml?alt=media)
{% endopenapi %}