# Modes d’intégration

Formerie est conçue comme une plateforme à contrôle progressif. Utilisez l’API
brute de l’environnement d’exécution si vous voulez un contrôle complet, ou passez
aux fonctions utilitaires du SDK, à l’état par framework, aux fonctions de montage
pour le navigateur, aux intégrations et aux pages hébergées si vous préférez que
Formerie prenne en charge une plus grande partie du traitement.

Tous les modes utilisent le même contrat public :

- schéma public du formulaire
- API de validation
- API de soumission
- format des erreurs de validation
- modèle de métadonnées sûres
- configuration de la livraison gérée côté serveur

Vous gardez ainsi une grande liberté de choix, sans qu’il faille créer un
comportement de produit distinct pour chaque style d’intégration.

## Tableau des modes

| Mode | État | Contrôlé par le client | Pris en charge par Formerie |
| --- | --- | --- | --- |
| API brute de l’environnement d’exécution | Disponible | Interface, état, affichage de la validation, style, hooks d’analytique | Schéma public, validation, soumission, livraison côté serveur |
| SDK de base | Disponible | Interface, état, style, hooks d’analytique | Construction des URL, format des requêtes, analyse des réponses, fonctions utilitaires d’erreurs |
| Framework headless | Premiers paquets disponibles | Balisage, composants de champs, style, mise en page, parcours des pages | Fonctions utilitaires d’état par framework et délégation au SDK |
| Fonctions de montage pour le navigateur | Premières fonctions du SDK disponibles | Emplacement du conteneur et CSS | Rendu à partir du schéma public, visibilité, soumission, affichage de la validation |
| Intégration ou formulaire hébergé | Premier environnement d’exécution disponible | Emplacement, domaine, thème de base | Environnement d’exécution, rendu, mises à niveau, soumission, validation, livraison |
| Moteur de rendu stylisé généré | Prévu | Jetons de thème et emplacement du contenu | Interface de formulaire accessible complète, état, soumission, affichage de la validation |
| AI Form Assist | Prévu | Révision par l’utilisateur, consentement, suggestions appliquées | Aide sur les champs, extraction de documents, remplissage conversationnel, suggestions de révision |

## Routes de l’environnement d’exécution

L’hôte par défaut de l’environnement d’exécution est `https://forms.formerie.com` :

```txt
GET  https://forms.formerie.com/{workspaceHandle}/{formHandle}/schema
POST https://forms.formerie.com/{workspaceHandle}/{formHandle}/validate
POST https://forms.formerie.com/{workspaceHandle}/{formHandle}/submit
```

Les noms d’hôte clients liés à un espace de travail utilisent `/{formHandle}/schema`,
`/{formHandle}/validate` et `/{formHandle}/submit`. Les noms d’hôte clients liés à
un formulaire utilisent `/schema`, `/validate` et `/submit`.

L’API de gestion expose aussi des routes compatibles `/v1/{workspaceHandle}/{formHandle}`
sur `https://api.formerie.com`. Les formulaires hébergés, les noms d’hôte clients de
l’environnement d’exécution, les intégrations et les exemples du SDK pour
l’environnement d’exécution devraient utiliser la forme épurée des routes.

## SDK pour le navigateur

Utilisez `@formerie/client` lorsqu’un projet JavaScript ou TypeScript a besoin de
constructeurs d’URL pour l’environnement d’exécution, du chargement du schéma
public, de formats de réponse typés, de fonctions utilitaires de validation et de
fonctions utilitaires de formulaire pour le navigateur, sans exposer la
configuration privée.

```ts
import { FormerieRuntimeClient } from "@formerie/client";

const formerie = new FormerieRuntimeClient();

await formerie.submit("example.com", "contact", {
  fields,
  verificationToken
});
```

Les fonctions de montage pour le navigateur peuvent charger le schéma public,
afficher un formulaire en DOM simple, lier la visibilité, recueillir les champs,
soumettre à l’environnement d’exécution et afficher les erreurs de validation.
L’API de l’environnement d’exécution garde la responsabilité de la validation qui
fait foi, de la vérification, des contrôles de pourriel, de l’acheminement, de la
livraison et de l’acceptation des soumissions.

## Pages hébergées et intégrations

Les pages hébergées et les intégrations utilisent le même contrat de schéma public
et de soumission que l’API brute de l’environnement d’exécution et les fonctions
utilitaires du SDK.

```html
<script src="https://forms.formerie.com/embed.js" data-formerie-form="example/contact"></script>
```

```txt
https://forms.formerie.com/example/contact
https://forms.example.com/contact
https://contact.example.com/
```

## Frontière de sécurité

Les clients publics soumettent seulement les valeurs des champs, les jetons de
vérification et des métadonnées sûres. Les destinataires, les identifiants des
fournisseurs, les gabarits, les règles de livraison, le choix du fournisseur, la
politique de limite de débit et la validation côté serveur restent configurés dans
Formerie.