10 · apis

Fonctions : préparer vos API métier

Une fonction transforme une URL HTTPS de votre système en outil : l'agent envoie les arguments en JSON, votre API répond en JSON. Préparez une API par action métier plutôt qu'une API fourre-tout.

Déclarez : un nom (verbe_objet), une description (quand l'appeler, quand ne pas l'appeler), le schéma JSON des arguments et l'URL.
L'agent envoie un corps JSON { function, arguments } à votre URL. Méthode, en-têtes (par exemple Authorization) et délai sont configurables.
Dry-run : le bouton d'essai exécute l'appel avec des arguments de test, avant tout rattachement à un bot.
Côté API : répondez en 2xx avec un JSON court et lisible (le modèle lit la réponse, tronquée au-delà de quelques milliers de caractères). Un code hors 2xx est transmis à l'agent sous la forme « Erreur : … » : soignez le message.
Une action qui écrit (annulation, remboursement) doit tolérer un rejeu : prévoyez une clé d'idempotence.
Gateway entreprise : si vos systèmes sont derrière une passerelle, branchez-la une fois dans Intégrations (URL, clé jamais renvoyée par l'API, délai de 5 à 60 s).
Les adresses privées sont bloquées par défaut ; utilisez une URL publique en HTTPS.

Fonction — schéma et réponse de votre API

// Schéma des arguments déclaré dans la fonction
{
  "type": "object",
  "properties": {
    "numero_commande": { "type": "string", "description": "Ex. CMD-2291" }
  },
  "required": ["numero_commande"]
}

// Appel envoyé par l'agent à votre URL HTTPS
POST https://api.votredomaine.com/suivi_commande
{ "function": "suivi_commande", "arguments": { "numero_commande": "CMD-2291" } }

// Réponse attendue : 2xx + JSON court
{ "statut": "en livraison", "livraison_prevue": "demain avant 18 h" }

Tutoriel vidéo associé