Documentation

Référence API et MCP

Tout ce qu’il faut pour créer, au nom d’un client final, une demande de devis auprès d’artisans français et en suivre les réponses : l’API REST v1 et le serveur MCP. Pour une présentation courte, voir la page d’introduction.

Vue d’ensemble

Fixou met en relation des particuliers avec des artisans locaux. L’API publique v1 et le serveur MCP permettent à un agent (ChatGPT, Claude, ou tout logiciel autonome) de créer une demande de devis au nom d’un client final, puis d’en suivre le statut et les réponses des artisans.

Point central : une demande créée par cette voie n’est pas publiée immédiatement. Elle naît avec le statut pending_confirmationet le client final reçoit un email « Confirmez votre demande » contenant un lien valable 48 heures. Tant qu’il n’a pas cliqué, aucun artisan n’est contacté (double opt-in). C’est le client, jamais l’agent, qui échange ensuite avec les artisans sur son espace fixou.fr.

Serveur de production : https://fixou.fr
Format d’échange : JSON (Content-Type: application/json).
Langue : les descriptions et messages d’erreur de l’API sont en français.

Le parcours d’un agent

Du besoin exprimé en langage naturel jusqu’aux réponses d’artisans, le chemin passe toujours par une confirmation du client final :

1
L’utilisateur décrit son besoin
Il explique son problème à un LLM (« j’ai une fuite sous mon évier à Marseille »).
2
L’agent prépare la demande
Il appelle list_categories pour trouver le bon métier et son questionnaire, puis create_request avec l’email du client final.
3
Le client confirme par email
Il reçoit « Confirmez votre demande », clique sur le lien (valable 48 h). C’est ce clic qui publie la demande et prévient les artisans du secteur.
4
Le client retrouve tout sur son espace
Le lien le connecte à fixou.fr, où il suit les réponses et échange avec les artisans. L’agent, lui, n’a jamais accès à cet espace.

Pour suivre les réponses, l’agent peut appeler get_request (ou GET /api/v1/requests/{id}) une fois la demande confirmée ; l’API ne renvoie jamais les coordonnées d’un artisan.

Authentification

API REST : clé Bearer

Les endpoints d’écriture et de suivi de l’API REST exigent une clé API, préfixée fixou_sk_, transmise dans l’en-tête HTTP :

Authorization: Bearer fixou_sk_...

Les clés sont distribuées manuellementpar l’équipe Fixou : écrivez à [email protected]. Une clé ne peut consulter que les demandes qu’elle a elle-même créées. Seul GET /api/v1/categories est public (aucune clé).

Serveur MCP : aucune clé côté client

Le serveur MCP ne demande aucune clé : la clé API vit côté serveur Fixou. Un client MCP (Claude, ChatGPT…) se connecte simplement à l’URL du serveur (voir la section MCP).

Référence REST

Trois endpoints, décrits par la spécification OpenAPI 3.1 servie sur /api/v1/openapi.json. Les exemples ci-dessous sont complets et directement exécutables.

GET /api/v1/categories

GET/api/v1/categoriesPublic, sans clé

Retourne tous les métiers, regroupés par famille, avec le questionnaire propre à chaque métier. À appeler avantde créer une demande : le slug d’un métier devient le categorySlug, et son questionnaire indique les questions à couvrir dans answers.

curl https://fixou.fr/api/v1/categories

Réponse (extrait, structure réelle) :

{
  "categories": [
    {
      "familySlug": "travaux-renovation",
      "familyName": "Travaux et rénovation",
      "slug": "plombier",
      "name": "Plombier",
      "questionnaire": [
        {
          "id": "type",
          "label": "De quel type d'intervention avez-vous besoin ?",
          "type": "single",
          "options": [
            { "value": "fuite", "label": "Réparation de fuite" },
            { "value": "installation", "label": "Installation d'un équipement sanitaire" },
            { "value": "debouchage", "label": "Débouchage de canalisation" }
          ]
        },
        {
          "id": "lieu",
          "label": "Où se situe l'intervention ?",
          "type": "single",
          "options": [
            { "value": "cuisine", "label": "Cuisine" },
            { "value": "salle-de-bain", "label": "Salle de bain ou WC" }
          ]
        }
      ]
    }
  ]
}

Chaque question a un type : single attend une seule valeur, multi attend un tableau de valeurs. Les valeurs à renvoyer sont les options.value (jamais les libellés).

POST /api/v1/requests

POST/api/v1/requestsClé requise

Enregistre une demande de devis en attente de confirmation (statut pending_confirmation) : elle n’est pas publiée et aucun artisan n’est contacté à ce stade. Un email de confirmation part vers l’adresse du client final. Le compte client est créé automatiquement à partir de cet email s’il est inconnu, réutilisé sinon.

Corps de la requête

categorySlug (requis) : slug du métier, obtenu via /categories.
answers (requis) : objet indexé par id de question. Une valeur (question single) ou un tableau (question multi), choisies parmi les options.value. Toutes les questions du métier doivent être renseignées.
description(requis) : texte libre en français, de 20 à 5000 caractères.
postalCode(requis) : code postal français du lieu d’intervention (5 chiffres).
email(requis) : adresse du client final ; il y reçoit le lien de confirmation.
phone(optionnel) : téléphone du client final, transmis aux seuls artisans qu’il choisira.

curl -X POST https://fixou.fr/api/v1/requests \
  -H "Authorization: Bearer fixou_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "categorySlug": "plombier",
    "answers": { "type": "fuite", "lieu": "cuisine", "urgence": "urgent" },
    "description": "Fuite sous le lavabo de la cuisine, intervention rapide souhaitee.",
    "postalCode": "13001",
    "email": "[email protected]",
    "phone": "+33612345678"
  }'

