# Propalix - documentation complète pour agents
API JSON de génération de devis et contrats PDF conformes au droit français.
Base : https://www.propalix.fr - Authentification facultative : en-tête `Authorization: Bearer ppx_...`
## Tiers et quotas
| Tier | Condition | Quota | Filigrane |
|---|---|---|---|
| keyless | aucune clé | 25 documents/jour/IP | oui |
| gratuit | clé API (compte gratuit) | 100 documents/mois | oui |
| pro | 19 €/mois | 2 000 documents/mois | non |
Chaque réponse de génération inclut `X-Propalix-Quota-Restant` et `X-Propalix-Filigrane`.
Quota dépassé → 429 avec `Retry-After` (secondes) et message en français.
Inscription : https://www.propalix.fr/app (magic link, la clé API est affichée à la première connexion).
## POST /v1/devis
Corps JSON :
- `emetteur` (objet, requis sauf si les paramètres du compte le fournissent) :
- `nom` (requis), `adresse` (requis), `code_postal` (requis), `ville` (requis)
- `siren` (9 chiffres) OU `siret` (14 chiffres) - requis, clé de Luhn vérifiée
- `forme_juridique`, `pays` (défaut France), `tva_intracom`, `email`, `telephone`, `logo_url` (https public uniquement)
- `client` (requis) : `nom` (requis), `adresse`, `code_postal`, `ville`, `pays`, `email`, `siren`, `represente_par`
- `prestations` (requis, 1 à 200) : `designation` (requis), `quantite` (défaut 1, max 3 décimales),
`unite`, `prix_unitaire_ht` (requis, euros, max 4 décimales), `taux_tva` (défaut 20 ;
admis : 0, 0.9, 1.05, 1.75, 2.1, 5.5, 8.5, 10, 13, 20)
- `tva_applicable` (défaut true) : false → mention « TVA non applicable, art. 293 B du CGI » (franchise en base)
- `mention_exoneration` : mention légale pour les lignes à taux 0 (ex. « Exonération de TVA, art. 262 ter, I du CGI »)
- `numero` (défaut auto : DEV-AAAAMMJJ-XXXXXXXX), `date_emission` (AAAA-MM-JJ, défaut aujourd'hui),
`duree_validite_jours` (défaut 30), `conditions_paiement` (défaut 30 jours), `notes`
- `hosted` (défaut false) : true → réponse JSON 201 au lieu du PDF binaire
Réponse sans hosted : `200 application/pdf` (en-têtes X-Propalix-Document-Id, X-Propalix-Numero, X-Propalix-Quota-Restant, X-Propalix-Filigrane).
Réponse avec hosted : `201 application/json` :
{"id":"…","numero":"…","url":"https://www.propalix.fr/d/{id}","pdf_url":"https://www.propalix.fr/d/{id}/pdf","statut":"en_attente","expire_le":"AAAA-MM-JJ","filigrane":true}
Le calcul de TVA regroupe par taux sur la base HT cumulée, arrondie au centime.
### Lien hébergé /d/{id}
Page publique : le client final consulte le devis, télécharge le PDF, clique « Bon pour accord »
(nom + email requis). L'acceptation capture nom, email, date, IP, user-agent, appose un cachet
« BON POUR ACCORD » sur le PDF figé, et notifie le webhook du compte si configuré :
POST {webhook_url} {"event":"devis.accepted","devis":{"id","numero","url","pdf_url","total_ttc_cents","client_nom"},"acceptation":{"nom","email","date","ip","user_agent"}}
Le lien expire à la date de validité du devis (acceptation refusée ensuite, 410).
## POST /v1/contrat
Corps JSON :
- `prestataire` : même forme que `emetteur` (pré-rempli par les paramètres du compte)
- `client` : même forme, plus `represente_par` (« Jeanne Dupont, gérante »)
- `objet` (requis) : ex. « la refonte du site vitrine du Client »
- `prestations` : comme le devis
- `tva_applicable`, `mention_exoneration` : comme le devis
- `modalites_paiement` (défaut 30 % signature / solde livraison / virement 30 j)
- `duree` (texte, défaut : jusqu'à complète exécution), `preavis_resiliation_jours` (défaut 15)
- `clauses_custom` (max 20) : [{"titre":"Confidentialité","texte":"…"}] - insérées avant l'article Litiges
- `numero` (défaut CTR-…), `date_signature`, `lieu_signature` (défaut ville du prestataire)
Articles générés : 1 Objet, 2 Prestations, 3 Prix et modalités, 4 Durée, 5 Résiliation,
6 Propriété intellectuelle (cession après complet paiement), clauses custom, N Litiges
(droit français, amiable d'abord), signatures « Lu et approuvé ».
Réponse : `200 application/pdf`.
## POST /v1/pdf
`{"html":"…
"}` ou corps direct avec `Content-Type: text/html` (max 2 Mo) → `200 application/pdf`.
## GET/PUT /v1/parametres (clé API requise)
PUT : tout champ de `emetteur` + `tva_applicable`, `conditions_paiement`, `webhook_url` (https public).
Champ à `null` → effacé. Ces valeurs pré-remplissent devis (emetteur) et contrats (prestataire) ;
les champs envoyés dans la requête gardent la priorité.
## Erreurs
- 400 : JSON illisible / IP indéterminable
- 401 : clé API invalide ou révoquée
- 413 : corps > 2 Mo
- 422 : validation - {"erreur":"…","details":[{"champ":"emetteur.siren","message":"…"}]} en français
- 429 : quota atteint - en-têtes Retry-After et X-Propalix-Quota-Restant: 0
- 502 : rendu PDF ou paiement momentanément indisponible
## Annuaire, préremplissage et carnet de clients
- `GET /v1/entreprises?q=` (sans clé, aucun quota, cache 1 h) : recherche dans l'annuaire officiel de l'État. Réponse `{"resultats":[{"nom","siren","siret_siege","forme_juridique","adresse","code_postal","ville","tva_intracom","activite"}]}`. Les entreprises en non-diffusion INSEE ont leurs champs masqués absents. Sert à préremplir un émetteur ou vérifier un client (3 à 80 caractères).
- `POST /v1/parametres/preremplir` (clé API) : `{"q":"","ecraser":false}` → cherche l'entreprise et enregistre son identité (nom, adresse, SIREN/SIRET, TVA) dans les paramètres émetteur du compte. Par défaut ne réécrit pas les champs déjà remplis (`ecraser:true` pour tout réécrire). Ensuite devis et contrats sont préremplis : plus besoin d'envoyer le bloc émetteur. Pensé pour les agents : configuration en un appel.
- `GET /v1/clients?q=` (clé API) : carnet de clients du compte, alimenté automatiquement à chaque devis/contrat, trié du plus récent au plus ancien, filtrable par `q` pour l'autocomplétion.
## MCP
`npx -y @propalix/mcp` - env : `PROPALIX_API_KEY` (facultatif), `PROPALIX_API_URL` (défaut https://www.propalix.fr).
Installation Claude Code : `claude mcp add propalix -e PROPALIX_API_KEY=ppx_... -- npx -y @propalix/mcp`.
Claude Desktop / Cursor : ajouter à `mcpServers` la commande `npx -y @propalix/mcp`.
Outils :
- `create_devis` : crée un devis PDF conforme et renvoie l'URL publique « Bon pour accord ».
- `create_contrat` : crée un contrat de prestation de services PDF (enregistré localement, chemin renvoyé).
- `rechercher_entreprise` : recherche une entreprise dans l'annuaire officiel (nom, SIREN ou SIRET) → identité complète + TVA intracom.
- `configurer_emetteur` : configure le compte de A à Z en un appel (annuaire → paramètres émetteur) ; ensuite tous les documents sont préremplis. Nécessite `PROPALIX_API_KEY`.
Sans clé : mode keyless (25 documents/jour, filigrane).