Développeurs
Jomi se branche de deux façons : le serveur MCP, pour qu'un assistant IA (Claude…) travaille dans le CRM avec les droits d'un utilisateur, et l'API REST v1, pour relier Jomi à tes autres outils de serveur à serveur. Les deux sont compris dans chaque plan.
| Ressource | Adresse |
|---|---|
| Documentation de l'API | app.thejomi.app/api/docs |
| Spécification OpenAPI 3.1 | app.thejomi.app/openapi.json |
| Serveur MCP | https://app.thejomi.app/api/mcp |
| Guide pour les agents IA | thejomi.app/llms.txt |
| Cette page en Markdown | thejomi.app/developers.md |
Démarrage rapide
Étape 1. Un admin de l'espace crée une clé dans Réglages → API & webhooks et choisit ses scopes. La clé n'est affichée qu'une fois.
Étape 2. Teste la connexion :
curl https://app.thejomi.app/api/v1/me \
-H "Authorization: Bearer crm_live_…"Étape 3. Crée ou mets à jour un contact (idempotent par external_id, sinon par email) :
curl -X POST https://app.thejomi.app/api/v1/contacts \
-H "Authorization: Bearer crm_live_…" \
-H "Content-Type: application/json" \
-d '{"external_id":"form-8812","full_name":"Jeanne Martin","email":"jeanne@example.com","source":"website"}'API REST v1
- Base :
https://app.thejomi.app/api/v1, réponses en JSON, jamais mises en cache. - Authentification :
Authorization: Bearer crm_live_<32 hex>, une clé par organisation. - Scopes :
readpour les lectures (GET),writepour les écritures (POST, PATCH, DELETE). Une clé sans le bon scope reçoit un 403forbidden_scope. - Pagination : par curseur. Suivre
next_cursortant quehas_moreest vrai ;updated_sincesert à la synchronisation incrémentale. - Montants : dans la devise de référence de l'organisation (EUR ou USD) ; un montant saisi dans l'autre devise est converti au taux BCE du jour.
- Ressources : contacts, deals, encaissements, calls, journal d'activités, webhooks. Le détail de chaque opération (paramètres, corps, réponses typées) est dans la documentation et la spécification OpenAPI.
Limites de débit
300 requêtes par minute et par clé, sur une fenêtre fixe d'une minute. Chaque réponse annonce la politique :
RateLimit-Policy: "per-key";q=300;w=60Au-delà, la réponse est un 429 rate_limited avec le délai d'attente en secondes :
RateLimit: "per-key";r=0;t=42
Retry-After: 42Erreurs
Toutes les erreurs ont la même forme, avec un code stable à tester plutôt que le message :
{ "error": { "code": "validation_error: stage", "message": "Valeur « nope » inconnue…", "docs": "https://thejomi.app/developers#erreurs" } }| Statut | Code | Que faire |
|---|---|---|
| 401 | invalid_key | Clé absente, mal formée ou révoquée : en créer une autre. |
| 403 | forbidden_scope | La clé n'a pas le scope write : en créer une avec ce scope. |
| 403 | org_suspended | L'accès de l'organisation est suspendu : contacter le support. |
| 404 | not_found | Ressource absente de ton organisation, ou adresse inconnue. |
| 422 | validation_error: <champ> | Corriger le champ indiqué ; le message liste les valeurs acceptées. |
| 429 | rate_limited | Attendre Retry-After secondes. |
| 500 | internal_error | Réessayer plus tard ; si ça dure, écrire au support. |
Webhooks
Des endpoints sortants reçoivent les événements de l'organisation : contact.created, contact.updated, contact.stage_changed, deal.created, deal.won, deal.lost, payment.recorded, call.scheduled, call.held, call.no_show. Chaque envoi est signé : X-CRM-Signature = sha256=HMAC_SHA256(secret, X-CRM-Timestamp + "." + corps brut). Le secret n'est donné qu'à la création de l'endpoint.
Jomi existe aussi en application privée Zapier et Make (lien d'installation dans Réglages → Intégrations), et reçoit les rendez-vous et paiements de Calendly, Cal.com, iClosed, Stripe et Whop (Réglages → Intégrations).
Serveur MCP
Pour Claude Desktop, Claude Code, claude.ai ou tout client MCP :
- Adresse :
https://app.thejomi.app/api/mcp(transport Streamable HTTP). - Connexion : OAuth 2.1 avec enregistrement dynamique du client. Le client découvre le serveur d'autorisation tout seul (
/.well-known/oauth-protected-resource) ; l'utilisateur se connecte à Jomi et accepte. - Droits : ceux de l'utilisateur connecté, exactement comme dans l'application.
- Outils : 13 en lecture (tableau de bord, pipeline, clients, relances du jour, calls, performance, analyse des calls, transcripts, projection de CA, recherche et fiche d'un contact, ses mails, guide d'écriture) et 8 en écriture (créer un contact, ajouter une note, journaliser un call, changer d'étape, assigner, planifier une relance, marquer une relance faite, enregistrer un encaissement). Aucune suppression.
- Limite : 120 appels par minute.
Le guide pas à pas est dans l'aide : Claude et le serveur MCP.
Versions et dépréciation
- La version est dans l'adresse (
/api/v1). Dans une version, on ne fait que des ajouts : nouveaux champs, nouveaux paramètres facultatifs, nouvelles opérations. Ton code doit ignorer les champs qu'il ne connaît pas. - Un changement qui casserait une intégration (champ retiré ou renommé, comportement modifié) passe par une nouvelle version (
/api/v2). - Avant de retirer une opération ou une version, on prévient au moins 6 mois à l'avance : par mail aux admins des organisations qui l'utilisent, dans les nouveautés, et dans les réponses avec les en-têtes
DeprecationetSunset(RFC 9745 et RFC 8594) et un lienLink: rel="deprecation"vers cette page. - Un champ déprécié reste accepté pendant cette période et est marqué
deprecateddans la spécification OpenAPI (exemple :eur_amount, remplacé parreceived_amount).
Support
Une question, une clé à révoquer, un besoin que l'API ne couvre pas : hello@thejomi.app.