Type Request (validation par un service externe)

Le type de question request permet à votre modèle d'appeler un service HTTP externe pour valider la saisie de l'utilisateur et d'utiliser la réponse du service pour pré-remplir d'autres champs du document. Il est destiné aux scénarios où une seule information (un code, un identifiant de référence, un numéro fiscal) permet de retrouver de nombreuses valeurs déjà connues que l'utilisateur ne devrait pas avoir à saisir manuellement.

Quand utiliser `request`

Cas d'usage courants :

Code promotionnel / de réduction : l'utilisateur saisit un code → le service le valide et renvoie le montant de la réduction, la description et la date d'expiration, qui sont automatiquement insérés dans le document.
Recherche par référence ou police : l'utilisateur saisit un numéro de police → le service renvoie le nom, l'adresse et la prime de l'assuré.
Résolution d'identifiant fiscal : l'utilisateur saisit un NIT/RUT → le service renvoie la raison sociale, l'adresse et le représentant.
Recherche de réservation / commande : l'utilisateur saisit une référence de réservation → le service renvoie les dates, les noms des participants et les montants.

Dans tous ces cas, la question request est la saisie directrice, et les autres questions du même modèle deviennent des sorties alimentées par la réponse du service.

Backend requis

Ce type exige que vous (ou votre équipe plateforme) développiez et hébergiez un endpoint HTTP respectant le contrat décrit ci-dessous. Le SDK Auco ne fournit aucun backend par défaut : il se contente d'appeler l'URL que vous configurez.

Structure de la question

{
  "name": "promo_code",
  "description": "Saisissez votre code promotionnel",
  "type": "request",
  "endpoint": "https://your-service.example.com/promo-validate"
}

Propriété	Type	Requis	Description
`name`	string	Requis	Identifiant unique de la question.
`description`	string	Requis	Texte affiché à l'utilisateur décrivant ce qu'il doit saisir.
`type`	string	Requis	Doit être `"request"`.
`endpoint`	string	Requis	URL HTTPS complète à laquelle le SDK enverra une requête POST.

L'interface de saisie de l'utilisateur est un simple champ de texte (comme type: text). Le libellé du bouton passe de « Suivant » à « Valider » afin que l'utilisateur sache que la valeur sera vérifiée auprès d'un service avant de continuer.

HTML correspondant

La question request elle-même utilise un span standard — rien de particulier :

<p>Code promotionnel : <span name="promo_code">___________</span></p>

Les questions qui seront pré-remplies par la réponse utilisent également des spans standard et doivent exister comme questions dans le config JSON afin que le SDK connaisse leurs types :

<p>Montant de la réduction : <span name="discount_amount">___________</span></p>
<p>Description de l'offre : <span name="promo_description">___________</span></p>
<p>Valable jusqu'au : <span name="promo_expiration">___________</span></p>

Contrat de l'endpoint

Requête

Le SDK envoie une requête POST à l'URL endpoint avec un corps JSON.

POST {endpoint}
Content-Type: application/json

{
  "key": "<question_name>",
  "value": "<user_input>"
}

Champ	Type	Description
`key`	string	Le `name` de la question `request` (par ex. `"promo_code"`).
`value`	string	Le texte saisi par l'utilisateur.

Réponse — Succès (HTTP `200`)

Le corps doit être un tableau JSON de paires {key, value}. Chaque paire indique au SDK de renseigner une question du document.

[
  { "key": "discount_amount",   "value": "15000" },
  { "key": "promo_description", "value": "Offre spéciale Black Friday" },
  { "key": "promo_expiration",  "value": "2026-12-31" }
]

Champ	Type	Description
`key`	string	Le `name` de la question du modèle à mettre à jour.
`value`	string	La chaîne à injecter. Pour les types `date`, utilisez le format ISO (`YYYY-MM-DD`). Pour `currency` / `number`, utilisez la chaîne numérique brute.

Ce que fait le SDK avec la réponse :

Pour chaque paire {key, value}, recherche la question dans config par name et définit sa valeur interne.
Pour chaque paire {key, value}, met à jour chaque <span name="{key}"> du document affiché avec value comme innerHTML.
Fait passer l'utilisateur à la question suivante du parcours.

