{ "openapi": "3.1.0", "info": { "title": "Klantly API", "version": "1.0.0", "description": "L'API publique de Klantly. Authentifiez-vous avec une clé API comme jeton Bearer. Guides, codes d'erreur et exemples se trouvent sur le portail développeurs.", "contact": { "name": "Klantly", "url": "https://developers.klantly.com/fr/support" } }, "externalDocs": { "url": "https://developers.klantly.com/fr", "description": "Klantly Developers" }, "servers": [ { "url": "https://app.klantly.com/api/v1" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Clé API", "description": "Testez votre connexion et voyez quelle clé, quelle entreprise, quels scopes et quelles limites s'appliquent." }, { "name": "Entreprise", "description": "Les données de votre propre entreprise : nom, adresse, langue et paramètres de TVA." }, { "name": "Utilisateurs", "description": "Les utilisateurs de votre entreprise, par exemple pour attribuer un deal à quelqu'un." }, { "name": "Clients", "description": "Clients et prospects : créer, rechercher, modifier et convertir un prospect en client." }, { "name": "Notes", "description": "Notes internes sur un client ou un deal. Votre client ne les voit jamais." }, { "name": "Étapes du pipeline", "description": "Les étapes de votre tableau de pipeline, dans l'ordre, et si une étape signifie ouvert, gagné ou perdu." }, { "name": "Deals", "description": "Les cartes de votre tableau de pipeline : créer, modifier, déplacer vers une autre étape, gagner, perdre et archiver." }, { "name": "Endpoints de webhook", "description": "Des adresses auxquelles Klantly envoie immédiatement un message dès qu'un changement a lieu. Les signatures et les nouvelles tentatives sont expliquées dans le guide des webhooks." }, { "name": "Événements", "description": "Tout ce qui a changé au cours des 30 derniers jours, sous forme de liste. Pour rattraper des webhooks manqués, ou pour interroger l'API au lieu d'utiliser des webhooks." } ], "paths": { "/me": { "get": { "operationId": "me", "summary": "Récupérer la clé et l'entreprise", "description": "Renvoie la clé avec laquelle vous faites la requête, avec l'entreprise, les scopes, la date d'expiration et les limites. Utilisez cet endpoint pour tester votre connexion : il ne requiert aucun scope.", "tags": [ "Clé API" ], "x-klantly-scope": null, "externalDocs": { "url": "https://developers.klantly.com/fr/reference/api-key#me" }, "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } }, "ETag": { "description": "Version de l'objet, pour If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ApiKey" } }, "additionalProperties": false }, "example": { "data": { "object": "api_key", "id": "01j7zq3k9x2m4n6p8r0t2v4w6y", "name": "Website", "prefix": "kly_4fZ2mQ8v", "scopes": [ "customers.read", "customers.write" ], "expires_at": "2027-09-14T10:15:00Z", "created_at": "2026-09-14T10:15:00Z", "company": { "object": "company", "id": "42", "name": "De Vries Bouw" }, "rate_limits": [ { "name": "key_minute", "limit": 120, "window_seconds": 60 } ] } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/company": { "get": { "operationId": "companyGet", "summary": "Récupérer l'entreprise", "description": "Les données de l'entreprise à laquelle appartient la clé, avec le taux de TVA par défaut et si les prix incluent la TVA.", "tags": [ "Entreprise" ], "x-klantly-scope": "company.read", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/company#companyget" }, "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } }, "ETag": { "description": "Version de l'objet, pour If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Company" } }, "additionalProperties": false }, "example": { "data": { "object": "company", "id": "42", "name": "De Vries Bouw", "email": "info@devriesbouw.nl", "phone": "+31 30 1234567", "website": "https://devriesbouw.nl", "coc_number": "12345678", "vat_number": "NL123456789B01", "address": "Industrieweg 5", "postal_code": "3542 AD", "city": "Utrecht", "country": "NL", "language": "nl", "currency": "EUR", "timezone": "Europe/Amsterdam", "default_vat_rate": "21.00", "prices_include_vat": false } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/users": { "get": { "operationId": "usersList", "summary": "Lister les utilisateurs", "description": "Les utilisateurs de votre entreprise, triés par id. Utilisez l'id comme assigned_user_id d'un deal.", "tags": [ "Utilisateurs" ], "x-klantly-scope": "users.read", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/users#userslist" }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Nombre de résultats par page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Le next_cursor ou prev_cursor de meta dans la réponse précédente.", "schema": { "type": "string" } }, { "name": "filter[status]", "in": "query", "required": false, "description": "Uniquement les utilisateurs actifs ou uniquement les utilisateurs désactivés.", "schema": { "type": "string", "enum": [ "active", "inactive" ] } } ], "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "additionalProperties": false }, "example": { "data": [ { "object": "user", "id": "7", "name": "Sanne Bakker", "email": "sanne@devriesbouw.nl", "role": "Verkoop", "is_owner": false, "status": "active", "created_at": "2026-09-14T10:15:00Z" } ], "meta": { "limit": 50, "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0", "prev_cursor": null } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "Les données saisies ne sont pas valides.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Les données saisies ne sont pas valides.", "status": 422, "code": "validation_failed", "detail": "1 champ n'est pas valide.", "errors": { "email": [ "Email doit être une adresse e-mail valide." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/customers": { "get": { "operationId": "customersList", "summary": "Lister les clients", "description": "Une liste de clients et de prospects, les plus récents d'abord. Filtrez par statut, type, adresse e-mail ou date de modification, recherchez avec q et naviguez avec le curseur de meta.", "tags": [ "Clients" ], "x-klantly-scope": "customers.read", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/customers#customerslist" }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Nombre de résultats par page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Le next_cursor ou prev_cursor de meta dans la réponse précédente.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Recherche dans le nom, l'adresse e-mail, le nom de l'entreprise et le numéro de téléphone.", "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }, { "name": "sort", "in": "query", "required": false, "description": "Tri par created_at ou updated_at ; un signe moins devant trie par ordre décroissant.", "schema": { "type": "string", "enum": [ "-created_at", "created_at", "-updated_at", "updated_at" ], "default": "-created_at" } }, { "name": "filter[status]", "in": "query", "required": false, "description": "Uniquement les prospects ou uniquement les clients.", "schema": { "type": "string", "enum": [ "lead", "customer" ] } }, { "name": "filter[type]", "in": "query", "required": false, "description": "Uniquement les particuliers ou uniquement les entreprises.", "schema": { "type": "string", "enum": [ "individual", "business" ] } }, { "name": "filter[email]", "in": "query", "required": false, "description": "Exactement cette adresse e-mail (sans tenir compte des majuscules).", "schema": { "type": "string", "format": "email" } }, { "name": "filter[updated_since]", "in": "query", "required": false, "description": "Uniquement ce qui a changé depuis ce moment : ISO 8601 avec fuseau horaire, par exemple 2026-09-14T10:15:00Z. Pratique pour synchroniser.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "additionalProperties": false }, "example": { "data": [ { "object": "customer", "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "type": "business", "status": "lead", "name": "Jan de Vries", "email": "jan@example.com", "phone": "+31 6 12345678", "company_name": "De Vries Bouw", "vat_number": "NL123456789B01", "coc_number": "12345678", "address": "Dorpsstraat 1", "postal_code": "3511 AB", "city": "Utrecht", "country": "NL", "email_unsubscribed": false, "converted_at": null, "last_activity_at": "2026-09-14T10:15:00Z", "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } ], "meta": { "limit": 50, "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0", "prev_cursor": null } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "Les données saisies ne sont pas valides.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Les données saisies ne sont pas valides.", "status": 422, "code": "validation_failed", "detail": "1 champ n'est pas valide.", "errors": { "email": [ "Email doit être une adresse e-mail valide." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "post": { "operationId": "customersCreate", "summary": "Créer un client", "description": "Crée un nouveau prospect. L'adresse e-mail est obligatoire et unique au sein de votre entreprise : une adresse existante renvoie une erreur de validation. Les automatisations et l'historique client fonctionnent exactement comme lors d'une création dans Klantly.", "tags": [ "Clients" ], "x-klantly-scope": "customers.write", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/customers#customerscreate" }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Une clé unique par requête (par exemple un UUID) : une nouvelle tentative ne crée alors pas de doublon. Valable 24 heures.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomersCreateRequest" }, "example": { "email": "jan@example.com", "name": "Jan de Vries", "type": "business", "company_name": "De Vries Bouw", "city": "Utrecht" } } } }, "responses": { "201": { "description": "Créé", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } }, "ETag": { "description": "Version de l'objet, pour If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Customer" } }, "additionalProperties": false }, "example": { "data": { "object": "customer", "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "type": "business", "status": "lead", "name": "Jan de Vries", "email": "jan@example.com", "phone": "+31 6 12345678", "company_name": "De Vries Bouw", "vat_number": "NL123456789B01", "coc_number": "12345678", "address": "Dorpsstraat 1", "postal_code": "3511 AB", "city": "Utrecht", "country": "NL", "email_unsubscribed": false, "converted_at": null, "last_activity_at": "2026-09-14T10:15:00Z", "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / limit_reached / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "limit_reached": { "summary": "La limite de l'abonnement est atteinte.", "value": { "type": "https://developers.klantly.com/errors/limit_reached", "title": "La limite de l'abonnement est atteinte.", "status": 403, "code": "limit_reached", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "409": { "description": "idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_in_progress": { "summary": "Une requête avec cette Idempotency-Key est encore en cours.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Une requête avec cette Idempotency-Key est encore en cours.", "status": 409, "code": "idempotency_in_progress", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "413": { "description": "payload_too_large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "summary": "Le corps de la requête est trop volumineux.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "Le corps de la requête est trop volumineux.", "status": 413, "code": "payload_too_large", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "415": { "description": "unsupported_media_type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "summary": "Ce format n'est pas pris en charge.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Ce format n'est pas pris en charge.", "status": 415, "code": "unsupported_media_type", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed / unknown_field / idempotency_key_reused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "Les données saisies ne sont pas valides.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Les données saisies ne sont pas valides.", "status": 422, "code": "validation_failed", "detail": "1 champ n'est pas valide.", "errors": { "email": [ "Email doit être une adresse e-mail valide." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "Les données contiennent un champ inconnu.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "Les données contiennent un champ inconnu.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "Cette Idempotency-Key a déjà été utilisée pour une autre requête.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Cette Idempotency-Key a déjà été utilisée pour une autre requête.", "status": 422, "code": "idempotency_key_reused", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/customers/{customer}": { "get": { "operationId": "customersGet", "summary": "Récupérer un client", "description": "Un seul client par id. La réponse contient un ETag que vous pouvez envoyer dans If-Match lors d'une modification.", "tags": [ "Clients" ], "x-klantly-scope": "customers.read", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/customers#customersget" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "L'id (UUID) du client.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } }, "ETag": { "description": "Version de l'objet, pour If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Customer" } }, "additionalProperties": false }, "example": { "data": { "object": "customer", "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "type": "business", "status": "lead", "name": "Jan de Vries", "email": "jan@example.com", "phone": "+31 6 12345678", "company_name": "De Vries Bouw", "vat_number": "NL123456789B01", "coc_number": "12345678", "address": "Dorpsstraat 1", "postal_code": "3511 AB", "city": "Utrecht", "country": "NL", "email_unsubscribed": false, "converted_at": null, "last_activity_at": "2026-09-14T10:15:00Z", "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Introuvable.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Introuvable.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "patch": { "operationId": "customersUpdate", "summary": "Modifier un client", "description": "Modifie uniquement les champs que vous envoyez. Le statut ne change pas via cet endpoint ; utilisez pour cela « Convertir un prospect en client ».", "tags": [ "Clients" ], "x-klantly-scope": "customers.write", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/customers#customersupdate" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "L'id (UUID) du client.", "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "required": false, "description": "L'ETag de la version récupérée. Si l'enregistrement a changé entre-temps, vous obtenez 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomersUpdateRequest" }, "example": { "phone": "+31 6 12345678", "city": "Amersfoort" } } } }, "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } }, "ETag": { "description": "Version de l'objet, pour If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Customer" } }, "additionalProperties": false }, "example": { "data": { "object": "customer", "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "type": "business", "status": "lead", "name": "Jan de Vries", "email": "jan@example.com", "phone": "+31 6 12345678", "company_name": "De Vries Bouw", "vat_number": "NL123456789B01", "coc_number": "12345678", "address": "Dorpsstraat 1", "postal_code": "3511 AB", "city": "Utrecht", "country": "NL", "email_unsubscribed": false, "converted_at": null, "last_activity_at": "2026-09-14T10:15:00Z", "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Introuvable.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Introuvable.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "412": { "description": "precondition_failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "precondition_failed": { "summary": "L'enregistrement a été modifié entre-temps.", "value": { "type": "https://developers.klantly.com/errors/precondition_failed", "title": "L'enregistrement a été modifié entre-temps.", "status": 412, "code": "precondition_failed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "413": { "description": "payload_too_large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "summary": "Le corps de la requête est trop volumineux.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "Le corps de la requête est trop volumineux.", "status": 413, "code": "payload_too_large", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "415": { "description": "unsupported_media_type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "summary": "Ce format n'est pas pris en charge.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Ce format n'est pas pris en charge.", "status": 415, "code": "unsupported_media_type", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed / unknown_field", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "Les données saisies ne sont pas valides.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Les données saisies ne sont pas valides.", "status": 422, "code": "validation_failed", "detail": "1 champ n'est pas valide.", "errors": { "email": [ "Email doit être une adresse e-mail valide." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "Les données contiennent un champ inconnu.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "Les données contiennent un champ inconnu.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/customers/{customer}/convert": { "post": { "operationId": "customersConvert", "summary": "Convertir un prospect en client", "description": "Convertit un prospect en client. S'il est déjà client, rien ne change et vous récupérez simplement le client.", "tags": [ "Clients" ], "x-klantly-scope": "customers.write", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/customers#customersconvert" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "L'id (UUID) du client.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Une clé unique par requête (par exemple un UUID) : une nouvelle tentative ne crée alors pas de doublon. Valable 24 heures.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } }, "ETag": { "description": "Version de l'objet, pour If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Customer" } }, "additionalProperties": false }, "example": { "data": { "object": "customer", "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "type": "business", "status": "lead", "name": "Jan de Vries", "email": "jan@example.com", "phone": "+31 6 12345678", "company_name": "De Vries Bouw", "vat_number": "NL123456789B01", "coc_number": "12345678", "address": "Dorpsstraat 1", "postal_code": "3511 AB", "city": "Utrecht", "country": "NL", "email_unsubscribed": false, "converted_at": null, "last_activity_at": "2026-09-14T10:15:00Z", "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Introuvable.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Introuvable.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "409": { "description": "idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_in_progress": { "summary": "Une requête avec cette Idempotency-Key est encore en cours.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Une requête avec cette Idempotency-Key est encore en cours.", "status": 409, "code": "idempotency_in_progress", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "idempotency_key_reused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_key_reused": { "summary": "Cette Idempotency-Key a déjà été utilisée pour une autre requête.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Cette Idempotency-Key a déjà été utilisée pour une autre requête.", "status": 422, "code": "idempotency_key_reused", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/customers/{customer}/activities": { "get": { "operationId": "customersActivities", "summary": "Historique d'un client", "description": "L'historique d'un client, le plus récent en premier : devis, factures, rendez-vous, e-mails et plus encore. Les références aux enregistrements liés figurent sous related.", "tags": [ "Clients" ], "x-klantly-scope": "customers.read", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/customers#customersactivities" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "L'id (UUID) du client.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Nombre de résultats par page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Le next_cursor ou prev_cursor de meta dans la réponse précédente.", "schema": { "type": "string" } }, { "name": "filter[type]", "in": "query", "required": false, "description": "Uniquement les activités de ce type, par exemple quote_sent ou invoice_created.", "schema": { "type": "string", "maxLength": 40 } } ], "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerActivity" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "additionalProperties": false }, "example": { "data": [ { "object": "customer_activity", "id": "9d3f7c62-3e7a-4f9d-8c4b-5a6e7f8a9ba3", "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "type": "quote_sent", "title": null, "description": null, "related": { "quote_id": null, "invoice_id": null, "appointment_id": null, "work_order_id": null, "task_id": null, "deal_id": null, "order_id": null, "conversation_id": null }, "happened_at": "2026-09-14T10:15:00Z", "created_at": "2026-09-14T10:15:00Z" } ], "meta": { "limit": 50, "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0", "prev_cursor": null } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Introuvable.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Introuvable.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "Les données saisies ne sont pas valides.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Les données saisies ne sont pas valides.", "status": 422, "code": "validation_failed", "detail": "1 champ n'est pas valide.", "errors": { "email": [ "Email doit être une adresse e-mail valide." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/customers/{customer}/notes": { "get": { "operationId": "notesListCustomer", "summary": "Lister les notes d'un client", "description": "Les notes d'un client, les plus récentes en premier.", "tags": [ "Notes" ], "x-klantly-scope": "customers.read", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/notes#noteslist-customer" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "L'id (UUID) du client.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Nombre de résultats par page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Le next_cursor ou prev_cursor de meta dans la réponse précédente.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Note" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "additionalProperties": false }, "example": { "data": [ { "object": "note", "id": "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92", "content": "Klant belt terug na de vakantie.", "is_important": true, "parent": { "object": "customer", "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" }, "author": { "object": "user", "id": "7", "name": "Sanne Bakker" }, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } ], "meta": { "limit": 50, "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0", "prev_cursor": null } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Introuvable.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Introuvable.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "Les données saisies ne sont pas valides.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Les données saisies ne sont pas valides.", "status": 422, "code": "validation_failed", "detail": "1 champ n'est pas valide.", "errors": { "email": [ "Email doit être une adresse e-mail valide." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "post": { "operationId": "notesCreateCustomer", "summary": "Ajouter une note à un client", "description": "Ajoute une note interne à un client. Elle apparaît immédiatement dans Klantly. Une note ajoutée via l'API n'a pas d'auteur.", "tags": [ "Notes" ], "x-klantly-scope": "customers.write", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/notes#notescreate-customer" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "L'id (UUID) du client.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Une clé unique par requête (par exemple un UUID) : une nouvelle tentative ne crée alors pas de doublon. Valable 24 heures.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotesCreateCustomerRequest" }, "example": { "content": "Klant belt terug na de vakantie.", "is_important": true } } } }, "responses": { "201": { "description": "Créé", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } }, "ETag": { "description": "Version de l'objet, pour If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Note" } }, "additionalProperties": false }, "example": { "data": { "object": "note", "id": "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92", "content": "Klant belt terug na de vakantie.", "is_important": true, "parent": { "object": "customer", "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" }, "author": { "object": "user", "id": "7", "name": "Sanne Bakker" }, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Introuvable.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Introuvable.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "409": { "description": "idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_in_progress": { "summary": "Une requête avec cette Idempotency-Key est encore en cours.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Une requête avec cette Idempotency-Key est encore en cours.", "status": 409, "code": "idempotency_in_progress", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "413": { "description": "payload_too_large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "summary": "Le corps de la requête est trop volumineux.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "Le corps de la requête est trop volumineux.", "status": 413, "code": "payload_too_large", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "415": { "description": "unsupported_media_type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "summary": "Ce format n'est pas pris en charge.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Ce format n'est pas pris en charge.", "status": 415, "code": "unsupported_media_type", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed / unknown_field / idempotency_key_reused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "Les données saisies ne sont pas valides.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Les données saisies ne sont pas valides.", "status": 422, "code": "validation_failed", "detail": "1 champ n'est pas valide.", "errors": { "email": [ "Email doit être une adresse e-mail valide." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "Les données contiennent un champ inconnu.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "Les données contiennent un champ inconnu.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "Cette Idempotency-Key a déjà été utilisée pour une autre requête.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Cette Idempotency-Key a déjà été utilisée pour une autre requête.", "status": 422, "code": "idempotency_key_reused", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/customers/{customer}/notes/{note}": { "patch": { "operationId": "notesUpdateCustomer", "summary": "Modifier une note d'un client", "description": "Modifie uniquement les champs que vous envoyez.", "tags": [ "Notes" ], "x-klantly-scope": "customers.write", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/notes#notesupdate-customer" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "L'id (UUID) du client.", "schema": { "type": "string", "format": "uuid" } }, { "name": "note", "in": "path", "required": true, "description": "L'id (UUID) de la note.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotesUpdateCustomerRequest" }, "example": { "is_important": false } } } }, "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } }, "ETag": { "description": "Version de l'objet, pour If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Note" } }, "additionalProperties": false }, "example": { "data": { "object": "note", "id": "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92", "content": "Klant belt terug na de vakantie.", "is_important": true, "parent": { "object": "customer", "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" }, "author": { "object": "user", "id": "7", "name": "Sanne Bakker" }, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Introuvable.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Introuvable.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "413": { "description": "payload_too_large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "summary": "Le corps de la requête est trop volumineux.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "Le corps de la requête est trop volumineux.", "status": 413, "code": "payload_too_large", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "415": { "description": "unsupported_media_type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "summary": "Ce format n'est pas pris en charge.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Ce format n'est pas pris en charge.", "status": 415, "code": "unsupported_media_type", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed / unknown_field", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "Les données saisies ne sont pas valides.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Les données saisies ne sont pas valides.", "status": 422, "code": "validation_failed", "detail": "1 champ n'est pas valide.", "errors": { "email": [ "Email doit être une adresse e-mail valide." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "Les données contiennent un champ inconnu.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "Les données contiennent un champ inconnu.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "delete": { "operationId": "notesDeleteCustomer", "summary": "Supprimer une note d'un client", "description": "Supprime la note et ses pièces jointes. Cette action est irréversible.", "tags": [ "Notes" ], "x-klantly-scope": "customers.write", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/notes#notesdelete-customer" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "L'id (UUID) du client.", "schema": { "type": "string", "format": "uuid" } }, { "name": "note", "in": "path", "required": true, "description": "L'id (UUID) de la note.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } }, "ETag": { "description": "Version de l'objet, pour If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DeletedObject" } }, "additionalProperties": false }, "example": { "data": { "object": "note", "id": "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92", "deleted": true } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Introuvable.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Introuvable.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}/notes": { "get": { "operationId": "notesListDeal", "summary": "Lister les notes d'un deal", "description": "Les notes d'un deal, les plus récentes en premier.", "tags": [ "Notes" ], "x-klantly-scope": "deals.read", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/notes#noteslist-deal" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "L'id (UUID) du deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Nombre de résultats par page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Le next_cursor ou prev_cursor de meta dans la réponse précédente.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Note" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "additionalProperties": false }, "example": { "data": [ { "object": "note", "id": "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92", "content": "Klant belt terug na de vakantie.", "is_important": true, "parent": { "object": "customer", "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" }, "author": { "object": "user", "id": "7", "name": "Sanne Bakker" }, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } ], "meta": { "limit": 50, "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0", "prev_cursor": null } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Introuvable.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Introuvable.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "Les données saisies ne sont pas valides.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Les données saisies ne sont pas valides.", "status": 422, "code": "validation_failed", "detail": "1 champ n'est pas valide.", "errors": { "email": [ "Email doit être une adresse e-mail valide." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "post": { "operationId": "notesCreateDeal", "summary": "Ajouter une note à un deal", "description": "Ajoute une note interne à un deal. Elle apparaît immédiatement dans Klantly. Une note ajoutée via l'API n'a pas d'auteur.", "tags": [ "Notes" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/notes#notescreate-deal" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "L'id (UUID) du deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Une clé unique par requête (par exemple un UUID) : une nouvelle tentative ne crée alors pas de doublon. Valable 24 heures.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotesCreateDealRequest" }, "example": { "content": "Klant belt terug na de vakantie.", "is_important": true } } } }, "responses": { "201": { "description": "Créé", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } }, "ETag": { "description": "Version de l'objet, pour If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Note" } }, "additionalProperties": false }, "example": { "data": { "object": "note", "id": "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92", "content": "Klant belt terug na de vakantie.", "is_important": true, "parent": { "object": "customer", "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" }, "author": { "object": "user", "id": "7", "name": "Sanne Bakker" }, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Introuvable.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Introuvable.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "409": { "description": "idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_in_progress": { "summary": "Une requête avec cette Idempotency-Key est encore en cours.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Une requête avec cette Idempotency-Key est encore en cours.", "status": 409, "code": "idempotency_in_progress", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "413": { "description": "payload_too_large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "summary": "Le corps de la requête est trop volumineux.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "Le corps de la requête est trop volumineux.", "status": 413, "code": "payload_too_large", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "415": { "description": "unsupported_media_type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "summary": "Ce format n'est pas pris en charge.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Ce format n'est pas pris en charge.", "status": 415, "code": "unsupported_media_type", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed / unknown_field / idempotency_key_reused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "Les données saisies ne sont pas valides.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Les données saisies ne sont pas valides.", "status": 422, "code": "validation_failed", "detail": "1 champ n'est pas valide.", "errors": { "email": [ "Email doit être une adresse e-mail valide." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "Les données contiennent un champ inconnu.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "Les données contiennent un champ inconnu.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "Cette Idempotency-Key a déjà été utilisée pour une autre requête.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Cette Idempotency-Key a déjà été utilisée pour une autre requête.", "status": 422, "code": "idempotency_key_reused", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}/notes/{note}": { "patch": { "operationId": "notesUpdateDeal", "summary": "Modifier une note d'un deal", "description": "Modifie uniquement les champs que vous envoyez.", "tags": [ "Notes" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/notes#notesupdate-deal" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "L'id (UUID) du deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "note", "in": "path", "required": true, "description": "L'id (UUID) de la note.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotesUpdateDealRequest" }, "example": { "is_important": false } } } }, "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } }, "ETag": { "description": "Version de l'objet, pour If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Note" } }, "additionalProperties": false }, "example": { "data": { "object": "note", "id": "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92", "content": "Klant belt terug na de vakantie.", "is_important": true, "parent": { "object": "customer", "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" }, "author": { "object": "user", "id": "7", "name": "Sanne Bakker" }, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Introuvable.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Introuvable.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "413": { "description": "payload_too_large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "summary": "Le corps de la requête est trop volumineux.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "Le corps de la requête est trop volumineux.", "status": 413, "code": "payload_too_large", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "415": { "description": "unsupported_media_type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "summary": "Ce format n'est pas pris en charge.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Ce format n'est pas pris en charge.", "status": 415, "code": "unsupported_media_type", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed / unknown_field", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "Les données saisies ne sont pas valides.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Les données saisies ne sont pas valides.", "status": 422, "code": "validation_failed", "detail": "1 champ n'est pas valide.", "errors": { "email": [ "Email doit être une adresse e-mail valide." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "Les données contiennent un champ inconnu.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "Les données contiennent un champ inconnu.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "delete": { "operationId": "notesDeleteDeal", "summary": "Supprimer une note d'un deal", "description": "Supprime la note et ses pièces jointes. Cette action est irréversible.", "tags": [ "Notes" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/notes#notesdelete-deal" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "L'id (UUID) du deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "note", "in": "path", "required": true, "description": "L'id (UUID) de la note.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } }, "ETag": { "description": "Version de l'objet, pour If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DeletedObject" } }, "additionalProperties": false }, "example": { "data": { "object": "note", "id": "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92", "deleted": true } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Introuvable.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Introuvable.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/pipeline-stages": { "get": { "operationId": "pipelineStagesList", "summary": "Lister les étapes du pipeline", "description": "Toutes les étapes actives du tableau de pipeline, dans l'ordre du tableau. Les noms dans les quatre langues figurent sous names.", "tags": [ "Étapes du pipeline" ], "x-klantly-scope": "deals.read", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/pipeline-stages#pipeline-stageslist" }, "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineStage" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "additionalProperties": false }, "example": { "data": [ { "object": "pipeline_stage", "id": "3", "name": "Offerte verstuurd", "names": { "nl": "Offerte verstuurd", "en": "Quote sent", "de": "Angebot gesendet", "fr": "Devis envoyé" }, "type": "open", "is_default": false, "position": 3, "probability": "50.00", "color": "#3B82F6" } ], "meta": { "limit": 50, "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0", "prev_cursor": null } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals": { "get": { "operationId": "dealsList", "summary": "Lister les deals", "description": "Une liste de deals, le plus récent en premier. Les deals archivés sont exclus par défaut ; utilisez filter[archived] pour les inclure. Filtrez par statut, étape, client, responsable ou date de modification.", "tags": [ "Deals" ], "x-klantly-scope": "deals.read", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/deals#dealslist" }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Nombre de résultats par page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Le next_cursor ou prev_cursor de meta dans la réponse précédente.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Tri par created_at, updated_at ou stage_changed_at ; un signe moins devant signifie décroissant.", "schema": { "type": "string", "enum": [ "-created_at", "created_at", "-updated_at", "updated_at", "-stage_changed_at", "stage_changed_at" ], "default": "-created_at" } }, { "name": "filter[status]", "in": "query", "required": false, "description": "Uniquement les deals ouverts, gagnés ou perdus.", "schema": { "type": "string", "enum": [ "open", "won", "lost" ] } }, { "name": "filter[stage_id]", "in": "query", "required": false, "description": "Uniquement les deals de cette étape (l'id vient de Lister les étapes du pipeline).", "schema": { "type": "integer" } }, { "name": "filter[customer_id]", "in": "query", "required": false, "description": "Uniquement les deals de ce client.", "schema": { "type": "string", "format": "uuid" } }, { "name": "filter[assigned_user_id]", "in": "query", "required": false, "description": "Uniquement les deals de cet utilisateur.", "schema": { "type": "integer" } }, { "name": "filter[archived]", "in": "query", "required": false, "description": "false (par défaut) affiche uniquement les deals du tableau, true uniquement les deals archivés, all les deux.", "schema": { "type": "string", "enum": [ "false", "true", "all" ], "default": "false" } }, { "name": "filter[updated_since]", "in": "query", "required": false, "description": "Uniquement ce qui a changé depuis ce moment : ISO 8601 avec fuseau horaire, par exemple 2026-09-14T10:15:00Z. Pratique pour synchroniser.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Deal" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "additionalProperties": false }, "example": { "data": [ { "object": "deal", "id": "9d3f7a20-1c5e-4d7b-8a2f-3e4c5d6f7a81", "title": "Veranda 5x3 m", "description": null, "status": "open", "value": "8450.00", "currency": "EUR", "value_source": "manual", "stage": { "object": "pipeline_stage", "id": "3" }, "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "assigned_user_id": "7", "source": "api", "lost_reason": null, "is_archived": false, "stage_changed_at": "2026-09-14T10:15:00Z", "won_at": null, "lost_at": null, "archived_at": null, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } ], "meta": { "limit": 50, "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0", "prev_cursor": null } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "Les données saisies ne sont pas valides.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Les données saisies ne sont pas valides.", "status": 422, "code": "validation_failed", "detail": "1 champ n'est pas valide.", "errors": { "email": [ "Email doit être une adresse e-mail valide." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "post": { "operationId": "dealsCreate", "summary": "Créer un deal", "description": "Place un client sur le tableau de pipeline. Un client ne peut avoir qu'un seul deal ouvert à la fois : s'il en a déjà un, vous recevez 409 avec son id dans deal_id. Sans stage_id, le deal arrive dans l'étape par défaut. Si vous envoyez value, Klantly conserve ce montant au lieu de le calculer à partir des devis.", "tags": [ "Deals" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/deals#dealscreate" }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Une clé unique par requête (par exemple un UUID) : une nouvelle tentative ne crée alors pas de doublon. Valable 24 heures.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealsCreateRequest" }, "example": { "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "title": "Veranda 5x3 m", "value": "8450.00" } } } }, "responses": { "201": { "description": "Créé", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } }, "ETag": { "description": "Version de l'objet, pour If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deal" } }, "additionalProperties": false }, "example": { "data": { "object": "deal", "id": "9d3f7a20-1c5e-4d7b-8a2f-3e4c5d6f7a81", "title": "Veranda 5x3 m", "description": null, "status": "open", "value": "8450.00", "currency": "EUR", "value_source": "manual", "stage": { "object": "pipeline_stage", "id": "3" }, "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "assigned_user_id": "7", "source": "api", "lost_reason": null, "is_archived": false, "stage_changed_at": "2026-09-14T10:15:00Z", "won_at": null, "lost_at": null, "archived_at": null, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "409": { "description": "conflict / idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "conflict": { "summary": "Ceci est en conflit avec l'état actuel.", "value": { "type": "https://developers.klantly.com/errors/conflict", "title": "Ceci est en conflit avec l'état actuel.", "status": 409, "code": "conflict", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_in_progress": { "summary": "Une requête avec cette Idempotency-Key est encore en cours.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Une requête avec cette Idempotency-Key est encore en cours.", "status": 409, "code": "idempotency_in_progress", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "413": { "description": "payload_too_large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "summary": "Le corps de la requête est trop volumineux.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "Le corps de la requête est trop volumineux.", "status": 413, "code": "payload_too_large", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "415": { "description": "unsupported_media_type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "summary": "Ce format n'est pas pris en charge.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Ce format n'est pas pris en charge.", "status": 415, "code": "unsupported_media_type", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed / unknown_field / idempotency_key_reused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "Les données saisies ne sont pas valides.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Les données saisies ne sont pas valides.", "status": 422, "code": "validation_failed", "detail": "1 champ n'est pas valide.", "errors": { "email": [ "Email doit être une adresse e-mail valide." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "Les données contiennent un champ inconnu.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "Les données contiennent un champ inconnu.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "Cette Idempotency-Key a déjà été utilisée pour une autre requête.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Cette Idempotency-Key a déjà été utilisée pour une autre requête.", "status": 422, "code": "idempotency_key_reused", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}": { "get": { "operationId": "dealsGet", "summary": "Récupérer un deal", "description": "Un deal par id. La réponse contient un ETag que vous pouvez envoyer dans If-Match lors d'une modification.", "tags": [ "Deals" ], "x-klantly-scope": "deals.read", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/deals#dealsget" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "L'id (UUID) du deal.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } }, "ETag": { "description": "Version de l'objet, pour If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deal" } }, "additionalProperties": false }, "example": { "data": { "object": "deal", "id": "9d3f7a20-1c5e-4d7b-8a2f-3e4c5d6f7a81", "title": "Veranda 5x3 m", "description": null, "status": "open", "value": "8450.00", "currency": "EUR", "value_source": "manual", "stage": { "object": "pipeline_stage", "id": "3" }, "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "assigned_user_id": "7", "source": "api", "lost_reason": null, "is_archived": false, "stage_changed_at": "2026-09-14T10:15:00Z", "won_at": null, "lost_at": null, "archived_at": null, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Introuvable.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Introuvable.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "patch": { "operationId": "dealsUpdate", "summary": "Modifier un deal", "description": "Modifie uniquement les champs que vous envoyez. Pour changer d'étape, utilisez déplacer, gagner ou perdre. Envoyer value met value_source sur manual.", "tags": [ "Deals" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/deals#dealsupdate" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "L'id (UUID) du deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "required": false, "description": "L'ETag de la version récupérée. Si l'enregistrement a changé entre-temps, vous obtenez 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealsUpdateRequest" }, "example": { "value": "9100.00", "assigned_user_id": 7 } } } }, "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } }, "ETag": { "description": "Version de l'objet, pour If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deal" } }, "additionalProperties": false }, "example": { "data": { "object": "deal", "id": "9d3f7a20-1c5e-4d7b-8a2f-3e4c5d6f7a81", "title": "Veranda 5x3 m", "description": null, "status": "open", "value": "8450.00", "currency": "EUR", "value_source": "manual", "stage": { "object": "pipeline_stage", "id": "3" }, "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "assigned_user_id": "7", "source": "api", "lost_reason": null, "is_archived": false, "stage_changed_at": "2026-09-14T10:15:00Z", "won_at": null, "lost_at": null, "archived_at": null, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Introuvable.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Introuvable.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "412": { "description": "precondition_failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "precondition_failed": { "summary": "L'enregistrement a été modifié entre-temps.", "value": { "type": "https://developers.klantly.com/errors/precondition_failed", "title": "L'enregistrement a été modifié entre-temps.", "status": 412, "code": "precondition_failed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "413": { "description": "payload_too_large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "summary": "Le corps de la requête est trop volumineux.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "Le corps de la requête est trop volumineux.", "status": 413, "code": "payload_too_large", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "415": { "description": "unsupported_media_type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "summary": "Ce format n'est pas pris en charge.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Ce format n'est pas pris en charge.", "status": 415, "code": "unsupported_media_type", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed / unknown_field", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "Les données saisies ne sont pas valides.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Les données saisies ne sont pas valides.", "status": 422, "code": "validation_failed", "detail": "1 champ n'est pas valide.", "errors": { "email": [ "Email doit être une adresse e-mail valide." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "Les données contiennent un champ inconnu.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "Les données contiennent un champ inconnu.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}/move": { "post": { "operationId": "dealsMove", "summary": "Déplacer un deal", "description": "Déplace le deal vers une autre étape, exactement comme un glisser-déposer sur le tableau. S'il s'agit d'une étape gagnée ou perdue, le deal est lui aussi gagné ou perdu.", "tags": [ "Deals" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/deals#dealsmove" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "L'id (UUID) du deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Une clé unique par requête (par exemple un UUID) : une nouvelle tentative ne crée alors pas de doublon. Valable 24 heures.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealsMoveRequest" }, "example": { "stage_id": 3 } } } }, "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } }, "ETag": { "description": "Version de l'objet, pour If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deal" } }, "additionalProperties": false }, "example": { "data": { "object": "deal", "id": "9d3f7a20-1c5e-4d7b-8a2f-3e4c5d6f7a81", "title": "Veranda 5x3 m", "description": null, "status": "open", "value": "8450.00", "currency": "EUR", "value_source": "manual", "stage": { "object": "pipeline_stage", "id": "3" }, "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "assigned_user_id": "7", "source": "api", "lost_reason": null, "is_archived": false, "stage_changed_at": "2026-09-14T10:15:00Z", "won_at": null, "lost_at": null, "archived_at": null, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Introuvable.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Introuvable.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "409": { "description": "idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_in_progress": { "summary": "Une requête avec cette Idempotency-Key est encore en cours.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Une requête avec cette Idempotency-Key est encore en cours.", "status": 409, "code": "idempotency_in_progress", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "413": { "description": "payload_too_large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "summary": "Le corps de la requête est trop volumineux.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "Le corps de la requête est trop volumineux.", "status": 413, "code": "payload_too_large", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "415": { "description": "unsupported_media_type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "summary": "Ce format n'est pas pris en charge.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Ce format n'est pas pris en charge.", "status": 415, "code": "unsupported_media_type", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed / unknown_field / idempotency_key_reused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "Les données saisies ne sont pas valides.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Les données saisies ne sont pas valides.", "status": 422, "code": "validation_failed", "detail": "1 champ n'est pas valide.", "errors": { "email": [ "Email doit être une adresse e-mail valide." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "Les données contiennent un champ inconnu.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "Les données contiennent un champ inconnu.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "Cette Idempotency-Key a déjà été utilisée pour une autre requête.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Cette Idempotency-Key a déjà été utilisée pour une autre requête.", "status": 422, "code": "idempotency_key_reused", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}/win": { "post": { "operationId": "dealsWin", "summary": "Gagner un deal", "description": "Déplace le deal vers l'étape que votre entreprise a définie comme gagnée. S'il est déjà gagné, rien ne change.", "tags": [ "Deals" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/deals#dealswin" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "L'id (UUID) du deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Une clé unique par requête (par exemple un UUID) : une nouvelle tentative ne crée alors pas de doublon. Valable 24 heures.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } }, "ETag": { "description": "Version de l'objet, pour If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deal" } }, "additionalProperties": false }, "example": { "data": { "object": "deal", "id": "9d3f7a20-1c5e-4d7b-8a2f-3e4c5d6f7a81", "title": "Veranda 5x3 m", "description": null, "status": "open", "value": "8450.00", "currency": "EUR", "value_source": "manual", "stage": { "object": "pipeline_stage", "id": "3" }, "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "assigned_user_id": "7", "source": "api", "lost_reason": null, "is_archived": false, "stage_changed_at": "2026-09-14T10:15:00Z", "won_at": null, "lost_at": null, "archived_at": null, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Introuvable.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Introuvable.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "409": { "description": "invalid_state_transition / idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_state_transition": { "summary": "Cette action n'est pas possible dans le statut actuel.", "value": { "type": "https://developers.klantly.com/errors/invalid_state_transition", "title": "Cette action n'est pas possible dans le statut actuel.", "status": 409, "code": "invalid_state_transition", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_in_progress": { "summary": "Une requête avec cette Idempotency-Key est encore en cours.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Une requête avec cette Idempotency-Key est encore en cours.", "status": 409, "code": "idempotency_in_progress", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "idempotency_key_reused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_key_reused": { "summary": "Cette Idempotency-Key a déjà été utilisée pour une autre requête.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Cette Idempotency-Key a déjà été utilisée pour une autre requête.", "status": 422, "code": "idempotency_key_reused", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}/lose": { "post": { "operationId": "dealsLose", "summary": "Perdre un deal", "description": "Déplace le deal vers l'étape que votre entreprise a définie comme perdue, avec une raison facultative.", "tags": [ "Deals" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/deals#dealslose" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "L'id (UUID) du deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Une clé unique par requête (par exemple un UUID) : une nouvelle tentative ne crée alors pas de doublon. Valable 24 heures.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealsLoseRequest" }, "example": { "lost_reason": "Te duur" } } } }, "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } }, "ETag": { "description": "Version de l'objet, pour If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deal" } }, "additionalProperties": false }, "example": { "data": { "object": "deal", "id": "9d3f7a20-1c5e-4d7b-8a2f-3e4c5d6f7a81", "title": "Veranda 5x3 m", "description": null, "status": "open", "value": "8450.00", "currency": "EUR", "value_source": "manual", "stage": { "object": "pipeline_stage", "id": "3" }, "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "assigned_user_id": "7", "source": "api", "lost_reason": null, "is_archived": false, "stage_changed_at": "2026-09-14T10:15:00Z", "won_at": null, "lost_at": null, "archived_at": null, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Introuvable.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Introuvable.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "409": { "description": "invalid_state_transition / idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_state_transition": { "summary": "Cette action n'est pas possible dans le statut actuel.", "value": { "type": "https://developers.klantly.com/errors/invalid_state_transition", "title": "Cette action n'est pas possible dans le statut actuel.", "status": 409, "code": "invalid_state_transition", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_in_progress": { "summary": "Une requête avec cette Idempotency-Key est encore en cours.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Une requête avec cette Idempotency-Key est encore en cours.", "status": 409, "code": "idempotency_in_progress", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "413": { "description": "payload_too_large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "summary": "Le corps de la requête est trop volumineux.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "Le corps de la requête est trop volumineux.", "status": 413, "code": "payload_too_large", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "415": { "description": "unsupported_media_type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "summary": "Ce format n'est pas pris en charge.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Ce format n'est pas pris en charge.", "status": 415, "code": "unsupported_media_type", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed / unknown_field / idempotency_key_reused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "Les données saisies ne sont pas valides.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Les données saisies ne sont pas valides.", "status": 422, "code": "validation_failed", "detail": "1 champ n'est pas valide.", "errors": { "email": [ "Email doit être une adresse e-mail valide." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "Les données contiennent un champ inconnu.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "Les données contiennent un champ inconnu.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "Cette Idempotency-Key a déjà été utilisée pour une autre requête.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Cette Idempotency-Key a déjà été utilisée pour une autre requête.", "status": 422, "code": "idempotency_key_reused", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}/archive": { "post": { "operationId": "dealsArchive", "summary": "Archiver un deal", "description": "Retire le deal du tableau sans le supprimer. Les deals ne peuvent pas être supprimés via l'API.", "tags": [ "Deals" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/deals#dealsarchive" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "L'id (UUID) du deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Une clé unique par requête (par exemple un UUID) : une nouvelle tentative ne crée alors pas de doublon. Valable 24 heures.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } }, "ETag": { "description": "Version de l'objet, pour If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deal" } }, "additionalProperties": false }, "example": { "data": { "object": "deal", "id": "9d3f7a20-1c5e-4d7b-8a2f-3e4c5d6f7a81", "title": "Veranda 5x3 m", "description": null, "status": "open", "value": "8450.00", "currency": "EUR", "value_source": "manual", "stage": { "object": "pipeline_stage", "id": "3" }, "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "assigned_user_id": "7", "source": "api", "lost_reason": null, "is_archived": false, "stage_changed_at": "2026-09-14T10:15:00Z", "won_at": null, "lost_at": null, "archived_at": null, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Introuvable.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Introuvable.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "409": { "description": "idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_in_progress": { "summary": "Une requête avec cette Idempotency-Key est encore en cours.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Une requête avec cette Idempotency-Key est encore en cours.", "status": 409, "code": "idempotency_in_progress", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "idempotency_key_reused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_key_reused": { "summary": "Cette Idempotency-Key a déjà été utilisée pour une autre requête.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Cette Idempotency-Key a déjà été utilisée pour une autre requête.", "status": 422, "code": "idempotency_key_reused", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}/unarchive": { "post": { "operationId": "dealsUnarchive", "summary": "Restaurer un deal", "description": "Remet un deal archivé sur le tableau.", "tags": [ "Deals" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/deals#dealsunarchive" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "L'id (UUID) du deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Une clé unique par requête (par exemple un UUID) : une nouvelle tentative ne crée alors pas de doublon. Valable 24 heures.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } }, "ETag": { "description": "Version de l'objet, pour If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deal" } }, "additionalProperties": false }, "example": { "data": { "object": "deal", "id": "9d3f7a20-1c5e-4d7b-8a2f-3e4c5d6f7a81", "title": "Veranda 5x3 m", "description": null, "status": "open", "value": "8450.00", "currency": "EUR", "value_source": "manual", "stage": { "object": "pipeline_stage", "id": "3" }, "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "assigned_user_id": "7", "source": "api", "lost_reason": null, "is_archived": false, "stage_changed_at": "2026-09-14T10:15:00Z", "won_at": null, "lost_at": null, "archived_at": null, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Introuvable.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Introuvable.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "409": { "description": "idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_in_progress": { "summary": "Une requête avec cette Idempotency-Key est encore en cours.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Une requête avec cette Idempotency-Key est encore en cours.", "status": 409, "code": "idempotency_in_progress", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "idempotency_key_reused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_key_reused": { "summary": "Cette Idempotency-Key a déjà été utilisée pour une autre requête.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Cette Idempotency-Key a déjà été utilisée pour une autre requête.", "status": 422, "code": "idempotency_key_reused", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/webhook-endpoints": { "get": { "operationId": "webhookEndpointsList", "summary": "Lister les endpoints de webhook", "description": "Tous les endpoints de webhook de votre entreprise, le plus ancien en premier. Le secret n'y figure jamais.", "tags": [ "Endpoints de webhook" ], "x-klantly-scope": "webhooks.manage", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/webhook-endpoints#webhook-endpointslist" }, "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "additionalProperties": false }, "example": { "data": [ { "object": "webhook_endpoint", "id": "01j7zr8m2k4n6p8r0t2v4w6y8a", "url": "https://example.com/webhooks/klantly", "description": "Boekhouding", "events": [ "customer.created", "deal.won" ], "status": "active", "disabled_reason": null, "disabled_at": null, "previous_secret_expires_at": null, "last_success_at": "2026-09-14T10:15:02Z", "last_failure_at": null, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } ], "meta": { "limit": 50, "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0", "prev_cursor": null } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "post": { "operationId": "webhookEndpointsCreate", "summary": "Créer un endpoint de webhook", "description": "Enregistre une adresse https qui reçoit les événements. La réponse contient le secret pour vérifier la signature : conservez-le immédiatement, vous ne le reverrez plus. Vous ne pouvez choisir que des événements portant sur des données que votre clé peut lire ; * signifie tous ces événements, y compris les futurs. 10 endpoints au maximum par entreprise.", "tags": [ "Endpoints de webhook" ], "x-klantly-scope": "webhooks.manage", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/webhook-endpoints#webhook-endpointscreate" }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Une clé unique par requête (par exemple un UUID) : une nouvelle tentative ne crée alors pas de doublon. Valable 24 heures.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointsCreateRequest" }, "example": { "url": "https://example.com/webhooks/klantly", "description": "Boekhouding", "events": [ "customer.created", "deal.won" ] } } } }, "responses": { "201": { "description": "Créé", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } }, "ETag": { "description": "Version de l'objet, pour If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpointWithSecret" } }, "additionalProperties": false }, "example": { "data": { "object": "webhook_endpoint", "id": "01j7zr8m2k4n6p8r0t2v4w6y8a", "url": "https://example.com/webhooks/klantly", "description": "Boekhouding", "events": [ "customer.created", "deal.won" ], "status": "active", "disabled_reason": null, "disabled_at": null, "previous_secret_expires_at": null, "last_success_at": "2026-09-14T10:15:02Z", "last_failure_at": null, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z", "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / limit_reached / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "limit_reached": { "summary": "La limite de l'abonnement est atteinte.", "value": { "type": "https://developers.klantly.com/errors/limit_reached", "title": "La limite de l'abonnement est atteinte.", "status": 403, "code": "limit_reached", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "409": { "description": "idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_in_progress": { "summary": "Une requête avec cette Idempotency-Key est encore en cours.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Une requête avec cette Idempotency-Key est encore en cours.", "status": 409, "code": "idempotency_in_progress", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "413": { "description": "payload_too_large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "summary": "Le corps de la requête est trop volumineux.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "Le corps de la requête est trop volumineux.", "status": 413, "code": "payload_too_large", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "415": { "description": "unsupported_media_type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "summary": "Ce format n'est pas pris en charge.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Ce format n'est pas pris en charge.", "status": 415, "code": "unsupported_media_type", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed / unknown_field / idempotency_key_reused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "Les données saisies ne sont pas valides.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Les données saisies ne sont pas valides.", "status": 422, "code": "validation_failed", "detail": "1 champ n'est pas valide.", "errors": { "email": [ "Email doit être une adresse e-mail valide." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "Les données contiennent un champ inconnu.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "Les données contiennent un champ inconnu.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "Cette Idempotency-Key a déjà été utilisée pour une autre requête.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Cette Idempotency-Key a déjà été utilisée pour une autre requête.", "status": 422, "code": "idempotency_key_reused", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/webhook-endpoints/{endpoint}": { "get": { "operationId": "webhookEndpointsGet", "summary": "Récupérer un endpoint de webhook", "description": "Un endpoint par id, avec son statut et l'heure de la dernière livraison réussie et de la dernière livraison échouée.", "tags": [ "Endpoints de webhook" ], "x-klantly-scope": "webhooks.manage", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/webhook-endpoints#webhook-endpointsget" }, "parameters": [ { "name": "endpoint", "in": "path", "required": true, "description": "L'id de l'endpoint de webhook.", "schema": { "type": "string", "pattern": "^[0-9a-z]{26}$" } } ], "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } }, "ETag": { "description": "Version de l'objet, pour If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "additionalProperties": false }, "example": { "data": { "object": "webhook_endpoint", "id": "01j7zr8m2k4n6p8r0t2v4w6y8a", "url": "https://example.com/webhooks/klantly", "description": "Boekhouding", "events": [ "customer.created", "deal.won" ], "status": "active", "disabled_reason": null, "disabled_at": null, "previous_secret_expires_at": null, "last_success_at": "2026-09-14T10:15:02Z", "last_failure_at": null, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Introuvable.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Introuvable.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "patch": { "operationId": "webhookEndpointsUpdate", "summary": "Modifier un endpoint de webhook", "description": "Modifie uniquement les champs que vous envoyez. Avec status, vous désactivez ou réactivez l'endpoint ; la réactivation remet le compteur d'erreurs à zéro.", "tags": [ "Endpoints de webhook" ], "x-klantly-scope": "webhooks.manage", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/webhook-endpoints#webhook-endpointsupdate" }, "parameters": [ { "name": "endpoint", "in": "path", "required": true, "description": "L'id de l'endpoint de webhook.", "schema": { "type": "string", "pattern": "^[0-9a-z]{26}$" } }, { "name": "If-Match", "in": "header", "required": false, "description": "L'ETag de la version récupérée. Si l'enregistrement a changé entre-temps, vous obtenez 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointsUpdateRequest" }, "example": { "events": [ "*" ], "status": "active" } } } }, "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } }, "ETag": { "description": "Version de l'objet, pour If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "additionalProperties": false }, "example": { "data": { "object": "webhook_endpoint", "id": "01j7zr8m2k4n6p8r0t2v4w6y8a", "url": "https://example.com/webhooks/klantly", "description": "Boekhouding", "events": [ "customer.created", "deal.won" ], "status": "active", "disabled_reason": null, "disabled_at": null, "previous_secret_expires_at": null, "last_success_at": "2026-09-14T10:15:02Z", "last_failure_at": null, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Introuvable.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Introuvable.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "412": { "description": "precondition_failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "precondition_failed": { "summary": "L'enregistrement a été modifié entre-temps.", "value": { "type": "https://developers.klantly.com/errors/precondition_failed", "title": "L'enregistrement a été modifié entre-temps.", "status": 412, "code": "precondition_failed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "413": { "description": "payload_too_large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "summary": "Le corps de la requête est trop volumineux.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "Le corps de la requête est trop volumineux.", "status": 413, "code": "payload_too_large", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "415": { "description": "unsupported_media_type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "summary": "Ce format n'est pas pris en charge.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Ce format n'est pas pris en charge.", "status": 415, "code": "unsupported_media_type", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed / unknown_field", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "Les données saisies ne sont pas valides.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Les données saisies ne sont pas valides.", "status": 422, "code": "validation_failed", "detail": "1 champ n'est pas valide.", "errors": { "email": [ "Email doit être une adresse e-mail valide." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "Les données contiennent un champ inconnu.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "Les données contiennent un champ inconnu.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "delete": { "operationId": "webhookEndpointsDelete", "summary": "Supprimer un endpoint de webhook", "description": "Supprime l'endpoint. Les événements encore en cours d'envoi ne sont plus livrés.", "tags": [ "Endpoints de webhook" ], "x-klantly-scope": "webhooks.manage", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/webhook-endpoints#webhook-endpointsdelete" }, "parameters": [ { "name": "endpoint", "in": "path", "required": true, "description": "L'id de l'endpoint de webhook.", "schema": { "type": "string", "pattern": "^[0-9a-z]{26}$" } } ], "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } }, "ETag": { "description": "Version de l'objet, pour If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DeletedObject" } }, "additionalProperties": false }, "example": { "data": { "object": "note", "id": "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92", "deleted": true } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Introuvable.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Introuvable.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/webhook-endpoints/{endpoint}/test": { "post": { "operationId": "webhookEndpointsTest", "summary": "Envoyer un message de test", "description": "Envoie immédiatement l'événement ping à l'endpoint, même s'il est désactivé, et renvoie la tentative de livraison. Un message de test n'est pas renvoyé en cas d'échec.", "tags": [ "Endpoints de webhook" ], "x-klantly-scope": "webhooks.manage", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/webhook-endpoints#webhook-endpointstest" }, "parameters": [ { "name": "endpoint", "in": "path", "required": true, "description": "L'id de l'endpoint de webhook.", "schema": { "type": "string", "pattern": "^[0-9a-z]{26}$" } } ], "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } }, "ETag": { "description": "Version de l'objet, pour If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookDelivery" } }, "additionalProperties": false }, "example": { "data": { "object": "webhook_delivery", "id": "1834", "webhook_endpoint_id": "01j7zr8m2k4n6p8r0t2v4w6y8a", "event_id": "evt_01j7zs1a2b3c4d5e6f7g8h9j0k", "event_type": "ping", "attempt": 1, "status": "succeeded", "response_status": 200, "error": null, "duration_ms": 184, "created_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Introuvable.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Introuvable.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/webhook-endpoints/{endpoint}/rotate-secret": { "post": { "operationId": "webhookEndpointsRotateSecret", "summary": "Renouveler le secret", "description": "Crée un nouveau secret et le renvoie une seule fois. Pendant le chevauchement, Klantly signe avec l'ancien et le nouveau secret, pour que votre récepteur puisse basculer sans interruption.", "tags": [ "Endpoints de webhook" ], "x-klantly-scope": "webhooks.manage", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/webhook-endpoints#webhook-endpointsrotate-secret" }, "parameters": [ { "name": "endpoint", "in": "path", "required": true, "description": "L'id de l'endpoint de webhook.", "schema": { "type": "string", "pattern": "^[0-9a-z]{26}$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Une clé unique par requête (par exemple un UUID) : une nouvelle tentative ne crée alors pas de doublon. Valable 24 heures.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointsRotateSecretRequest" }, "example": { "overlap_hours": 24 } } } }, "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } }, "ETag": { "description": "Version de l'objet, pour If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpointWithSecret" } }, "additionalProperties": false }, "example": { "data": { "object": "webhook_endpoint", "id": "01j7zr8m2k4n6p8r0t2v4w6y8a", "url": "https://example.com/webhooks/klantly", "description": "Boekhouding", "events": [ "customer.created", "deal.won" ], "status": "active", "disabled_reason": null, "disabled_at": null, "previous_secret_expires_at": null, "last_success_at": "2026-09-14T10:15:02Z", "last_failure_at": null, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z", "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Introuvable.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Introuvable.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "409": { "description": "idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_in_progress": { "summary": "Une requête avec cette Idempotency-Key est encore en cours.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Une requête avec cette Idempotency-Key est encore en cours.", "status": 409, "code": "idempotency_in_progress", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "413": { "description": "payload_too_large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "summary": "Le corps de la requête est trop volumineux.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "Le corps de la requête est trop volumineux.", "status": 413, "code": "payload_too_large", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "415": { "description": "unsupported_media_type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "summary": "Ce format n'est pas pris en charge.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Ce format n'est pas pris en charge.", "status": 415, "code": "unsupported_media_type", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed / unknown_field / idempotency_key_reused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "Les données saisies ne sont pas valides.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Les données saisies ne sont pas valides.", "status": 422, "code": "validation_failed", "detail": "1 champ n'est pas valide.", "errors": { "email": [ "Email doit être une adresse e-mail valide." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "Les données contiennent un champ inconnu.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "Les données contiennent un champ inconnu.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "Cette Idempotency-Key a déjà été utilisée pour une autre requête.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Cette Idempotency-Key a déjà été utilisée pour une autre requête.", "status": 422, "code": "idempotency_key_reused", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/events": { "get": { "operationId": "eventsList", "summary": "Lister les événements", "description": "Les événements des 30 derniers jours, le plus récent en premier. Vous ne voyez que les événements portant sur des données que votre clé peut lire. Avec sort=created_at et filter[created_since], vous rattrapez les événements manqués dans l'ordre.", "tags": [ "Événements" ], "x-klantly-scope": "events.read", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/events#eventslist" }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Nombre de résultats par page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Le next_cursor ou prev_cursor de meta dans la réponse précédente.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "created_at respecte l'ordre dans lequel tout s'est produit, -created_at (par défaut) affiche le plus récent en premier.", "schema": { "type": "string", "enum": [ "-created_at", "created_at" ], "default": "-created_at" } }, { "name": "filter[type]", "in": "query", "required": false, "description": "Uniquement ces types d'événements, séparés par des virgules, par exemple customer.created,deal.won.", "schema": { "type": "string", "maxLength": 500 } }, { "name": "filter[created_since]", "in": "query", "required": false, "description": "Uniquement les événements à partir de ce moment : ISO 8601 avec fuseau horaire, par exemple 2026-09-14T10:15:00Z.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "additionalProperties": false }, "example": { "data": [ { "object": "event", "id": "evt_01j7zs1a2b3c4d5e6f7g8h9j0k", "type": "customer.created", "created_at": "2026-09-14T10:15:00Z", "data": { "object": { "object": "customer", "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "type": "business", "status": "lead", "name": "Jan de Vries", "email": "jan@example.com", "phone": "+31 6 12345678", "company_name": "De Vries Bouw", "vat_number": "NL123456789B01", "coc_number": "12345678", "address": "Dorpsstraat 1", "postal_code": "3511 AB", "city": "Utrecht", "country": "NL", "email_unsubscribed": false, "converted_at": null, "last_activity_at": "2026-09-14T10:15:00Z", "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } ], "meta": { "limit": 50, "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0", "prev_cursor": null } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "Les données saisies ne sont pas valides.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Les données saisies ne sont pas valides.", "status": 422, "code": "validation_failed", "detail": "1 champ n'est pas valide.", "errors": { "email": [ "Email doit être une adresse e-mail valide." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/events/{event}": { "get": { "operationId": "eventsGet", "summary": "Récupérer un événement", "description": "Un événement par id, par exemple le webhook-id d'un message reçu.", "tags": [ "Événements" ], "x-klantly-scope": "events.read", "externalDocs": { "url": "https://developers.klantly.com/fr/reference/events#eventsget" }, "parameters": [ { "name": "event", "in": "path", "required": true, "description": "L'id de l'événement (evt_…).", "schema": { "type": "string", "pattern": "^evt_[0-9a-z]{26}$" } } ], "responses": { "200": { "description": "Réussi", "headers": { "X-Request-Id": { "description": "Id unique de cette requête. Indiquez-le en contactant le support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Requêtes restantes et secondes avant la réinitialisation de la limite la plus stricte.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Toutes les limites qui s'appliquent à cette requête.", "schema": { "type": "string" } }, "ETag": { "description": "Version de l'objet, pour If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Event" } }, "additionalProperties": false }, "example": { "data": { "object": "event", "id": "evt_01j7zs1a2b3c4d5e6f7g8h9j0k", "type": "customer.created", "created_at": "2026-09-14T10:15:00Z", "data": { "object": { "object": "customer", "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "type": "business", "status": "lead", "name": "Jan de Vries", "email": "jan@example.com", "phone": "+31 6 12345678", "company_name": "De Vries Bouw", "vat_number": "NL123456789B01", "coc_number": "12345678", "address": "Dorpsstraat 1", "postal_code": "3511 AB", "city": "Utrecht", "country": "NL", "email_unsubscribed": false, "converted_at": null, "last_activity_at": "2026-09-14T10:15:00Z", "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authentification requise.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentification requise.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Clé API invalide.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Clé API invalide.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Cette clé API a été révoquée.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Cette clé API a été révoquée.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Cette clé API a expiré.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Cette clé API a expiré.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Cette clé API n'a pas accès à cette action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Cette clé API n'a pas accès à cette action.", "status": 403, "code": "insufficient_scope", "detail": "Le scope customers.write est nécessaire. Modifiez les scopes de la clé dans Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Cette adresse IP ne peut pas utiliser cette clé API.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Cette adresse IP ne peut pas utiliser cette clé API.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Le compte de cette entreprise est bloqué.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Le compte de cette entreprise est bloqué.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Cette entreprise n'a pas d'abonnement actif.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Cette entreprise n'a pas d'abonnement actif.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Cette fonctionnalité n'est pas disponible pour cette entreprise.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Introuvable.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Introuvable.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Trop de requêtes.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Trop de requêtes.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Un problème est survenu de notre côté.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Un problème est survenu de notre côté.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Clé API de votre entreprise (kly_…), à créer dans Klantly sous Intégrations → API." } }, "schemas": { "Problem": { "type": "object", "description": "Une erreur selon la RFC 9457 (problem details).", "required": [ "type", "title", "status", "code" ], "properties": { "type": { "type": "string", "format": "uri", "description": "URL de la page qui explique cette erreur." }, "title": { "type": "string", "description": "Courte description, dans la langue de la requête." }, "status": { "type": "integer", "description": "Code de statut HTTP." }, "code": { "type": "string", "enum": [ "bad_request", "unauthenticated", "invalid_api_key", "api_key_revoked", "api_key_expired", "ip_not_allowed", "account_suspended", "subscription_inactive", "feature_not_available", "insufficient_scope", "forbidden", "limit_reached", "not_found", "method_not_allowed", "conflict", "invalid_state_transition", "idempotency_in_progress", "precondition_failed", "payload_too_large", "unsupported_media_type", "validation_failed", "unknown_field", "idempotency_key_reused", "rate_limited", "server_error", "api_disabled" ], "description": "Code d'erreur fixe, en anglais : programmez sur celui-ci." }, "detail": { "type": "string", "description": "Explication de cette erreur précise." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Erreurs de validation par champ." }, "request_id": { "type": "string", "description": "Id de la requête, pour le support." } } }, "ListMeta": { "type": "object", "required": [ "limit", "next_cursor", "prev_cursor" ], "properties": { "limit": { "type": "integer", "description": "Nombre de résultats par page.", "examples": [ 50 ] }, "next_cursor": { "type": [ "string", "null" ], "description": "Curseur de la page suivante, ou null sur la dernière page.", "examples": [ "eyJpZCI6IjlkM2Y2YzFlIn0" ] }, "prev_cursor": { "type": [ "string", "null" ], "description": "Curseur de la page précédente, ou null sur la première page.", "examples": [ null ] } }, "additionalProperties": false }, "Customer": { "type": "object", "required": [ "object", "id", "type", "status", "name", "email", "phone", "company_name", "vat_number", "coc_number", "address", "postal_code", "city", "country", "email_unsubscribed", "converted_at", "last_activity_at", "created_at", "updated_at" ], "properties": { "object": { "type": "string", "const": "customer", "description": "Toujours « customer ».", "examples": [ "customer" ] }, "id": { "type": "string", "format": "uuid", "description": "Id unique (UUID).", "examples": [ "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" ] }, "type": { "type": "string", "enum": [ "individual", "business" ], "description": "individual (particulier) ou business (entreprise).", "examples": [ "business" ] }, "status": { "type": "string", "enum": [ "lead", "customer" ], "description": "lead (prospect) ou customer (client).", "examples": [ "lead" ] }, "name": { "type": [ "string", "null" ], "description": "Nom de la personne de contact.", "examples": [ "Jan de Vries" ] }, "email": { "type": "string", "format": "email", "description": "Adresse e-mail ; unique au sein de votre entreprise.", "examples": [ "jan@example.com" ] }, "phone": { "type": [ "string", "null" ], "description": "Numéro de téléphone.", "examples": [ "+31 6 12345678" ] }, "company_name": { "type": [ "string", "null" ], "description": "Nom de l'entreprise, pour un client professionnel.", "examples": [ "De Vries Bouw" ] }, "vat_number": { "type": [ "string", "null" ], "description": "Numéro de TVA.", "examples": [ "NL123456789B01" ] }, "coc_number": { "type": [ "string", "null" ], "description": "Numéro d'immatriculation (registre du commerce).", "examples": [ "12345678" ] }, "address": { "type": [ "string", "null" ], "description": "Rue et numéro.", "examples": [ "Dorpsstraat 1" ] }, "postal_code": { "type": [ "string", "null" ], "description": "Code postal.", "examples": [ "3511 AB" ] }, "city": { "type": [ "string", "null" ], "description": "Ville.", "examples": [ "Utrecht" ] }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Pays.", "examples": [ "NL" ] }, "email_unsubscribed": { "type": "boolean", "description": "S'est désabonné des e-mails.", "examples": [ false ] }, "converted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Date à laquelle le prospect est devenu client.", "examples": [ null ] }, "last_activity_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Dernière activité dans Klantly.", "examples": [ "2026-09-14T10:15:00Z" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Créé le (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Dernière modification le (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] } }, "additionalProperties": false }, "ApiKey": { "type": "object", "required": [ "object", "id", "name", "prefix", "scopes", "expires_at", "created_at", "company", "rate_limits" ], "properties": { "object": { "type": "string", "const": "api_key", "description": "Toujours « api_key ».", "examples": [ "api_key" ] }, "id": { "type": "string", "description": "Id de la clé.", "examples": [ "01j7zq3k9x2m4n6p8r0t2v4w6y" ] }, "name": { "type": "string", "description": "Le nom donné à la clé dans Klantly.", "examples": [ "Website" ] }, "prefix": { "type": "string", "description": "Le début de la clé, pour la reconnaître.", "examples": [ "kly_4fZ2mQ8v" ] }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Les scopes de la clé.", "examples": [ [ "customers.read", "customers.write" ] ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Date d'expiration, ou null si la clé n'expire pas.", "examples": [ "2027-09-14T10:15:00Z" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Créée le (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "company": { "description": "L'entreprise à laquelle appartient la clé.", "type": "object", "required": [ "object", "id", "name" ], "properties": { "object": { "type": "string", "const": "company", "description": "Toujours « company ».", "examples": [ "company" ] }, "id": { "type": "string", "description": "Id de l'entreprise.", "examples": [ "42" ] }, "name": { "type": "string", "description": "Nom de l'entreprise.", "examples": [ "De Vries Bouw" ] } }, "additionalProperties": false }, "rate_limits": { "type": "array", "items": { "type": "object", "required": [ "name", "limit", "window_seconds" ], "properties": { "name": { "type": "string", "description": "Nom de la limite.", "examples": [ "key_minute" ] }, "limit": { "type": "integer", "description": "Nombre maximal de requêtes dans la fenêtre.", "examples": [ 120 ] }, "window_seconds": { "type": "integer", "description": "Durée de la fenêtre en secondes.", "examples": [ 60 ] } }, "additionalProperties": false }, "description": "Les limites qui s'appliquent à cette clé.", "examples": [ [ { "name": "key_minute", "limit": 120, "window_seconds": 60 } ] ] } }, "additionalProperties": false }, "Company": { "type": "object", "required": [ "object", "id", "name", "email", "phone", "website", "coc_number", "vat_number", "address", "postal_code", "city", "country", "language", "currency", "timezone", "default_vat_rate", "prices_include_vat" ], "properties": { "object": { "type": "string", "const": "company", "description": "Toujours « company ».", "examples": [ "company" ] }, "id": { "type": "string", "description": "Id de l'entreprise.", "examples": [ "42" ] }, "name": { "type": "string", "description": "Nom de l'entreprise.", "examples": [ "De Vries Bouw" ] }, "email": { "type": [ "string", "null" ], "description": "Adresse e-mail générale.", "examples": [ "info@devriesbouw.nl" ] }, "phone": { "type": [ "string", "null" ], "description": "Numéro de téléphone.", "examples": [ "+31 30 1234567" ] }, "website": { "type": [ "string", "null" ], "description": "Site web.", "examples": [ "https://devriesbouw.nl" ] }, "coc_number": { "type": [ "string", "null" ], "description": "Numéro d'immatriculation (registre du commerce).", "examples": [ "12345678" ] }, "vat_number": { "type": [ "string", "null" ], "description": "Numéro de TVA.", "examples": [ "NL123456789B01" ] }, "address": { "type": [ "string", "null" ], "description": "Rue et numéro.", "examples": [ "Industrieweg 5" ] }, "postal_code": { "type": [ "string", "null" ], "description": "Code postal.", "examples": [ "3542 AD" ] }, "city": { "type": [ "string", "null" ], "description": "Ville.", "examples": [ "Utrecht" ] }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Pays, sous forme de code ISO à deux lettres (par exemple FR).", "examples": [ "NL" ] }, "language": { "type": "string", "enum": [ "nl", "en", "de", "fr" ], "description": "Langue principale de l'entreprise.", "examples": [ "nl" ] }, "currency": { "type": "string", "const": "EUR", "description": "Toujours « EUR ».", "examples": [ "EUR" ] }, "timezone": { "type": "string", "description": "Fuseau horaire dans lequel Klantly affiche les heures à l'entreprise. L'API renvoie toujours les heures en UTC.", "examples": [ "Europe/Amsterdam" ] }, "default_vat_rate": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Taux de TVA par défaut en pourcentage, sous forme de texte à deux décimales.", "examples": [ "21.00" ] }, "prices_include_vat": { "type": "boolean", "description": "Si les prix sont saisis TTC par défaut.", "examples": [ false ] } }, "additionalProperties": false }, "User": { "type": "object", "required": [ "object", "id", "name", "email", "role", "is_owner", "status", "created_at" ], "properties": { "object": { "type": "string", "const": "user", "description": "Toujours « user ».", "examples": [ "user" ] }, "id": { "type": "string", "description": "Id de l'utilisateur.", "examples": [ "7" ] }, "name": { "type": "string", "description": "Nom.", "examples": [ "Sanne Bakker" ] }, "email": { "type": "string", "format": "email", "description": "Adresse e-mail.", "examples": [ "sanne@devriesbouw.nl" ] }, "role": { "type": [ "string", "null" ], "description": "Nom du rôle dans votre entreprise, ou null sans rôle.", "examples": [ "Verkoop" ] }, "is_owner": { "type": "boolean", "description": "Le propriétaire du compte.", "examples": [ false ] }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "active ou inactive (désactivé).", "examples": [ "active" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Créé le (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] } }, "additionalProperties": false }, "CustomerActivity": { "type": "object", "required": [ "object", "id", "customer_id", "type", "title", "description", "related", "happened_at", "created_at" ], "properties": { "object": { "type": "string", "const": "customer_activity", "description": "Toujours « customer_activity ».", "examples": [ "customer_activity" ] }, "id": { "type": "string", "format": "uuid", "description": "Id unique (UUID).", "examples": [ "9d3f7c62-3e7a-4f9d-8c4b-5a6e7f8a9ba3" ] }, "customer_id": { "type": "string", "format": "uuid", "description": "Le client auquel l'activité appartient.", "examples": [ "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" ] }, "type": { "type": "string", "description": "Type d'activité, par exemple quote_sent, invoice_created ou appointment_created. De nouveaux types peuvent apparaître : traitez proprement une valeur inconnue.", "examples": [ "quote_sent" ] }, "title": { "type": [ "string", "null" ], "description": "Brève description.", "examples": [ null ] }, "description": { "type": [ "string", "null" ], "description": "Précisions.", "examples": [ null ] }, "related": { "description": "Références aux enregistrements liés ; seules celles qui s'appliquent ont une valeur.", "type": "object", "required": [ "quote_id", "invoice_id", "appointment_id", "work_order_id", "task_id", "deal_id", "order_id", "conversation_id" ], "properties": { "quote_id": { "type": [ "string", "null" ], "description": "Id du devis lié.", "examples": [ null ] }, "invoice_id": { "type": [ "string", "null" ], "description": "Id de la facture liée.", "examples": [ null ] }, "appointment_id": { "type": [ "string", "null" ], "description": "Id du rendez-vous lié.", "examples": [ null ] }, "work_order_id": { "type": [ "string", "null" ], "description": "Id du bon d'intervention lié.", "examples": [ null ] }, "task_id": { "type": [ "string", "null" ], "description": "Id de la tâche liée.", "examples": [ null ] }, "deal_id": { "type": [ "string", "null" ], "description": "Id du deal lié.", "examples": [ null ] }, "order_id": { "type": [ "string", "null" ], "description": "Id de la commande liée.", "examples": [ null ] }, "conversation_id": { "type": [ "string", "null" ], "description": "Id de la conversation liée.", "examples": [ null ] } }, "additionalProperties": false }, "happened_at": { "type": "string", "format": "date-time", "description": "Quand cela s'est produit (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Enregistré le (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] } }, "additionalProperties": false }, "Note": { "type": "object", "required": [ "object", "id", "content", "is_important", "parent", "author", "created_at", "updated_at" ], "properties": { "object": { "type": "string", "const": "note", "description": "Toujours « note ».", "examples": [ "note" ] }, "id": { "type": "string", "format": "uuid", "description": "Id unique (UUID).", "examples": [ "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92" ] }, "content": { "type": "string", "description": "Le texte de la note.", "examples": [ "Klant belt terug na de vakantie." ] }, "is_important": { "type": "boolean", "description": "Marquée comme importante.", "examples": [ true ] }, "parent": { "description": "Ce à quoi la note appartient.", "type": "object", "required": [ "object", "id" ], "properties": { "object": { "type": "string", "enum": [ "customer", "deal" ], "description": "« customer » ou « deal ».", "examples": [ "customer" ] }, "id": { "type": "string", "format": "uuid", "description": "Id du client ou du deal.", "examples": [ "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" ] } }, "additionalProperties": false }, "author": { "description": "Qui a écrit la note, ou null pour une note ajoutée via l'API.", "type": [ "object", "null" ], "required": [ "object", "id", "name" ], "properties": { "object": { "type": "string", "const": "user", "description": "Toujours « user ».", "examples": [ "user" ] }, "id": { "type": "string", "description": "Id de l'utilisateur.", "examples": [ "7" ] }, "name": { "type": "string", "description": "Nom de l'utilisateur.", "examples": [ "Sanne Bakker" ] } }, "additionalProperties": false }, "created_at": { "type": "string", "format": "date-time", "description": "Créé le (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Dernière modification le (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] } }, "additionalProperties": false }, "PipelineStage": { "type": "object", "required": [ "object", "id", "name", "names", "type", "is_default", "position", "probability", "color" ], "properties": { "object": { "type": "string", "const": "pipeline_stage", "description": "Toujours « pipeline_stage ».", "examples": [ "pipeline_stage" ] }, "id": { "type": "string", "description": "Id de l'étape.", "examples": [ "3" ] }, "name": { "type": "string", "description": "Nom dans la langue de la requête.", "examples": [ "Offerte verstuurd" ] }, "names": { "description": "Le nom dans les quatre langues.", "type": "object", "required": [ "nl", "en", "de", "fr" ], "properties": { "nl": { "type": [ "string", "null" ], "description": "Nom néerlandais.", "examples": [ "Offerte verstuurd" ] }, "en": { "type": [ "string", "null" ], "description": "Nom anglais.", "examples": [ "Quote sent" ] }, "de": { "type": [ "string", "null" ], "description": "Nom allemand.", "examples": [ "Angebot gesendet" ] }, "fr": { "type": [ "string", "null" ], "description": "Nom français.", "examples": [ "Devis envoyé" ] } }, "additionalProperties": false }, "type": { "type": "string", "enum": [ "open", "won", "lost" ], "description": "open (ouvert), won (gagné) ou lost (perdu) : un deal dans cette étape reçoit ce statut.", "examples": [ "open" ] }, "is_default": { "type": "boolean", "description": "Les nouveaux deals arrivent dans cette étape.", "examples": [ false ] }, "position": { "type": "integer", "description": "Position sur le tableau, de gauche à droite.", "examples": [ 3 ] }, "probability": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Probabilité de gain en pourcentage, sous forme de texte à deux décimales.", "examples": [ "50.00" ] }, "color": { "type": [ "string", "null" ], "description": "Couleur sur le tableau (hex).", "examples": [ "#3B82F6" ] } }, "additionalProperties": false }, "Deal": { "type": "object", "required": [ "object", "id", "title", "description", "status", "value", "currency", "value_source", "stage", "customer_id", "assigned_user_id", "source", "lost_reason", "is_archived", "stage_changed_at", "won_at", "lost_at", "archived_at", "created_at", "updated_at" ], "properties": { "object": { "type": "string", "const": "deal", "description": "Toujours « deal ».", "examples": [ "deal" ] }, "id": { "type": "string", "format": "uuid", "description": "Id unique (UUID).", "examples": [ "9d3f7a20-1c5e-4d7b-8a2f-3e4c5d6f7a81" ] }, "title": { "type": "string", "description": "Titre du deal.", "examples": [ "Veranda 5x3 m" ] }, "description": { "type": [ "string", "null" ], "description": "Description.", "examples": [ null ] }, "status": { "type": "string", "enum": [ "open", "won", "lost" ], "description": "open (ouvert), won (gagné) ou lost (perdu) ; découle de l'étape.", "examples": [ "open" ] }, "value": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Valeur sous forme de texte à deux décimales, par exemple « 8450.00 ». À la création et à la modification, vous pouvez aussi envoyer un nombre.", "examples": [ "8450.00" ] }, "currency": { "type": "string", "const": "EUR", "description": "Toujours « EUR ».", "examples": [ "EUR" ] }, "value_source": { "type": "string", "enum": [ "quotes", "manual" ], "description": "quotes : la valeur découle des devis liés ; manual : définie à la main.", "examples": [ "manual" ] }, "stage": { "description": "L'étape dans laquelle se trouve le deal ; les noms figurent dans Lister les étapes du pipeline.", "type": [ "object", "null" ], "required": [ "object", "id" ], "properties": { "object": { "type": "string", "const": "pipeline_stage", "description": "Toujours « pipeline_stage ».", "examples": [ "pipeline_stage" ] }, "id": { "type": "string", "description": "Id de l'étape.", "examples": [ "3" ] } }, "additionalProperties": false }, "customer_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Le client du deal.", "examples": [ "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" ] }, "assigned_user_id": { "type": [ "string", "null" ], "description": "L'utilisateur qui gère le deal, ou null.", "examples": [ "7" ] }, "source": { "type": [ "string", "null" ], "description": "D'où vient le deal ; via l'API, c'est api.", "examples": [ "api" ] }, "lost_reason": { "type": [ "string", "null" ], "description": "Pourquoi le deal a été perdu, ou null.", "examples": [ null ] }, "is_archived": { "type": "boolean", "description": "Archivé : n'est plus sur le tableau.", "examples": [ false ] }, "stage_changed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Quand le deal a changé d'étape pour la dernière fois.", "examples": [ "2026-09-14T10:15:00Z" ] }, "won_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Quand le deal a été gagné.", "examples": [ null ] }, "lost_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Quand le deal a été perdu.", "examples": [ null ] }, "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Quand le deal a été archivé.", "examples": [ null ] }, "created_at": { "type": "string", "format": "date-time", "description": "Créé le (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Dernière modification le (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] } }, "additionalProperties": false }, "DealAction": { "type": "object", "required": [ "stage_id", "notes" ], "properties": { "stage_id": { "type": "integer", "description": "L'id de l'étape vers laquelle le deal est déplacé (voir Lister les étapes du pipeline).", "examples": [ 3 ] }, "notes": { "type": [ "string", "null" ], "description": "Remarque facultative ; conservée avec le changement d'étape dans l'historique du deal.", "examples": [ null ] } }, "additionalProperties": false }, "WebhookEndpoint": { "type": "object", "required": [ "object", "id", "url", "description", "events", "status", "disabled_reason", "disabled_at", "previous_secret_expires_at", "last_success_at", "last_failure_at", "created_at", "updated_at" ], "properties": { "object": { "type": "string", "const": "webhook_endpoint", "description": "Toujours « webhook_endpoint ».", "examples": [ "webhook_endpoint" ] }, "id": { "type": "string", "description": "Id de l'endpoint.", "examples": [ "01j7zr8m2k4n6p8r0t2v4w6y8a" ] }, "url": { "type": "string", "format": "uri", "description": "L'adresse https à laquelle Klantly envoie les événements. Pas d'adresses internes, et uniquement les ports 443, 80 ou 8443.", "examples": [ "https://example.com/webhooks/klantly" ] }, "description": { "type": [ "string", "null" ], "description": "Votre propre description, par exemple à quoi sert l'endpoint.", "examples": [ "Boekhouding" ] }, "events": { "type": "array", "items": { "type": "string" }, "description": "Les types d'événements que cet endpoint reçoit, ou [\"*\"] pour tous les événements que la clé ou l'utilisateur peut lire.", "examples": [ [ "customer.created", "deal.won" ] ] }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "active ou disabled (désactivé).", "examples": [ "active" ] }, "disabled_reason": { "type": [ "string", "null" ], "enum": [ "failing", "manual", null, null ], "description": "Pourquoi l'endpoint est désactivé : failing (uniquement des erreurs pendant 5 jours) ou manual (à la main), sinon null.", "examples": [ null ] }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Quand l'endpoint a été désactivé.", "examples": [ null ] }, "previous_secret_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Jusqu'à quand l'ancien secret est encore utilisé après un renouvellement, sinon null.", "examples": [ null ] }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Dernière livraison réussie.", "examples": [ "2026-09-14T10:15:02Z" ] }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Dernière livraison échouée.", "examples": [ null ] }, "created_at": { "type": "string", "format": "date-time", "description": "Créé le (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Dernière modification le (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] } }, "additionalProperties": false }, "WebhookEndpointWithSecret": { "type": "object", "required": [ "object", "id", "url", "description", "events", "status", "disabled_reason", "disabled_at", "previous_secret_expires_at", "last_success_at", "last_failure_at", "created_at", "updated_at", "secret" ], "properties": { "object": { "type": "string", "const": "webhook_endpoint", "description": "Toujours « webhook_endpoint ».", "examples": [ "webhook_endpoint" ] }, "id": { "type": "string", "description": "Id de l'endpoint.", "examples": [ "01j7zr8m2k4n6p8r0t2v4w6y8a" ] }, "url": { "type": "string", "format": "uri", "description": "L'adresse https à laquelle Klantly envoie les événements. Pas d'adresses internes, et uniquement les ports 443, 80 ou 8443.", "examples": [ "https://example.com/webhooks/klantly" ] }, "description": { "type": [ "string", "null" ], "description": "Votre propre description, par exemple à quoi sert l'endpoint.", "examples": [ "Boekhouding" ] }, "events": { "type": "array", "items": { "type": "string" }, "description": "Les types d'événements que cet endpoint reçoit, ou [\"*\"] pour tous les événements que la clé ou l'utilisateur peut lire.", "examples": [ [ "customer.created", "deal.won" ] ] }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "active ou disabled (désactivé).", "examples": [ "active" ] }, "disabled_reason": { "type": [ "string", "null" ], "enum": [ "failing", "manual", null, null ], "description": "Pourquoi l'endpoint est désactivé : failing (uniquement des erreurs pendant 5 jours) ou manual (à la main), sinon null.", "examples": [ null ] }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Quand l'endpoint a été désactivé.", "examples": [ null ] }, "previous_secret_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Jusqu'à quand l'ancien secret est encore utilisé après un renouvellement, sinon null.", "examples": [ null ] }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Dernière livraison réussie.", "examples": [ "2026-09-14T10:15:02Z" ] }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Dernière livraison échouée.", "examples": [ null ] }, "created_at": { "type": "string", "format": "date-time", "description": "Créé le (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Dernière modification le (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "secret": { "type": "string", "pattern": "^whsec_", "description": "Le secret (whsec_…) pour vérifier les signatures. Uniquement dans cette réponse : conservez-le immédiatement.", "examples": [ "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw" ] } }, "additionalProperties": false }, "WebhookDelivery": { "type": "object", "required": [ "object", "id", "webhook_endpoint_id", "event_id", "event_type", "attempt", "status", "response_status", "error", "duration_ms", "created_at" ], "properties": { "object": { "type": "string", "const": "webhook_delivery", "description": "Toujours « webhook_delivery ».", "examples": [ "webhook_delivery" ] }, "id": { "type": "string", "description": "Id de la tentative de livraison.", "examples": [ "1834" ] }, "webhook_endpoint_id": { "type": "string", "description": "L'endpoint.", "examples": [ "01j7zr8m2k4n6p8r0t2v4w6y8a" ] }, "event_id": { "type": "string", "description": "L'événement envoyé.", "examples": [ "evt_01j7zs1a2b3c4d5e6f7g8h9j0k" ] }, "event_type": { "type": "string", "description": "Le type d'événement ; ping pour un test.", "examples": [ "ping" ] }, "attempt": { "type": "integer", "description": "Numéro de la tentative (1 est la première).", "examples": [ 1 ] }, "status": { "type": "string", "enum": [ "succeeded", "failed" ], "description": "succeeded (réponse 2xx) ou failed.", "examples": [ "succeeded" ] }, "response_status": { "type": [ "integer", "null" ], "description": "Statut HTTP de votre serveur, ou null en l'absence de réponse.", "examples": [ 200 ] }, "error": { "type": [ "string", "null" ], "description": "Ce qui a échoué en l'absence de réponse, par exemple connection_failed, sinon null.", "examples": [ null ] }, "duration_ms": { "type": "integer", "description": "Durée de la tentative, en millisecondes.", "examples": [ 184 ] }, "created_at": { "type": "string", "format": "date-time", "description": "Heure de la tentative (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] } }, "additionalProperties": false }, "Event": { "type": "object", "required": [ "object", "id", "type", "created_at", "data" ], "properties": { "object": { "type": "string", "const": "event", "description": "Toujours « event ».", "examples": [ "event" ] }, "id": { "type": "string", "pattern": "^evt_", "description": "Id unique (evt_…). Identique à l'en-tête webhook-id : utilisez-le pour reconnaître les messages en double.", "examples": [ "evt_01j7zs1a2b3c4d5e6f7g8h9j0k" ] }, "type": { "type": "string", "enum": [ "customer.created", "customer.updated", "customer.converted", "deal.created", "deal.updated", "deal.stage_changed", "deal.won", "deal.lost", "note.created", "note.updated", "note.deleted" ], "description": "Le type d'événement, par exemple customer.created.", "examples": [ "customer.created" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Quand cela s'est produit (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "data": { "description": "Le contenu de l'événement.", "type": "object", "required": [ "object" ], "properties": { "object": { "type": "object", "description": "L'objet tel qu'il était après la modification, sous la même forme que dans l'API REST (pour note.deleted : tel qu'il était avant la suppression).", "examples": [ { "object": "customer", "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "type": "business", "status": "lead", "name": "Jan de Vries", "email": "jan@example.com", "phone": "+31 6 12345678", "company_name": "De Vries Bouw", "vat_number": "NL123456789B01", "coc_number": "12345678", "address": "Dorpsstraat 1", "postal_code": "3511 AB", "city": "Utrecht", "country": "NL", "email_unsubscribed": false, "converted_at": null, "last_activity_at": "2026-09-14T10:15:00Z", "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } ] } }, "additionalProperties": false } }, "additionalProperties": false }, "DeletedObject": { "type": "object", "required": [ "object", "id", "deleted" ], "properties": { "object": { "type": "string", "enum": [ "note", "webhook_endpoint" ], "description": "Le type d'objet supprimé, par exemple « note ».", "examples": [ "note" ] }, "id": { "type": "string", "description": "Id de l'objet supprimé.", "examples": [ "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92" ] }, "deleted": { "type": "boolean", "const": true, "description": "Toujours true.", "examples": [ true ] } }, "additionalProperties": false }, "CustomersCreateRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 255, "x-unique": true, "description": "Adresse e-mail ; unique au sein de votre entreprise." }, "type": { "type": "string", "enum": [ "individual", "business" ], "description": "individual (particulier) ou business (entreprise)." }, "name": { "type": [ "string", "null" ], "maxLength": 255, "description": "Nom de la personne de contact." }, "phone": { "type": [ "string", "null" ], "maxLength": 255, "description": "Numéro de téléphone." }, "address": { "type": [ "string", "null" ], "maxLength": 255, "description": "Rue et numéro." }, "city": { "type": [ "string", "null" ], "maxLength": 255, "description": "Ville." }, "postal_code": { "type": [ "string", "null" ], "maxLength": 64, "description": "Code postal." }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "minLength": 2, "maxLength": 2, "description": "Pays." }, "company_name": { "type": [ "string", "null" ], "maxLength": 255, "description": "Nom de l'entreprise, pour un client professionnel." }, "vat_number": { "type": [ "string", "null" ], "maxLength": 20, "description": "Numéro de TVA." }, "coc_number": { "type": [ "string", "null" ], "maxLength": 30, "description": "Numéro d'immatriculation (registre du commerce)." } }, "additionalProperties": false }, "CustomersUpdateRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255, "x-unique": true, "description": "Adresse e-mail ; unique au sein de votre entreprise." }, "type": { "type": "string", "enum": [ "individual", "business" ], "description": "individual (particulier) ou business (entreprise)." }, "name": { "type": [ "string", "null" ], "maxLength": 255, "description": "Nom de la personne de contact." }, "phone": { "type": [ "string", "null" ], "maxLength": 255, "description": "Numéro de téléphone." }, "address": { "type": [ "string", "null" ], "maxLength": 255, "description": "Rue et numéro." }, "city": { "type": [ "string", "null" ], "maxLength": 255, "description": "Ville." }, "postal_code": { "type": [ "string", "null" ], "maxLength": 64, "description": "Code postal." }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "minLength": 2, "maxLength": 2, "description": "Pays." }, "company_name": { "type": [ "string", "null" ], "maxLength": 255, "description": "Nom de l'entreprise, pour un client professionnel." }, "vat_number": { "type": [ "string", "null" ], "maxLength": 20, "description": "Numéro de TVA." }, "coc_number": { "type": [ "string", "null" ], "maxLength": 30, "description": "Numéro d'immatriculation (registre du commerce)." } }, "additionalProperties": false }, "NotesCreateCustomerRequest": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "maxLength": 10000, "description": "Le texte de la note." }, "is_important": { "type": "boolean", "description": "Marquée comme importante." } }, "additionalProperties": false }, "NotesUpdateCustomerRequest": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 10000, "description": "Le texte de la note." }, "is_important": { "type": "boolean", "description": "Marquée comme importante." } }, "additionalProperties": false }, "NotesCreateDealRequest": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "maxLength": 10000, "description": "Le texte de la note." }, "is_important": { "type": "boolean", "description": "Marquée comme importante." } }, "additionalProperties": false }, "NotesUpdateDealRequest": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 10000, "description": "Le texte de la note." }, "is_important": { "type": "boolean", "description": "Marquée comme importante." } }, "additionalProperties": false }, "DealsCreateRequest": { "type": "object", "required": [ "customer_id" ], "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "Le client du deal." }, "title": { "type": [ "string", "null" ], "maxLength": 255, "description": "Titre du deal." }, "description": { "type": [ "string", "null" ], "maxLength": 10000, "description": "Description." }, "value": { "type": [ "number", "null" ], "minimum": 0, "maximum": 99999999, "multipleOf": 0.01, "description": "Valeur sous forme de texte à deux décimales, par exemple « 8450.00 ». À la création et à la modification, vous pouvez aussi envoyer un nombre." }, "stage_id": { "type": [ "integer", "null" ], "description": "L'étape dans laquelle le deal arrive. Sans stage_id : l'étape par défaut." }, "assigned_user_id": { "type": [ "integer", "null" ], "description": "L'utilisateur qui gère le deal, ou null." } }, "additionalProperties": false }, "DealsUpdateRequest": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255, "description": "Titre du deal." }, "description": { "type": [ "string", "null" ], "maxLength": 10000, "description": "Description." }, "value": { "type": "number", "minimum": 0, "maximum": 99999999, "multipleOf": 0.01, "description": "Valeur sous forme de texte à deux décimales, par exemple « 8450.00 ». À la création et à la modification, vous pouvez aussi envoyer un nombre." }, "assigned_user_id": { "type": [ "integer", "null" ], "description": "L'utilisateur qui gère le deal, ou null." } }, "additionalProperties": false }, "DealsMoveRequest": { "type": "object", "required": [ "stage_id" ], "properties": { "stage_id": { "type": "integer", "description": "L'id de l'étape vers laquelle le deal est déplacé (voir Lister les étapes du pipeline)." }, "notes": { "type": [ "string", "null" ], "maxLength": 500, "description": "Remarque facultative ; conservée avec le changement d'étape dans l'historique du deal." } }, "additionalProperties": false }, "DealsLoseRequest": { "type": "object", "properties": { "lost_reason": { "type": [ "string", "null" ], "maxLength": 255, "description": "Pourquoi le deal a été perdu, ou null." } }, "additionalProperties": false }, "WebhookEndpointsCreateRequest": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "L'adresse https à laquelle Klantly envoie les événements. Pas d'adresses internes, et uniquement les ports 443, 80 ou 8443." }, "description": { "type": [ "string", "null" ], "maxLength": 255, "description": "Votre propre description, par exemple à quoi sert l'endpoint." }, "events": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Les types d'événements que cet endpoint reçoit, ou [\"*\"] pour tous les événements que la clé ou l'utilisateur peut lire." } }, "additionalProperties": false }, "WebhookEndpointsUpdateRequest": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "L'adresse https à laquelle Klantly envoie les événements. Pas d'adresses internes, et uniquement les ports 443, 80 ou 8443." }, "description": { "type": [ "string", "null" ], "maxLength": 255, "description": "Votre propre description, par exemple à quoi sert l'endpoint." }, "events": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Les types d'événements que cet endpoint reçoit, ou [\"*\"] pour tous les événements que la clé ou l'utilisateur peut lire." }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "active ou disabled (désactivé)." } }, "additionalProperties": false }, "WebhookEndpointsRotateSecretRequest": { "type": "object", "properties": { "overlap_hours": { "type": "integer", "enum": [ "0", "1", "24", "168" ], "description": "Combien de temps l'ancien secret reste valable à côté du nouveau : 0, 1, 24 (par défaut) ou 168 heures." } }, "additionalProperties": false } } } }