{
  "openapi": "3.1.0",
  "info": {
    "title": "Jomi — API publique",
    "version": "1.0.0",
    "description": "API REST par organisation : contacts, deals, encaissements, calls, journal d'activités et webhooks sortants. Authentification par clé API (`Authorization: Bearer crm_live_…`), créée dans Réglages → API & webhooks. Toutes les réponses sont en JSON, non cachées. Devise de référence : celle de l'organisation (`organization.currency`, EUR ou USD, choisie à l'onboarding, modifiable dans Réglages → Relances, objectifs, devise) ; les montants saisis dans l'autre devise sont convertis au taux BCE du jour.\n\nLimites : 300 requêtes par minute et par clé (en-têtes `RateLimit-Policy`, et `RateLimit` + `Retry-After` sur un 429). Erreurs : `{ \"error\": { \"code\", \"message\", \"docs\" } }`, codes stables listés sur https://thejomi.app/developers#erreurs.\n\nVersions et dépréciation : la version est dans l'adresse (`/api/v1`) ; dans une version, seulement des ajouts (ignorer les champs inconnus). Un changement incompatible passe par `/api/v2`. Le retrait d'une opération ou d'une version est annoncé au moins 6 mois avant, par mail aux admins concernés et par les en-têtes `Deprecation` et `Sunset` (RFC 9745, RFC 8594). Détail : https://thejomi.app/developers#versions-et-depreciation",
    "contact": {
      "name": "Support Jomi",
      "email": "hello@thejomi.app",
      "url": "https://thejomi.app/developers"
    }
  },
  "servers": [
    {
      "url": "https://app.thejomi.app/api/v1",
      "description": "Production"
    }
  ],
  "security": [
    {
      "apiKey": [
        "read"
      ]
    }
  ],
  "tags": [
    {
      "name": "Compte",
      "description": "Identité de la clé"
    },
    {
      "name": "Contacts",
      "description": "Prospects et clients du pipeline"
    },
    {
      "name": "Deals",
      "description": "Opportunités rattachées à un contact"
    },
    {
      "name": "Encaissements",
      "description": "Paiements reçus sur un deal"
    },
    {
      "name": "Calls",
      "description": "Appels de vente et de suivi"
    },
    {
      "name": "Événements",
      "description": "Journal d'activités de l'organisation"
    },
    {
      "name": "Webhooks",
      "description": "Endpoints sortants signés HMAC-SHA256"
    }
  ],
  "paths": {
    "/me": {
      "get": {
        "operationId": "getMe",
        "tags": [
          "Compte"
        ],
        "summary": "Organisation et clé utilisées",
        "description": "Test de connexion : renvoie l'organisation rattachée à la clé et les scopes de la clé.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "example": {
                  "organization": {
                    "id": "5f1c…",
                    "name": "Mon entreprise",
                    "slug": "mon-entreprise",
                    "currency": "EUR"
                  },
                  "key": {
                    "id": "9a2b…",
                    "name": "Zapier",
                    "prefix": "crm_live_3f9a1c2b",
                    "scopes": [
                      "read",
                      "write"
                    ],
                    "created_at": "2026-09-26T09:00:00+00:00"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/Me"
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "security": [
          {
            "apiKey": []
          }
        ]
      }
    },
    "/contacts": {
      "get": {
        "operationId": "listContacts",
        "tags": [
          "Contacts"
        ],
        "summary": "Lister les contacts",
        "description": "Triés par `updated_at` croissant (pratique pour une synchronisation incrémentale avec `updated_since`). Pagination par curseur : suivre `next_cursor` tant que `has_more` est vrai. Les contacts archivés sont inclus (champ `archived`).",
        "parameters": [
          {
            "name": "stage",
            "in": "query",
            "description": "Ne garder que cette étape",
            "schema": {
              "type": "string",
              "enum": [
                "to_qualify",
                "qualified",
                "booked",
                "presented",
                "proposal_sent",
                "signed",
                "sans_suite"
              ]
            }
          },
          {
            "name": "search",
            "in": "query",
            "description": "Filtre texte sur le nom, l'email ou le handle",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "updated_since",
            "in": "query",
            "description": "Ne garder que les contacts modifiés depuis cette date (ISO 8601)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "Page de contacts",
            "content": {
              "application/json": {
                "example": {
                  "data": [
                    {
                      "id": "c0ffee…",
                      "full_name": "Jeanne Martin",
                      "email": "jeanne@example.com",
                      "stage": "qualified",
                      "hot": false,
                      "archived": false,
                      "next_followup_at": "2026-09-29T09:00:00+00:00",
                      "updated_at": "2026-09-26T09:00:00+00:00"
                    }
                  ],
                  "has_more": true,
                  "next_cursor": "MjAyNi0wOS0yNi…"
                },
                "schema": {
                  "$ref": "#/components/schemas/ContactPage"
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "$ref": "#/components/responses/Validation"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "security": [
          {
            "apiKey": [
              "read"
            ]
          }
        ],
        "x-required-scope": "read"
      },
      "post": {
        "operationId": "upsertContact",
        "tags": [
          "Contacts"
        ],
        "summary": "Créer ou mettre à jour un contact (idempotent)",
        "description": "Clé d'idempotence : `external_id` si fourni (identifiant chez vous), sinon `email`. Si le contact existe, seuls les champs fournis sont modifiés ; `note` est ajoutée en tête des notes (une seule fois) ; `stage` déclenche la même synchronisation deal / relance que l'app ; `deal_*` n'est pris en compte qu'à la création. À la création : étape `qualified` par défaut, relance automatique programmée (sauf étape close), propriétaire = admin de l'organisation. Renvoie 201 à la création, 200 à la mise à jour.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContactInput"
              },
              "example": {
                "external_id": "typeform-8812",
                "full_name": "Jeanne Martin",
                "email": "jeanne@example.com",
                "handle": "@jeanne",
                "phone": "+33612345678",
                "source": "website",
                "stage": "qualified",
                "note": "Formulaire site — veut un audit",
                "deal_value": 3000,
                "deal_currency": "EUR",
                "deal_title": "Audit"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Contact mis à jour",
            "content": {
              "application/json": {
                "example": {
                  "created": false,
                  "contact": {
                    "id": "c0ffee…",
                    "full_name": "Jeanne Martin",
                    "stage": "qualified"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ContactUpsertResult"
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            }
          },
          "201": {
            "description": "Contact créé",
            "content": {
              "application/json": {
                "example": {
                  "created": true,
                  "contact": {
                    "id": "c0ffee…",
                    "full_name": "Jeanne Martin",
                    "stage": "qualified"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ContactUpsertResult"
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "$ref": "#/components/responses/Validation"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "security": [
          {
            "apiKey": [
              "write"
            ]
          }
        ],
        "x-required-scope": "write"
      }
    },
    "/contacts/{id}": {
      "get": {
        "operationId": "getContact",
        "tags": [
          "Contacts"
        ],
        "summary": "Fiche d'un contact",
        "description": "Contact + deals (chacun avec ses encaissements) + calls.",
        "parameters": [
          {
            "$ref": "#/components/parameters/id"
          }
        ],
        "responses": {
          "200": {
            "description": "Fiche",
            "content": {
              "application/json": {
                "example": {
                  "contact": {
                    "id": "c0ffee…",
                    "full_name": "Jeanne Martin",
                    "stage": "signed"
                  },
                  "deals": [
                    {
                      "id": "d3a1…",
                      "title": "Audit",
                      "value": 3000,
                      "currency": "EUR",
                      "status": "won",
                      "payments": [
                        {
                          "id": "p4y…",
                          "amount": 1500,
                          "paid_at": "2026-09-20T10:00:00+00:00"
                        }
                      ]
                    }
                  ],
                  "calls": [
                    {
                      "id": "ca11…",
                      "type": "closing",
                      "round": "r1",
                      "status": "held",
                      "scheduled_at": "2026-09-18T14:00:00+00:00"
                    }
                  ]
                },
                "schema": {
                  "$ref": "#/components/schemas/ContactDetail"
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "security": [
          {
            "apiKey": [
              "read"
            ]
          }
        ],
        "x-required-scope": "read"
      },
      "patch": {
        "operationId": "updateContact",
        "tags": [
          "Contacts"
        ],
        "summary": "Changer l'étape d'un contact",
        "description": "Synchronise le deal (Signé → gagné, Sans suite → perdu, étape active → ouvert) et la relance automatique, exactement comme le glisser-déposer du pipeline. `proposal_sent` (Proposition envoyée) n'est à utiliser que si l'organisation a activé cette étape (Réglages → Pipeline). Avec `stage: sans_suite`, `lost_reason` (facultatif) enregistre le motif : prix, timing, decideur, besoin, concurrence, confiance, injoignable, non_qualifie ou autre — il alimente « Pourquoi on perd » dans Performance. `owner_id` (uuid d'un membre actif, pas un observateur) assigne le contact à la personne qui le suit ; il peut se combiner avec `stage`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "example": {
                "stage": "sans_suite",
                "lost_reason": "prix",
                "owner_id": "m3mb3r…"
              },
              "schema": {
                "$ref": "#/components/schemas/ContactUpdateInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Contact mis à jour",
            "content": {
              "application/json": {
                "example": {
                  "contact": {
                    "id": "c0ffee…",
                    "stage": "booked"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ContactResult"
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Validation"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "security": [
          {
            "apiKey": [
              "write"
            ]
          }
        ],
        "x-required-scope": "write"
      }
    },
    "/deals": {
      "get": {
        "operationId": "listDeals",
        "tags": [
          "Deals"
        ],
        "summary": "Lister les deals",
        "description": "Montants dans la devise de référence de l'organisation (`value`) ; montant facturé dans sa devise dans `original_amount` + `currency`. Triés par `updated_at`, pagination par curseur.",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "open",
                "won",
                "lost"
              ]
            }
          },
          {
            "name": "contact_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "updated_since",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "Page de deals",
            "content": {
              "application/json": {
                "example": {
                  "data": [
                    {
                      "id": "d3a1…",
                      "contact_id": "c0ffee…",
                      "title": "Audit",
                      "value": 3000,
                      "currency": "EUR",
                      "original_amount": 3000,
                      "stage": "qualified",
                      "status": "open"
                    }
                  ],
                  "has_more": false,
                  "next_cursor": null
                },
                "schema": {
                  "$ref": "#/components/schemas/DealPage"
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "$ref": "#/components/responses/Validation"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "security": [
          {
            "apiKey": [
              "read"
            ]
          }
        ],
        "x-required-scope": "read"
      },
      "post": {
        "operationId": "createDeal",
        "tags": [
          "Deals"
        ],
        "summary": "Créer un deal",
        "description": "Nouvelle opportunité sur un contact. Un client déjà Signé / Sans suite revient dans le pipeline à l'étape « Qualifié » (ses deals gagnés sont conservés). `value` est dans `currency` (défaut : devise de référence de l'organisation ; l'autre devise est convertie au taux BCE du jour).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DealInput"
              },
              "example": {
                "contact_id": "c0ffee…",
                "title": "Accompagnement 3 mois",
                "value": 4500,
                "currency": "USD",
                "category": "coaching"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Deal créé",
            "content": {
              "application/json": {
                "example": {
                  "deal": {
                    "id": "d3a1…",
                    "value": 4127.85,
                    "currency": "USD",
                    "original_amount": 4500,
                    "fx_rate": 0.9173,
                    "status": "open"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/DealResult"
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Validation"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "security": [
          {
            "apiKey": [
              "write"
            ]
          }
        ],
        "x-required-scope": "write"
      }
    },
    "/payments": {
      "post": {
        "operationId": "createPayment",
        "tags": [
          "Encaissements"
        ],
        "summary": "Enregistrer un encaissement",
        "description": "Le deal passe « gagné » et le contact « Signé » (relance coupée), comme dans l'app. `amount` est dans `currency` (défaut : devise de référence de l'organisation) ; pour un paiement dans l'autre devise, `received_amount` = montant réellement crédité dans la devise de référence (relevé bancaire) prime sur le taux du jour. Si le taux est indisponible, la réponse est 422 : renvoyer avec `received_amount`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentInput"
              },
              "example": {
                "deal_id": "d3a1…",
                "amount": 1500,
                "currency": "EUR",
                "method": "stripe",
                "paid_at": "2026-09-26T10:12:00Z",
                "note": "Acompte 50 %"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Encaissement enregistré",
            "content": {
              "application/json": {
                "example": {
                  "payment": {
                    "id": "p4y…",
                    "deal_id": "d3a1…",
                    "amount": 1500,
                    "currency": "EUR",
                    "method": "stripe",
                    "paid_at": "2026-09-26T10:12:00+00:00"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/PaymentResult"
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Validation"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "security": [
          {
            "apiKey": [
              "write"
            ]
          }
        ],
        "x-required-scope": "write"
      }
    },
    "/calls": {
      "get": {
        "operationId": "listCalls",
        "tags": [
          "Calls"
        ],
        "summary": "Lister les calls",
        "description": "Calls de l'organisation, triés par `updated_at` (synchronisation incrémentale avec `updated_since`), pagination par curseur. Les suivis client (`type: suivi`) sont inclus ; ils ne comptent pas dans les statistiques de vente.",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "booked",
                "held",
                "no_show",
                "canceled",
                "rescheduled"
              ]
            }
          },
          {
            "name": "contact_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "updated_since",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "Page de calls",
            "content": {
              "application/json": {
                "example": {
                  "data": [
                    {
                      "id": "ca11…",
                      "contact_id": "c0ffee…",
                      "type": "qualif",
                      "round": "r1",
                      "status": "booked",
                      "scheduled_at": "2026-09-30T14:00:00+00:00",
                      "duration_min": 30
                    }
                  ],
                  "has_more": false,
                  "next_cursor": null
                },
                "schema": {
                  "$ref": "#/components/schemas/CallPage"
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "$ref": "#/components/responses/Validation"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "security": [
          {
            "apiKey": [
              "read"
            ]
          }
        ],
        "x-required-scope": "read"
      },
      "post": {
        "operationId": "createCall",
        "tags": [
          "Calls"
        ],
        "summary": "Journaliser un call",
        "description": "Round auto-attribué (R1, R2…) si absent, sauf pour un suivi client. Statut par défaut : `booked` si `scheduled_at` est dans le futur, `held` sinon.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CallInput"
              },
              "example": {
                "contact_id": "c0ffee…",
                "type": "closing",
                "scheduled_at": "2026-09-30T14:00:00Z",
                "duration_min": 45
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Call créé",
            "content": {
              "application/json": {
                "example": {
                  "call": {
                    "id": "ca11…",
                    "type": "closing",
                    "round": "r1",
                    "status": "booked",
                    "scheduled_at": "2026-09-30T14:00:00+00:00"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/CallResult"
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Validation"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "security": [
          {
            "apiKey": [
              "write"
            ]
          }
        ],
        "x-required-scope": "write"
      }
    },
    "/events": {
      "get": {
        "operationId": "listEvents",
        "tags": [
          "Événements"
        ],
        "summary": "Journal d'activités",
        "description": "Activités de l'organisation (contact créé, étape changée, call, encaissement, relance…) en ordre chronologique à partir de `since` (7 derniers jours par défaut). Pour suivre le flux : rappeler avec `since` = `next_since`.",
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "description": "Strictement après cette date (ISO 8601)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 500
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Activités",
            "content": {
              "application/json": {
                "example": {
                  "data": [
                    {
                      "id": "ac7…",
                      "contact_id": "c0ffee…",
                      "type": "stage_changed",
                      "actor_id": null,
                      "payload": {
                        "from": "qualified",
                        "to": "booked"
                      },
                      "at": "2026-09-26T09:30:00+00:00"
                    }
                  ],
                  "next_since": "2026-09-26T09:30:00+00:00",
                  "has_more": false
                },
                "schema": {
                  "$ref": "#/components/schemas/EventList"
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "$ref": "#/components/responses/Validation"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "security": [
          {
            "apiKey": [
              "read"
            ]
          }
        ],
        "x-required-scope": "read"
      }
    },
    "/webhooks": {
      "get": {
        "operationId": "listWebhooks",
        "tags": [
          "Webhooks"
        ],
        "summary": "Lister les endpoints",
        "description": "Endpoints sortants de l'organisation, par date de création. Le secret HMAC n'est jamais renvoyé ici.",
        "responses": {
          "200": {
            "description": "Endpoints (sans secret)",
            "content": {
              "application/json": {
                "example": {
                  "data": [
                    {
                      "id": "wh1…",
                      "url": "https://hooks.example.com/crm",
                      "events": [
                        "contact.created",
                        "payment.recorded"
                      ],
                      "description": null,
                      "active": true,
                      "created_at": "2026-09-26T09:00:00+00:00"
                    }
                  ]
                },
                "schema": {
                  "$ref": "#/components/schemas/WebhookList"
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "security": [
          {
            "apiKey": [
              "read"
            ]
          }
        ],
        "x-required-scope": "read"
      },
      "post": {
        "operationId": "createWebhook",
        "tags": [
          "Webhooks"
        ],
        "summary": "Créer un endpoint",
        "description": "Le `secret` (clé HMAC) n'est renvoyé qu'à la création : conservez-le. Événements : contact.created, contact.updated, contact.stage_changed, deal.created, deal.won, deal.lost, payment.recorded, call.scheduled, call.held, call.no_show.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "example": {
                "url": "https://hooks.example.com/crm",
                "events": [
                  "contact.created",
                  "deal.won",
                  "payment.recorded"
                ],
                "description": "Sync compta"
              },
              "schema": {
                "$ref": "#/components/schemas/WebhookInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Endpoint créé",
            "content": {
              "application/json": {
                "example": {
                  "endpoint": {
                    "id": "wh1…",
                    "url": "https://hooks.example.com/crm",
                    "events": [
                      "contact.created",
                      "deal.won",
                      "payment.recorded"
                    ],
                    "active": true,
                    "secret": "6f1e…(64 hex)",
                    "created_at": "2026-09-26T09:00:00+00:00"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/WebhookCreateResult"
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "$ref": "#/components/responses/Validation"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "security": [
          {
            "apiKey": [
              "write"
            ]
          }
        ],
        "x-required-scope": "write"
      }
    },
    "/webhooks/{id}": {
      "delete": {
        "operationId": "deleteWebhook",
        "tags": [
          "Webhooks"
        ],
        "summary": "Supprimer un endpoint",
        "description": "Supprime l'endpoint : plus aucun événement ne lui est envoyé.",
        "parameters": [
          {
            "$ref": "#/components/parameters/id"
          }
        ],
        "responses": {
          "200": {
            "description": "Supprimé",
            "content": {
              "application/json": {
                "example": {
                  "deleted": true,
                  "id": "wh1…"
                },
                "schema": {
                  "$ref": "#/components/schemas/WebhookDeleteResult"
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "security": [
          {
            "apiKey": [
              "write"
            ]
          }
        ],
        "x-required-scope": "write"
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "crm_live_<32 hex>",
        "description": "Clé API créée dans Réglages → API & webhooks (admin), une par organisation. Scopes : `read` (lectures, GET) et `write` (écritures, POST / PATCH / DELETE), choisis à la création de la clé. Les scopes requis par chaque opération sont listés dans son `security` et dans `x-required-scope`.",
        "x-scopes": {
          "read": "Lire contacts, deals, calls, journal d'activités et webhooks",
          "write": "Créer et modifier contacts, deals, encaissements, calls ; créer et supprimer des webhooks"
        }
      }
    },
    "parameters": {
      "id": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "limit": {
        "name": "limit",
        "in": "query",
        "description": "Taille de page (1 à 200)",
        "schema": {
          "type": "integer",
          "default": 50,
          "minimum": 1,
          "maximum": 200
        }
      },
      "cursor": {
        "name": "cursor",
        "in": "query",
        "description": "Curseur opaque renvoyé dans `next_cursor`",
        "schema": {
          "type": "string"
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Clé absente, mal formée, inconnue ou révoquée",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "invalid_key",
                "message": "Clé API inconnue ou révoquée.",
                "docs": "https://thejomi.app/developers#erreurs"
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "Scope insuffisant (`forbidden_scope`) ou organisation suspendue (`org_suspended`)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "forbidden_scope",
                "message": "Cette clé n'a pas le scope « write ».",
                "docs": "https://thejomi.app/developers#erreurs"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Ressource inexistante dans votre organisation",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "Contact introuvable.",
                "docs": "https://thejomi.app/developers#erreurs"
              }
            }
          }
        }
      },
      "Validation": {
        "description": "Corps ou paramètre invalide ; `code` = `validation_error: <champ>`",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "validation_error: stage",
                "message": "Valeur « nope » inconnue. Valeurs acceptées : to_qualify, qualified, booked, presented, signed, sans_suite.",
                "docs": "https://thejomi.app/developers#erreurs"
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Plus de 300 requêtes par minute pour cette clé",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "rate_limited",
                "message": "Plus de 300 requêtes par minute pour cette clé. Réessaie dans une minute.",
                "docs": "https://thejomi.app/developers#erreurs"
              }
            }
          }
        },
        "headers": {
          "RateLimit-Policy": {
            "description": "Politique de limite : 300 requêtes par fenêtre de 60 s, par clé",
            "schema": {
              "type": "string",
              "examples": [
                "\"per-key\";q=300;w=60"
              ]
            }
          },
          "RateLimit": {
            "description": "Requêtes restantes (r) et secondes avant la nouvelle fenêtre (t)",
            "schema": {
              "type": "string",
              "examples": [
                "\"per-key\";r=0;t=42"
              ]
            }
          },
          "Retry-After": {
            "description": "Secondes à attendre avant de réessayer",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 60
            }
          }
        }
      },
      "InternalError": {
        "description": "Erreur interne : réessayer plus tard",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "internal_error",
                "message": "Erreur interne.",
                "docs": "https://thejomi.app/developers#erreurs"
              }
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "Code stable, à tester plutôt que le message : invalid_key, forbidden_scope, org_suspended, not_found, validation_error: <champ>, rate_limited, internal_error",
                "examples": [
                  "validation_error: stage"
                ]
              },
              "message": {
                "type": "string",
                "description": "Explication lisible (français), avec les valeurs acceptées pour une erreur de validation"
              },
              "docs": {
                "type": "string",
                "format": "uri",
                "description": "Page qui décrit chaque code et quoi faire",
                "examples": [
                  "https://thejomi.app/developers#erreurs"
                ]
              }
            }
          }
        }
      },
      "ContactInput": {
        "type": "object",
        "properties": {
          "external_id": {
            "type": "string",
            "description": "Votre identifiant (clé d'idempotence)"
          },
          "full_name": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Clé d'idempotence si external_id absent"
          },
          "handle": {
            "type": "string",
            "description": "@handle Instagram / LinkedIn"
          },
          "phone": {
            "type": "string"
          },
          "source": {
            "type": "string",
            "enum": [
              "instagram",
              "linkedin",
              "mail",
              "referral",
              "website",
              "ads",
              "event",
              "direct",
              "manual",
              "other"
            ],
            "default": "manual"
          },
          "stage": {
            "type": "string",
            "enum": [
              "to_qualify",
              "qualified",
              "booked",
              "presented",
              "proposal_sent",
              "signed",
              "sans_suite"
            ],
            "default": "qualified"
          },
          "note": {
            "type": "string"
          },
          "deal_value": {
            "type": "number",
            "exclusiveMinimum": 0,
            "description": "Crée un deal à la création du contact, dans deal_currency"
          },
          "deal_currency": {
            "type": "string",
            "enum": [
              "EUR",
              "USD"
            ],
            "description": "Défaut : devise de référence de l'organisation"
          },
          "deal_title": {
            "type": "string"
          }
        }
      },
      "DealInput": {
        "type": "object",
        "required": [
          "contact_id",
          "value"
        ],
        "properties": {
          "contact_id": {
            "type": "string",
            "format": "uuid"
          },
          "title": {
            "type": "string"
          },
          "value": {
            "type": "number",
            "exclusiveMinimum": 0,
            "description": "Montant dans currency"
          },
          "currency": {
            "type": "string",
            "enum": [
              "EUR",
              "USD"
            ],
            "description": "Défaut : devise de référence de l'organisation"
          },
          "category": {
            "type": "string"
          }
        }
      },
      "PaymentInput": {
        "type": "object",
        "required": [
          "deal_id",
          "amount"
        ],
        "properties": {
          "deal_id": {
            "type": "string",
            "format": "uuid"
          },
          "amount": {
            "type": "number",
            "exclusiveMinimum": 0,
            "description": "Montant reçu dans currency"
          },
          "currency": {
            "type": "string",
            "enum": [
              "EUR",
              "USD"
            ],
            "description": "Défaut : devise de référence de l'organisation"
          },
          "received_amount": {
            "type": "number",
            "exclusiveMinimum": 0,
            "description": "Montant réellement crédité dans la devise de référence (paiement dans l'autre devise, relevé bancaire) ; prime sur le taux du jour"
          },
          "eur_amount": {
            "type": "number",
            "exclusiveMinimum": 0,
            "deprecated": true,
            "description": "Ancien nom de received_amount (quand la référence était toujours l'euro), toujours accepté"
          },
          "method": {
            "type": "string",
            "enum": [
              "transfer",
              "stripe",
              "cash",
              "manual",
              "other"
            ],
            "default": "manual"
          },
          "paid_at": {
            "type": "string",
            "format": "date-time",
            "description": "Défaut : maintenant"
          },
          "note": {
            "type": "string"
          }
        }
      },
      "CallInput": {
        "type": "object",
        "required": [
          "contact_id",
          "scheduled_at"
        ],
        "properties": {
          "contact_id": {
            "type": "string",
            "format": "uuid"
          },
          "deal_id": {
            "type": "string",
            "format": "uuid"
          },
          "type": {
            "type": "string",
            "enum": [
              "qualif",
              "closing",
              "audit",
              "suivi"
            ],
            "default": "qualif"
          },
          "scheduled_at": {
            "type": "string",
            "format": "date-time"
          },
          "duration_min": {
            "type": "integer",
            "default": 30
          },
          "round": {
            "type": "string",
            "enum": [
              "r1",
              "r2",
              "r3",
              "r4",
              "r5",
              "r6",
              "r7",
              "r8"
            ],
            "description": "Auto si absent"
          },
          "status": {
            "type": "string",
            "enum": [
              "booked",
              "held",
              "no_show",
              "canceled",
              "rescheduled"
            ]
          },
          "outcome": {
            "type": "string",
            "description": "Compte-rendu"
          }
        }
      },
      "WebhookPayload": {
        "type": "object",
        "description": "Corps envoyé à un endpoint. Signature : X-CRM-Signature = sha256=HMAC_SHA256(secret, X-CRM-Timestamp + '.' + corps brut).",
        "required": [
          "id",
          "event",
          "org_id",
          "occurred_at",
          "data"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Id de livraison (dédoublonnage côté récepteur)"
          },
          "event": {
            "type": "string",
            "enum": [
              "contact.created",
              "contact.updated",
              "contact.stage_changed",
              "deal.created",
              "deal.won",
              "deal.lost",
              "payment.recorded",
              "call.scheduled",
              "call.held",
              "call.no_show"
            ]
          },
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "occurred_at": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "type": "object",
            "description": "La ligne concernée (contact, deal, paiement ou call) ; `previous_stage` ajouté pour contact.stage_changed, `contact_id` pour payment.recorded"
          }
        }
      },
      "Contact": {
        "type": "object",
        "description": "Contact (prospect ou client). Liste non exhaustive : de nouveaux champs peuvent apparaître (ajouts seulement dans la v1), à ignorer s'ils sont inconnus.",
        "required": [
          "id",
          "stage",
          "archived",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "external_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Votre identifiant (clé d'idempotence)"
          },
          "full_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "email": {
            "type": [
              "string",
              "null"
            ]
          },
          "handle": {
            "type": [
              "string",
              "null"
            ]
          },
          "phone": {
            "type": [
              "string",
              "null"
            ]
          },
          "external_source": {
            "type": "string",
            "enum": [
              "instagram",
              "linkedin",
              "mail",
              "referral",
              "website",
              "ads",
              "event",
              "direct",
              "manual",
              "other",
              "manychat",
              "boosend"
            ]
          },
          "stage": {
            "type": "string",
            "enum": [
              "to_qualify",
              "qualified",
              "booked",
              "presented",
              "proposal_sent",
              "signed",
              "sans_suite"
            ]
          },
          "owner_id": {
            "type": "string",
            "format": "uuid",
            "description": "Membre qui suit le contact"
          },
          "notes": {
            "type": [
              "string",
              "null"
            ]
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "hot": {
            "type": "boolean"
          },
          "hot_score": {
            "type": "number"
          },
          "magnet": {
            "type": [
              "string",
              "null"
            ]
          },
          "next_followup_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "followups_paused": {
            "type": "boolean"
          },
          "followup_note": {
            "type": [
              "string",
              "null"
            ]
          },
          "setting_started_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "qualified_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "archived": {
            "type": "boolean"
          },
          "visibility": {
            "type": "string",
            "enum": [
              "team",
              "private"
            ]
          },
          "lost_reason": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "prix",
              "timing",
              "decideur",
              "besoin",
              "concurrence",
              "confiance",
              "injoignable",
              "non_qualifie",
              "autre",
              null
            ]
          },
          "lost_stage": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "to_qualify",
              "qualified",
              "booked",
              "presented",
              "proposal_sent",
              "signed",
              "sans_suite",
              null
            ]
          },
          "lost_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Deal": {
        "type": "object",
        "description": "Opportunité rattachée à un contact. Liste non exhaustive : de nouveaux champs peuvent apparaître (ajouts seulement dans la v1), à ignorer s'ils sont inconnus.",
        "required": [
          "id",
          "contact_id",
          "value",
          "currency",
          "stage",
          "status",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "contact_id": {
            "type": "string",
            "format": "uuid"
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "value": {
            "type": "number",
            "description": "Montant dans la devise de référence de l'organisation"
          },
          "currency": {
            "type": "string",
            "enum": [
              "EUR",
              "USD"
            ],
            "description": "Devise du montant saisi"
          },
          "original_amount": {
            "type": [
              "number",
              "null"
            ],
            "description": "Montant saisi, dans `currency`"
          },
          "fx_rate": {
            "type": [
              "number",
              "null"
            ],
            "description": "Taux appliqué vers la devise de référence"
          },
          "fx_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "fx_source": {
            "type": [
              "string",
              "null"
            ],
            "description": "ecb, ecb-cache, manuel ou fixe"
          },
          "category": {
            "type": [
              "string",
              "null"
            ]
          },
          "stage": {
            "type": "string",
            "enum": [
              "to_qualify",
              "qualified",
              "booked",
              "presented",
              "proposal_sent",
              "signed",
              "sans_suite"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "open",
              "won",
              "lost"
            ]
          },
          "closed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "closer_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "setter_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "lost_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Payment": {
        "type": "object",
        "description": "Encaissement sur un deal. Liste non exhaustive : de nouveaux champs peuvent apparaître (ajouts seulement dans la v1), à ignorer s'ils sont inconnus.",
        "required": [
          "id",
          "deal_id",
          "amount",
          "currency",
          "method",
          "paid_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "deal_id": {
            "type": "string",
            "format": "uuid"
          },
          "amount": {
            "type": "number",
            "description": "Montant dans la devise de référence de l'organisation"
          },
          "currency": {
            "type": "string",
            "enum": [
              "EUR",
              "USD"
            ]
          },
          "original_amount": {
            "type": [
              "number",
              "null"
            ],
            "description": "Montant saisi, dans `currency`"
          },
          "fx_rate": {
            "type": [
              "number",
              "null"
            ],
            "description": "Taux appliqué vers la devise de référence"
          },
          "fx_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "fx_source": {
            "type": [
              "string",
              "null"
            ],
            "description": "ecb, ecb-cache, manuel ou fixe"
          },
          "method": {
            "type": "string",
            "enum": [
              "transfer",
              "stripe",
              "cash",
              "manual",
              "other"
            ]
          },
          "paid_at": {
            "type": "string",
            "format": "date-time"
          },
          "note": {
            "type": [
              "string",
              "null"
            ]
          },
          "recorded_by": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "collected_by": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "DealWithPayments": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Deal"
          },
          {
            "type": "object",
            "required": [
              "payments"
            ],
            "properties": {
              "payments": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Payment"
                },
                "description": "Par date de paiement"
              }
            }
          }
        ]
      },
      "Call": {
        "type": "object",
        "description": "Rendez-vous de vente ou de suivi. Liste non exhaustive : de nouveaux champs peuvent apparaître (ajouts seulement dans la v1), à ignorer s'ils sont inconnus.",
        "required": [
          "id",
          "contact_id",
          "type",
          "scheduled_at",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "contact_id": {
            "type": "string",
            "format": "uuid"
          },
          "deal_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "type": {
            "type": "string",
            "enum": [
              "qualif",
              "closing",
              "audit",
              "suivi"
            ],
            "description": "`suivi` = suivi client, hors statistiques de vente"
          },
          "round": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "r1",
              "r2",
              "r3",
              "r4",
              "r5",
              "r6",
              "r7",
              "r8",
              null
            ],
            "description": "Toujours null pour un suivi"
          },
          "scheduled_at": {
            "type": "string",
            "format": "date-time"
          },
          "duration_min": {
            "type": [
              "integer",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "booked",
              "held",
              "no_show",
              "canceled",
              "rescheduled"
            ]
          },
          "outcome": {
            "type": [
              "string",
              "null"
            ]
          },
          "external_event_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "fathom_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "closer_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Activity": {
        "type": "object",
        "description": "Entrée du journal d'activités. Liste non exhaustive : de nouveaux champs peuvent apparaître (ajouts seulement dans la v1), à ignorer s'ils sont inconnus.",
        "required": [
          "id",
          "contact_id",
          "type",
          "at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "contact_id": {
            "type": "string",
            "format": "uuid"
          },
          "type": {
            "type": "string",
            "enum": [
              "contact_created",
              "qualified",
              "stage_changed",
              "call_scheduled",
              "call_done",
              "call_no_show",
              "deal_created",
              "deal_won",
              "deal_lost",
              "payment_recorded",
              "document_added",
              "followup_set",
              "note_added",
              "alert_raised",
              "alert_resolved",
              "contact_assigned"
            ]
          },
          "actor_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "null pour une action automatique ou de l'API"
          },
          "payload": {
            "type": [
              "object",
              "null"
            ],
            "description": "Détail selon le type, par exemple { from, to } pour stage_changed"
          },
          "at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookEndpoint": {
        "type": "object",
        "required": [
          "id",
          "url",
          "events",
          "active",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "contact.created",
                "contact.updated",
                "contact.stage_changed",
                "deal.created",
                "deal.won",
                "deal.lost",
                "payment.recorded",
                "call.scheduled",
                "call.held",
                "call.no_show"
              ]
            }
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "active": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookEndpointWithSecret": {
        "allOf": [
          {
            "$ref": "#/components/schemas/WebhookEndpoint"
          },
          {
            "type": "object",
            "required": [
              "secret"
            ],
            "properties": {
              "secret": {
                "type": "string",
                "pattern": "^[0-9a-f]{64}$",
                "description": "Clé HMAC, renvoyée seulement à la création"
              }
            }
          }
        ]
      },
      "WebhookInput": {
        "type": "object",
        "required": [
          "url",
          "events"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Adresse https qui recevra les événements"
          },
          "events": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string",
              "enum": [
                "contact.created",
                "contact.updated",
                "contact.stage_changed",
                "deal.created",
                "deal.won",
                "deal.lost",
                "payment.recorded",
                "call.scheduled",
                "call.held",
                "call.no_show"
              ]
            }
          },
          "description": {
            "type": "string"
          }
        }
      },
      "ContactUpdateInput": {
        "type": "object",
        "description": "Au moins `stage` ou `owner_id`.",
        "properties": {
          "stage": {
            "type": "string",
            "enum": [
              "to_qualify",
              "qualified",
              "booked",
              "presented",
              "proposal_sent",
              "signed",
              "sans_suite"
            ]
          },
          "lost_reason": {
            "type": "string",
            "enum": [
              "prix",
              "timing",
              "decideur",
              "besoin",
              "concurrence",
              "confiance",
              "injoignable",
              "non_qualifie",
              "autre"
            ],
            "description": "Seulement avec stage = sans_suite"
          },
          "owner_id": {
            "type": "string",
            "format": "uuid",
            "description": "Membre actif (pas un observateur)"
          }
        }
      },
      "Me": {
        "type": "object",
        "required": [
          "organization",
          "key"
        ],
        "properties": {
          "organization": {
            "type": "object",
            "required": [
              "id",
              "name",
              "currency"
            ],
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": "string"
              },
              "slug": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "currency": {
                "type": "string",
                "enum": [
                  "EUR",
                  "USD"
                ]
              }
            }
          },
          "key": {
            "type": "object",
            "required": [
              "id",
              "name",
              "prefix",
              "scopes",
              "created_at"
            ],
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": "string"
              },
              "prefix": {
                "type": "string"
              },
              "scopes": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "read",
                    "write"
                  ]
                }
              },
              "created_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        }
      },
      "ContactPage": {
        "type": "object",
        "required": [
          "data",
          "has_more",
          "next_cursor"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Contact"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "À passer en `cursor` pour la page suivante"
          }
        }
      },
      "DealPage": {
        "type": "object",
        "required": [
          "data",
          "has_more",
          "next_cursor"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Deal"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "À passer en `cursor` pour la page suivante"
          }
        }
      },
      "CallPage": {
        "type": "object",
        "required": [
          "data",
          "has_more",
          "next_cursor"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Call"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "À passer en `cursor` pour la page suivante"
          }
        }
      },
      "EventList": {
        "type": "object",
        "required": [
          "data",
          "next_since",
          "has_more"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Activity"
            }
          },
          "next_since": {
            "type": "string",
            "description": "À passer en `since` pour la suite"
          },
          "has_more": {
            "type": "boolean"
          }
        }
      },
      "ContactResult": {
        "type": "object",
        "required": [
          "contact"
        ],
        "properties": {
          "contact": {
            "$ref": "#/components/schemas/Contact"
          }
        }
      },
      "ContactUpsertResult": {
        "type": "object",
        "required": [
          "contact",
          "created"
        ],
        "properties": {
          "created": {
            "type": "boolean"
          },
          "contact": {
            "$ref": "#/components/schemas/Contact"
          }
        }
      },
      "ContactDetail": {
        "type": "object",
        "required": [
          "contact",
          "deals",
          "calls"
        ],
        "properties": {
          "contact": {
            "$ref": "#/components/schemas/Contact"
          },
          "deals": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DealWithPayments"
            },
            "description": "Du plus récent au plus ancien"
          },
          "calls": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Call"
            },
            "description": "Du plus récent au plus ancien"
          }
        }
      },
      "DealResult": {
        "type": "object",
        "required": [
          "deal"
        ],
        "properties": {
          "deal": {
            "$ref": "#/components/schemas/Deal"
          }
        }
      },
      "PaymentResult": {
        "type": "object",
        "required": [
          "payment"
        ],
        "properties": {
          "payment": {
            "$ref": "#/components/schemas/Payment"
          }
        }
      },
      "CallResult": {
        "type": "object",
        "required": [
          "call"
        ],
        "properties": {
          "call": {
            "$ref": "#/components/schemas/Call"
          }
        }
      },
      "WebhookList": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookEndpoint"
            }
          }
        }
      },
      "WebhookCreateResult": {
        "type": "object",
        "required": [
          "endpoint"
        ],
        "properties": {
          "endpoint": {
            "$ref": "#/components/schemas/WebhookEndpointWithSecret"
          }
        }
      },
      "WebhookDeleteResult": {
        "type": "object",
        "required": [
          "deleted",
          "id"
        ],
        "properties": {
          "deleted": {
            "type": "boolean",
            "const": true
          },
          "id": {
            "type": "string",
            "format": "uuid"
          }
        }
      }
    },
    "headers": {
      "RateLimitPolicy": {
        "description": "Politique de limite : 300 requêtes par fenêtre de 60 s, par clé",
        "schema": {
          "type": "string",
          "examples": [
            "\"per-key\";q=300;w=60"
          ]
        }
      }
    }
  },
  "externalDocs": {
    "description": "Portail développeurs (API, MCP, webhooks)",
    "url": "https://thejomi.app/developers"
  }
}