Réponse 201 Created :

{
  "requestId": "req_a1b2c3d4",
  "status": "pending_confirmation"
}

Après cet appel, invitez explicitement l’utilisateur à ouvrir sa boîte mail et à cliquer sur le lien de confirmation : sans cela, la demande n’est jamais publiée et expire au bout de 48 heures.

Le statut pending_confirmation et le délai de 48 heures

pending_confirmationsignifie que la demande existe mais reste invisible des artisans. Le lien de l’email « Confirmez votre demande » est valable 48 heures ; le clic la fait passer en published, la transmet aux artisans du secteur et connecte le client à son espace. Sans confirmation sous 48 heures, la demande bascule en expired et n’est jamais transmise.

Codes d’erreur

400 : corps invalide ou incomplet (champ manquant, questionnaire incomplet, code postal inconnu, JSON illisible).
401 : clé API absente, inconnue ou révoquée.
429 : limite de débit atteinte (par clé, ou par adresse email destinataire — voir Limites de débit).

Toute erreur renvoie un objet error en français :

{ "error": "Corps de requête invalide ou incomplet." }

GET /api/v1/requests/{id}

GET/api/v1/requests/{id}Clé requise

Retourne le statut de la demande et, pour chaque réponse reçue, le nom de l’entreprise, le message, le prix indicatif, le délai proposé, le statut de la réponse et la note moyenne de l’artisan. Une clé ne peut consulter que ses propres demandes : toute autre renvoie 404 (jamais 403), pour ne pas confirmer l’existence d’une demande.

curl https://fixou.fr/api/v1/requests/req_a1b2c3d4 \
  -H "Authorization: Bearer fixou_sk_..."

Réponse 200 OK :

{
  "requestId": "req_a1b2c3d4",
  "status": "published",
  "createdAt": "2026-07-21T09:12:00.000Z",
  "responses": [
    {
      "companyName": "Plomberie Durand",
      "message": "Bonjour, je peux intervenir dès demain matin.",
      "priceIndicative": 120,
      "delay": "Sous 24 h",
      "status": "sent",
      "createdAt": "2026-07-21T10:04:00.000Z",
      "artisanAverageRating": 4.7,
      "artisanReviewCount": 23
    }
  ]
}

Champs d’une réponse d’artisan

companyName : nom de l’entreprise.
message : message de l’artisan au client.
priceIndicative : prix indicatif en euros, ou null.
delay : délai proposé (texte libre), ou null.
status : statut de cette réponse — sent, chosen ou declined (à ne pas confondre avec le statut de la demande).
createdAt : date ISO 8601 de la réponse.
artisanAverageRating : note moyenne (1 à 5) de l’artisan, ou null si aucun avis.
artisanReviewCount : nombre d’avis reçus par l’artisan.

Statuts possibles d’une demande

pending_confirmation : créée via l’API/MCP, en attente de confirmation par email (aucun artisan contacté).
published : confirmée, ouverte aux réponses des artisans.
closed : clôturée par le client (qu’il ait choisi un artisan ou non).
expired : fermée automatiquement après inactivité, ou jamais confirmée sous 48 heures.

Codes d’erreur

401 : clé API absente, inconnue ou révoquée.
404 : demande introuvable, ou appartenant à une autre clé.
429 : trop de requêtes pour cette clé.

Limites de débit

Deux limites indépendantes protègent l’API, toutes deux renvoyant 429 :

Par clé API : 60 requêtes par minute (fenêtre fixe), appliquée à POST /requests comme à GET /requests/{id}.
Par adresse email destinataire : au plus 10 demandes par heure vers une même adresse de client final. Ce plafond, vérifié avant toute création, évite qu’un appelant bombarde une boîte mail de liens de confirmation. Au-delà, la demande n’est ni écrite ni envoyée.

{ "error": "Trop de demandes récentes pour cette adresse email, réessayez plus tard." }

Serveur MCP

Le serveur MCP (Model Context Protocol) expose les mêmes capacités que l’API REST, directement intégrables dans un client compatible, sans appel HTTP manuel.

URL : https://mcp.fixou.fr/mcp
Transport : Streamable HTTP, sans état (chaque requête est un POST autonome).
Authentification : aucune. La clé API vit côté serveur.

Les trois outils

list_categories : aucun paramètre. Renvoie les métiers regroupés par famille, avec leurs questionnaires.
create_request : categorySlug, answers, description (min. 20 caractères), postalCode, email (obligatoire, celui du client final), phone (optionnel). Renvoie le requestId et rappelle que le client doit confirmer par email.
get_request : requestId. Renvoie le statut et les réponses des artisans (jamais de coordonnées).

Ajouter le serveur dans Claude

Dans les paramètres de Claude, ajoutez un connecteur personnalisé :

Nom : Fixou
URL du serveur MCP : https://mcp.fixou.fr/mcp

Aucune clé ni identifiant à saisir. Une fois le connecteur ajouté, les outils list_categories, create_request et get_request deviennent disponibles dans la conversation.

Registre officiel

Le serveur est publié au registre officiel MCP sous le nom fr.fixou/fixou (registry.modelcontextprotocol.io) : les clients et annuaires qui ingèrent ce registre peuvent le découvrir automatiquement.

Ressources

Spécification OpenAPI 3.1 : /api/v1/openapi.json
Description pour agents IA : /llms.txt
Introduction : /developpeurs
Obtenir une clé API : [email protected]