Réponse — Erreur (HTTP `4xx` / `5xx` ou corps qui n'est pas un tableau)

Le SDK affiche le message d'erreur « Código inválido » (« Code invalide ») sous le champ de saisie et empêche l'utilisateur de continuer tant qu'il n'a pas saisi une valeur valide.

Messages d'erreur

Le SDK affiche un message d'erreur générique, quel que soit le code de statut HTTP ou le corps de la réponse. Si vous devez différencier les erreurs (par ex. « code expiré » ou « introuvable »), envisagez de renvoyer un HTTP 200 avec un tableau vide et un champ de statut distinct, ou d'étendre le SDK dans votre intégration.

Exemple complet — Code promotionnel

JSON

{
  "name": "Abonnement avec code promotionnel",
  "preBuild": false,
  "config": [
    {
      "name": "promo_code",
      "description": "Saisissez votre code promotionnel",
      "type": "request",
      "endpoint": "https://api.example.com/promo-validate"
    },
    {
      "name": "promo_description",
      "description": "Description de l'offre",
      "type": "text"
    },
    {
      "name": "discount_amount",
      "description": "Montant de la réduction",
      "type": "currency"
    },
    {
      "name": "promo_expiration",
      "description": "Valable jusqu'au",
      "type": "date"
    },
    {
      "name": "subscriber_name",
      "description": "Saisissez votre nom complet",
      "type": "name"
    },
    {
      "name": "subscriber_email",
      "description": "Saisissez votre adresse e-mail",
      "type": "email"
    }
  ],
  "signatureProfile": [
    {
      "name": "subscriber_name",
      "identification": "subscriber_email",
      "email": "subscriber_email",
      "type": "subscriber"
    }
  ],
  "sign": ["subscriber_name", "subscriber_email"]
}

HTML (extrait)

<h2>Code promotionnel</h2>
<p>Code : <span name="promo_code">___________</span></p>
<p>Offre : <span name="promo_description">___________</span></p>
<p>Réduction : <span name="discount_amount">___________</span></p>
<p>Valable jusqu'au : <span name="promo_expiration">___________</span></p>

Exemple d'implémentation du service (Node.js / Express)

const express = require('express');
const app = express();
app.use(express.json());

const promos = {
  BLACK2026: {
    promo_description: 'Offre spéciale Black Friday',
    discount_amount: '15000',
    promo_expiration: '2026-12-31',
  },
  SPRING10: {
    promo_description: 'Réduction de printemps',
    discount_amount: '5000',
    promo_expiration: '2026-06-30',
  },
};

app.post('/promo-validate', (req, res) => {
  const { value } = req.body;
  const promo = promos[value?.toUpperCase()];

  if (!promo) return res.status(404).json({ message: 'Code introuvable' });

  const response = Object.entries(promo).map(([key, value]) => ({ key, value }));
  res.json(response);
});

app.listen(3000);

Exemple d'implémentation du service (Python / FastAPI)

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

promos = {
    "BLACK2026": {
        "promo_description": "Offre spéciale Black Friday",
        "discount_amount": "15000",
        "promo_expiration": "2026-12-31",
    },
}

class RequestPayload(BaseModel):
    key: str
    value: str

@app.post("/promo-validate")
def validate(payload: RequestPayload):
    promo = promos.get(payload.value.upper())
    if not promo:
        raise HTTPException(status_code=404, detail="Code introuvable")

    return [{"key": k, "value": v} for k, v in promo.items()]

Recommandations de mise en œuvre

Pour les équipes backend qui développent le service

Utilisez HTTPS. Le SDK rejette les endpoints http://.
Activez CORS pour l'origine du SDK Auco — l'appel est effectué depuis le navigateur, et non de serveur à serveur.
Ne renvoyez que des questions existantes dans le config du modèle. Les clés qui ne correspondent à aucune question sont ignorées silencieusement.
Les valeurs sont injectées comme des chaînes sûres pour le HTML. Si vous devez afficher des images ou du balisage, vous devez utiliser un type de question qui le permet (image) et vous assurer que votre valeur est une URI de données valide. Le HTML brut dans value n'est pas assaini par le SDK.
Respectez les types de données. Si une question cible est de type: date, renvoyez YYYY-MM-DD. Si elle est de type: currency, renvoyez le nombre brut sans mise en forme — le SDK s'en chargera.
Ne faites pas confiance au client. Le champ key reprend le nom de la question, mais la logique de validation réelle doit utiliser value. Traitez cet endpoint comme n'importe quel autre endpoint public en matière de limites de débit, d'authentification et d'abus.

Pour les auteurs de modèles

Chaque {key} renvoyée par votre service doit exister comme question dans le config JSON, faute de quoi elle sera ignorée.
Les questions pré-remplies doivent tout de même figurer dans le HTML sous forme d'espaces réservés <span name="{key}">.
Si une question pré-remplie figure aussi dans le tableau sign, l'utilisateur pourra continuer même s'il ne l'a pas saisie lui-même — la valeur fournie par le service compte comme renseignée.
Vous pouvez enchaîner plusieurs questions request dans un même modèle si différentes saisies permettent de renseigner différents champs.

Limitations

Le SDK effectue actuellement la requête depuis le navigateur. Aucune validation côté serveur n'a lieu automatiquement — votre endpoint doit être accessible sur Internet depuis le navigateur de l'utilisateur.
La réponse doit être un tableau plat de paires {key, value}. Les objets imbriqués ne sont pas pris en charge.
Tous les champs value de la réponse sont des chaînes. Les booléens ou les nombres doivent être sérialisés sous forme de chaînes.
Les réponses d'erreur sont affichées de manière générique sous la forme « Código inválido ». Les messages d'erreur détaillés par champ ne sont pas pris en charge.
La question request elle-même n'est pas renvoyée au service dans le cadre du document final — elle ne sert qu'à déclencher la recherche. La saisie de l'utilisateur est stockée dans le value de la question comme n'importe quel autre champ.

Quand utiliser request​

Structure de la question​

HTML correspondant​

Contrat de l'endpoint​

Requête​

Réponse — Succès (HTTP 200)​

Réponse — Erreur (HTTP 4xx / 5xx ou corps qui n'est pas un tableau)​

Exemple complet — Code promotionnel​

JSON​

HTML (extrait)​

Exemple d'implémentation du service (Node.js / Express)​

Exemple d'implémentation du service (Python / FastAPI)​

Recommandations de mise en œuvre​

Pour les équipes backend qui développent le service​

Pour les auteurs de modèles​

Limitations​