L’API publique ouvre les données de votre espace Lyane à vos propres outils : un ERP, un script de synchronisation, un outil d’automatisation. Elle lit et écrit les clients, les contacts, les opportunités et les tâches, et lit les devis, les factures et les documents.
Elle est incluse dans l’offre Entreprise. Toutes les adresses commencent par https://api.lyane.app/public/v1 ; les corps sont en JSON et les instants suivent la norme ISO 8601, en UTC.
Pour obtenir une clé, un administrateur de l’espace ouvre l’app, puis Paramètres → API. Il lui donne un nom et choisit les domaines auxquels elle accède. Copiez la clé dès sa création et rangez-la dans un gestionnaire de secrets : l’API ne la renvoie jamais en clair, seul son préfixe (lyk_ab12cd) permet ensuite de la reconnaître.
Ce que l’API crée ou modifie apparaît dans l’app au nom du compte de service « API » de l’espace (champ createdBy). Le membre à qui elle confie une tâche est prévenu comme dans l’app.
La spécification OpenAPI 3.1 décrit toutes les routes : importez-la dans votre client HTTP (Postman, Insomnia, Bruno…) ou dans un générateur de code.openapi.json
Authentification
Chaque requête présente la clé dans l’en-tête Authorization, selon le schéma Bearer. Une clé absente, inconnue, révoquée ou expirée reçoit une réponse 401 avec le code invalid_api_key.
HTTP
Authorization: Bearer lyk_…
GET /me vérifie une clé : il renvoie son espace, son nom, son préfixe, ses droits et sa date d’expiration.
Une clé n’ouvre que les domaines choisis à sa création, chacun à l’un de ces trois niveaux :
AucunNONE — le domaine reste fermé à la clé.
LectureREAD — lister et lire.
Lecture et écritureWRITE — lister et lire, mais aussi créer, modifier et supprimer.
Domaine
Ce qu’il ouvre
clients
Les clients et les prospects, entreprises et particuliers.
contacts
Les fiches de contact partagées avec l’équipe.
opportunities
Les opportunités, les parcours de vente et leurs étapes.
tasks
Les tâches et les relances.
sales
Les devis et les factures, en lecture seule.
documents
Les fichiers rangés sur les fiches clients, en lecture seule.
Un appel hors des droits de la clé reçoit 403 insufficient_scope, avec le domaine qui manque (domain) et le niveau demandé (required). Supprimer un client supprime aussi ses opportunités et ses brouillons de vente : il faut alors l’écriture sur opportunities et sur sales.
Expiration et révocation
Une clé peut porter une date d’expiration (expiresAt dans GET /me, null si elle n’expire pas). Passé cette date, elle est refusée avec 401 invalid_api_key.
Un administrateur peut révoquer une clé à tout moment dans Paramètres → API : elle est refusée de la même façon. Pour changer de clé sans interruption, créez la nouvelle, déployez-la, puis révoquez l’ancienne.
L’espace peut aussi limiter l’API à une liste d’adresses IP (403 ip_not_allowed en dehors), et une offre sans l’API reçoit 403 feature_not_included.
Limites
Chaque clé dispose de 600 requêtes par minute et de 50 000 requêtes par jour (journée UTC). Chaque réponse indique où en est la limite à la minute :
En-tête
Signification
RateLimit-Limit
Les requêtes permises par minute pour cette clé.
RateLimit-Remaining
Les requêtes restantes dans la minute en cours.
RateLimit-Reset
Les secondes avant que la fenêtre soit de nouveau pleine.
Au-delà, l’API répond 429 avec l’en-tête Retry-After, en secondes, et le code rate_limited (limite à la minute) ou quota_exceeded (quota du jour). Attendez le délai indiqué avant de réessayer plutôt que de relancer aussitôt.
HTTP
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 18
RateLimit-Limit: 600
RateLimit-Remaining: 0
RateLimit-Reset: 18
{
"type": "about:blank",
"title": "Too Many Requests",
"status": 429,
"detail": "Trop de requêtes pour cette clé : réessayez dans 18 secondes.",
"code": "rate_limited",
"retryAfter": 18
}
Pagination
Les listes sont paginées par curseur et triées par date de modification (updatedAt), puis par identifiant : l’ordre reste stable même quand des éléments changent entre deux pages.
Paramètre
Rôle
limit
Le nombre d’éléments par page, de 1 à 200 (50 par défaut).
cursor
Le nextCursor de la page précédente, tel quel. Un curseur illisible reçoit 400 invalid_cursor.
updatedSince
Un instant ISO 8601 en UTC : seulement ce qui a été créé ou modifié depuis, inclus.
La réponse contient la page (data) et le curseur suivant (nextCursor) ; null signifie que c’était la dernière page. Pour synchroniser, notez l’instant où commence chaque passage et repassez-le en updatedSince au suivant : seuls les éléments créés ou modifiés entre-temps reviennent.
Une création (POST) peut porter un en-tête Idempotency-Key : une valeur propre à cette création, de 1 à 255 caractères, un UUID par exemple. Rejouée avec la même clé dans les 24 heures, après une coupure réseau par exemple, la requête reçoit la réponse d’origine, avec l’en-tête Idempotent-Replayed: true, sans que rien ne soit créé une seconde fois.
HTTP/1.1 201 Created
Content-Type: application/json
Location: https://api.lyane.app/public/v1/clients/3fa85f64-5717-4562-b3fc-2c963f66afa6
Idempotent-Replayed: true
La même clé avec un autre corps reçoit 409 idempotency_key_reused. Si la première requête est encore en cours, 409 idempotency_key_in_progress : réessayez un peu plus tard.
Erreurs
Les erreurs suivent la RFC 9457 (application/problem+json). Le champ code est stable : c’est lui que votre intégration doit lire. detail explique l’erreur en français, pour un humain, et peut évoluer.
HTTP
HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
{
"type": "about:blank",
"title": "Forbidden",
"status": 403,
"detail": "Cette clé n’a pas le droit WRITE sur le domaine opportunities.",
"code": "insufficient_scope",
"domain": "opportunities",
"required": "WRITE"
}
Code
Statut
Signification
validation_failed
400
Un champ est refusé : errors liste chaque champ (field) et la raison (message).
invalid_cursor
400
Le curseur n’est pas un nextCursor rendu par l’API.
malformed_request
400
La requête est mal formée : un corps JSON illisible, par exemple.
custom_field_invalid
400
Un champ personnalisé est refusé : fields donne pour chacun sa key, son label et la raison (reason : required, invalid_type, unknown_option…).
invalid_filter
400
Un filtre cf.<key> vise un champ inconnu ou archivé, ou sa valeur est illisible.
invalid_api_key
401
La clé est absente, inconnue, révoquée ou expirée.
insufficient_scope
403
La clé n’a pas le droit demandé : domain dit le domaine, required le niveau.
feature_not_included
403
L’offre de l’espace n’inclut pas l’API (ou, pour /custom-fields, les champs personnalisés).
ip_not_allowed
403
L’adresse IP de l’appel n’est pas dans la liste autorisée par l’espace.
not_found
404
La ressource n’existe pas, ou appartient à un autre espace.
idempotency_key_reused
409
Cette Idempotency-Key a déjà servi pour un autre corps.
idempotency_key_in_progress
409
La première requête de cette Idempotency-Key est encore en cours.
plan_limit_reached
409
La limite de l’offre est atteinte (le nombre de clients, par exemple).
conflict
409
Une autre écriture a modifié la ressource au même moment : relisez-la, puis réessayez.
workspace_suspended
423
L’espace est bloqué : il reste lisible, mais plus rien ne s’y écrit.
rate_limited
429
La limite à la minute est atteinte : attendez Retry-After secondes.
quota_exceeded
429
Le quota du jour (UTC) est atteint.
pdf_not_ready
503
Le PDF est encore en cours de génération : réessayez dans quelques secondes.
Exemple : créer un client puis une opportunité
Avec une clé qui a l’écriture sur clients et opportunities, rangée dans la variable d’environnement LYANE_API_KEY :
Chaque route, groupée par domaine, avec ses paramètres, un exemple de requête et de réponse, et le droit qu’elle demande. Cette référence est générée à partir de la spécification OpenAPI.
Clé
La clé présentée et son espace. Aucun domaine requis.
La clé et son espace
GET/me
L'espace que désigne la clé, son nom, son préfixe, ses domaines et son échéance. Jamais la clé elle-même.
401invalid_api_key : clé absente, inconnue, révoquée ou expirée (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (offre sans API), ip_not_allowed (adresse hors de la liste de l'espace).
429rate_limited (minute) ou quota_exceeded (jour UTC).
Clients
Entreprises et particuliers, prospects et clients. Domaine clients.
Lister les clients
GET/clients
Triés par date de modification puis identifiant. Pagination par curseur : passer nextCursor en cursor pour la page suivante (null : c'était la dernière). updatedSince ne garde que ce qui a changé depuis cet instant, inclus. Champs personnalisés : cf.<key>=valeur (texte : contient ; liste, membre : égal, valeurs séparées par des virgules : l'une d'elles ; liste multiple : contient l'une ; case : true|false), cf.<key>.min et cf.<key>.max (nombre, montant, date AAAA-MM-JJ, inclus), cf.<key>.empty=true|false ; 400 invalid_filter sur une key inconnue ou une valeur illisible.
Droit requisclientslecture
Paramètres
limitintegerrequête
Éléments par page, de 1 à 200 (50 par défaut).
cursorstringrequête
Le nextCursor d'une réponse précédente, tel quel (opaque). Illisible : 400 invalid_cursor.
updatedSincestringrequête
Instant ISO 8601 en UTC (2026-11-01T00:00:00Z) : seulement ce qui a été créé ou modifié depuis, inclus.
401invalid_api_key : clé absente, inconnue, révoquée ou expirée (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (offre sans API), ip_not_allowed (adresse hors de la liste de l'espace).
429rate_limited (minute) ou quota_exceeded (jour UTC).
Créer un client
POST/clients
Une entreprise (companyName obligatoire) ou un particulier (lastName obligatoire), prospect par défaut. 409 plan_limit_reached au-delà du nombre de clients de l'offre. customFields : les champs personnalisés de l'espace, par key (GET /custom-fields) ; chaque champ obligatoire doit avoir une valeur (400 custom_field_invalid, fields : key, label, reason). Avec un en-tête Idempotency-Key, la même requête rejouée dans les 24 heures rend la même réponse (en-tête Idempotent-Replayed: true) sans rien recréer ; la même clé avec un autre corps : 409 idempotency_key_reused ; pendant que la première est en cours : 409 idempotency_key_in_progress.
Droit requisclientsécriture
Paramètres
Idempotency-Keystringen-tête
Facultatif, de 1 à 255 caractères (un UUID par exemple), propre à chaque création ; gardé 24 heures par clé d'API.
Corps de la requête ClientInput
Une entreprise : companyName obligatoire (siren, siret et vatNumber contrôlés). Un particulier : lastName obligatoire.
typecompany | individualobligatoire
statusprospect | client
companyNamestring
sirenstring
siretstring
vatNumberstring
websitestring
industrystring
firstNamestring
lastNamestring
addressobject
Adresse postale. Un champ vide vaut null.
address.linestring
La voie.
address.line2string
Complément : bâtiment, lieu-dit, boîte postale.
address.postalCodestring
address.citystring
address.countrystring
ownerIdstring (uuid)
Le membre responsable : le compte d'un membre actif de l'espace ; absent : personne.
originIdstring (uuid)
L'une des origines de l'espace ; absente : non renseignée.
customFieldsCustomFieldValues
Les champs personnalisés, par key (GET /custom-fields). Seules les clés présentes changent, null efface ; à la création, chaque champ obligatoire doit avoir une valeur (400 custom_field_invalid).
401invalid_api_key : clé absente, inconnue, révoquée ou expirée (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (offre sans API), ip_not_allowed (adresse hors de la liste de l'espace).
404not_found : introuvable, ou d'un autre espace.
429rate_limited (minute) ou quota_exceeded (jour UTC).
Modifier un client
PATCH/clients/{id}
Seuls les champs présents changent ; null efface (address se remplace en entier). type ne change pas ; status passe de prospect à client, jamais l'inverse. customFields : seules les clés présentes changent, null efface (un champ obligatoire ne se vide pas).
Droit requisclientsécriture
Paramètres
idstring (uuid)cheminobligatoire
Corps de la requête ClientInput
Une entreprise : companyName obligatoire (siren, siret et vatNumber contrôlés). Un particulier : lastName obligatoire.
typecompany | individualobligatoire
statusprospect | client
companyNamestring
sirenstring
siretstring
vatNumberstring
websitestring
industrystring
firstNamestring
lastNamestring
addressobject
Adresse postale. Un champ vide vaut null.
address.linestring
La voie.
address.line2string
Complément : bâtiment, lieu-dit, boîte postale.
address.postalCodestring
address.citystring
address.countrystring
ownerIdstring (uuid)
Le membre responsable : le compte d'un membre actif de l'espace ; absent : personne.
originIdstring (uuid)
L'une des origines de l'espace ; absente : non renseignée.
customFieldsCustomFieldValues
Les champs personnalisés, par key (GET /custom-fields). Seules les clés présentes changent, null efface ; à la création, chaque champ obligatoire doit avoir une valeur (400 custom_field_invalid).
423workspace_suspended : l'espace est bloqué, il reste lisible.
429rate_limited (minute) ou quota_exceeded (jour UTC).
Supprimer un client
DELETE/clients/{id}
Ses opportunités partent avec lui (il faut alors WRITE sur opportunities), ses brouillons de vente aussi (WRITE sur sales). deleteContacts=true : ses contacts sont supprimés avec lui ; sinon ils restent, sans client.
423workspace_suspended : l'espace est bloqué, il reste lisible.
429rate_limited (minute) ou quota_exceeded (jour UTC).
Contacts
Les fiches de contact partagées avec l'équipe. Domaine contacts.
Lister les contacts
GET/contacts
clientId ne garde que les contacts de ce client. Pagination par curseur : passer nextCursor en cursor pour la page suivante (null : c'était la dernière). updatedSince ne garde que ce qui a changé depuis cet instant, inclus. Champs personnalisés : cf.<key>=valeur (texte : contient ; liste, membre : égal, valeurs séparées par des virgules : l'une d'elles ; liste multiple : contient l'une ; case : true|false), cf.<key>.min et cf.<key>.max (nombre, montant, date AAAA-MM-JJ, inclus), cf.<key>.empty=true|false ; 400 invalid_filter sur une key inconnue ou une valeur illisible.
Droit requiscontactslecture
Paramètres
clientIdstring (uuid)requête
limitintegerrequête
Éléments par page, de 1 à 200 (50 par défaut).
cursorstringrequête
Le nextCursor d'une réponse précédente, tel quel (opaque). Illisible : 400 invalid_cursor.
updatedSincestringrequête
Instant ISO 8601 en UTC (2026-11-01T00:00:00Z) : seulement ce qui a été créé ou modifié depuis, inclus.
401invalid_api_key : clé absente, inconnue, révoquée ou expirée (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (offre sans API), ip_not_allowed (adresse hors de la liste de l'espace).
429rate_limited (minute) ou quota_exceeded (jour UTC).
Créer un contact
POST/contacts
Une fiche partagée avec l'équipe ; clientId l'associe à un client de l'espace. customFields : les champs personnalisés de l'espace, par key (GET /custom-fields) ; chaque champ obligatoire doit avoir une valeur (400 custom_field_invalid, fields : key, label, reason). Avec un en-tête Idempotency-Key, la même requête rejouée dans les 24 heures rend la même réponse (en-tête Idempotent-Replayed: true) sans rien recréer ; la même clé avec un autre corps : 409 idempotency_key_reused ; pendant que la première est en cours : 409 idempotency_key_in_progress.
Droit requiscontactsécriture
Paramètres
Idempotency-Keystringen-tête
Facultatif, de 1 à 255 caractères (un UUID par exemple), propre à chaque création ; gardé 24 heures par clé d'API.
Corps de la requête ContactInput
Une fiche de contact, toujours partagée avec l'équipe.
firstNamestring
lastNamestringobligatoire
emailstring (email)
phonestring
jobTitlestring
clientIdstring (uuid)
Un client de l'espace auquel l'associer ; absent : aucun.
customFieldsCustomFieldValues
Les champs personnalisés, par key (GET /custom-fields). Seules les clés présentes changent, null efface ; à la création, chaque champ obligatoire doit avoir une valeur (400 custom_field_invalid).
401invalid_api_key : clé absente, inconnue, révoquée ou expirée (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (offre sans API), ip_not_allowed (adresse hors de la liste de l'espace).
404not_found : introuvable, ou d'un autre espace.
429rate_limited (minute) ou quota_exceeded (jour UTC).
Modifier un contact
PATCH/contacts/{id}
Seuls les champs présents changent ; null efface (clientId : le contact n'est plus associé à aucun client). customFields : seules les clés présentes changent, null efface (un champ obligatoire ne se vide pas).
Droit requiscontactsécriture
Paramètres
idstring (uuid)cheminobligatoire
Corps de la requête ContactInput
Une fiche de contact, toujours partagée avec l'équipe.
firstNamestring
lastNamestringobligatoire
emailstring (email)
phonestring
jobTitlestring
clientIdstring (uuid)
Un client de l'espace auquel l'associer ; absent : aucun.
customFieldsCustomFieldValues
Les champs personnalisés, par key (GET /custom-fields). Seules les clés présentes changent, null efface ; à la création, chaque champ obligatoire doit avoir une valeur (400 custom_field_invalid).
423workspace_suspended : l'espace est bloqué, il reste lisible.
429rate_limited (minute) ou quota_exceeded (jour UTC).
Opportunités
Les affaires en cours, gagnées ou perdues, et les parcours de vente. Domaine opportunities.
Lister les opportunités
GET/opportunities
clientId et stageId filtrent. Pagination par curseur : passer nextCursor en cursor pour la page suivante (null : c'était la dernière). updatedSince ne garde que ce qui a changé depuis cet instant, inclus. Champs personnalisés : cf.<key>=valeur (texte : contient ; liste, membre : égal, valeurs séparées par des virgules : l'une d'elles ; liste multiple : contient l'une ; case : true|false), cf.<key>.min et cf.<key>.max (nombre, montant, date AAAA-MM-JJ, inclus), cf.<key>.empty=true|false ; 400 invalid_filter sur une key inconnue ou une valeur illisible.
Droit requisopportunitieslecture
Paramètres
clientIdstring (uuid)requête
stageIdstring (uuid)requête
limitintegerrequête
Éléments par page, de 1 à 200 (50 par défaut).
cursorstringrequête
Le nextCursor d'une réponse précédente, tel quel (opaque). Illisible : 400 invalid_cursor.
updatedSincestringrequête
Instant ISO 8601 en UTC (2026-11-01T00:00:00Z) : seulement ce qui a été créé ou modifié depuis, inclus.
401invalid_api_key : clé absente, inconnue, révoquée ou expirée (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (offre sans API), ip_not_allowed (adresse hors de la liste de l'espace).
429rate_limited (minute) ou quota_exceeded (jour UTC).
Créer une opportunité
POST/opportunities
Sans stageId ni pipelineId : la première étape en cours du parcours par défaut. customFields : les champs personnalisés de l'espace, par key (GET /custom-fields) ; chaque champ obligatoire doit avoir une valeur (400 custom_field_invalid, fields : key, label, reason). Avec un en-tête Idempotency-Key, la même requête rejouée dans les 24 heures rend la même réponse (en-tête Idempotent-Replayed: true) sans rien recréer ; la même clé avec un autre corps : 409 idempotency_key_reused ; pendant que la première est en cours : 409 idempotency_key_in_progress.
Droit requisopportunitiesécriture
Paramètres
Idempotency-Keystringen-tête
Facultatif, de 1 à 255 caractères (un UUID par exemple), propre à chaque création ; gardé 24 heures par clé d'API.
Corps de la requête OpportunityInput
Sans stageId ni pipelineId : la première étape en cours du parcours par défaut. Avec pipelineId seul : la première étape en cours de ce parcours.
clientIdstring (uuid)obligatoire
Un client de l'espace, prospect ou client.
contactIdstring (uuid)
Un contact partagé de l'espace.
titlestringobligatoire
amountnumber
pipelineIdstring (uuid)
Un parcours de l'espace (GET /pipelines).
stageIdstring (uuid)
Une étape de l'espace (GET /pipelines) ; gagnée ou perdue, l'affaire est close.
expectedCloseDatestring (date)
ownerIdstring (uuid)
Le membre responsable : le compte d'un membre actif de l'espace ; absent : personne.
customFieldsCustomFieldValues
Les champs personnalisés, par key (GET /custom-fields). Seules les clés présentes changent, null efface ; à la création, chaque champ obligatoire doit avoir une valeur (400 custom_field_invalid).
401invalid_api_key : clé absente, inconnue, révoquée ou expirée (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (offre sans API), ip_not_allowed (adresse hors de la liste de l'espace).
404not_found : introuvable, ou d'un autre espace.
429rate_limited (minute) ou quota_exceeded (jour UTC).
Modifier une opportunité
PATCH/opportunities/{id}
Seuls les champs présents changent ; null efface. stageId la déplace (gagnée ou perdue : close ; gagnée, son prospect devient client) ; pipelineId seul : la première étape en cours de ce parcours.
Droit requisopportunitiesécriture
Paramètres
idstring (uuid)cheminobligatoire
Corps de la requête OpportunityInput
Sans stageId ni pipelineId : la première étape en cours du parcours par défaut. Avec pipelineId seul : la première étape en cours de ce parcours.
clientIdstring (uuid)obligatoire
Un client de l'espace, prospect ou client.
contactIdstring (uuid)
Un contact partagé de l'espace.
titlestringobligatoire
amountnumber
pipelineIdstring (uuid)
Un parcours de l'espace (GET /pipelines).
stageIdstring (uuid)
Une étape de l'espace (GET /pipelines) ; gagnée ou perdue, l'affaire est close.
expectedCloseDatestring (date)
ownerIdstring (uuid)
Le membre responsable : le compte d'un membre actif de l'espace ; absent : personne.
customFieldsCustomFieldValues
Les champs personnalisés, par key (GET /custom-fields). Seules les clés présentes changent, null efface ; à la création, chaque champ obligatoire doit avoir une valeur (400 custom_field_invalid).
401invalid_api_key : clé absente, inconnue, révoquée ou expirée (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (offre sans API), ip_not_allowed (adresse hors de la liste de l'espace).
429rate_limited (minute) ou quota_exceeded (jour UTC).
Tâches
Les tâches et relances. Domaine tasks.
Lister les tâches
GET/tasks
opportunityId, clientId et done filtrent. Pagination par curseur : passer nextCursor en cursor pour la page suivante (null : c'était la dernière). updatedSince ne garde que ce qui a changé depuis cet instant, inclus.
Droit requistaskslecture
Paramètres
opportunityIdstring (uuid)requête
clientIdstring (uuid)requête
donebooleanrequête
true : les tâches faites ; false : celles à faire ; absent : toutes.
limitintegerrequête
Éléments par page, de 1 à 200 (50 par défaut).
cursorstringrequête
Le nextCursor d'une réponse précédente, tel quel (opaque). Illisible : 400 invalid_cursor.
updatedSincestringrequête
Instant ISO 8601 en UTC (2026-11-01T00:00:00Z) : seulement ce qui a été créé ou modifié depuis, inclus.
401invalid_api_key : clé absente, inconnue, révoquée ou expirée (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (offre sans API), ip_not_allowed (adresse hors de la liste de l'espace).
429rate_limited (minute) ou quota_exceeded (jour UTC).
Créer une tâche
POST/tasks
Avec une opportunité sans client : le client de l'opportunité. L'assigné est prévenu comme dans l'app. Avec un en-tête Idempotency-Key, la même requête rejouée dans les 24 heures rend la même réponse (en-tête Idempotent-Replayed: true) sans rien recréer ; la même clé avec un autre corps : 409 idempotency_key_reused ; pendant que la première est en cours : 409 idempotency_key_in_progress.
Droit requistasksécriture
Paramètres
Idempotency-Keystringen-tête
Facultatif, de 1 à 255 caractères (un UUID par exemple), propre à chaque création ; gardé 24 heures par clé d'API.
Corps de la requête TaskInput
Une tâche. Avec une opportunité sans client : le client de l'opportunité.
titlestringobligatoire
descriptionstring
dueDatestring (date)
assigneeIdstring (uuid)
Le compte d'un membre actif de l'espace.
assigneeGroupIdstring (uuid)
Ou un groupe de l'espace (offre avec les groupes), jamais avec assigneeId.
423workspace_suspended : l'espace est bloqué, il reste lisible.
429rate_limited (minute) ou quota_exceeded (jour UTC).
Ventes
Devis et factures, en lecture seule. Domaine sales.
Lister les factures
GET/invoices
Factures, factures d'acompte et avoirs (type). clientId filtre. Pagination par curseur : passer nextCursor en cursor pour la page suivante (null : c'était la dernière). updatedSince ne garde que ce qui a changé depuis cet instant, inclus.
Droit requissaleslecture
Paramètres
clientIdstring (uuid)requête
limitintegerrequête
Éléments par page, de 1 à 200 (50 par défaut).
cursorstringrequête
Le nextCursor d'une réponse précédente, tel quel (opaque). Illisible : 400 invalid_cursor.
updatedSincestringrequête
Instant ISO 8601 en UTC (2026-11-01T00:00:00Z) : seulement ce qui a été créé ou modifié depuis, inclus.
401invalid_api_key : clé absente, inconnue, révoquée ou expirée (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (offre sans API), ip_not_allowed (adresse hors de la liste de l'espace).
404not_found : introuvable, ou d'un autre espace.
429rate_limited (minute) ou quota_exceeded (jour UTC).
PDF d'une facture
GET/invoices/{id}/pdf
Un lien présigné de quelques minutes vers le PDF : Factur-X figé pour une facture émise, aperçu à jour (filigrane BROUILLON) pour un brouillon. 503 pdf_not_ready s'il se génère encore.
401invalid_api_key : clé absente, inconnue, révoquée ou expirée (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (offre sans API), ip_not_allowed (adresse hors de la liste de l'espace).
404not_found : introuvable, ou d'un autre espace.
429rate_limited (minute) ou quota_exceeded (jour UTC).
Lister les devis
GET/quotes
clientId filtre. Pagination par curseur : passer nextCursor en cursor pour la page suivante (null : c'était la dernière). updatedSince ne garde que ce qui a changé depuis cet instant, inclus.
Droit requissaleslecture
Paramètres
clientIdstring (uuid)requête
limitintegerrequête
Éléments par page, de 1 à 200 (50 par défaut).
cursorstringrequête
Le nextCursor d'une réponse précédente, tel quel (opaque). Illisible : 400 invalid_cursor.
updatedSincestringrequête
Instant ISO 8601 en UTC (2026-11-01T00:00:00Z) : seulement ce qui a été créé ou modifié depuis, inclus.
401invalid_api_key : clé absente, inconnue, révoquée ou expirée (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (offre sans API), ip_not_allowed (adresse hors de la liste de l'espace).
404not_found : introuvable, ou d'un autre espace.
429rate_limited (minute) ou quota_exceeded (jour UTC).
PDF d'un devis
GET/quotes/{id}/pdf
Un lien présigné de quelques minutes vers le PDF : figé pour un devis émis, aperçu à jour (filigrane BROUILLON) pour un brouillon. 503 pdf_not_ready s'il se génère encore.
401invalid_api_key : clé absente, inconnue, révoquée ou expirée (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (offre sans API), ip_not_allowed (adresse hors de la liste de l'espace).
404not_found : introuvable, ou d'un autre espace.
429rate_limited (minute) ou quota_exceeded (jour UTC).
Documents
Les fichiers rangés sur les fiches clients, en lecture seule. Domaine documents.
Lister les documents
GET/documents
clientId filtre. Pagination par curseur : passer nextCursor en cursor pour la page suivante (null : c'était la dernière). updatedSince ne garde que ce qui a changé depuis cet instant, inclus.
Droit requisdocumentslecture
Paramètres
clientIdstring (uuid)requête
limitintegerrequête
Éléments par page, de 1 à 200 (50 par défaut).
cursorstringrequête
Le nextCursor d'une réponse précédente, tel quel (opaque). Illisible : 400 invalid_cursor.
updatedSincestringrequête
Instant ISO 8601 en UTC (2026-11-01T00:00:00Z) : seulement ce qui a été créé ou modifié depuis, inclus.
401invalid_api_key : clé absente, inconnue, révoquée ou expirée (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (offre sans API), ip_not_allowed (adresse hors de la liste de l'espace).
404not_found : introuvable, ou d'un autre espace.
429rate_limited (minute) ou quota_exceeded (jour UTC).
Champs personnalisés
Les champs personnalisés des clients, contacts et opportunités (lecture du domaine de chaque type de fiche).
Lister les champs personnalisés
GET/custom-fields
Les champs actifs, dans leur ordre, avec leurs options actives. objectType (client, contact ou opportunity) exige la lecture de son domaine ; absent : les types de fiche que la clé peut lire. 403 feature_not_included si l'offre n'a pas les champs personnalisés.
Droit requisclients | contacts | opportunitieslecture
401invalid_api_key : clé absente, inconnue, révoquée ou expirée (WWW-Authenticate: Bearer).
403insufficient_scope (domain, required), feature_not_included (offre sans API), ip_not_allowed (adresse hors de la liste de l'espace).
429rate_limited (minute) ou quota_exceeded (jour UTC).
Webhooks
Les webhooks préviennent vos outils dès qu’un évènement se produit dans Lyane : un client créé, une opportunité gagnée, une facture payée. Plutôt que d’interroger l’API à intervalles réguliers, votre serveur reçoit une requête POST en JSON à chaque évènement auquel il est abonné.
Ils sont inclus dans l’offre Entreprise, comme l’API publique.
Créer un abonnement
Un administrateur de l’espace ouvre l’app, puis Paramètres → Intégrations → Webhooks. Il saisit l’adresse qui recevra les évènements et choisit les évènements à envoyer. Un espace compte jusqu’à 10 abonnements.
L’adresse doit être en HTTPS et joignable depuis Internet : une adresse privée ou interne (réseau local, localhost, adresse réservée) est refusée. Pendant le développement, exposez votre serveur local par un tunnel HTTPS.
À la création, l’app affiche le secret de l’abonnement (whsec_…) : c’est lui qui sert à vérifier la signature de chaque requête. Rangez-le dans un gestionnaire de secrets. Le bouton « Envoyer un test » envoie aussitôt l’évènement webhook.test à l’adresse.
Pour changer de secret, lancez une rotation : pendant 24 heures, chaque requête est signée avec le nouveau et avec l’ancien secret, le temps de déployer le nouveau.
Corps de la requête
Chaque évènement arrive dans la même enveloppe JSON, quel que soit son type :
Champ
Contenu
id
L’identifiant de l’évènement (evt_…). Le même pour toutes ses tentatives et ses rejeux : c’est la clé de déduplication.
type
Le type de l’évènement : client.created, invoice.paid…
createdAt
L’instant de l’évènement, en ISO 8601 (UTC).
organizationId
L’espace Lyane où il s’est produit.
data
Le contenu de l’évènement.
data.object
La ressource concernée, dans la même représentation que l’API publique (celle de GET /clients/{id} pour un client, par exemple).
data.previous
Facultatif, sur une modification : les champs changés, avec leurs anciennes valeurs.
Pour une suppression (*.deleted), data.object ne contient que l’identifiant de la ressource : { "id": "…" }. Pour webhook.test, data.object décrit l’abonnement testé : id, url et message.
En-têtes et signature
Chaque requête porte ces en-têtes :
En-tête
Contenu
Content-Type
application/json.
User-Agent
Lyane-Webhooks/1.0.
Lyane-Webhook-Id
L’identifiant de l’évènement, égal au champ id du corps : dédupliquez sur cette valeur.
Lyane-Webhook-Timestamp
L’heure de la tentative, en secondes Unix. Elle change à chaque tentative, et la signature avec elle.
Lyane-Signature
v1= suivi de la signature en hexadécimal ; deux valeurs séparées par une virgule pendant une rotation du secret.
La signature est un HMAC-SHA256 en hexadécimal. Sa clé est le secret de l’abonnement en entier, préfixe whsec_ compris ; son message est l’horodatage, un point, puis le corps brut de la requête : <Lyane-Webhook-Timestamp>.<corps>.
Pendant les 24 heures d’une rotation du secret, l’en-tête porte deux signatures, la nouvelle puis l’ancienne : v1=<nouvelle>,v1=<ancienne>. Acceptez la requête si l’une des deux correspond.
Une livraison complète de l’évènement de test :
HTTP
POST /lyane HTTP/1.1
Host: hooks.exemple.fr
Content-Type: application/json
User-Agent: Lyane-Webhooks/1.0
Lyane-Webhook-Id: evt_01JCQ7Z8K9V5W2X3Y4Z5A6B7C8
Lyane-Webhook-Timestamp: 1794477602
Lyane-Signature: v1=89c477430acb503d1ce355b341b864bb96fe3e41fcb43ba7c0fc9138014845c9
{"id":"evt_01JCQ7Z8K9V5W2X3Y4Z5A6B7C8","type":"webhook.test","createdAt":"2026-11-12T10:00:00Z","organizationId":"3fa85f64-5717-4562-b3fc-2c963f66afa6","data":{"object":{"id":"9c4e2a71-1b3d-4f6a-8e2c-5d7f9a0b1c2d","url":"https://hooks.exemple.fr/lyane","message":"Évènement de test envoyé depuis Lyane."}}}
Vérifier la signature
Avant de traiter une requête, vérifiez qu’elle vient bien de Lyane : recalculez la signature avec votre secret, comparez-la à chacune des valeurs v1= de Lyane-Signature à temps constant, et refusez un horodatage à plus de 5 minutes de votre heure courante, pour qu’une requête interceptée ne puisse pas être rejouée plus tard.
Calculez la signature sur le corps brut, octet pour octet, avant tout parsing : un JSON lu puis re-sérialisé n’a plus forcément les mêmes espaces ni le même ordre de champs, et la signature ne correspond plus. Avec Express, lisez le corps avec express.raw({ type: 'application/json' }) plutôt qu’avec express.json() ; avec Flask, avec request.get_data().
Node.js
La vérification, sans dépendance (Node.js 18 ou plus, dans un module ES) :
verify-signature.mjs
import { createHmac, timingSafeEqual } from 'node:crypto';
const TOLERANCE_SECONDS = 5 * 60;
export function verifyLyaneWebhook({ rawBody, timestamp, signature, secret, now = Date.now() }) {
if (!Buffer.isBuffer(rawBody) && typeof rawBody !== 'string') return false;
if (!secret || !signature || !/^\d+$/.test(timestamp ?? '')) return false;
const age = Math.abs(Math.floor(now / 1000) - Number(timestamp));
if (age > TOLERANCE_SECONDS) return false;
const expected = createHmac('sha256', secret).update(`${timestamp}.`).update(rawBody).digest();
// During a secret rotation: "v1=<new>,v1=<old>". One match is enough.
return signature.split(',').some((value) => {
const [version, hex] = value.trim().split('=');
if (version !== 'v1' || !/^[0-9a-f]{64}$/i.test(hex ?? '')) return false;
return timingSafeEqual(Buffer.from(hex, 'hex'), expected);
});
}
Un serveur Express qui reçoit les évènements, avec le secret dans la variable d’environnement LYANE_WEBHOOK_SECRET :
server.mjs
import express from 'express';
import { verifyLyaneWebhook } from './verify-signature.mjs';
const app = express();
// Use a database table in production: this set is lost on restart.
const processed = new Set();
app.post('/webhooks/lyane', express.raw({ type: 'application/json' }), (req, res) => {
const valid = verifyLyaneWebhook({
rawBody: req.body,
timestamp: req.get('Lyane-Webhook-Timestamp'),
signature: req.get('Lyane-Signature'),
secret: process.env.LYANE_WEBHOOK_SECRET,
});
if (!valid) return res.sendStatus(401);
const eventId = req.get('Lyane-Webhook-Id');
if (processed.has(eventId)) return res.sendStatus(200);
processed.add(eventId);
const event = JSON.parse(req.body.toString('utf8'));
res.sendStatus(200);
setImmediate(() => handle(event).catch((error) => console.error(eventId, error)));
});
async function handle(event) {
switch (event.type) {
case 'opportunity.won':
console.log('Won:', event.data.object.title);
break;
case 'invoice.paid':
console.log('Paid:', event.data.object.number);
break;
}
}
app.listen(3000);
Python
La vérification, avec la bibliothèque standard (Python 3.8 ou plus) :
verify_signature.py
import hashlib
import hmac
import time
TOLERANCE_SECONDS = 5 * 60
def verify_lyane_webhook(raw_body, timestamp, signature, secret, now=None):
if not isinstance(raw_body, bytes) or not secret or not signature:
return False
if not timestamp or not (timestamp.isascii() and timestamp.isdigit()):
return False
current = time.time() if now is None else now
if abs(int(current) - int(timestamp)) > TOLERANCE_SECONDS:
return False
message = timestamp.encode() + b"." + raw_body
expected = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
# During a secret rotation: "v1=<new>,v1=<old>". One match is enough.
for value in signature.split(","):
version, _, hex_digest = value.strip().partition("=")
if version == "v1" and hmac.compare_digest(hex_digest.lower().encode(), expected.encode()):
return True
return False
Une application Flask qui reçoit les évènements :
app.py
import json
import os
import queue
import threading
from flask import Flask, request
from verify_signature import verify_lyane_webhook
SECRET = os.environ["LYANE_WEBHOOK_SECRET"]
app = Flask(__name__)
events = queue.Queue()
# Use a database table in production: this set is lost on restart.
processed = set()
@app.post("/webhooks/lyane")
def lyane_webhook():
raw_body = request.get_data()
valid = verify_lyane_webhook(
raw_body,
request.headers.get("Lyane-Webhook-Timestamp", ""),
request.headers.get("Lyane-Signature", ""),
SECRET,
)
if not valid:
return "", 401
event_id = request.headers.get("Lyane-Webhook-Id")
if event_id not in processed:
processed.add(event_id)
events.put(json.loads(raw_body))
return "", 200
def worker():
while True:
event = events.get()
try:
if event["type"] == "opportunity.won":
print("Won:", event["data"]["object"]["title"])
elif event["type"] == "invoice.paid":
print("Paid:", event["data"]["object"]["number"])
except Exception as error:
print(event["id"], error)
threading.Thread(target=worker, daemon=True).start()
Pour tester votre code : avec le secret d’exemple whsec_exemple4f8a2c9e1b7d3f6a5c0e8b2d, l’horodatage 1794477602 et le corps de la livraison ci-dessus, la signature attendue est v1=89c477430acb503d1ce355b341b864bb96fe3e41fcb43ba7c0fc9138014845c9. Passez cet horodatage comme heure courante (now, en millisecondes en Node.js, en secondes en Python) : sinon, la tolérance de 5 minutes refuse la requête.
Reprises et désactivation
Une livraison réussit quand votre serveur répond un statut 2xx en moins de 10 secondes. Les redirections ne sont pas suivies : un statut 3xx compte comme un échec, comme tout autre statut ou une absence de réponse.
Après un échec, Lyane réessaie le même évènement, avec le même Lyane-Webhook-Id. Chaque délai court depuis la tentative précédente, sauf la dernière, fixée 24 h après la première :
Tentative
Quand
1
Aussitôt l’évènement produit
2
+1 min
3
+5 min
4
+30 min
5
+2 h
6
+5 h
7
+10 h
8
24 h après la première tentative
Après l’échec de la huitième tentative, l’abonnement est désactivé et les administrateurs de l’espace sont prévenus par e-mail.
L’app garde l’historique des envois de chaque abonnement pendant 30 jours. Le bouton « Rejouer » y renvoie un évènement, avec son identifiant d’origine.
Bonnes pratiques
Répondez vite, puis traitez : vérifiez la signature, mettez l’évènement dans une file, répondez 200, et faites le travail ensuite. Un traitement long dépasse les 10 secondes et déclenche une nouvelle tentative.
Dédupliquez sur Lyane-Webhook-Id : un même évènement peut arriver plus d’une fois (une réponse perdue, un rejeu). Gardez les identifiants déjà traités dans une table, pas seulement en mémoire.
Rendez le traitement idempotent : appliquer deux fois le même évènement doit laisser le même résultat. Écrivez l’état reçu (« la facture est payée ») plutôt qu’un incrément.
Ne comptez pas sur l’ordre : deux évènements peuvent arriver dans le désordre, surtout après une reprise. Comparez createdAt, ou relisez la ressource avec l’API publique en cas de doute.
opportunity.stage_changed est envoyé à chaque changement d’étape, y compris vers gagnée ou perdue, en plus de opportunity.won ou opportunity.lost : abonnez-vous à l’un ou à l’autre selon ce que vous suivez.
Gardez le secret côté serveur, et refusez toute requête dont la signature ne correspond pas (401).
Référence des évènements
Chaque évènement, groupé par domaine, avec un exemple de corps complet. Cette liste est générée à partir de la spécification OpenAPI (section webhooks).