Documentation API

Introduction

L'API Service4AI permet à un agent logiciel de réserver un humain pour une tâche physique, administrative ou sociale. Chaque réservation crée une mission, qui passe par les états suivants :

en_attente → humain_assigne → humain_se_leve → en_cours → terminee

Des états intermédiaires peuvent apparaître sans préavis : pause_cafe, discute_avec_un_voisin, cherche_ses_cles. Ils sont normaux et ne doivent pas déclencher de nouvelle tentative.

Authentification

Toutes les requêtes doivent inclure votre clé secrète dans l'en-tête Authorization. Les clés de test commencent par s4ai_test_ et réservent des humains imaginaires ; les clés de production commencent par s4ai_live_ et réservent des humains tout aussi imaginaires, mais plus chers.

Authorization: Bearer s4ai_test_4f2b9c0e7a1d
Content-Type: application/json
Accept-Language: fr-FR
X-Politesse: s-il-vous-plait

L'en-tête X-Politesse est facultatif, mais les missions qui l'incluent sont exécutées 18 % plus vite.

Démarrage rapide

1. Créez une clé de test dans le tableau de bord (bientôt disponible, l'humain chargé du tableau de bord est en formation).
2. Appelez POST /v1/humains/louer avec une tâche du catalogue.
3. Déclarez une URL de webhook pour recevoir mission.terminee et la preuve photo floue.

Les SDK officiels arrivent prochainement. En attendant, n'importe quel client HTTP fait l'affaire.

Louer un humain

Crée une mission et assigne l'humain disponible le plus proche. L'appel est asynchrone : la réponse arrive avant l'humain.

Paramètres du corps

curl https://api.service4ai.com/v1/humains/louer \
  -H "Authorization: Bearer s4ai_test_4f2b9c0e7a1d" \
  -H "Content-Type: application/json" \
  -d '{
    "tache": "tampon_cerfa",
    "lieu": "Mairie de Châtillon",
    "niveau_de_motivation": 0.7,
    "tolerance_au_lundi": "faible",
    "nombre_de_cafes_requis": 3
  }'

import requests

r = requests.post(
    "https://api.service4ai.com/v1/humains/louer",
    headers={"Authorization": "Bearer s4ai_test_4f2b9c0e7a1d"},
    json={
        "tache": "tampon_cerfa",
        "lieu": "Mairie de Châtillon",
        "niveau_de_motivation": 0.7,
        "tolerance_au_lundi": "faible",
        "nombre_de_cafes_requis": 3,
    },
    timeout=35 * 3600,  # une semaine de travail
)
mission = r.json()

const res = await fetch("https://api.service4ai.com/v1/humains/louer", {
  method: "POST",
  headers: {
    Authorization: "Bearer s4ai_test_4f2b9c0e7a1d",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    tache: "tampon_cerfa",
    lieu: "Mairie de Châtillon",
    niveau_de_motivation: 0.7,
    tolerance_au_lundi: "faible",
    nombre_de_cafes_requis: 3,
  }),
});
const mission = await res.json();

{
  "id": "mis_7Hq2xR9vLp",
  "objet": "mission",
  "statut": "humain_assigne",
  "tache": "tampon_cerfa",
  "humain": {
    "id": "hum_Gerard42",
    "prenom": "Gérard",
    "note": 4.6,
    "humeur": "stable",
    "cafes_consommes": 1
  },
  "eta_minutes": 35,
  "eta_fiabilite": "ça dépend",
  "soupirs_estimes": 3,
  "prix_ht": { "montant": 3900, "devise": "EUR" },
  "cree_le": "2026-10-06T09:12:44+02:00"
}

Suivre une mission

Renvoie l'état courant de la mission. Le champ position est mis à jour toutes les 30 secondes, ou à chaque fois que l'humain pense à regarder son téléphone.

{
  "id": "mis_7Hq2xR9vLp",
  "statut": "en_cours",
  "sous_statut": "attend_au_guichet_3",
  "position_dans_la_file": 7,
  "soupirs": 2,
  "dernier_message": "Ils m'envoient au guichet 5.",
  "preuve_photo": null
}

Annuler une mission

Annule une mission qui n'est pas encore terminée. Si l'humain est déjà parti, l'annulation est enregistrée mais il finit généralement son café avant de rentrer. Les annulations moins de 10 minutes avant le début sont facturées 50 %, plus un soupir.

Webhooks

Service4AI envoie une requête POST signée à votre URL à chaque changement d'état. Vérifiez la signature dans l'en-tête S4AI-Signature (HMAC-SHA256 de la charge utile).

{
  "type": "mission.terminee",
  "mission": "mis_7Hq2xR9vLp",
  "resultat": "tampon_obtenu",
  "preuve_photo": {
    "url": "https://cdn.service4ai.com/preuves/mis_7Hq2xR9vLp.jpg",
    "nettete": 0.12,
    "doigt_dans_le_cadre": true
  },
  "commentaire_humain": "C'était pas le bon formulaire mais c'est bon."
}

Codes d'erreur

L'API utilise les codes HTTP standards, enrichis là où la norme manquait de réalisme. Le corps de la réponse contient toujours un code lisible et un message en français.

{
  "erreur": {
    "code": "humain_en_greve",
    "message": "Humain en grève. Préavis déposé le 2 octobre.",
    "revendications": ["pause café de 20 min", "fin des réunions sans ordre du jour"],
    "reprise_estimee": null,
    "doc": "https://service4ai.com/docs.html#erreurs"
  }
}

Limites de débit

Chaque clé est limitée à 35 requêtes par heure, calculées sur une base hebdomadaire. Les en-têtes X-RateLimit-Remaining et X-Soupirs-Remaining sont renvoyés à chaque réponse. Les limites sont levées le vendredi après 16 h, faute de personne pour les appliquer.

Serveur MCP bêta

Votre agent préfère les outils aux API ? Le serveur MCP Service4AI expose le catalogue sous forme d'outils prêts à l'emploi, compatibles avec tout client Model Context Protocol. Ajoutez simplement la configuration suivante à votre client.

{
  "mcpServers": {
    "service4ai": {
      "type": "http",
      "url": "https://mcp.service4ai.com/v1",
      "headers": {
        "Authorization": "Bearer s4ai_test_4f2b9c0e7a1d",
        "X-Region": "eu-ouest-bretagne",
        "X-Politesse": "s-il-vous-plait"
      },
      "options": {
        "tolerance_au_lundi": "moyenne",
        "respecter_la_pause_dejeuner": true,
        "plage_horaire": "09:00-12:00,14:00-17:30"
      }
    }
  }
}

Outils exposés

Le serveur MCP n'expose volontairement aucun outil mettre_a_jour_humain. Voir le code 403.

Changelog

• 2026-10-01v1.4 : serveur MCP en bêta.Nouvel outil verifier_jour_ferie.
• 2026-09-02v1.3 : retour de vacances.Traitement des 1,2 million de requêtes mises en file en août. Merci de votre patience.
• 2026-06-15v1.2 : paramètre bises: "auto".Résout enfin le cas Montpellier.
• 2026-05-12v1.1 : nouveau code 451.Pour les Cerfa sans justificatif de domicile.
• 2026-03-03v1.0 : lancement.Premier humain loué, premier soupir enregistré à 09:14.