# 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](https://app.thejomi.app/api/docs) |
| Spécification OpenAPI 3.1 | [app.thejomi.app/openapi.json](https://app.thejomi.app/openapi.json) |
| Serveur MCP | `https://app.thejomi.app/api/mcp` |
| Guide pour les agents IA | [thejomi.app/llms.txt](https://thejomi.app/llms.txt) |
| Cette page en Markdown | [thejomi.app/developers.md](https://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 :

```bash
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`) :

```bash
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** : `read` pour les lectures (GET), `write` pour les écritures (POST, PATCH, DELETE). Une clé sans le bon scope reçoit un 403 `forbidden_scope`.
- **Pagination** : par curseur. Suivre `next_cursor` tant que `has_more` est vrai ; `updated_since` sert à 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=60
```

Au-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: 42
```

## Erreurs

Toutes les erreurs ont la même forme, avec un code stable à tester plutôt que le message :

```json
{ "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](/aide/06-claude-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 `Deprecation` et `Sunset` (RFC 9745 et RFC 8594) et un lien `Link: rel="deprecation"` vers cette page.
- Un champ déprécié reste accepté pendant cette période et est marqué `deprecated` dans la spécification OpenAPI (exemple : `eur_amount`, remplacé par `received_amount`).

## Support

Une question, une clé à révoquer, un besoin que l'API ne couvre pas : hello@thejomi.app.
