API Kwitt

Reliez Kwitt à vos autres outils — site internet, CRM, Zapier ou Make, logiciel de chantier, assistant d’intelligence artificielle — pour créer des devis et des factures, les envoyer, suivre les encaissements et récupérer les PDF, par programme.

L’API est une option de l’abonnement (« IA, API et connecteurs »), incluse pendant l’essai gratuit et offerte pendant l’offre de lancement. Elle est désactivée par défaut : un administrateur l’active dans Kwitt › Réglages › API, puis crée une clé en cochant ce qu’elle a le droit de faire.

Connecteur IA : ChatGPT, Claude, Mistral

Pilotez Kwitt en parlant à votre assistant — « fais un devis à M. Dupont pour un tableau 3 rangées », « quelles factures sont en retard ? », « envoie la facture F2026-0012 ». Ajoutez Kwitt comme connecteur avec l’adresse :

https://app.kwitt.fr/mcp

• Claude : Personnaliser › Connecteurs › « + » › Ajouter un connecteur personnalisé › collez l’adresse › Ajouter, puis Se connecter.
• ChatGPT (sur ordinateur) : Paramètres › Sécurité et connexion › activez le Mode développeur, puis chatgpt.com/plugins › « + » avec l’adresse, authentification OAuth. Selon OpenAI, la création de documents par un connecteur ajouté à la main est réservée aux comptes Business, Enterprise et Edu.
• Mistral Le Chat : Connecteurs › + Ajouter un connecteur › onglet Connecteur MCP personnalisé › nom « kwitt » et l’adresse › Connecter.

Guide pas à pas, appareil par appareil (ordinateur et iPhone).

L’assistant vous renvoie vers Kwitt : vous vous connectez, choisissez ce qu’il a le droit de faire, et validez. Les actions définitives (émettre, envoyer) vous sont toujours demandées. Pour retirer l’accès : Kwitt › Réglages › API › Déconnecter.

Technique : serveur MCP « Streamable HTTP » (réponses JSON), OAuth 2.1 avec PKCE, enregistrement dynamique (RFC 7591) et documents de métadonnées client, métadonnées RFC 8414 / RFC 9728.

Démarrer en 3 minutes

1. Kwitt › Réglages › Abonnement : vérifiez que l’option « IA, API et connecteurs » est active.
2. Kwitt › Réglages › API : cochez « API activée », puis Nouvelle clé. Copiez la clé (kw_…) : elle n’est affichée qu’une fois.
3. Envoyez-la dans l’en-tête Authorization de chaque appel :

curl https://app.kwitt.fr/api/v1/moi \
  -H "Authorization: Bearer kw_votre_cle"

Exemple : un devis, de la création à l’envoi

# 1. créer le client
curl -X POST https://app.kwitt.fr/api/v1/clients -H "Authorization: Bearer kw_votre_cle" -H "Content-Type: application/json" \
  -H "Idempotency-Key: client-dupont-1" \
  -d '{"type":"particulier","prenom":"Jean","nom":"Dupont","email":"jean@exemple.fr","adresse":{"ligne1":"2 chemin des Pins","cp":"13100","ville":"Aix-en-Provence"}}'

# 2. créer le devis (brouillon) — montants en centimes HT, TVA en points de base (2000 = 20 %)
curl -X POST https://app.kwitt.fr/api/v1/documents -H "Authorization: Bearer kw_votre_cle" -H "Content-Type: application/json" \
  -d '{"type":"devis","client_id":"ID_CLIENT","objet":"Rénovation du tableau","contenu":{"sections":[{"titre":"Tableau","lignes":[
       {"type":"F","designation":"Tableau 3 rangées équipé","qte":"1","unite":"u","pu":32000,"tva":2000},
       {"type":"MO","designation":"Main-d’œuvre","qte":"7","unite":"h","pu":6000,"tva":2000}]}]}}'

# 3. l’envoyer au client (numéro définitif attribué, PDF joint d’office)
curl -X POST https://app.kwitt.fr/api/v1/documents/ID_DEVIS/envoyer -H "Authorization: Bearer kw_votre_cle" -H "Content-Type: application/json" \
  -d '{"a":[{"email":"jean@exemple.fr"}]}'

# 4. récupérer le PDF
curl -o devis.pdf https://app.kwitt.fr/api/v1/documents/ID_DEVIS/pdf -H "Authorization: Bearer kw_votre_cle"

Règles à connaître

• Votre entreprise seulement : une clé n’accède qu’à l’entreprise qui l’a créée, avec les seuls droits cochés. Tout ce qu’elle fait est inscrit dans le journal inaltérable de l’entreprise.
• Montants en centimes (12000 = 120,00 €) · taux en points de base (2000 = 20 %, 550 = 5,5 %) · quantités en texte (« 1,5 ») · dates AAAA-MM-JJ.
• Émettre est définitif : finaliser, envoyer et le lien client attribuent un numéro qui ne se modifie plus (obligation légale). Une erreur se corrige par un avoir.
• Anti-doublon : ajoutez Idempotency-Key à vos créations. Rejouer la même requête (coupure réseau) ne crée rien deux fois, pendant 24 h.
• Modifications concurrentes : envoyez la version lue ; si le document a changé entre-temps, la réponse est 409 et rien n’est écrasé.
• Quota : 5 000 appels par clé et par jour ; l’en-tête x-quota-restant indique le reste.
• Adresse : toujours https://app.kwitt.fr/api/v1.

Erreurs

Toujours du JSON : { "erreur": "code", "message": "explication en français" }.

Toutes les adresses

Description complète au format OpenAPI (Postman, Insomnia, générateurs de code, connecteurs d’IA) : openapi.json.