{ "openapi": "3.1.0", "info": { "title": "API Kafinea", "version": "1.0", "summary": "Référence complète de l'API de Kafinea : enregistrements, requêtes, documents, comptabilité, paramétrage.", "description": "L'API de Kafinea donne accès, par HTTP, aux mêmes données et aux mêmes règles que l'interface : chaque appel s'exécute avec les droits de l'utilisateur connecté.\n\n## Démarrage rapide\n\nTrois appels suffisent pour lire vos premières données. Remplacez `votre-instance`, l'utilisateur et sa clé d'accès :\n\n```bash\nBASE=https://apps.kafinea.com/votre-instance/webservice.php\n\n# 1. Jeton à usage unique\nTOKEN=$(curl -s \"$BASE?operation=getchallenge&username=integration\" | jq -r .result.token)\n\n# 2. Session : empreinte SHA-256 du jeton suivi de la clé d'accès\nHASH=$(printf '%s' \"$TOKEN$ACCESS_KEY\" | sha256sum | cut -d' ' -f1)\nSESSION=$(curl -s -X POST \"$BASE\" -d operation=login -d username=integration -d accessKey=$HASH | jq -r .result.sessionName)\n\n# 3. Première requête : cinq comptes\ncurl -s -G \"$BASE\" --data-urlencode operation=query --data-urlencode sessionName=$SESSION \\\n --data-urlencode \"query=SELECT accountname, email1 FROM Accounts LIMIT 5;\"\n```\n\n## Appeler l'API\n\nToutes les opérations passent par un point d'entrée unique, `webservice.php`, et se distinguent par le paramètre `operation` :\n\n- une opération **GET** lit ses paramètres dans l'URL ;\n- une opération **POST** lit ses paramètres dans le corps du formulaire (`application/x-www-form-urlencoded`).\n\nL'adresse de base est celle de votre instance, par exemple `https://apps.kafinea.com/votre-instance`.\n\n## S'authentifier\n\n1. `getchallenge` renvoie un jeton à usage unique pour un nom d'utilisateur.\n2. `login` reçoit `sha256(jeton + clé d'accès)` (empreinte hexadécimale ; MD5 reste accepté) et renvoie un identifiant de session. La clé d'accès se trouve dans **Mes préférences** de l'utilisateur.\n3. Chaque appel suivant transmet cet identifiant dans le paramètre `sessionName`.\n\nCréez un utilisateur dédié à chaque intégration : ses droits délimitent exactement ce que l'intégration peut lire et modifier.\n\n## Lire une réponse\n\nToutes les réponses ont la même enveloppe JSON :\n\n```json\n{ \"success\": true, \"result\": { } }\n```\n\nEn cas d'échec, `success` vaut `false` et `error` donne un code stable et un message :\n\n```json\n{ \"success\": false, \"error\": { \"code\": \"ACCESS_DENIED\", \"message\": \"Permission to perform the operation is denied\" } }\n```\n\nLe statut HTTP reste 200 : testez toujours `success`.\n\n## Conventions\n\n- **Identifiants** : un enregistrement est désigné par un identifiant `x`, par exemple `11x42`. `describe` et `listtypes` donnent les modules disponibles.\n- **Paramètres JSON** : un paramètre de type objet ou liste s'envoie sous forme de texte JSON (`element={\"accountname\":\"Exemple SARL\"}`).\n- **Modules et champs** : les champs dépendent du paramétrage de chaque instance. `describe` renvoie la liste exacte, avec les champs personnalisés.\n- **Droits** : les opérations marquées *Administrateur* sont réservées aux utilisateurs administrateurs de l'instance.\n\n## Guides\n\nLes guides expliquent les cas d'usage pas à pas :\n\n- [Authentification](https://www.kafinea.com/fr/documentation/api/api-rest-authentification/)\n- [Requêtes et interrogation](https://www.kafinea.com/fr/documentation/api/api-rest-requetes-et-interrogation/) : le langage de requête, les filtres, la pagination\n- [Relations entre entités](https://www.kafinea.com/fr/documentation/api/api-rest-operations-liees/)\n- [Gestion des fichiers](https://www.kafinea.com/fr/documentation/api/api-rest-fichiers/) et [PDF des documents](https://www.kafinea.com/fr/documentation/api/api-rest-documents-pdf/)\n- [Import en masse (upsert)](https://www.kafinea.com/fr/documentation/api/api-rest-import-en-masse/) et [suppression en masse](https://www.kafinea.com/fr/documentation/api/api-rest-suppression-en-masse/)\n- [Tous les guides de l'API](https://www.kafinea.com/fr/documentation/api/)\n\n## Télécharger la spécification\n\nCette référence est générée depuis une spécification **OpenAPI 3.1**, téléchargeable pour vos outils (générateurs de clients, agents IA, tests) : https://www.kafinea.com/fr/api/openapi.json", "contact": { "name": "Support Kafinea", "url": "https://www.kafinea.com/fr/" } }, "servers": [ { "url": "https://apps.kafinea.com/{instance}", "description": "Votre instance Kafinea", "variables": { "instance": { "default": "votre-instance", "description": "Nom de votre instance, tel qu'il apparaît dans l'adresse de Kafinea." } } } ], "security": [ { "session": [] } ], "tags": [ { "name": "Authentification", "description": "Ouverture, prolongation et fermeture d'une session d'API. La connexion se fait en deux étapes : `getchallenge` fournit un jeton à usage unique, `login` l'échange contre un identifiant de session (`sessionName`) à transmettre à toutes les autres opérations. `connection_context` décrit l'instance et l'utilisateur connectés." }, { "name": "Enregistrements", "description": "Lecture, création, modification et suppression des enregistrements d'un module, à l'unité ou par lots, ainsi que la corbeille, les étiquettes et la synchronisation incrémentale. Tous les identifiants d'enregistrement ont la forme `11x42` (préfixe du module, `x`, numéro). Les droits appliqués sont ceux de l'utilisateur de la session." }, { "name": "Requêtes et listes", "description": "Interroger les données : requêtes de lecture, agrégations calculées par la base (totaux, comptages, moyennes) et listes enregistrées d'un module, avec leur définition, leurs enregistrements et leurs réglages d'affichage." }, { "name": "Relations", "description": "Listes connexes affichées sur la fiche d'un enregistrement (documents d'un client, contacts d'une opportunité...). `relatedtypes` donne les listes d'un module et leur libellé, `query_related` et `retrieve_related` les lisent, `add_related` et `delete_related` ajoutent ou retirent des liens. Les droits appliqués sont ceux de l'utilisateur de la session." }, { "name": "Modules et champs", "description": "Découvrir la structure des modules (types disponibles, champs, listes de choix) et la configurer : champs personnalisés, blocs, disposition des champs, visibilité, listes de choix et numérotation des documents. Les opérations de configuration sont réservées aux administrateurs." }, { "name": "Fichiers et documents", "description": "Dépôt de fichiers privés, pièces jointes et documents, génération de PDF à partir des modèles d'impression, facture électronique Factur-X et modèles d'e-mail. Un fichier déposé avec `file_upload` reçoit un identifiant privé (`fileId`) que les autres opérations réutilisent sans renvoyer les octets." }, { "name": "Imports", "description": "Imports de données par fichier : référentiels (clients, produits...), relevés bancaires OFX, fichier des écritures comptables (FEC) avec reprise des pièces, et consultation des relevés de ventes des distributeurs. Le fichier source est d'abord déposé avec `file_upload`, puis analysé sans écriture, et enfin importé à l'issue d'une revue." }, { "name": "Comptabilité", "description": "Rapports de comptabilité générale (balance, grand livre, journaux, bilan, compte de résultat, balance âgée, rapprochement bancaire, annexes de copropriété), exports PDF et Excel, et saisies manuelles d'écritures. Les rapports sont calculés à partir des écritures comptabilisées, quelle que soit leur origine." }, { "name": "Comptabilité analytique", "description": "Activation et configuration de la comptabilité analytique, ventilation des écritures et des lignes de documents, rapports analytiques (totaux, croisement d'axes, tableau de bord, compte de résultat, grand livre) et répartitions de clôture. Les rapports et les écritures de clôture nécessitent que la comptabilité analytique soit activée sur l'instance." }, { "name": "Immobilisations", "description": "Registre des immobilisations d'une société : création (manuelle ou depuis une facture fournisseur), plans d'amortissement linéaire, dégressif et dérogatoire, comptabilisation des dotations, révisions, cessions et mises au rebut, états et paramètres comptables. Les montants sont en centimes de la devise comptable, les dates au format AAAA-MM-JJ. Les droits d'accès aux immobilisations de l'utilisateur s'appliquent." }, { "name": "Notes de frais", "description": "Saisie, soumission, approbation et remboursement des notes de frais, avec lecture des justificatifs par l'IA, indemnités kilométriques et forfaits. Les opérations agissent au nom de l'utilisateur connecté. La configuration (catégories, barèmes, regroupement) est réservée aux administrateurs. Les erreurs sont renvoyées avec un code `EXPENSE_...` en tête du message." }, { "name": "Approbations", "description": "Circuits d'approbation par module, demandes d'approbation sur un enregistrement et réponses des approbateurs. Les opérations de configuration des circuits sont réservées aux administrateurs. Les erreurs métier portent un code lisible en début de message (`APPROVAL_REFUSED`, `APPROVAL_CIRCUIT_INVALID`, `APPROVAL_CIRCUIT_REVISION_CHANGED`, `APPROVAL_FEATURE_DISABLED`)." }, { "name": "Stocks et catalogue", "description": "Compositions des kits produits, lignes d'inventaire physique, suivi de la synchronisation des documents de stock et opérations de reprise des documents importés d'une boutique en ligne. Les opérations de reprise sont réservées aux administrateurs." }, { "name": "Fiscalité", "description": "Configuration des régions fiscales : régions, grilles de taxes, frais supplémentaires, correspondances par pays et par territoire. Les opérations de cette famille sont réservées aux administrateurs et chaque modification est journalisée." }, { "name": "Automatisation", "description": "Workflows et liens d'action par e-mail. Les opérations `workflow_*` permettent à un administrateur de lire, tester, configurer et exécuter les workflows de l'instance, et de vérifier les expressions de calcul qu'ils utilisent. Les liens d'action permettent d'envoyer à un destinataire un lien qui exécute une action précise après sa confirmation, sans connexion." }, { "name": "Administration", "description": "Paramétrage de l'instance et gestion des comptes : réglages d'instance, serveur de messagerie sortante, profils et droits, préférences et mots de passe des utilisateurs, et correction des soldes de congés. La plupart de ces opérations sont réservées aux administrateurs ; une opération refusée retourne `ACCESS_DENIED`." }, { "name": "Assistant et découverte", "description": "Découvrir par programme ce que l'API sait faire : catalogue des opérations et de leurs schémas, guides métier partagés, et recherche dans la documentation publiée avec l'instance. Ces opérations servent surtout aux assistants et aux outils d'intégration qui construisent leurs appels dynamiquement." } ], "x-tagGroups": [ { "name": "Fondamentaux", "tags": [ "Authentification", "Enregistrements", "Requêtes et listes", "Relations", "Modules et champs", "Fichiers et documents" ] }, { "name": "Import de données", "tags": [ "Imports" ] }, { "name": "Comptabilité et finance", "tags": [ "Comptabilité", "Comptabilité analytique", "Immobilisations", "Fiscalité" ] }, { "name": "Activité", "tags": [ "Notes de frais", "Approbations", "Stocks et catalogue" ] }, { "name": "Paramétrage et automatisation", "tags": [ "Automatisation", "Administration", "Assistant et découverte" ] } ], "paths": { "/webservice.php?operation=getchallenge": { "get": { "operationId": "getchallenge", "tags": [ "Authentification" ], "summary": "Obtenir un jeton de connexion", "description": "Première étape de la connexion. Génère un jeton à usage unique, valable 5 minutes, pour l'utilisateur indiqué. Chaque appel remplace le jeton précédent du même utilisateur : n'enchaînez pas deux `getchallenge` avant d'avoir appelé `login`.\n\nLe jeton sert à calculer le paramètre `accessKey` de `login`. Aucune session n'est nécessaire.\n\nErreur `ACCESS_DENIED` lorsque le nom d'utilisateur est vide ou inconnu.\n\n> Ne demande pas de session.", "security": [], "x-kafinea-access": "public", "parameters": [ { "in": "query", "name": "username", "required": true, "schema": { "type": "string" }, "example": "integration", "description": "Nom d'utilisateur Kafinea." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le jeton, l'heure du serveur et l'heure d'expiration du jeton (horodatages Unix en secondes).", "type": "object", "properties": { "token": { "type": "string" }, "serverTime": { "type": "integer" }, "expireTime": { "type": "integer" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "token": "6553a1b2c3d4e", "serverTime": 1763200000, "expireTime": 1763200300 } } } } } } } }, "/webservice.php?operation=login": { "post": { "operationId": "login", "tags": [ "Authentification" ], "summary": "Ouvrir une session", "description": "Seconde étape de la connexion. Échange le jeton obtenu avec `getchallenge` contre une session d'API.\n\nLe paramètre `accessKey` n'est pas la clé d'accès elle-même mais l'empreinte hexadécimale SHA-256 de la concaténation du jeton et de la clé d'accès de l'utilisateur : `sha256(token + clé d'accès)`. L'empreinte MD5 reste acceptée pour les intégrations existantes. La clé d'accès se lit dans les préférences de l'utilisateur dans Kafinea.\n\nTransmettez ensuite le `sessionName` reçu dans toutes les autres opérations. Les droits de la session sont ceux de l'utilisateur.\n\nErreurs : `INVALID_AUTH_TOKEN` (jeton absent ou expiré), `ACCESSKEY_UNDEFINED` (l'utilisateur n'a pas de clé d'accès), `INVALID_USER_CREDENTIALS` (empreinte incorrecte ou utilisateur inactif).\n\n> Ne demande pas de session.", "security": [], "x-kafinea-access": "public", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "Nom d'utilisateur Kafinea, le même que celui donné à `getchallenge`.", "example": "integration" }, "accessKey": { "type": "string", "description": "Empreinte SHA-256 en hexadécimal de la concaténation du jeton et de la clé d'accès de l'utilisateur. Attention, le nom du paramètre porte un K majuscule.", "example": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" } }, "required": [ "username", "accessKey" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "L'identité de l'utilisateur et la session ouverte. `sessionName` est à passer à toutes les opérations suivantes ; `userId` est l'identifiant de l'utilisateur au format `19x1`.", "type": "object", "properties": { "username": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string" }, "time_zone": { "type": "string" }, "hour_format": { "type": "string" }, "date_format": { "type": "string" }, "is_admin": { "type": "string" }, "call_duration": { "type": "string" }, "other_event_duration": { "type": "string" }, "sessionName": { "type": "string" }, "userId": { "type": "string" }, "version": { "type": "string" }, "kafineaVersion": { "type": "string" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "username": "integration", "first_name": "Claire", "last_name": "Exemple", "email": "claire@exemple.test", "time_zone": "Europe/Paris", "hour_format": "24", "date_format": "dd-mm-yyyy", "is_admin": "off", "call_duration": "5", "other_event_duration": "5", "sessionName": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6", "userId": "19x7", "version": "0.22", "kafineaVersion": "1.0" } } } } } } } }, "/webservice.php?operation=extendsession": { "post": { "operationId": "extendsession", "tags": [ "Authentification" ], "summary": "Reprendre une session ouverte dans l'interface", "description": "Ouvre une session d'API à partir d'une session déjà authentifiée dans l'interface web de Kafinea : le navigateur envoie son cookie de session, l'opération renvoie un `sessionName` utilisable avec les autres opérations, avec les droits de l'utilisateur connecté. Elle sert aux scripts exécutés dans la page ; une intégration serveur utilise `getchallenge` puis `login`.\n\nAucun paramètre n'est attendu. Erreur `AUTHENTICATION_FAILURE` si aucune session authentifiée n'est associée à la requête, `AUTHENTICATION_REQUIRED` si la requête ne la transmet pas.\n\n> Ne demande pas de session.", "security": [], "x-kafinea-access": "public", "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La session et l'identifiant de l'utilisateur connecté.", "type": "object", "properties": { "sessionName": { "type": "string" }, "userId": { "type": "string" }, "version": { "type": "string" }, "kafineaVersion": { "type": "string" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "sessionName": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6", "userId": "19x7", "version": "0.22", "kafineaVersion": "1.0" } } } } } } } }, "/webservice.php?operation=logout": { "post": { "operationId": "logout", "tags": [ "Authentification" ], "summary": "Fermer une session", "description": "Détruit la session d'API indiquée. L'identifiant de session n'est plus utilisable ensuite : il faut rouvrir une session avec `getchallenge` puis `login`.", "x-kafinea-access": "user", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "sessionName": { "type": "string", "description": "Identifiant de session reçu à la connexion.", "example": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" } }, "required": [ "sessionName" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Confirmation de la fermeture.", "type": "object", "properties": { "message": { "type": "string" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "message": "successfull" } } } } } } } }, "/webservice.php?operation=connection_context": { "get": { "operationId": "connection_context", "tags": [ "Authentification" ], "summary": "Décrire l'instance et l'utilisateur connectés", "description": "Renvoie les informations sur la connexion en cours, sans aucun secret (ni jeton, ni clé d'accès) :\n\n- l'instance (`instanceId`, `baseUrl`) et son type (`instanceType`: `production`, `sandbox` ou `demo`; `isProduction`) ;\n- l'utilisateur authentifié (`user`) ;\n- le périmètre des requêtes (`queryScope`), dont l'organisation courante de l'utilisateur ;\n- l'adresse de l'API et le mode d'authentification (`api`) ;\n- l'activation de l'écriture par les agents d'intelligence artificielle (`agentDataModification`) : quand elle est désactivée, les écritures des agents et de l'assistant sont refusées, les lectures ne le sont jamais. Seul un administrateur peut l'activer.\n\nAppelez cette opération avant la première écriture pour vérifier que vous visez la bonne instance, en particulier une instance de production.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Description de la connexion.", "type": "object", "properties": { "instanceId": { "type": "string" }, "baseUrl": { "type": "string" }, "instanceType": { "type": "string" }, "isProduction": { "type": "boolean" }, "agentDataModification": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "appliesTo": { "type": "string" }, "whenDisabled": { "type": "string" } } }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "queryScope": { "type": "object", "properties": { "currentOrganizationId": { "type": "string" }, "queryOperation": { "type": "string" }, "assistantQueryTools": { "type": "string" } } }, "api": { "type": "object", "properties": { "url": { "type": "string" }, "discoveryOperation": { "type": "string" }, "exactOperationParameter": { "type": "string" }, "readMethod": { "type": "string" }, "writeMethod": { "type": "string" }, "encoding": { "type": "string" } } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "instanceId": "1042", "baseUrl": "https://apps.kafinea.com/exemple", "instanceType": "production", "isProduction": true, "agentDataModification": { "enabled": false, "appliesTo": "Opérations d'écriture et de configuration du serveur MCP et de l'assistant intégré.", "whenDisabled": "Toute écriture est refusée." }, "user": { "id": 7, "name": "integration" }, "queryScope": { "currentOrganizationId": "46x3", "queryOperation": "Tous les enregistrements accessibles à l'utilisateur ; aucun filtre automatique sur l'organisation courante.", "assistantQueryTools": "Les outils de requête de l'assistant se limitent à l'organisation courante par défaut." }, "api": { "url": "https://apps.kafinea.com/exemple/webservice.php", "discoveryOperation": "list_operations", "exactOperationParameter": "operationName", "readMethod": "GET", "writeMethod": "POST", "encoding": "application/x-www-form-urlencoded" } } } } } } } } }, "/webservice.php?operation=retrieve": { "get": { "operationId": "retrieve", "tags": [ "Enregistrements" ], "summary": "Lire un enregistrement", "description": "Renvoie un enregistrement et ses champs visibles par l'utilisateur. Les champs liés à un autre enregistrement sont renvoyés sous forme d'identifiant (`19x1`). Un champ secret (clé d'API, mot de passe) est renvoyé à `null`, accompagné d'un champ `_set` qui indique si une valeur est enregistrée.\n\nErreurs fréquentes : `ACCESS_DENIED` (module ou enregistrement non accessible), `RECORD_NOT_FOUND`, `INVALID_ID_ATTRIBUTE`.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "id", "required": true, "schema": { "type": "string" }, "example": "11x42", "description": "Identifiant de l'enregistrement." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "L'enregistrement, champ par champ.", "type": "object", "properties": { "id": { "type": "string" }, "accountname": { "type": "string" }, "assigned_user_id": { "type": "string" }, "createdtime": { "type": "string" }, "modifiedtime": { "type": "string" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "id": "11x42", "accountname": "Exemple SARL", "assigned_user_id": "19x1", "createdtime": "2026-11-03 09:15:22", "modifiedtime": "2026-11-10 14:32:05" } } } } } } } }, "/webservice.php?operation=create": { "post": { "operationId": "create", "tags": [ "Enregistrements" ], "summary": "Créer un enregistrement", "description": "Crée un enregistrement dans un module. Tous les champs obligatoires doivent être fournis ; les champs qui désignent un autre enregistrement s'expriment avec son identifiant (`19x1`). Utilisez `describe` pour connaître les champs, leur type et leur caractère obligatoire.\n\nErreur `MANDATORY_FIELDS_MISSING` quand un champ obligatoire manque, `ACCESS_DENIED` quand l'utilisateur ne peut pas créer dans ce module. Pour les documents de gestion commerciale (devis, commandes, factures, avoirs, factures fournisseur), les montants des lignes, la TVA par taux et les totaux sont toujours calculés par le serveur et jamais acceptés. Quand `describe` liste le champ `mdspricesincludetax` et que le document le porte à 1, les prix s'entendent toutes taxes comprises : chaque entrée de `LineItems` doit alors fournir `mdsunitpriceincltax` (le prix hors taxe `listprice` est déduit par le serveur, et une ligne qui ne donne que `listprice` est refusée), et `mdspricesincludetax` ne change qu'avec `LineItems`.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "elementType": { "type": "string", "description": "Module de l'enregistrement à créer.", "example": "Accounts" }, "element": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "description": "Texte JSON (objet). Champs de l'enregistrement, sous la forme nom du champ : valeur.", "example": "{\"accountname\":\"Exemple SARL\",\"assigned_user_id\":\"19x1\"}" } }, "required": [ "elementType", "element" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "L'enregistrement créé, avec son identifiant.", "type": "object", "properties": { "id": { "type": "string" }, "accountname": { "type": "string" }, "assigned_user_id": { "type": "string" }, "createdtime": { "type": "string" }, "modifiedtime": { "type": "string" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "id": "11x42", "accountname": "Exemple SARL", "assigned_user_id": "19x1", "createdtime": "2026-11-03 09:15:22", "modifiedtime": "2026-11-10 14:32:05" } } } } } } } }, "/webservice.php?operation=update": { "post": { "operationId": "update", "tags": [ "Enregistrements" ], "summary": "Remplacer un enregistrement", "description": "Met à jour un enregistrement en envoyant l'enregistrement complet : tous les champs obligatoires doivent être présents, `id` compris. Pour ne changer que quelques champs, utilisez `revise`.\n\nPour modifier uniquement les champs autorisés d'un document verrouillé (une facture validée, par exemple), ajoutez le paramètre `partial_edit=1` au même niveau que `operation`; les lignes du document ne sont alors pas modifiées. Sans lui, la modification d'un enregistrement verrouillé est refusée avec `ACCESS_DENIED`. Pour les documents de gestion commerciale (devis, commandes, factures, avoirs, factures fournisseur), les montants des lignes, la TVA par taux et les totaux sont toujours calculés par le serveur et jamais acceptés. Quand `describe` liste le champ `mdspricesincludetax` et que le document le porte à 1, les prix s'entendent toutes taxes comprises : chaque entrée de `LineItems` doit alors fournir `mdsunitpriceincltax` (le prix hors taxe `listprice` est déduit par le serveur, et une ligne qui ne donne que `listprice` est refusée), et `mdspricesincludetax` ne change qu'avec `LineItems`.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "element": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "description": "Texte JSON (objet). Enregistrement complet, avec son `id`.", "example": "{\"id\":\"12x57\",\"lastname\":\"Martin\",\"email\":\"martin@exemple.test\",\"assigned_user_id\":\"19x1\"}" } }, "required": [ "element" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "L'enregistrement après modification.", "type": "object", "properties": { "id": { "type": "string" }, "lastname": { "type": "string" }, "email": { "type": "string" }, "assigned_user_id": { "type": "string" }, "modifiedtime": { "type": "string" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "id": "12x57", "lastname": "Martin", "email": "martin@exemple.test", "assigned_user_id": "19x1", "modifiedtime": "2026-11-10 14:32:05" } } } } } } } }, "/webservice.php?operation=revise": { "post": { "operationId": "revise", "tags": [ "Enregistrements" ], "summary": "Modifier des champs d'un enregistrement", "description": "Modification partielle : envoyez l'`id` et les seuls champs à changer, tous les autres conservent leur valeur.\n\nPour éviter d'écraser le travail d'un autre utilisateur, transmettez dans `expectedModifiedTime` la valeur de `modifiedtime` lue avec `retrieve` : si l'enregistrement a changé depuis, rien n'est enregistré et l'erreur `RECORD_CHANGED` est renvoyée. Relisez alors l'enregistrement et recommencez.\n\nQuand une règle d'enregistrement ajuste ou retire une valeur sans bloquer (épuration du HTML d'un modèle d'impression, par exemple), l'enregistrement renvoyé porte une liste `warnings`, absente sinon. Pour les documents de gestion commerciale (devis, commandes, factures, avoirs, factures fournisseur), les montants des lignes, la TVA par taux et les totaux sont toujours calculés par le serveur et jamais acceptés. Quand `describe` liste le champ `mdspricesincludetax` et que le document le porte à 1, les prix s'entendent toutes taxes comprises : chaque entrée de `LineItems` doit alors fournir `mdsunitpriceincltax` (le prix hors taxe `listprice` est déduit par le serveur, et une ligne qui ne donne que `listprice` est refusée), et `mdspricesincludetax` ne change qu'avec `LineItems`.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "element": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "description": "Texte JSON (objet). `id` de l'enregistrement et champs à modifier.", "example": "{\"id\":\"11x42\",\"phone\":\"01 23 45 67 89\"}" }, "expectedModifiedTime": { "type": "string", "default": "", "description": "Facultatif. Valeur de `modifiedtime` lue avec `retrieve`; si l'enregistrement a changé depuis, rien n'est enregistré (erreur `RECORD_CHANGED`).", "example": "2026-11-10 14:32:05" } }, "required": [ "element" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "L'enregistrement après modification, avec une liste `warnings` si une règle d'enregistrement a ajusté une valeur.", "type": "object", "properties": { "id": { "type": "string" }, "accountname": { "type": "string" }, "assigned_user_id": { "type": "string" }, "createdtime": { "type": "string" }, "modifiedtime": { "type": "string" }, "phone": { "type": "string" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "id": "11x42", "accountname": "Exemple SARL", "assigned_user_id": "19x1", "createdtime": "2026-11-03 09:15:22", "modifiedtime": "2026-11-10 14:32:05", "phone": "01 23 45 67 89" } } } } } } } }, "/webservice.php?operation=delete": { "post": { "operationId": "delete", "tags": [ "Enregistrements" ], "summary": "Supprimer un enregistrement", "description": "Envoie un enregistrement à la corbeille. Il garde son identifiant, ses liens et son historique, et un administrateur peut le restaurer avec `recycle_bin_restore`. La corbeille ne se vide que depuis l'interface de Kafinea.\n\nErreurs : `ACCESS_DENIED` (pas de droit de suppression sur le module ou l'enregistrement), `RECORD_NOT_FOUND`, `INVALID_ID_ATTRIBUTE`.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifiant de l'enregistrement à supprimer.", "example": "11x42" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Confirmation de la suppression.", "type": "object", "properties": { "status": { "type": "string" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "status": "successful" } } } } } } } }, "/webservice.php?operation=mass_delete": { "post": { "operationId": "mass_delete", "tags": [ "Enregistrements" ], "summary": "Supprimer des enregistrements par lot", "description": "Envoie jusqu'à 500 enregistrements d'un même module à la corbeille en un seul appel, comme `delete` le ferait un par un. Réservé aux administrateurs.\n\n- Le module est obligatoire et chaque identifiant doit lui appartenir : un identifiant d'un autre module est refusé, avec le module réellement trouvé dans le motif.\n- Les droits sont ceux de `delete` (accès au module, droit de suppression, partage de l'enregistrement).\n- Un identifiant déjà à la corbeille est compté dans `alreadyDeleted` et n'est pas une erreur, ce qui permet de rejouer un lot interrompu.\n- Un identifiant qui ne désigne rien est signalé comme tel.\n- Une erreur sur une ligne n'arrête pas les autres : elle est listée dans `errors` avec sa position dans le lot.\n\nUn lot illisible (JSON invalide, vide, plus de 500 identifiants) est refusé en entier avec `QUERY_SYNTAX_ERROR`. La restauration passe par `recycle_bin_restore`.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "elementType": { "type": "string", "description": "Module des enregistrements à supprimer.", "example": "SalesOrder" }, "ids": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array" }, "description": "Texte JSON (liste). Identifiants des enregistrements, 500 au maximum.", "example": "[\"7x54993\",\"7x54994\",\"7x54995\"]" } }, "required": [ "elementType", "ids" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Bilan du lot : `deleted` (envoyés à la corbeille), `alreadyDeleted`, le détail par position dans `records` et les refus dans `errors`.", "type": "object", "properties": { "module": { "type": "string" }, "processed": { "type": "integer" }, "deleted": { "type": "integer" }, "alreadyDeleted": { "type": "integer" }, "records": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "id": { "type": "string" }, "outcome": { "type": "string" } } } }, "errors": { "type": "array" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "module": "SalesOrder", "processed": 3, "deleted": 2, "alreadyDeleted": 1, "records": [ { "index": 0, "id": "7x54993", "outcome": "deleted" }, { "index": 1, "id": "7x54994", "outcome": "deleted" }, { "index": 2, "id": "7x54995", "outcome": "alreadyDeleted" } ], "errors": [] } } } } } } } }, "/webservice.php?operation=mass_revise": { "post": { "operationId": "mass_revise", "tags": [ "Enregistrements" ], "summary": "Appliquer les mêmes valeurs à plusieurs enregistrements", "description": "Applique les mêmes valeurs de champs à 1 à 100 enregistrements d'un même module : une modification partielle (comme `revise`) par enregistrement, avec le droit de modification contrôlé sur chacun, ainsi que ses règles d'enregistrement et ses workflows.\n\n- Un enregistrement qui porte déjà les valeurs n'est pas touché (`unchanged`).\n- Chaque enregistrement reçoit un résultat `updated`, `unchanged` ou `error` (avec `message`, repris dans `errors`). Une erreur n'arrête pas les autres.\n- Les identifiants doivent être distincts et appartenir au module indiqué.\n\nPour traiter plus de 100 enregistrements, rappelez l'opération avec les identifiants suivants.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "elementType": { "type": "string", "description": "Module de tous les enregistrements.", "example": "Accounts" }, "ids": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array", "items": { "type": "string" } }, "description": "Texte JSON (liste). Identifiants des enregistrements à modifier, 100 au maximum par appel.", "example": "[\"11x42\",\"11x43\"]" }, "element": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "description": "Texte JSON (objet). Champs et valeurs appliqués à chaque enregistrement, sans `id`. Les autres champs gardent leur valeur.", "example": "{\"accounttype\":\"Customer\"}" } }, "required": [ "elementType", "ids", "element" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Bilan du lot, un résultat par enregistrement.", "type": "object", "properties": { "module": { "type": "string" }, "processed": { "type": "integer" }, "updated": { "type": "integer" }, "unchanged": { "type": "integer" }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "outcome": { "type": "string" } } } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "message": { "type": "string" } } } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "module": "Accounts", "processed": 1, "updated": 1, "unchanged": 0, "records": [ { "id": "11x42", "outcome": "updated" }, { "id": "11x43", "outcome": "error", "message": "Permission to perform the operation is denied" } ], "errors": [ { "id": "11x43", "message": "Permission to perform the operation is denied" } ] } } } } } } } }, "/webservice.php?operation=mass_upsert": { "post": { "operationId": "mass_upsert", "tags": [ "Enregistrements" ], "summary": "Créer ou modifier des enregistrements par clé naturelle", "description": "Écrit un lot d'enregistrements d'un même module, identifiés par une clé naturelle (`keyFields`) plutôt que par leur identifiant. Réservé aux administrateurs.\n\nPour chaque enregistrement, l'ERP cherche celui qui porte la clé : s'il existe, il est modifié partiellement ; sinon il est créé ; si aucune valeur ne change, rien n'est écrit (pas de changement de date de modification, pas de ligne d'historique). Rejouer un lot est donc sans danger. Les contrôles de droits, de champs obligatoires et de types sont ceux de `create` et `revise`.\n\n- Envoyez des lots de 100 enregistrements (un lot plus grand peut dépasser le délai HTTP) ; 500 est la limite stricte.\n- Les valeurs de clé sont comparées comme du texte, entités HTML décodées ; une clé de type référence accepte un identifiant (`11x42`). Une valeur de clé vide est refusée.\n- Une clé qui correspond à plusieurs enregistrements est refusée : l'ERP ne devine pas lequel modifier.\n- Un rejeu envoyé pendant que le premier appel s'exécute attend la fin de celui-ci, sans créer de doublon.\n- Une erreur sur une ligne est listée dans `errors` avec sa position, les autres lignes sont écrites.\n\nUn lot illisible (JSON invalide, vide, trop grand, champ de clé inconnu) est refusé en entier avec `QUERY_SYNTAX_ERROR`.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "elementType": { "type": "string", "description": "Module des enregistrements.", "example": "Products" }, "keyFields": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array" }, "description": "Texte JSON (liste). Noms des champs qui forment la clé naturelle.", "example": "[\"productcode\"]" }, "elements": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array" }, "description": "Texte JSON (liste). Enregistrements à écrire, chacun sous la forme nom du champ : valeur. Chacun doit renseigner les champs de la clé. 500 au maximum, 100 recommandés.", "example": "[{\"productcode\":\"ART-001\",\"productname\":\"Chaise de bureau\",\"unit_price\":\"89.00\"}]" } }, "required": [ "elementType", "keyFields", "elements" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Bilan du lot : compteurs, résultat par position dans `records` (`created`, `updated` ou `unchanged`) et refus dans `errors`.", "type": "object", "properties": { "module": { "type": "string" }, "keyFields": { "type": "array", "items": { "type": "string" } }, "processed": { "type": "integer" }, "created": { "type": "integer" }, "updated": { "type": "integer" }, "unchanged": { "type": "integer" }, "records": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "id": { "type": "string" }, "outcome": { "type": "string" } } } }, "errors": { "type": "array" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "module": "Products", "keyFields": [ "productcode" ], "processed": 2, "created": 1, "updated": 0, "unchanged": 1, "records": [ { "index": 0, "id": "14x310", "outcome": "created" }, { "index": 1, "id": "14x311", "outcome": "unchanged" } ], "errors": [] } } } } } } } }, "/webservice.php?operation=original_numbers_preview": { "get": { "operationId": "original_numbers_preview", "tags": [ "Enregistrements" ], "summary": "Prévisualiser la restauration des numéros d'origine", "description": "Liste les enregistrements d'un module à numérotation propre (`Invoice`, `MdsPayable`, `MdsAcPaymentCustomer`...) dont le numéro d'origine (champ `mdsoriginalrecordnumber`, le numéro dans l'ancien logiciel) diffère du numéro actuel, avec la collision que la restauration rencontrerait : `taken` (un autre enregistrement porte déjà ce numéro) ou `duplicate` (un enregistrement plus haut dans la liste le reçoit en premier).\n\nN'écrit rien. Réservé aux administrateurs (complets ou restreints), avec le droit de modification sur le module. Erreur `ORIGINAL_NUMBERS_BAD_MODULE` si le module n'a pas de numérotation propre, `ORIGINAL_NUMBERS_BAD_PARAMETER` si `recordIds` contient autre chose que des identifiants.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "module", "required": true, "schema": { "type": "string" }, "example": "Invoice", "description": "Module à examiner." }, { "in": "query", "name": "recordIds", "required": false, "schema": { "type": "string", "default": "" }, "example": "7x101,7x102", "description": "Facultatif. Limite l'examen à ces enregistrements : liste séparée par des virgules ou tableau JSON d'identifiants." }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer", "default": 0 }, "example": 0, "description": "Rang du premier résultat renvoyé, pour paginer." }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "default": 50 }, "example": 50, "description": "Nombre maximal de résultats, borné entre 1 et 200." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le module, le nombre total d'enregistrements concernés et la page demandée. `collision` vaut `null` quand le numéro d'origine peut être restauré.", "type": "object", "properties": { "module": { "type": "string" }, "total": { "type": "integer" }, "offset": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "recordId": { "type": "integer" }, "number": { "type": "string" }, "originalNumber": { "type": "string" }, "collision": { "type": "null" }, "takenBy": { "type": "null" } } } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "module": "Invoice", "total": 2, "offset": 0, "items": [ { "recordId": 101, "number": "INV-0101", "originalNumber": "F2024-0007", "collision": null, "takenBy": null }, { "recordId": 102, "number": "INV-0102", "originalNumber": "F2024-0008", "collision": "taken", "takenBy": 77 } ] } } } } } } } }, "/webservice.php?operation=original_numbers_restore": { "post": { "operationId": "original_numbers_restore", "tags": [ "Enregistrements" ], "summary": "Restaurer les numéros d'origine", "description": "Donne aux enregistrements d'un module leur numéro d'origine (`mdsoriginalrecordnumber`) comme numéro, comme le propose le bandeau de la liste dans l'interface.\n\nSans `apply` à `true`, l'opération se contente d'une prévisualisation, identique à `original_numbers_preview` (`applied` vaut `false`). Avec `apply=true`, elle écrit chaque numéro qu'aucun autre enregistrement ne porte et laisse une ligne d'historique : un numéro n'est jamais écrasé, et les enregistrements en collision sont listés dans `refused` avec leur motif (`taken` ou `duplicate`). Faites contrôler la prévisualisation avant d'appliquer.\n\nRéservé aux administrateurs (complets ou restreints), avec le droit de modification sur le module. Mêmes erreurs que `original_numbers_preview`.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "module": { "type": "string", "description": "Module à traiter.", "example": "Invoice" }, "recordIds": { "type": "string", "default": "", "description": "Facultatif. Limite le traitement à ces enregistrements : liste séparée par des virgules ou tableau JSON d'identifiants.", "example": "7x101,7x102" }, "apply": { "type": "string", "default": "", "description": "`true` (ou `1`, `yes`) pour écrire les numéros. Toute autre valeur, ou l'absence du paramètre, donne une simple prévisualisation.", "example": "true" } }, "required": [ "module" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le module et `applied` : `false` pour une prévisualisation (accompagnée de `total`, `offset` et `items` comme `original_numbers_preview`), `true` quand les numéros ont été écrits (accompagné de `refused`, la liste des enregistrements non restaurés et de leur motif).", "type": "object", "properties": { "module": { "type": "string" }, "applied": { "type": "boolean" }, "refused": { "type": "array", "items": { "type": "object", "properties": { "recordId": { "type": "integer" }, "number": { "type": "string" }, "originalNumber": { "type": "string" }, "collision": { "type": "string" }, "takenBy": { "type": "integer" }, "reason": { "type": "string" } } } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "module": "Invoice", "applied": true, "refused": [ { "recordId": 102, "number": "INV-0102", "originalNumber": "F2024-0008", "collision": "taken", "takenBy": 77, "reason": "taken" } ] } } } } } } } }, "/webservice.php?operation=recycle_bin_list": { "get": { "operationId": "recycle_bin_list", "tags": [ "Enregistrements" ], "summary": "Lister la corbeille", "description": "Liste les enregistrements de la corbeille, du plus récemment supprimé au plus ancien : identifiant, module, libellé, date et auteur de la suppression, responsable. Réservé aux administrateurs.\n\nLa pagination se fait avec `limit` (1 à 100) et `offset` : `nextOffset` donne le décalage de la page suivante, ou `null` en fin de liste. Un module sans corbeille est refusé. Restaurez avec `recycle_bin_restore` ; le vidage de la corbeille n'est possible que depuis l'interface de Kafinea.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "module", "required": false, "schema": { "type": "string", "default": "" }, "example": "Accounts", "description": "Module des enregistrements supprimés, ou vide pour tous les modules." }, { "in": "query", "name": "query", "required": false, "schema": { "type": "string", "default": "" }, "example": "Exemple", "description": "Partie du libellé de l'enregistrement à rechercher (200 caractères au maximum)." }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "default": 50 }, "example": 50, "description": "Nombre maximal d'enregistrements par page, de 1 à 100." }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer", "default": 0 }, "example": 0, "description": "Rang du premier enregistrement renvoyé." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Les enregistrements de la page, le nombre total et le décalage de la page suivante.", "type": "object", "properties": { "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "module": { "type": "string" }, "label": { "type": "string" }, "deletedTime": { "type": "string" }, "deletedBy": { "type": "string" }, "owner": { "type": "string" } } } }, "total": { "type": "integer" }, "nextOffset": { "type": "null" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "records": [ { "id": "11x42", "module": "Accounts", "label": "Exemple SARL", "deletedTime": "2026-11-10 14:32:05", "deletedBy": "Claire Exemple", "owner": "Claire Exemple" } ], "total": 1, "nextOffset": null } } } } } } } }, "/webservice.php?operation=recycle_bin_restore": { "post": { "operationId": "recycle_bin_restore", "tags": [ "Enregistrements" ], "summary": "Restaurer des enregistrements de la corbeille", "description": "Restaure des enregistrements de la corbeille à partir de leur identifiant exact. Réservé aux administrateurs.\n\nChaque enregistrement restauré est décrit dans `restored`. Un identifiant inexact (un libellé ou un numéro seul), absent de la corbeille ou d'un module sans corbeille est signalé dans `errors` : rien n'est deviné et les autres identifiants sont traités. De 1 à 100 identifiants par appel. Le vidage de la corbeille n'est pas proposé par l'API.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "ids": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array", "items": { "type": "string" } }, "description": "Texte JSON (liste). Identifiants exacts renvoyés par `recycle_bin_list`, 100 au maximum.", "example": "[\"11x42\"]" } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Les enregistrements restaurés et les identifiants refusés.", "type": "object", "properties": { "restored": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "module": { "type": "string" }, "label": { "type": "string" }, "deletedTime": { "type": "string" }, "deletedBy": { "type": "string" }, "owner": { "type": "string" } } } }, "errors": { "type": "array" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "restored": [ { "id": "11x42", "module": "Accounts", "label": "Exemple SARL", "deletedTime": "2026-11-10 14:32:05", "deletedBy": "Claire Exemple", "owner": "Claire Exemple" } ], "errors": [] } } } } } } } }, "/webservice.php?operation=sync": { "get": { "operationId": "sync", "tags": [ "Enregistrements" ], "summary": "Lire les modifications depuis une date", "description": "Synchronisation incrémentale : renvoie les enregistrements créés ou modifiés (`updated`) et supprimés (`deleted`) depuis l'horodatage `modifiedTime`, pour les enregistrements dont l'utilisateur est le responsable et qu'il a le droit de lire.\n\nChaque appel renvoie au plus 100 enregistrements modifiés. Quand `more` vaut `true`, rappelez l'opération avec `lastModifiedTime` comme nouveau `modifiedTime` jusqu'à `more` à `false`, puis conservez la dernière valeur pour la synchronisation suivante. Le module `Users` est ignoré. Erreur `ACCESS_DENIED` pour un module inaccessible.", "x-kafinea-access": "user", "parameters": [ { "in": "query", "name": "modifiedTime", "required": true, "schema": { "type": "integer" }, "example": 1763100000, "description": "Horodatage Unix, en secondes, à partir duquel lire les modifications." }, { "in": "query", "name": "elementType", "required": false, "schema": { "type": "string" }, "example": "Accounts", "description": "Module à synchroniser. Vide : tous les modules accessibles." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Les enregistrements modifiés, les identifiants supprimés, le curseur à réutiliser et l'indicateur de suite.", "type": "object", "properties": { "updated": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "accountname": { "type": "string" }, "assigned_user_id": { "type": "string" }, "createdtime": { "type": "string" }, "modifiedtime": { "type": "string" } } } }, "deleted": { "type": "array", "items": { "type": "string" } }, "lastModifiedTime": { "type": "integer" }, "more": { "type": "boolean" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "updated": [ { "id": "11x42", "accountname": "Exemple SARL", "assigned_user_id": "19x1", "createdtime": "2026-11-03 09:15:22", "modifiedtime": "2026-11-10 14:32:05" } ], "deleted": [ "11x40" ], "lastModifiedTime": 1763116325, "more": false } } } } } } } }, "/webservice.php?operation=tag_create": { "post": { "operationId": "tag_create", "tags": [ "Enregistrements" ], "summary": "Créer une étiquette publique", "description": "Crée une étiquette publique portant ce nom. Si une étiquette du même nom existe déjà, elle est réutilisée et devient publique. L'identifiant renvoyé sert à `tag_object`.\n\nLes erreurs sont renvoyées dans la réponse, à l'intérieur de `result` : testez `result.success` plutôt que seulement `success`.", "x-kafinea-access": "user", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "tagName": { "type": "string", "description": "Nom de l'étiquette.", "example": "prioritaire" } }, "required": [ "tagName" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "`success` indique si l'étiquette a été créée ou retrouvée ; en cas d'échec, `error` donne le motif.", "type": "object", "properties": { "success": { "type": "boolean" }, "tag_id": { "type": "integer" }, "tag_name": { "type": "string" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "success": true, "tag_id": 12, "tag_name": "prioritaire" } } } } } } } }, "/webservice.php?operation=query": { "get": { "operationId": "query", "tags": [ "Requêtes et listes" ], "summary": "Interroger les enregistrements d'un module", "description": "Exécute une requête de lecture sur **un seul module** et renvoie les enregistrements auxquels l'utilisateur connecté a accès, avec les seuls champs qu'il peut lire.\n\n- Seule l'instruction `SELECT` est acceptée (`SELECT * | champs | count(*) FROM Module WHERE ... ORDER BY ... LIMIT ...`), sans jointure.\n- Les conditions se combinent avec `AND` et `OR`, sans parenthèses.\n- Une requête renvoie au plus 100 enregistrements : paginez avec `LIMIT décalage, nombre`.\n- La requête doit se terminer par un point-virgule.\n- Un accès refusé au module ou à sa lecture renvoie une erreur de permission.\n\nPour calculer des totaux ou des comptages sur de nombreux enregistrements, préférez `aggregate`. Pour retrouver les enregistrements d'une liste enregistrée, utilisez `customview_records`.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "query", "required": true, "schema": { "type": "string" }, "example": "SELECT accountname, bill_city FROM Accounts WHERE bill_city = 'Lyon' ORDER BY accountname LIMIT 0, 20;", "description": "Requête `SELECT` complète, terminée par un point-virgule et encodée pour l'URL." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Tableau des enregistrements trouvés. Chaque enregistrement contient son identifiant (`id`) et les champs demandés. Un `count(*)` renvoie un seul élément portant le nombre d'enregistrements.", "type": "array", "items": { "type": "object", "properties": { "accountname": { "type": "string" }, "bill_city": { "type": "string" }, "id": { "type": "string" } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": [ { "accountname": "Exemple SARL", "bill_city": "Lyon", "id": "3x42" }, { "accountname": "Exemple Industrie", "bill_city": "Lyon", "id": "3x57" } ] } } } } } } }, "/webservice.php?operation=aggregate": { "get": { "operationId": "aggregate", "tags": [ "Requêtes et listes" ], "summary": "Calculer des totaux, comptages et moyennes", "description": "Calcule directement dans la base des sommes, comptages, moyennes, minimums et maximums sur **un module**, avec ou sans regroupement (par mois, par client, etc.), en respectant les droits de l'utilisateur sur les enregistrements.\n\n- Fonctions disponibles : `SUM`, `COUNT`, `AVG`, `MIN`, `MAX` et `GROUP_CONCAT` (`COUNT` accepte `*`).\n- Une agrégation s'écrit sous forme d'objet `{field, function, alias}` ou de chaîne `\"SUM(hdnGrandTotal) AS total\"`.\n- `groupBy` accepte des noms de champs ou les fonctions `YEAR()`, `MONTH()`, `DAY()`, `DATE()`, `HOUR()` et `MINUTE()` appliquées à un champ.\n- `where` reprend la syntaxe des conditions de `query`, sans le mot `WHERE` et sans sous-requête.\n- Sur une instance à plusieurs sociétés, un module rattaché à une société est limité par défaut à la société courante de l'utilisateur. Passez `crossOrg` à `true` pour compter toutes les sociétés. Le membre `organizationScope` de la réponse indique le périmètre appliqué.\n\nUne agrégation invalide (champ inconnu, fonction non prévue, `where` incorrect) est refusée avec un message explicite. Utilisez cette opération plutôt que de relire tous les enregistrements avec `query`, limitée à 100 résultats par page.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "elementType", "required": true, "schema": { "type": "string" }, "example": "Invoice", "description": "Module à agréger." }, { "in": "query", "name": "aggregations", "required": true, "schema": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array" } }, "example": "[{\"field\":\"hdnGrandTotal\",\"function\":\"SUM\",\"alias\":\"total\"},\"COUNT(id) AS nombre\"]", "description": "Texte JSON (liste). Liste des calculs à effectuer : objets `{field, function, alias}` ou chaînes du type `SUM(hdnGrandTotal) AS total`. Au moins un calcul est obligatoire." }, { "in": "query", "name": "groupBy", "required": false, "schema": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array", "items": { "type": "string" } }, "default": "[]" }, "example": "[\"YEAR(invoicedate)\",\"MONTH(invoicedate)\"]", "description": "Texte JSON (liste). Expressions de regroupement : noms de champs ou fonctions de date (`YEAR`, `MONTH`, `DAY`, `DATE`, `HOUR`, `MINUTE`) appliquées à un champ." }, { "in": "query", "name": "where", "required": false, "schema": { "type": "string", "default": "" }, "example": "YEAR(invoicedate) = 2026", "description": "Filtre sans le mot `WHERE` : conditions sur les champs, `AND`/`OR`, chaînes entre apostrophes, fonctions de date. Sous-requêtes interdites." }, { "in": "query", "name": "orderBy", "required": false, "schema": { "type": "string", "default": "" }, "example": "YEAR(invoicedate), MONTH(invoicedate)", "description": "Tri : champ, expression de regroupement ou alias d'un calcul. Plusieurs expressions séparées par des virgules sont acceptées, chacune avec `ASC` ou `DESC` facultatif." }, { "in": "query", "name": "order", "required": false, "schema": { "type": "string", "enum": [ "", "ASC", "DESC" ], "default": "" }, "example": "ASC", "description": "Sens de tri appliqué aux expressions de `orderBy` qui n'en précisent pas (`ASC` par défaut)." }, { "in": "query", "name": "crossOrg", "required": false, "schema": { "type": "boolean", "default": false }, "description": "`false` (défaut) : un module rattaché à une société est limité à la société courante. `true` : toutes les sociétés sont comptées." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Les lignes calculées (`rows`), leur nombre, un rappel des agrégations et regroupements, et le périmètre de société appliqué. Chaque ligne porte une clé par expression de regroupement, puis une clé par alias de calcul.", "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "YEAR(invoicedate)": { "type": "string" }, "MONTH(invoicedate)": { "type": "string" }, "total": { "type": "string" }, "nombre": { "type": "string" } } } }, "rowCount": { "type": "integer" }, "aggregations": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "function": { "type": "string" }, "alias": { "type": "string" } } } }, "groupBy": { "type": "array", "items": { "type": "string" } }, "organizationScope": { "type": "object", "properties": { "applied": { "type": "boolean" }, "reason": { "type": "string" } } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "rows": [ { "YEAR(invoicedate)": "2026", "MONTH(invoicedate)": "1", "total": "12450.00", "nombre": "8" }, { "YEAR(invoicedate)": "2026", "MONTH(invoicedate)": "2", "total": "9830.50", "nombre": "6" } ], "rowCount": 2, "aggregations": [ { "field": "hdnGrandTotal", "function": "SUM", "alias": "total" }, { "field": "id", "function": "COUNT", "alias": "nombre" } ], "groupBy": [ "YEAR(invoicedate)", "MONTH(invoicedate)" ], "organizationScope": { "applied": false, "reason": "single_company" } } } } } } } } }, "/webservice.php?operation=customview_list": { "get": { "operationId": "customview_list", "tags": [ "Requêtes et listes" ], "summary": "Lister les listes d'un module", "description": "Renvoie les listes (filtres enregistrés) d'un module que l'utilisateur connecté peut ouvrir, dans l'ordre du sélecteur de listes de l'interface.\n\nChaque liste porte son identifiant numérique (`id`, le paramètre `viewname` du lien d'une liste), son nom, son statut (`system` : la liste sur laquelle arrive tout utilisateur, `public`, `private` ou `pending`), un indicateur `default` et son propriétaire. L'opération n'est pas réservée aux administrateurs : chacun voit les listes qu'il voit à l'écran.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "moduleName", "required": true, "schema": { "type": "string" }, "example": "HelpDesk", "description": "Module dont on veut lister les listes." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le module, la liste de ses listes et leur nombre.", "type": "object", "properties": { "module": { "type": "string" }, "views": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "string" }, "default": { "type": "boolean" }, "owner": { "type": "string" } } } }, "count": { "type": "integer" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "module": "HelpDesk", "views": [ { "id": 12, "name": "Tous", "status": "system", "default": false, "owner": "" }, { "id": 437, "name": "Tickets ouverts", "status": "public", "default": true, "owner": "Marie Exemple" } ], "count": 2 } } } } } } } }, "/webservice.php?operation=customview_read": { "get": { "operationId": "customview_read", "tags": [ "Requêtes et listes" ], "summary": "Lire la définition d'une liste", "description": "Renvoie la définition d'une liste que l'utilisateur peut ouvrir : colonnes, conditions, filtre de date et affichage.\n\n- `groups` contient les conditions telles qu'elles sont enregistrées (groupe 1 : toutes doivent être vraies, groupe 2 : l'une d'elles suffit, avec le lien vers la condition ou le groupe suivant).\n- Une condition portant sur un enregistrement lié nomme son champ avec `through` et `throughModule`.\n- `conditions` reprend un groupe unique sous la forme acceptée par `customview_upsert`, et `replayable` indique si la définition entière peut être réécrite telle quelle.\n- Les opérateurs sont ceux de `customview_upsert`. Un opérateur de date relative (`today`, `last7days`, `thismonth`...) est conservé tel quel et évalué à l'exécution de la liste.\n- `display` (réglages d'affichage) n'est renvoyé que si les affichages de liste sont activés sur l'instance.\n\nPour obtenir les enregistrements, appelez `customview_records` plutôt que de reconstruire les conditions dans une requête.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "moduleName", "required": true, "schema": { "type": "string" }, "example": "HelpDesk", "description": "Module de la liste (paramètre `module` de son lien)." }, { "in": "query", "name": "view", "required": true, "schema": { "type": "string" }, "example": "437", "description": "Numéro de la liste (`viewname` de son lien, par exemple `437`) ou son nom exact." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Résumé de la liste (`id`, `name`, `status`, `default`, `owner`) complété de ses colonnes, conditions, groupes, filtre de date et indicateur `replayable`.", "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "string" }, "default": { "type": "boolean" }, "owner": { "type": "string" }, "module": { "type": "string" }, "columns": { "type": "array", "items": { "type": "string" } }, "columnDetails": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" } } } }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "operator": { "type": "string" }, "value": { "type": "string" }, "glue": { "type": "string" } } } }, "groups": { "type": "array", "items": { "type": "object", "properties": { "group": { "type": "integer" }, "glue": { "type": "string" }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "operator": { "type": "string" }, "value": { "type": "string" }, "glue": { "type": "string" } } } } } } }, "dateFilter": { "type": "null" }, "replayable": { "type": "boolean" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "id": 437, "name": "Tickets ouverts", "status": "public", "default": true, "owner": "Marie Exemple", "module": "HelpDesk", "columns": [ "ticket_no", "ticket_title", "ticketstatus" ], "columnDetails": [ { "field": "ticket_no" }, { "field": "ticket_title" }, { "field": "ticketstatus" } ], "conditions": [ { "field": "ticketstatus", "operator": "not_equal", "value": "Closed", "glue": "" } ], "groups": [ { "group": 1, "glue": "", "conditions": [ { "field": "ticketstatus", "operator": "not_equal", "value": "Closed", "glue": "" } ] } ], "dateFilter": null, "replayable": true } } } } } } } }, "/webservice.php?operation=customview_records": { "get": { "operationId": "customview_records", "tags": [ "Requêtes et listes" ], "summary": "Lire les enregistrements d'une liste", "description": "Renvoie, page par page, les enregistrements qu'affiche une liste, à partir de la requête propre à la liste : partage des enregistrements, société courante et conditions évaluées à l'instant de l'appel (dates relatives, utilisateur courant), exactement comme à l'écran.\n\n- Les enregistrements ont la forme de ceux de `query`, limités aux colonnes de la liste que l'utilisateur peut lire. `columnsOmitted` nomme les colonnes d'enregistrements liés et les champs masqués.\n- `limit` va de 1 à 100 ; une valeur hors bornes est refusée.\n- Tant que `hasMore` vaut `true`, rappelez l'opération avec `offset` égal à `nextOffset`.\n- Sans `orderBy`, le tri se fait sur la dernière modification, comme à l'écran ; le champ de tri doit être un champ renvoyé par `describe`.\n\nÀ utiliser dès que l'on dispose d'un lien de liste (`view=List&viewname=`) ou du nom d'une liste.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "moduleName", "required": true, "schema": { "type": "string" }, "example": "HelpDesk", "description": "Module de la liste (paramètre `module` de son lien)." }, { "in": "query", "name": "view", "required": true, "schema": { "type": "string" }, "example": "437", "description": "Numéro de la liste (`viewname` de son lien, par exemple `437`) ou son nom exact." }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "default": 20 }, "description": "Nombre d'enregistrements par page, de 1 à 100." }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Rang du premier enregistrement de la page (0 pour la première)." }, { "in": "query", "name": "includeTotal", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Compte aussi tous les enregistrements de la liste et renvoie `total` (une requête supplémentaire)." }, { "in": "query", "name": "orderBy", "required": false, "schema": { "type": "string", "default": "" }, "example": "ticket_title", "description": "Champ de tri. Vide : tri sur la dernière modification, comme à l'écran." }, { "in": "query", "name": "sortOrder", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC", "" ], "default": "" }, "description": "Sens du tri : `ASC` ou `DESC`. Vide : `DESC`." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le module, la liste, les colonnes lues, les colonnes omises, la page d'enregistrements et les éléments de pagination. `total` n'est présent que si `includeTotal` est demandé.", "type": "object", "properties": { "module": { "type": "string" }, "view": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "columns": { "type": "array", "items": { "type": "string" } }, "columnsOmitted": { "type": "array" }, "records": { "type": "array", "items": { "type": "object", "properties": { "ticket_no": { "type": "string" }, "ticket_title": { "type": "string" }, "ticketstatus": { "type": "string" }, "id": { "type": "string" } } } }, "offset": { "type": "integer" }, "limit": { "type": "integer" }, "hasMore": { "type": "boolean" }, "nextOffset": { "type": "null" }, "total": { "type": "integer" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "module": "HelpDesk", "view": { "id": 437, "name": "Tickets ouverts" }, "columns": [ "ticket_no", "ticket_title", "ticketstatus" ], "columnsOmitted": [], "records": [ { "ticket_no": "TT101", "ticket_title": "Imprimante en panne", "ticketstatus": "Open", "id": "17x230" }, { "ticket_no": "TT100", "ticket_title": "Accès à la facturation", "ticketstatus": "In Progress", "id": "17x229" } ], "offset": 0, "limit": 20, "hasMore": false, "nextOffset": null, "total": 2 } } } } } } } }, "/webservice.php?operation=customview_upsert": { "post": { "operationId": "customview_upsert", "tags": [ "Requêtes et listes" ], "summary": "Créer ou réécrire une liste", "description": "Crée ou réécrit entièrement une liste nommée d'un module (colonnes, conditions et, si l'option est activée, affichage). Réservé aux administrateurs.\n\nLa définition passée dans `view` est un objet JSON :\n\n- `name` (obligatoire) : nom de la liste, clé de l'upsert. Une liste de ce nom est réécrite, sinon elle est créée.\n- `columns` (obligatoire) : noms de champs. Un appel remplace les colonnes : une liste vide est refusée.\n- `conditions` : objets `{field, operator, value, glue}`. `glue` (`and` ou `or`, `and` par défaut) lie la condition à la suivante.\n- `status` : `public` (défaut) ou `private`. `default` : `true` pour en faire la liste par défaut.\n- `display` : réglages d'affichage de la liste (voir ci-dessous). Sans cette clé, l'affichage actuel est conservé.\n\nOpérateurs lisibles : `equals`, `not_equal`, `starts_with`, `ends_with`, `contains`, `not_contains`, `less_than`, `greater_than`, `less_or_equal`, `greater_or_equal`, `before`, `after`, `between`, `empty`, `not_empty`. Les comparateurs bruts de l'interface restent acceptés, ce qui permet de réécrire telle quelle une liste lue par `customview_read`.\n\nLes champs sont désignés par leur nom API et doivent être actifs. La liste « système » (celle sur laquelle arrive tout utilisateur) peut changer de colonnes, mais ni de statut ni de caractère par défaut.\n\nClé `display` : `{\"default\": \"list|kanban|cards|calendar|planning|gantt|map|analysis\", \"kanban\": {...}, \"cards\": {...}, \"calendar\": {...}, \"planning\": {...}, \"gantt\": {...}, \"map\": {...}, \"analysis\": {...}}`.\n\n- `kanban` : `groupBy` (champ des colonnes), `laneBy` (couloirs, ou `null`), `personField` (photo sur la carte), `sumField` (total de colonne), `cardFields` (jusqu'à 4 champs), `dueField`, `hideEmptyColumns`, `density` (`comfortable` ou `compact`), `wipLimits` (limite de 1 à 999 par valeur de colonne) et `cardOrder` (`list` ou `manual`).\n- `cards` : `imageField`, `cardFields`, `groupBy`, `size` (`small`, `medium`, `large`).\n- `calendar`, `planning`, `gantt` : `startField`, `endField`, `startTimeField`, `endTimeField`, `colorBy`, `resourceField` (planning), `progressField`, `groupBy` (gantt), `personField` (calendrier, gantt), `cardFields`.\n- `map` : `addressBy` (`bill`, `ship`, `add`, `address`, `mailing`, `lane`, `other`, ou `ref::` pour l'adresse d'un enregistrement lié), `colorBy`, `cardFields`.\n- `analysis` : `rowsBy`, `colsBy`, `measure` (champ montant, ou `null` pour compter), `aggregate` (`sum`, `avg`, `min`, `max`), `dateGrain` (`day`, `week`, `month`, `quarter`, `year`) et `chart` (`bar`, `stacked`, `line`, `pie`, `none`).\n\nLes clés omises reprennent les valeurs par défaut du module (`list_display_defaults_get`).\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "configure", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "moduleName": { "type": "string", "description": "Module auquel appartient la liste.", "example": "Accounts" }, "view": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "description": "Texte JSON (objet). Définition complète de la liste : `name`, `columns`, `conditions`, `status`, `default` et éventuellement `display`.", "example": "{\"name\":\"Clients en dépassement d'encours\",\"columns\":[\"accountname\",\"bill_city\"],\"conditions\":[{\"field\":\"bill_city\",\"operator\":\"equals\",\"value\":\"Lyon\",\"glue\":\"and\"}],\"status\":\"public\"}" } }, "required": [ "moduleName", "view" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La liste écrite : identifiant, action (`created` ou `rewritten`), nombre de colonnes et de conditions, indicateur de liste système et réglages d'affichage en vigueur.", "type": "object", "properties": { "module": { "type": "string" }, "view": { "type": "string" }, "id": { "type": "integer" }, "action": { "type": "string" }, "columns": { "type": "integer" }, "conditions": { "type": "integer" }, "system_view": { "type": "boolean" }, "display": { "type": "null" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "module": "Accounts", "view": "Clients en dépassement d'encours", "id": 438, "action": "created", "columns": 2, "conditions": 1, "system_view": false, "display": null } } } } } } } }, "/webservice.php?operation=customview_delete": { "post": { "operationId": "customview_delete", "tags": [ "Requêtes et listes" ], "summary": "Supprimer une liste", "description": "Supprime une liste nommée d'un module, comme le fait l'éditeur de filtres. Réservé aux administrateurs.\n\nL'opération refuse :\n\n- la liste sur laquelle arrive tout utilisateur (liste système) ;\n- la liste par défaut du module : définissez d'abord une autre liste par défaut ;\n- un nom partagé par plusieurs listes (ambigu) ;\n- un nom inconnu (enregistrement introuvable).\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "configure", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "moduleName": { "type": "string", "description": "Module auquel appartient la liste.", "example": "Accounts" }, "name": { "type": "string", "description": "Nom exact de la liste à supprimer, tel que l'utilisateur le lit.", "example": "Clients en dépassement d'encours" } }, "required": [ "moduleName", "name" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La liste supprimée.", "type": "object", "properties": { "module": { "type": "string" }, "view": { "type": "string" }, "id": { "type": "integer" }, "action": { "type": "string" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "module": "Accounts", "view": "Clients en dépassement d'encours", "id": 438, "action": "deleted" } } } } } } } }, "/webservice.php?operation=list_display_defaults_get": { "get": { "operationId": "list_display_defaults_get", "tags": [ "Requêtes et listes" ], "summary": "Lire les affichages par défaut des listes", "description": "Renvoie les réglages d'affichage par défaut des listes d'un module (champ des colonnes Kanban, total de colonne, champs des cartes, date d'échéance, affichage ouvert par les listes), ce que le module choisirait de lui-même et les champs autorisés pour chaque réglage. Réservé aux administrateurs.\n\n`defaults` vaut `null` lorsque le module n'a aucun réglage : les listes utilisent alors les valeurs détectées (`detected`). Une liste surcharge ces défauts clé par clé avec `customview_upsert`.\n\n> Réservée aux administrateurs de l'instance. Disponible lorsque les affichages de liste (Kanban, calendrier, planning, Gantt) sont activés sur l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "moduleName", "required": true, "schema": { "type": "string" }, "example": "Potentials", "description": "Module dont on veut lire les affichages par défaut." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le module, ses réglages par défaut (`defaults`), les réglages détectés automatiquement (`detected`), les champs candidats par réglage (`candidates`) et une note d'usage (`notice`)." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=list_display_defaults_upsert": { "post": { "operationId": "list_display_defaults_upsert", "tags": [ "Requêtes et listes" ], "summary": "Définir les affichages par défaut des listes", "description": "Remplace les réglages d'affichage par défaut que toutes les listes d'un module utilisent tant qu'elles n'ont pas les leurs. Réservé aux administrateurs.\n\n- `display` est un objet : une liste ou une valeur non objet est refusée.\n- Les clés omises ne sont plus définies : l'appel remplace l'ensemble des défauts du module.\n- Les champs sont vérifiés : un champ inconnu ou inadapté est refusé, avec la liste des champs acceptés.\n\nLa forme de `display` est celle de la clé `display` de `customview_upsert`. Utilisez `list_display_defaults_get` pour connaître les champs acceptés par rôle.\n\n> Réservée aux administrateurs de l'instance. Disponible lorsque les affichages de liste (Kanban, calendrier, planning, Gantt) sont activés sur l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "configure", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "moduleName": { "type": "string", "description": "Module dont on définit les affichages par défaut.", "example": "Potentials" }, "display": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "description": "Texte JSON (objet). Réglages d'affichage, de même forme que la clé `display` de `customview_upsert` : `default`, `kanban`, `cards`, `calendar`, `planning`, `gantt`, `map`, `analysis`.", "example": "{\"default\":\"kanban\",\"kanban\":{\"groupBy\":\"sales_stage\",\"sumField\":\"amount\"}}" } }, "required": [ "moduleName", "display" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le module et les réglages par défaut enregistrés (`defaults`)." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=relatedtypes": { "get": { "operationId": "relatedtypes", "tags": [ "Relations" ], "summary": "Lister les listes connexes d'un module", "description": "Renvoie les listes connexes disponibles pour un module et accessibles à l'utilisateur. Pour chacune, la clé de `information` est le libellé de la liste, à utiliser tel quel dans `relatedLabel` (lecture) et `relationIdLabel` (ajout, retrait) : un même module peut apparaître sous plusieurs libellés.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "elementType", "required": true, "schema": { "type": "string" }, "example": "Accounts", "description": "Module dont on veut les listes connexes." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "`types` liste les modules liés ; `information` décrit chaque liste par son libellé (`name`: module lié, `isEntity`: 1 pour un module d'enregistrements).", "type": "object", "properties": { "types": { "type": "array", "items": { "type": "string" } }, "information": { "type": "object", "properties": { "Contacts": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "isEntity": { "type": "integer" } } }, "Documents": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "isEntity": { "type": "integer" } } } } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "types": [ "Contacts", "Documents" ], "information": { "Contacts": { "name": "Contacts", "label": "Contacts", "isEntity": 1 }, "Documents": { "name": "Documents", "label": "Documents", "isEntity": 1 } } } } } } } } } }, "/webservice.php?operation=query_related": { "get": { "operationId": "query_related", "tags": [ "Relations" ], "summary": "Interroger une liste connexe", "description": "Lit les enregistrements d'une liste connexe d'un enregistrement source. `query` est une requête `SELECT` sur le module de la liste (`SELECT * FROM Documents`), qui peut porter une clause `WHERE` ; l'ERP la restreint aux enregistrements liés à `id`. Le module de la requête doit être celui que `relatedtypes` annonce pour `relatedLabel`, sinon l'erreur `UNKOWN_ENTITY` signale une relation incorrecte.\n\nLe droit de lecture sur l'enregistrement source est contrôlé. Un lien porté seulement par un champ de référence de l'autre enregistrement n'est pas une liste connexe : lisez-le avec `query` sur ce champ.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "query", "required": true, "schema": { "type": "string" }, "example": "SELECT * FROM Documents WHERE filesize > 10000", "description": "Requête `SELECT` sur le module de la liste connexe." }, { "in": "query", "name": "id", "required": true, "schema": { "type": "string" }, "example": "11x42", "description": "Identifiant de l'enregistrement source." }, { "in": "query", "name": "relatedLabel", "required": true, "schema": { "type": "string" }, "example": "Documents", "description": "Libellé de la liste connexe, tel que renvoyé par `relatedtypes`." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Les enregistrements liés qui répondent à la requête, avec leurs champs.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "notes_title": { "type": "string" }, "filesize": { "type": "string" }, "assigned_user_id": { "type": "string" } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": [ { "id": "15x7890", "notes_title": "Contrat cadre", "filesize": "48213", "assigned_user_id": "19x1" } ] } } } } } } }, "/webservice.php?operation=retrieve_related": { "get": { "operationId": "retrieve_related", "tags": [ "Relations" ], "summary": "Lire une liste connexe", "description": "Équivalent de `query_related` avec `SELECT *` sur le module lié : renvoie tous les enregistrements de la liste connexe, avec tous leurs champs visibles. Utilisez `query_related` pour filtrer ou choisir les champs.", "x-kafinea-access": "user", "parameters": [ { "in": "query", "name": "id", "required": true, "schema": { "type": "string" }, "example": "11x42", "description": "Identifiant de l'enregistrement source." }, { "in": "query", "name": "relatedType", "required": true, "schema": { "type": "string" }, "example": "Documents", "description": "Module de la liste connexe, tel que renvoyé par `relatedtypes` (champ `name`)." }, { "in": "query", "name": "relatedLabel", "required": true, "schema": { "type": "string" }, "example": "Documents", "description": "Libellé de la liste connexe, tel que renvoyé par `relatedtypes`." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Les enregistrements liés, avec leurs champs.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "notes_title": { "type": "string" }, "filesize": { "type": "string" }, "assigned_user_id": { "type": "string" } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": [ { "id": "15x7890", "notes_title": "Contrat cadre", "filesize": "48213", "assigned_user_id": "19x1" } ] } } } } } } }, "/webservice.php?operation=add_related": { "post": { "operationId": "add_related", "tags": [ "Relations" ], "summary": "Ajouter un enregistrement à une liste connexe", "description": "Relie un enregistrement à un enregistrement source dans une liste connexe existante. Il faut le droit de modifier la source et de lire l'enregistrement lié ; pour la liste des produits spécifiques, qui met à jour la fiche liée, le droit de modification des deux produits.\n\nUn libellé qui ne désigne aucune liste connexe compatible renvoie l'erreur `REFERENCE_INVALID` au lieu d'un succès sans effet. Les compositions de kit de produits sont refusées : utilisez les opérations dédiées aux kits (`product_kit_set_components`).", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "sourceRecordId": { "type": "string", "description": "Identifiant de l'enregistrement source.", "example": "11x42" }, "relatedRecordId": { "type": "string", "description": "Identifiant de l'enregistrement à relier.", "example": "15x7890" }, "relationIdLabel": { "type": "string", "description": "Libellé exact de la liste connexe, tel que renvoyé par `relatedtypes`.", "example": "Documents" } }, "required": [ "sourceRecordId", "relatedRecordId", "relationIdLabel" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Confirmation de l'ajout.", "type": "object", "properties": { "message": { "type": "string" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "message": "successfull" } } } } } } } }, "/webservice.php?operation=delete_related": { "post": { "operationId": "delete_related", "tags": [ "Relations" ], "summary": "Retirer un enregistrement d'une liste connexe", "description": "Opération inverse de `add_related`, avec le même libellé et le droit de modification sur la source. Seul le lien est supprimé, jamais un enregistrement. Quand le lien est porté par un champ de référence de l'enregistrement lié, ce champ est vidé et le droit de modification sur cet enregistrement est requis.\n\n`relatedRecordId` accepte un identifiant ou un tableau JSON d'au plus 100 identifiants du même module. Les compositions de kit de produits sont refusées : utilisez `product_kit_remove_component`. Un libellé inconnu renvoie `REFERENCE_INVALID`.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "sourceRecordId": { "type": "string", "description": "Identifiant de l'enregistrement source ; le droit de modification est requis.", "example": "11x42" }, "relatedRecordId": { "type": "string", "description": "Identifiant de l'enregistrement lié, ou tableau JSON d'au plus 100 identifiants du même module.", "example": "15x7890" }, "relationIdLabel": { "type": "string", "description": "Libellé exact de la liste connexe, tel que renvoyé par `relatedtypes` (même règle que pour `add_related`).", "example": "Documents" } }, "required": [ "sourceRecordId", "relatedRecordId", "relationIdLabel" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Confirmation, avec les identifiants dont le lien a été retiré.", "type": "object", "properties": { "message": { "type": "string" }, "sourceRecordId": { "type": "string" }, "removed": { "type": "array", "items": { "type": "string" } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "message": "successfull", "sourceRecordId": "11x42", "removed": [ "15x7890" ] } } } } } } } }, "/webservice.php?operation=listtypes": { "get": { "operationId": "listtypes", "tags": [ "Modules et champs" ], "summary": "Lister les modules accessibles", "description": "Renvoie les modules auxquels l'utilisateur connecté a accès, avec leur libellé. Les droits de l'utilisateur s'appliquent : un module qu'il ne peut pas ouvrir n'est pas listé.\n\nLe paramètre facultatif `fieldTypeList` limite la réponse aux modules qui possèdent au moins un champ de l'un des types indiqués. Les noms de la liste `types` sont ceux à passer comme `elementType` ou `moduleName` aux autres opérations.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "fieldTypeList", "required": false, "schema": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array", "items": { "type": "string" } }, "default": "[]" }, "example": "[\"picklist\"]", "description": "Texte JSON (liste). Types de champs recherchés (par exemple `reference`, `picklist`). Vide : tous les modules accessibles sont renvoyés." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "`types` : noms des modules accessibles. `information` : pour chaque nom, `isEntity` (module à enregistrements), `label` (pluriel) et `singular` (singulier), traduits dans la langue de l'utilisateur.", "type": "object", "properties": { "types": { "type": "array", "items": { "type": "string" } }, "information": { "type": "object", "properties": { "Accounts": { "type": "object", "properties": { "isEntity": { "type": "boolean" }, "label": { "type": "string" }, "singular": { "type": "string" } } }, "Contacts": { "type": "object", "properties": { "isEntity": { "type": "boolean" }, "label": { "type": "string" }, "singular": { "type": "string" } } }, "Invoice": { "type": "object", "properties": { "isEntity": { "type": "boolean" }, "label": { "type": "string" }, "singular": { "type": "string" } } } } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "types": [ "Accounts", "Contacts", "Invoice" ], "information": { "Accounts": { "isEntity": true, "label": "Organisations", "singular": "Organisation" }, "Contacts": { "isEntity": true, "label": "Contacts", "singular": "Contact" }, "Invoice": { "isEntity": true, "label": "Factures", "singular": "Facture" } } } } } } } } } }, "/webservice.php?operation=describe": { "get": { "operationId": "describe", "tags": [ "Modules et champs" ], "summary": "Décrire un module et ses champs", "description": "Renvoie la description d'un module : droits de l'utilisateur (création, modification, suppression, lecture), préfixe des identifiants (`idPrefix`), champs qui composent le libellé d'un enregistrement (`labelFields`) et liste des champs avec leur libellé, leur type, leur caractère obligatoire ou modifiable. Seuls les champs que l'utilisateur peut lire sont renvoyés.\n\nChaque champ porte `custom` : `true` pour un champ créé par un administrateur (nom commençant par `cf_`), `false` pour un champ livré avec l'ERP.\n\nPar défaut, seuls les champs actifs sont décrits. `fieldStatus` à `all` ou `inactive` ajoute ou renvoie les champs livrés mais non activés (chacun porte alors `active`) : cette variante est réservée aux administrateurs. Un module sans enregistrements ou non accessible à l'utilisateur est refusé avec une erreur de permission.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "elementType", "required": true, "schema": { "type": "string" }, "example": "Accounts", "description": "Nom du module à décrire." }, { "in": "query", "name": "fieldStatus", "required": false, "schema": { "type": "string", "default": "active", "enum": [ "active", "all", "inactive" ] }, "example": "active", "description": "Champs à décrire : `active` (défaut), `inactive` ou `all`. Les deux dernières valeurs sont réservées aux administrateurs." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La description du module et de ses champs.", "type": "object", "properties": { "label": { "type": "string" }, "name": { "type": "string" }, "createable": { "type": "boolean" }, "updateable": { "type": "boolean" }, "deleteable": { "type": "boolean" }, "retrieveable": { "type": "boolean" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "mandatory": { "type": "boolean" }, "type": { "type": "object", "properties": { "name": { "type": "string" } } }, "isunique": { "type": "boolean" }, "nullable": { "type": "boolean" }, "editable": { "type": "boolean" }, "custom": { "type": "boolean" } } } }, "idPrefix": { "type": "string" }, "isEntity": { "type": "boolean" }, "allowDuplicates": { "type": "boolean" }, "labelFields": { "type": "string" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "label": "Organisations", "name": "Accounts", "createable": true, "updateable": true, "deleteable": true, "retrieveable": true, "fields": [ { "name": "accountname", "label": "Nom de l'organisation", "mandatory": true, "type": { "name": "string" }, "isunique": false, "nullable": false, "editable": true, "custom": false }, { "name": "id", "label": "Identifiant", "mandatory": false, "type": { "name": "autogenerated" }, "isunique": false, "nullable": false, "editable": false, "custom": false } ], "idPrefix": "3", "isEntity": true, "allowDuplicates": true, "labelFields": "accountname" } } } } } } } }, "/webservice.php?operation=field_upsert": { "post": { "operationId": "field_upsert", "tags": [ "Modules et champs" ], "summary": "Créer ou modifier un champ personnalisé", "description": "Crée ou modifie **un champ personnalisé** d'un module, par l'éditeur de disposition. Réservé aux administrateurs. L'opération ne peut jamais ajouter ni remodeler un champ livré avec l'ERP.\n\nLa définition passée dans `field` est un objet JSON :\n\n- `name` : nom du champ, `cf_` suivi de lettres et de chiffres. C'est la clé de l'upsert : un nom existant désigne un champ à modifier. Omis à la création, le champ est nommé `cf_`. Un nom que l'éditeur transformerait (ponctuation, espaces) est refusé avec le nom accepté.\n- `label` : libellé du champ, aussi clé de traduction. Obligatoire à la création, unique dans le module.\n- `type` : obligatoire à la création, non modifiable ensuite. Valeurs : `Text`, `Decimal`, `Integer`, `Percent`, `Currency`, `Date`, `Email`, `Phone`, `Picklist`, `URL`, `Checkbox`, `TextArea`, `MultiSelectCombo`, `Time`, `MdsRichText`, `MdsLinkButton`, `MdsRollup`.\n- `block` : libellé (ou identifiant) du bloc d'accueil, obligatoire à la création.\n- `length` et `decimal` (création seulement) : taille des champs `Text`, `Decimal`, `Integer`, `Currency` (100 par défaut) et nombre de décimales de `Decimal` et `Currency` (2 par défaut).\n- `picklistValues` (création seulement) : valeurs d'un `Picklist` ou d'un `MultiSelectCombo`, en tableau ou séparées par des virgules. Pour un champ existant, utilisez `setPicklistValues`.\n- `defaultValue`, `mandatory` (faux par défaut), `quickcreate` (2 : affiché, 1 : non affiché, valeur par défaut), `masseditable`, `summaryfield`, `headerfield`.\n- `labels` : texte du libellé par code de langue d'un pack de langue installé, par exemple `{\"fr_fr\": \"Encours\", \"en_us\": \"Outstanding\"}`. Un code inconnu est refusé avant toute écriture.\n- `rollup` (type `MdsRollup`, obligatoire à la création) : valeur en lecture seule calculée par l'ERP à partir des enregistrements liés. Objet `{relation, aggregate, field, conditions}` où `relation` est `{\"type\": \"related_list\", \"module\": ..., \"label\": ...}` ou `{\"type\": \"entity_link\", \"module\": \"HelpDesk|Project|ProjectTask\", \"link_type\": ...}`, `aggregate` vaut `count`, `count_distinct`, `sum`, `avg`, `min` ou `max`, et `conditions` filtre les enregistrements liés. Chaque enregistrement est recalculé après une sauvegarde.\n\nLa création est tout ou rien : la nouvelle colonne est d'abord essayée sur une copie de la table. Si la base la refuse (limite de taille de ligne de la table des champs personnalisés, typiquement), la création est refusée avec le motif de la base et rien n'est écrit. Pour un champ de texte long, un champ `TextArea` évite cette limite.\n\nSur un champ personnalisé existant, seuls `label`, `labels`, `defaultValue`, `mandatory`, `quickcreate`, `masseditable`, `summaryfield`, `headerfield` et le `rollup` d'un champ `MdsRollup` peuvent changer ; le type et la taille ne changent jamais. Pour détecter des champs déjà cassés, utilisez `field_schema_check`.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "configure", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "moduleName": { "type": "string", "description": "Module qui porte le champ.", "example": "Accounts" }, "field": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "Text", "Decimal", "Integer", "Percent", "Currency", "Date", "Email", "Phone", "Picklist", "URL", "Checkbox", "TextArea", "MultiSelectCombo", "Time", "MdsRichText", "MdsLinkButton", "MdsRollup" ] }, "rollup": { "type": "object" }, "block": { "type": "string" }, "length": { "type": "integer", "minimum": 1 }, "decimal": { "type": "integer", "minimum": 0 }, "picklistValues": { "type": [ "array", "string" ], "items": { "type": "string" } }, "defaultValue": { "type": [ "string", "number" ] }, "mandatory": { "type": "boolean" }, "quickcreate": { "type": [ "integer", "boolean" ] }, "masseditable": { "type": [ "integer", "boolean" ] }, "summaryfield": { "type": [ "integer", "boolean" ] }, "headerfield": { "type": [ "integer", "boolean" ] }, "labels": { "type": "object", "additionalProperties": { "type": "string" } } } }, "description": "Texte JSON (objet). Définition du champ : `name`, `label`, `type`, `block`, `length`, `decimal`, `picklistValues`, `defaultValue`, `mandatory`, `quickcreate`, `masseditable`, `summaryfield`, `headerfield`, `labels`, `rollup`.", "example": "{\"label\":\"Encours autorisé\",\"type\":\"Currency\",\"block\":\"LBL_ACCOUNT_INFORMATION\",\"mandatory\":false,\"labels\":{\"fr_fr\":\"Encours autorisé\",\"en_us\":\"Credit limit\"}}" } }, "required": [ "moduleName", "field" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le champ concerné, l'action effectuée (`created`, `modified` ou `unchanged`) et, si `labels` est envoyé, le résultat par langue (`created`, `updated` ou `unchanged`).", "type": "object", "properties": { "module": { "type": "string" }, "field": { "type": "string" }, "action": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "labels": { "type": "object", "properties": { "fr_fr": { "type": "string" }, "en_us": { "type": "string" } } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "module": "Accounts", "field": "cf_1042", "action": "created", "label": "Encours autorisé", "type": "Currency", "labels": { "fr_fr": "created", "en_us": "created" } } } } } } } } }, "/webservice.php?operation=field_schema_check": { "get": { "operationId": "field_schema_check", "tags": [ "Modules et champs" ], "summary": "Détecter les champs sans colonne en base", "description": "Liste les champs dont la colonne est absente de la base de données, par exemple après une création de champ refusée par la base. Chaque lecture du module concerné échoue tant que ce défaut subsiste. Lecture seule, réservée aux administrateurs.\n\nChaque entrée donne le module, le champ, son libellé, la table et la colonne attendues, l'existence de la table, `custom` (champ créé par un administrateur) et `active`. Un champ personnalisé listé se supprime dans l'éditeur de disposition, puis se recrée avec `field_upsert`. Un champ livré avec l'ERP est réparé par la mise à jour de l'instance.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "moduleName", "required": false, "schema": { "type": "string", "default": "" }, "example": "Accounts", "description": "Limite la vérification à un module. Vide : tous les modules sont vérifiés." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "`fieldsWithoutColumn` : champs concernés. `total` : leur nombre. `notice` : consigne de réparation.", "type": "object", "properties": { "fieldsWithoutColumn": { "type": "array" }, "total": { "type": "integer" }, "notice": { "type": "string" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "fieldsWithoutColumn": [], "total": 0, "notice": "Every field has its column." } } } } } } } }, "/webservice.php?operation=set_field_visibility": { "post": { "operationId": "set_field_visibility", "tags": [ "Modules et champs" ], "summary": "Activer ou désactiver des champs", "description": "Active ou désactive des champs existants d'un module : l'ERP livre le champ, l'intégrateur l'active. Réservé aux administrateurs. L'opération est idempotente : un champ déjà dans l'état demandé est rapporté dans `unchanged`.\n\n- Elle ne crée aucun champ (voir `field_upsert`).\n- Elle refuse ce que l'éditeur de disposition refuse : désactiver un champ structurel ou obligatoire, ou modifier un champ qui n'est jamais affiché dans les formulaires.\n- Un champ inconnu ou refusé est rapporté dans `errors` sans bloquer les autres champs de la demande.\n- Un champ activé est placé en fin de son bloc ; `layout_move_field` permet ensuite de le déplacer.\n\nUne liste `fields` vide ou un `state` autre que `active` ou `inactive` est refusé avec une erreur de syntaxe.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "configure", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "moduleName": { "type": "string", "description": "Module dont les champs sont modifiés.", "example": "Products" }, "fields": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array" }, "description": "Texte JSON (liste). Noms des champs à traiter (tableau non vide de noms API).", "example": "[\"mdsweight\",\"vendor_id\"]" }, "state": { "type": "string", "description": "État voulu : `active` ou `inactive`.", "example": "active" } }, "required": [ "moduleName", "fields", "state" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Les champs modifiés (`changed`), ceux qui avaient déjà l'état demandé (`unchanged`) et les champs refusés avec leur motif (`errors`).", "type": "object", "properties": { "module": { "type": "string" }, "state": { "type": "string" }, "changed": { "type": "array", "items": { "type": "string" } }, "unchanged": { "type": "array" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "module": "Products", "state": "active", "changed": [ "mdsweight" ], "unchanged": [], "errors": [ { "field": "vendor_id", "message": "Field [vendor_id] does not exist on module [Products]." } ] } } } } } } } }, "/webservice.php?operation=layout_move_field": { "post": { "operationId": "layout_move_field", "tags": [ "Modules et champs" ], "summary": "Déplacer ou réordonner des champs", "description": "Déplace des champs vers un autre bloc et/ou change leur ordre dans le formulaire. Réservé aux administrateurs. Champs et blocs sont désignés par leur nom et leur libellé, jamais par un identifiant : la même disposition se rejoue sur n'importe quelle instance.\n\nChaque élément de `moves` est un objet :\n\n- `field` (obligatoire) : nom du champ ;\n- `block` : libellé du bloc d'arrivée (le bloc actuel du champ si omis) ;\n- `sequence` : position dans le bloc (le champ est ajouté à la fin du bloc si omis).\n\nLes déplacements sont appliqués dans l'ordre, au mieux : un champ ou un bloc inconnu, ou un déplacement refusé, est rapporté dans `errors` sans bloquer les autres. Une liste `moves` vide ou un élément sans `field` est refusé avec une erreur de syntaxe. Cette opération est le préalable à `block_delete`, qui refuse un bloc contenant encore des champs.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "configure", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "moduleName": { "type": "string", "description": "Module dont on réorganise la disposition.", "example": "Accounts" }, "moves": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array" }, "description": "Texte JSON (liste). Déplacements à effectuer : objets `{field, block, sequence}`.", "example": "[{\"field\":\"cf_1042\",\"block\":\"Encours client\",\"sequence\":3}]" } }, "required": [ "moduleName", "moves" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Les champs déplacés (avec leur bloc et leur position finale) et les déplacements en erreur.", "type": "object", "properties": { "module": { "type": "string" }, "moved": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "block": { "type": "string" }, "sequence": { "type": "integer" } } } }, "errors": { "type": "array" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "module": "Accounts", "moved": [ { "field": "cf_1042", "block": "Encours client", "sequence": 3 } ], "errors": [] } } } } } } } }, "/webservice.php?operation=block_upsert": { "post": { "operationId": "block_upsert", "tags": [ "Modules et champs" ], "summary": "Créer, renommer ou replier un bloc", "description": "Crée un bloc de la disposition d'un module, le renomme, le replie par défaut et définit le texte de son libellé par langue. Réservé aux administrateurs.\n\nLa définition passée dans `block` est un objet JSON :\n\n- `label` (obligatoire) : libellé du bloc tel qu'affiché dans l'éditeur de disposition. C'est la clé de l'upsert, insensible à la casse : le bloc est créé si aucun ne porte ce libellé.\n- `before` (création seulement) : libellé du bloc devant lequel placer le nouveau bloc. Par défaut, en fin de formulaire.\n- `collapsed` : `true` pour que le bloc s'ouvre replié, `false` déplié. Autorisé sur un bloc livré avec l'ERP.\n- `rename_to` : nouveau libellé d'un bloc personnalisé existant. Refusé sur un bloc livré : utilisez `labels`.\n- `labels` : texte du libellé par code de langue d'un pack installé, par exemple `{\"fr_fr\": \"Encours\", \"en_us\": \"Outstanding\"}`. C'est aussi le moyen de traduire un bloc livré.\n\nUn code de langue inconnu est refusé avant toute écriture, et un bloc créé par l'appel est supprimé si ses traductions ne peuvent pas être écrites.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "configure", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "moduleName": { "type": "string", "description": "Module dont on modifie la disposition.", "example": "Accounts" }, "block": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object", "properties": { "label": { "type": "string" }, "before": { "type": "string" }, "collapsed": { "type": [ "boolean", "string" ] }, "rename_to": { "type": "string" }, "labels": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "label" ] }, "description": "Texte JSON (objet). Définition du bloc : `label`, `before`, `collapsed`, `rename_to`, `labels`.", "example": "{\"label\":\"Encours client\",\"before\":\"Description\",\"labels\":{\"fr_fr\":\"Encours client\",\"en_us\":\"Customer outstanding\"}}" } }, "required": [ "moduleName", "block" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le bloc concerné et l'action effectuée (`created`, `modified` ou `unchanged`). À la création, `sequence` donne sa position ; à la modification, `changed` liste ce qui a changé. Si `labels` est envoyé, `labels` donne le résultat par langue (`created`, `updated` ou `unchanged`).", "type": "object", "properties": { "module": { "type": "string" }, "block": { "type": "string" }, "action": { "type": "string" }, "sequence": { "type": "integer" }, "labels": { "type": "object", "properties": { "fr_fr": { "type": "string" }, "en_us": { "type": "string" } } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "module": "Accounts", "block": "Encours client", "action": "created", "sequence": 4, "labels": { "fr_fr": "created", "en_us": "created" } } } } } } } } }, "/webservice.php?operation=block_delete": { "post": { "operationId": "block_delete", "tags": [ "Modules et champs" ], "summary": "Supprimer un bloc vide", "description": "Supprime un bloc personnalisé vide de la disposition d'un module. Réservé aux administrateurs. L'opération refuse exactement ce que l'éditeur de disposition refuse :\n\n- un bloc qui contient encore des champs : déplacez-les d'abord avec `layout_move_field`, pour qu'aucun champ ne soit supprimé par effet de bord ;\n- un bloc livré avec l'ERP, qui ne peut pas être supprimé.\n\nUn libellé inconnu est refusé avec la liste des blocs existants.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "configure", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "moduleName": { "type": "string", "description": "Module auquel appartient le bloc.", "example": "Accounts" }, "block": { "type": "string", "description": "Libellé du bloc tel qu'affiché dans l'éditeur de disposition (insensible à la casse). Une valeur numérique est interprétée comme l'identifiant du bloc.", "example": "Commentaire import" } }, "required": [ "moduleName", "block" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le bloc supprimé.", "type": "object", "properties": { "module": { "type": "string" }, "block": { "type": "string" }, "action": { "type": "string" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "module": "Accounts", "block": "Commentaire import", "action": "deleted" } } } } } } } }, "/webservice.php?operation=getPicklistValues": { "get": { "operationId": "getPicklistValues", "tags": [ "Modules et champs" ], "summary": "Lire les valeurs d'une liste de choix", "description": "Renvoie les valeurs sélectionnables d'un champ de type liste de choix (liste simple ou liste dépendant du rôle). Réservé aux administrateurs. Un champ introuvable ou qui n'est pas une liste de choix est refusé.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "moduleName", "required": true, "schema": { "type": "string" }, "example": "HelpDesk", "description": "Module qui porte le champ." }, { "in": "query", "name": "fieldName", "required": true, "schema": { "type": "string" }, "example": "ticketpriorities", "description": "Nom API du champ liste de choix." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le module, le champ et la liste de ses valeurs.", "type": "object", "properties": { "moduleName": { "type": "string" }, "fieldName": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "moduleName": "HelpDesk", "fieldName": "ticketpriorities", "values": [ "Low", "Normal", "High", "Urgent" ] } } } } } } } }, "/webservice.php?operation=setPicklistValues": { "post": { "operationId": "setPicklistValues", "tags": [ "Modules et champs" ], "summary": "Remplacer les valeurs d'une liste de choix", "description": "Remplace la liste des valeurs sélectionnables d'un champ de type liste de choix. Réservé aux administrateurs.\n\n- Les valeurs absentes de `values` sont supprimées de la liste ; les valeurs nouvelles sont ajoutées.\n- La même règle que l'éditeur de listes s'applique avant toute écriture : aucune valeur ne peut être ajoutée à une liste fermée, et une valeur protégée ne peut pas être supprimée. Le refus nomme le champ et les valeurs concernées.\n- Un champ introuvable ou qui n'est pas une liste de choix est refusé.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "configure", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "moduleName": { "type": "string", "description": "Module qui porte le champ.", "example": "HelpDesk" }, "fieldName": { "type": "string", "description": "Nom API du champ liste de choix.", "example": "ticketpriorities" }, "values": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array" }, "description": "Texte JSON (liste). Liste complète des valeurs voulues, qui remplace la liste actuelle.", "example": "[\"Low\",\"Normal\",\"High\",\"Urgent\",\"Critique\"]" } }, "required": [ "moduleName", "fieldName", "values" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La liste résultante (`values`) et la différence appliquée : valeurs ajoutées (`added`) et supprimées (`removed`).", "type": "object", "properties": { "moduleName": { "type": "string" }, "fieldName": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } }, "added": { "type": "array", "items": { "type": "string" } }, "removed": { "type": "array" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "moduleName": "HelpDesk", "fieldName": "ticketpriorities", "values": [ "Low", "Normal", "High", "Urgent", "Critique" ], "added": [ "Critique" ], "removed": [] } } } } } } } }, "/webservice.php?operation=numbering_upsert": { "post": { "operationId": "numbering_upsert", "tags": [ "Modules et champs" ], "summary": "Lire ou régler la numérotation des documents", "description": "Lit la numérotation d'un module de documents, repositionne un compteur ou prépare le compteur d'une période à venir. Réservé aux administrateurs. L'opération applique les mêmes garde-fous que l'assistant de numérotation de l'interface : elle refuse un numéro déjà porté par un document, un retour en arrière une fois des documents émis, et un compteur qui a bougé depuis sa lecture.\n\nUn compteur est rattaché à une **série** (module, société et préfixe résolu), et le préfixe dépend de la **date du document**, jamais de la date du jour. Le contenu de `numbering` décide du mode :\n\n- vide ou `{}`, ou `{\"date\": \"2026-09-07\"}` : **lecture** de la série de cette date (aujourd'hui par défaut) ;\n- `{\"prefix\": \"FC126\", \"next\": 161}` : **reprise** du compteur de la série au numéro `next` (le préfixe de la date du document si `prefix` est omis) ;\n- `{\"date\": \"2027-01-15\", \"first\": 1}` : **préparation** de la série d'une date qui n'en a pas encore, avec `first` comme premier numéro.\n\nClés admises : `date` (AAAA-MM-JJ, date réelle obligatoire), `prefix`, `next`, `first` et `organization` (identifiant de la société). `next` et `first` sont exclusifs. Sur une instance à plusieurs sociétés, `organization` est obligatoire pour un module numéroté par société. Seuls les modules numérotés par l'ERP sont acceptés : le refus liste ceux qui le sont.\n\nLa réponse donne toujours l'état complet (masque, série courante, séries existantes avec leurs compteurs et les documents correspondants), car l'appelant n'a pas d'écran.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "configure", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "moduleName": { "type": "string", "description": "Module de documents dont on lit ou règle la numérotation.", "example": "Invoice" }, "numbering": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "default": "[]", "description": "Texte JSON (objet). Objet JSON : `date`, `prefix`, `next`, `first`, `organization`. Vide pour lire.", "example": "{\"prefix\":\"FC126\",\"next\":161}" } }, "required": [ "moduleName" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "L'état de la numérotation après l'appel : `action` (`read`, `unchanged`, `modified` ou `created`), société, date du document, format (`format`), série courante (`current_series`) et liste des séries (`series`). Après une écriture, `series`, `previous_next`, `next` et `warnings` complètent la réponse.", "type": "object", "properties": { "module": { "type": "string" }, "action": { "type": "string" }, "organization": { "type": "integer" }, "document_date": { "type": "string" }, "format": { "type": "object", "properties": { "exists": { "type": "boolean" }, "prefix_pattern": { "type": "string" }, "suffix_pattern": { "type": "string" }, "padding": { "type": "integer" }, "reset_per_prefix": { "type": "boolean" }, "scope": { "type": "string" } } }, "current_series": { "type": "string" }, "series": { "type": "array", "items": { "type": "object", "properties": { "prefix": { "type": "string" }, "is_current": { "type": "boolean" }, "last_sequence": { "type": "integer" }, "next_number": { "type": "integer" }, "documents": { "type": "integer" }, "max_document": { "type": "string" }, "last_used": { "type": "string" }, "diagnostics": { "type": "array" } } } }, "previous_next": { "type": "integer" }, "next": { "type": "integer" }, "warnings": { "type": "array" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "module": "Invoice", "action": "modified", "organization": 1, "document_date": "2026-09-07", "format": { "exists": true, "prefix_pattern": "FC{yy}", "suffix_pattern": "", "padding": 5, "reset_per_prefix": true, "scope": "organization" }, "current_series": "FC126", "series": [ { "prefix": "FC126", "is_current": true, "last_sequence": 160, "next_number": 161, "documents": 157, "max_document": "FC12600157", "last_used": "2026-09-07 10:12:03", "diagnostics": [] } ], "previous_next": 158, "next": 161, "warnings": [] } } } } } } } }, "/webservice.php?operation=file_upload": { "post": { "operationId": "file_upload", "tags": [ "Fichiers et documents" ], "summary": "Déposer un fichier privé", "description": "Dépose un fichier privé destiné à être lu, analysé ou importé. Le fichier est rattaché à l'utilisateur authentifié et expire au bout de sept jours.\n\n- Le contenu est envoyé en base64 canonique.\n- La taille maximale est de 5 Mio par défaut ; un administrateur règle la limite et le quota par utilisateur dans les paramètres de l'instance.\n- Le nom de fichier comporte de 1 à 180 caractères, sans chemin ni caractère de contrôle.\n\nCette opération n'importe aucun enregistrement : elle fournit un `fileId` à passer aux opérations d'import, de création de document ou de pièce jointe.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "filename": { "type": "string", "description": "Nom du fichier avec son extension, sans répertoire.", "example": "clients.csv" }, "base64": { "type": "string", "description": "Contenu du fichier encodé en base64.", "example": "Y29kZTtub20KQzAwMTtFeGVtcGxlIFNBUkw=" } }, "required": [ "filename", "base64" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Les métadonnées du fichier déposé et son identifiant privé, valable jusqu'à la date d'expiration.", "type": "object", "properties": { "filename": { "type": "string" }, "mime": { "type": "string" }, "size": { "type": "integer" }, "sha256": { "type": "string" }, "fileId": { "type": "string" }, "expiresAt": { "type": "string" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "filename": "clients.csv", "mime": "text/csv", "size": 38, "sha256": "3f1c5a0e8b7d4c2a9e6f1b0d3a5c7e9f2b4d6a8c0e1f3a5b7c9d1e3f5a7b9c1d", "fileId": "9a8b7c6d5e4f30211203f4e5d6c7b8a99a8b7c6d5e4f30211203f4e5d6c7b8a9", "expiresAt": "2026-11-22T10:15:00+00:00" } } } } } } } }, "/webservice.php?operation=file_read": { "get": { "operationId": "file_read", "tags": [ "Fichiers et documents" ], "summary": "Lire un fichier privé", "description": "Lit un fichier privé déposé avec `file_upload` (ou produit par `document_pdf` avec `output=file`). Le fichier n'est lisible que par son propriétaire, avant son expiration.\n\nValeurs de `format` :\n\n- `metadata` (défaut) : nom, type, taille, empreinte et date d'expiration.\n- `content` : contenu complet en base64.\n- `text` : texte extrait, paginé par caractères avec `offset` et `length` (au plus 32 000) ; `nextOffset` vaut `null` à la fin.\n- `preview` : contenu en base64 d'un fichier PDF, PNG, JPEG, WEBP ou GIF.\n- `table` : lignes d'un fichier CSV ou XLSX sous forme de valeurs exactes, 100 lignes par page au plus ; `offset` et `length` comptent des lignes. Les formules, cellules en erreur et nombres mis en forme sont refusés : écrivez les dates, pourcentages et identifiants à zéros en texte explicite.\n\nUn fichier absent, expiré ou appartenant à un autre utilisateur répond `FILE_NOT_AVAILABLE`.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "fileId", "required": true, "schema": { "type": "string" }, "example": "9a8b7c6d5e4f30211203f4e5d6c7b8a99a8b7c6d5e4f30211203f4e5d6c7b8a9", "description": "Identifiant privé du fichier, renvoyé par `file_upload`." }, { "in": "query", "name": "format", "required": false, "schema": { "type": "string", "enum": [ "metadata", "content", "text", "preview", "table" ], "default": "metadata" }, "description": "Forme de la lecture : `metadata`, `content`, `text`, `preview` ou `table`." }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Position de départ : caractères pour `text`, lignes pour `table`." }, { "in": "query", "name": "length", "required": false, "schema": { "type": "integer", "default": 12000 }, "description": "Nombre de caractères (`text`, 1 à 32 000) ou de lignes (`table`, 100 au plus) à renvoyer." }, { "in": "query", "name": "delimiter", "required": false, "schema": { "type": "string", "enum": [ ";", ",", "\t" ], "default": ";" }, "description": "Séparateur d'un fichier CSV lu en `table` : point-virgule, virgule ou tabulation." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Les métadonnées du fichier, complétées selon `format` : `base64` (`content`, `preview`), `text`, `totalCharacters` et `nextOffset` (`text`), ou `columns`, `rows`, `totalRows` et `nextOffset` (`table`).", "type": "object", "properties": { "fileId": { "type": "string" }, "filename": { "type": "string" }, "mime": { "type": "string" }, "size": { "type": "integer" }, "sha256": { "type": "string" }, "expiresAt": { "type": "string" }, "text": { "type": "string" }, "totalCharacters": { "type": "integer" }, "nextOffset": { "type": "null" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "fileId": "9a8b7c6d5e4f30211203f4e5d6c7b8a99a8b7c6d5e4f30211203f4e5d6c7b8a9", "filename": "clients.csv", "mime": "text/csv", "size": 38, "sha256": "3f1c5a0e8b7d4c2a9e6f1b0d3a5c7e9f2b4d6a8c0e1f3a5b7c9d1e3f5a7b9c1d", "expiresAt": "2026-11-22T10:15:00+00:00", "text": "code;nom\nC001;Exemple SARL", "totalCharacters": 25, "nextOffset": null } } } } } } } }, "/webservice.php?operation=file_delete": { "post": { "operationId": "file_delete", "tags": [ "Fichiers et documents" ], "summary": "Supprimer un fichier privé", "description": "Supprime un fichier privé appartenant à l'utilisateur authentifié. Les pièces jointes des enregistrements ne sont pas concernées.\n\nUn fichier retenu par un import en cours de préparation ne peut pas être supprimé : abandonnez d'abord cet import.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "fileId": { "type": "string", "description": "Identifiant privé du fichier à supprimer.", "example": "9a8b7c6d5e4f30211203f4e5d6c7b8a99a8b7c6d5e4f30211203f4e5d6c7b8a9" } }, "required": [ "fileId" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "L'identifiant du fichier et la confirmation de suppression.", "type": "object", "properties": { "fileId": { "type": "string" }, "deleted": { "type": "boolean" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "fileId": "9a8b7c6d5e4f30211203f4e5d6c7b8a99a8b7c6d5e4f30211203f4e5d6c7b8a9", "deleted": true } } } } } } } }, "/webservice.php?operation=FileUpload": { "post": { "operationId": "FileUpload", "tags": [ "Fichiers et documents" ], "summary": "Joindre un fichier à un enregistrement", "description": "Ajoute une pièce jointe à un enregistrement modifiable, par exemple un logo ou un document commercial.\n\n- L'utilisateur doit avoir le droit de modifier l'enregistrement parent.\n- Le contenu vient soit d'un fichier privé déjà déposé (`fileId`), soit de `fileName` et `fileContents` en base64 ; les deux ensemble sont refusés.\n- L'extension doit figurer dans la liste autorisée et le contenu réel est contrôlé ; avec `attachmentType` valant `Image`, les contrôles d'image sont toujours appliqués.\n\nUn refus de contenu ne produit pas d'erreur d'enveloppe : le résultat porte `success` à `false` et un message `error`.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "parentId": { "type": "string", "description": "Identifiant de l'enregistrement auquel joindre le fichier.", "example": "11x42" }, "attachmentType": { "type": "string", "description": "Nature de la pièce jointe : `Attachment` (défaut du service) ou `Image` pour imposer les contrôles d'image.", "example": "Attachment" }, "fileName": { "type": "string", "default": "", "description": "Nom du fichier avec son extension, sans répertoire. Avec `fileId`, reprend par défaut le nom du fichier privé.", "example": "contrat.pdf" }, "fileContents": { "type": "string", "default": "", "description": "Contenu du fichier encodé en base64, uniquement si `fileId` n'est pas fourni." }, "fileId": { "type": "string", "default": "", "description": "Identifiant privé d'un fichier déposé avec `file_upload`, pour éviter d'envoyer le contenu en base64.", "example": "9a8b7c6d5e4f30211203f4e5d6c7b8a99a8b7c6d5e4f30211203f4e5d6c7b8a9" } }, "required": [ "parentId", "attachmentType" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "`success` et l'identifiant de la pièce jointe créée, ou `success` à `false` avec le motif du refus dans `error`.", "type": "object", "properties": { "success": { "type": "boolean" }, "attachmentId": { "type": "integer" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "success": true, "attachmentId": 1234 } } } } } } } }, "/webservice.php?operation=files_retrieve": { "get": { "operationId": "files_retrieve", "tags": [ "Fichiers et documents" ], "summary": "Télécharger une pièce jointe", "description": "Lit une pièce jointe à partir de son identifiant, avec les droits de l'enregistrement parent : l'utilisateur doit pouvoir consulter cet enregistrement.\n\nL'identifiant est composé du préfixe du module parent et de l'identifiant numérique de la pièce jointe (`x`). Le contenu est renvoyé en base64.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "id", "required": true, "schema": { "type": "string" }, "example": "15x1234", "description": "Identifiant de la pièce jointe : préfixe du module parent, `x`, identifiant de la pièce jointe." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La liste des fichiers de la pièce jointe, avec nom, type, taille en octets et contenu en base64.", "type": "array", "items": { "type": "object", "properties": { "fileid": { "type": "string" }, "filename": { "type": "string" }, "filetype": { "type": "string" }, "filesize": { "type": "integer" }, "filecontents": { "type": "string" } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": [ { "fileid": "1234", "filename": "contrat.pdf", "filetype": "application/pdf", "filesize": 18432, "filecontents": "JVBERi0xLjQK..." } ] } } } } } } }, "/webservice.php?operation=document_create_with_file": { "post": { "operationId": "document_create_with_file", "tags": [ "Fichiers et documents" ], "summary": "Créer un document avec son fichier", "description": "Crée en une seule étape un enregistrement `Documents` qui porte un fichier. L'extension et le contenu réel sont contrôlés avant toute création : un fichier refusé ne laisse jamais de document vide, et tout échec ultérieur annule l'ensemble.\n\n- Formats acceptés : jpg, jpeg, png, gif, heic, webp, avif, svg, csv, xls, xlsx, ods, doc, docx, txt, odp, zip, pdf (rptdesign pour les administrateurs). Les fichiers ods et odp doivent être de véritables fichiers OpenDocument ; un fichier txt est toujours servi en texte brut.\n- Taille maximale : celle de `file_upload` (5 Mio par défaut).\n- Le contenu vient d'un fichier privé (`fileId`) ou de `fileContents` en base64, jamais des deux.\n- L'utilisateur doit avoir le droit de créer des documents, et de modifier l'enregistrement lié s'il y en a un.\n\nUn fichier refusé répond `FILE_REFUSED` avec la liste des formats acceptés.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": false, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "fileId": { "type": "string", "default": "", "description": "Identifiant privé d'un fichier déposé avec `file_upload` (recommandé).", "example": "9a8b7c6d5e4f30211203f4e5d6c7b8a99a8b7c6d5e4f30211203f4e5d6c7b8a9" }, "fileName": { "type": "string", "default": "", "description": "Nom du fichier avec son extension ; par défaut, le nom du fichier privé.", "example": "contrat.pdf" }, "fileContents": { "type": "string", "default": "", "description": "Contenu en base64, uniquement si `fileId` n'est pas fourni." }, "title": { "type": "string", "default": "", "description": "Titre du document ; par défaut, le nom du fichier sans extension.", "example": "Contrat de maintenance" }, "folderId": { "type": "string", "default": "", "description": "Identifiant du dossier de documents (`22x1` ou `1`) ; par défaut, le premier dossier.", "example": "22x1" }, "description": { "type": "string", "default": "", "description": "Description du document." }, "relatedRecordId": { "type": "string", "default": "", "description": "Enregistrement auquel lier le document (droit de modification requis), par exemple un ticket ou une facture.", "example": "11x42" } } } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le document créé et les caractéristiques de son fichier.", "type": "object", "properties": { "id": { "type": "string" }, "attachmentId": { "type": "integer" }, "filename": { "type": "string" }, "filetype": { "type": "string" }, "filesize": { "type": "integer" }, "folderId": { "type": "string" }, "relatedRecordId": { "type": "string" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "id": "15x987", "attachmentId": 1234, "filename": "contrat.pdf", "filetype": "application/pdf", "filesize": 18432, "folderId": "1", "relatedRecordId": "11x42" } } } } } } } }, "/webservice.php?operation=attachment_copy": { "post": { "operationId": "attachment_copy", "tags": [ "Fichiers et documents" ], "summary": "Copier des pièces jointes en documents", "description": "Copie des pièces jointes existantes (fichiers d'un ticket et de ses commentaires, par exemple) vers des enregistrements `Documents` liés à un enregistrement cible, côté serveur : aucun octet ne transite par l'appelant.\n\n- Indiquez soit `attachmentIds` (50 au plus), soit `sourceRecordId` pour copier les pièces jointes d'un enregistrement et de ses commentaires, 50 par appel ; suivez `nextOffset` jusqu'à `null`. Les deux ensemble sont refusés.\n- Droits requis : lecture sur l'enregistrement de chaque pièce jointe (un commentaire se lit par son parent), modification de la cible et création de documents.\n- Mêmes contrôles de format et de taille qu'un dépôt de fichier.\n- L'opération est idempotente : une pièce jointe dont le nom et le contenu sont déjà portés par un document actif lié à la cible est ignorée.\n- Chaque pièce jointe reçoit un statut `created`, `skipped` ou `error` (codes `FILE_REFUSED`, `FILE_TOO_LARGE`, `FILE_MISSING`, `ACCESS_DENIED`) ; une erreur n'interrompt pas les autres.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "targetRecordId": { "type": "string", "description": "Enregistrement auquel les nouveaux documents sont liés (droit de modification requis).", "example": "11x42" }, "attachmentIds": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array", "items": { "type": "string" } }, "default": "[]", "description": "Texte JSON (liste). Pièces jointes à copier, sous la forme renvoyée par `files_retrieve` (`x`) ou identifiants de pièces jointes ; 50 au plus.", "example": "[\"15x1234\",\"15x1235\"]" }, "sourceRecordId": { "type": "string", "default": "", "description": "À la place de `attachmentIds` : enregistrement dont on copie les pièces jointes et celles de ses commentaires.", "example": "17x310" }, "offset": { "type": "integer", "default": 0, "description": "Avec `sourceRecordId` : position de la première pièce jointe ; suivre `nextOffset` jusqu'à `null`." }, "folderId": { "type": "string", "default": "", "description": "Dossier de documents des nouveaux documents ; par défaut, le premier dossier.", "example": "22x1" } }, "required": [ "targetRecordId" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le résultat par pièce jointe, les compteurs et, avec `sourceRecordId`, `total` et `nextOffset`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=document_pdf": { "get": { "operationId": "document_pdf", "tags": [ "Fichiers et documents" ], "summary": "Générer le PDF d'un document", "description": "Génère le PDF d'un enregistrement avec le moteur d'impression de Kafinea, pour tout module qui possède au moins un modèle d'impression (`Invoice`, `Quotes`, `SalesOrder`, `PurchaseOrder`...).\n\n- `id` et `templateId` sont des identifiants de service web (`11x42`) ; un identifiant brut est refusé.\n- Sans `templateId`, le modèle par défaut du module est utilisé ; un modèle qui n'appartient pas au module répond `INVALID_TEMPLATE`.\n- Un module sans modèle d'impression répond `PDF_NOT_SUPPORTED`.\n- Facture ou avoir verrouillé sur une instance configurée pour Factur-X : le PDF produit est un PDF/A-3 qui embarque le fichier XML, sans paramètre particulier.\n\nTrois modes de sortie :\n\n- `output=inline` (défaut) : le PDF est renvoyé en base64 dans le résultat.\n- `output=file` : le PDF est déposé comme fichier privé et le résultat porte son `fileId` (lisible avec `file_read`).\n- `download=1` : les octets du PDF sont renvoyés directement, sans enveloppe JSON, pour un enregistrement par `curl -o`. Incompatible avec `output=file`.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "id", "required": false, "schema": { "type": "string", "default": "" }, "example": "6x54325", "description": "Identifiant de l'enregistrement à imprimer (droit de lecture requis)." }, { "in": "query", "name": "templateId", "required": false, "schema": { "type": "string", "default": "" }, "example": "47x12", "description": "Identifiant du modèle d'impression à utiliser ; par défaut, le modèle par défaut du module." }, { "in": "query", "name": "output", "required": false, "schema": { "type": "string", "enum": [ "inline", "file" ], "default": "inline" }, "description": "`inline` renvoie le PDF en base64 ; `file` le dépose comme fichier privé et renvoie son `fileId`." }, { "in": "query", "name": "download", "required": false, "schema": { "type": "string", "default": "0", "enum": [ "0", "1" ] }, "example": "0", "description": "`1` renvoie directement les octets du PDF au lieu de l'enveloppe JSON ; `0` (défaut) renvoie l'enveloppe JSON." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Les caractéristiques du PDF avec son contenu en base64 (`output=inline`), ou avec `fileId` et `expiresAt` (`output=file`).", "type": "object", "properties": { "id": { "type": "string" }, "module": { "type": "string" }, "templateId": { "type": "string" }, "filename": { "type": "string" }, "mime": { "type": "string" }, "size": { "type": "integer" }, "base64": { "type": "string" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "id": "6x54325", "module": "Invoice", "templateId": "47x12", "filename": "FA-2026-0042.pdf", "mime": "application/pdf", "size": 48213, "base64": "JVBERi0xLjcK..." } } } } } } } }, "/webservice.php?operation=mds_document_pdf": { "get": { "operationId": "mds_document_pdf", "tags": [ "Fichiers et documents" ], "summary": "Générer le PDF d'un document (ancien nom)", "description": "Ancien nom de `document_pdf`, conservé pour les intégrations existantes. Même comportement, mode `inline` ou `download=1` uniquement. Utilisez `document_pdf` pour les nouveaux développements.\n\n> Obsolète : utilisez `document_pdf`.", "x-badges": [ { "name": "Obsolète", "color": "var(--scalar-color-red)" } ], "deprecated": true, "x-kafinea-access": "user", "parameters": [ { "in": "query", "name": "id", "required": true, "schema": { "type": "string" }, "example": "6x54325", "description": "Identifiant de l'enregistrement à imprimer." }, { "in": "query", "name": "templateId", "required": false, "schema": { "type": "string" }, "example": "47x12", "description": "Identifiant du modèle d'impression ; par défaut, celui du module." }, { "in": "query", "name": "download", "required": false, "schema": { "type": "string", "default": "0", "enum": [ "0", "1" ] }, "description": "`1` renvoie directement les octets du PDF ; `0` renvoie l'enveloppe JSON." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Identique à `document_pdf` en mode `inline`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=template_preview": { "post": { "operationId": "template_preview", "tags": [ "Fichiers et documents" ], "summary": "Prévisualiser un modèle d'impression non enregistré", "description": "Rend un enregistrement avec du code HTML de modèle d'impression qui n'est **pas** enregistré, pour essayer une mise en page avant de la sauvegarder.\n\n- Le HTML est nettoyé exactement comme lors d'un enregistrement, puis rendu avec le moteur d'impression partagé.\n- Fournissez au moins une des parties `header`, `body` ou `footer` ; une partie vide conserve celle du modèle.\n- Les réglages (marges, thème, langue) et les autres parties viennent du modèle `templateId`, ou du modèle par défaut du module.\n- Le droit de modifier les modèles d'impression est requis, ainsi que le droit de lecture sur l'enregistrement.\n- Rien n'est écrit, hormis le fichier privé de la prévisualisation.\n\nLe résultat donne l'identifiant du fichier privé (à lire avec `file_read`) et la liste `warnings` de ce que le nettoyage a retiré (éléments, attributs, propriétés CSS, commentaires, instructions `{*...*}`).", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Enregistrement à rendre.", "example": "6x54325" }, "templateId": { "type": "string", "default": "", "description": "Modèle d'impression du module de l'enregistrement dont on reprend les réglages et les autres parties ; par défaut, le modèle par défaut du module.", "example": "47x12" }, "header": { "type": "string", "default": "", "description": "HTML d'en-tête à essayer ; vide, il conserve celui du modèle.", "example": "
Exemple SARL
" }, "body": { "type": "string", "default": "", "description": "HTML du corps à essayer ; vide, il conserve celui du modèle." }, "footer": { "type": "string", "default": "", "description": "HTML de pied de page à essayer ; vide, il conserve celui du modèle." } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Les caractéristiques du PDF de prévisualisation, son `fileId` privé et les avertissements du nettoyage.", "type": "object", "properties": { "id": { "type": "string" }, "module": { "type": "string" }, "templateId": { "type": "string" }, "saved": { "type": "boolean" }, "filename": { "type": "string" }, "mime": { "type": "string" }, "size": { "type": "integer" }, "warnings": { "type": "array" }, "fileId": { "type": "string" }, "expiresAt": { "type": "string" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "id": "6x54325", "module": "Invoice", "templateId": "47x12", "saved": false, "filename": "FA-2026-0042.pdf", "mime": "application/pdf", "size": 47102, "warnings": [], "fileId": "5c4d3e2f1a0b99887766554433221100ffeeddccbbaa99887766554433221100", "expiresAt": "2026-11-22T10:15:00+00:00" } } } } } } } }, "/webservice.php?operation=document_capabilities": { "get": { "operationId": "document_capabilities", "tags": [ "Fichiers et documents" ], "summary": "Décrire le rendu et les balises d'un module", "description": "Décrit comment les documents d'un module sont rendus : champs d'un modèle d'impression, règles de sélection du modèle par défaut, syntaxe des conditions, réglages de mise en page et opérations utiles. Avec `section=tags`, renvoie la liste paginée des balises de fusion disponibles pour l'utilisateur courant.\n\nLes balises doivent être utilisées exactement comme renvoyées ; leurs valeurs dépendent de l'utilisateur qui génère le document et de ses droits. Suivez `nextOffset` jusqu'à `null` ; `query` filtre sur le libellé et la balise.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "elementType", "required": true, "schema": { "type": "string" }, "example": "Invoice", "description": "Module du document décrit." }, { "in": "query", "name": "section", "required": false, "schema": { "type": "string", "default": "summary", "enum": [ "summary", "tags" ] }, "description": "`summary` (défaut) pour la description du rendu, `tags` pour les balises de fusion." }, { "in": "query", "name": "query", "required": false, "schema": { "type": "string", "default": "" }, "description": "Avec `section=tags` : texte recherché dans le libellé ou la balise." }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "default": 100 }, "description": "Avec `section=tags` : nombre de balises par page, de 1 à 200." }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Avec `section=tags` : position de la première balise." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Avec `section=tags` : `tags` (groupe, libellé, balise), `total` et `nextOffset`. Avec `summary` : la description du rendu du module." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=invoice_facturx": { "get": { "operationId": "invoice_facturx", "tags": [ "Fichiers et documents" ], "summary": "Obtenir la facture Factur-X", "description": "Renvoie, pour une facture (`Invoice`), le fichier Factur-X en base64.\n\n- `format=xml` (défaut) : le XML Factur-X de la facture. La facture doit être verrouillée définitivement, sinon `INVOICE_NOT_LOCKED`.\n- `format=pdf` : le PDF/A-3 de la facture avec le XML embarqué.\n\nL'enregistrement doit être une facture ; sinon `INVALID_PARAM`. Le droit de lecture sur la facture est requis. Pour le PDF ordinaire d'un document, préférez `document_pdf`.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "id", "required": false, "schema": { "type": "string", "default": "" }, "example": "6x54325", "description": "Identifiant de la facture." }, { "in": "query", "name": "format", "required": false, "schema": { "type": "string", "default": "xml" }, "description": "`xml` (défaut) ou `pdf`." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le format, le nom de fichier, le type, la taille et le contenu en base64.", "type": "object", "properties": { "format": { "type": "string" }, "filename": { "type": "string" }, "mime": { "type": "string" }, "size": { "type": "integer" }, "base64": { "type": "string" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "format": "xml", "filename": "FA-2026-0042.xml", "mime": "application/xml", "size": 9120, "base64": "PD94bWwgdmVyc2lvbj0iMS4wIj8+..." } } } } } } } }, "/webservice.php?operation=mds_invoice_facturx": { "get": { "operationId": "mds_invoice_facturx", "tags": [ "Fichiers et documents" ], "summary": "Obtenir la facture Factur-X (ancien nom)", "description": "Ancien nom de `invoice_facturx`, conservé pour les intégrations existantes. Même comportement. Utilisez `invoice_facturx` pour les nouveaux développements.\n\n> Obsolète : utilisez `invoice_facturx`.", "x-badges": [ { "name": "Obsolète", "color": "var(--scalar-color-red)" } ], "deprecated": true, "x-kafinea-access": "user", "parameters": [ { "in": "query", "name": "id", "required": true, "schema": { "type": "string" }, "example": "6x54325", "description": "Identifiant de la facture." }, { "in": "query", "name": "format", "required": false, "schema": { "type": "string", "default": "xml", "enum": [ "xml", "pdf" ] }, "description": "`xml` (défaut) ou `pdf`." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Identique à `invoice_facturx`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=email_template_read": { "get": { "operationId": "email_template_read", "tags": [ "Fichiers et documents" ], "summary": "Lister ou lire les modèles d'e-mail", "description": "Sans `id`, liste les modèles d'e-mail (identifiant, nom, sujet, description, module, indicateur de modèle système), avec pagination. Avec `id`, renvoie ce modèle avec son corps HTML.\n\nLe droit de consulter les modèles d'e-mail est requis. `limit` va de 1 à 100 ; suivez `nextOffset` jusqu'à `null`.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "id", "required": false, "schema": { "type": "string", "default": "" }, "example": "12", "description": "Identifiant numérique du modèle : renvoie ce modèle avec son corps. Omis, liste les modèles." }, { "in": "query", "name": "moduleName", "required": false, "schema": { "type": "string", "default": "" }, "example": "Invoice", "description": "Ne liste que les modèles de ce module." }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Position du premier modèle de la liste." }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "default": 50 }, "description": "Nombre de modèles par page, de 1 à 100." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Sans `id` : `templates`, `total` et `nextOffset`. Avec `id` : le modèle et son corps HTML.", "type": "object", "properties": { "templates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "subject": { "type": "string" }, "description": { "type": "string" }, "module": { "type": "string" }, "systemTemplate": { "type": "boolean" } } } }, "total": { "type": "integer" }, "nextOffset": { "type": "null" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "templates": [ { "id": 12, "name": "Relance facture", "subject": "Facture en attente de règlement", "description": "Première relance", "module": "Invoice", "systemTemplate": false } ], "total": 1, "nextOffset": null } } } } } } } }, "/webservice.php?operation=email_template_upsert": { "post": { "operationId": "email_template_upsert", "tags": [ "Fichiers et documents" ], "summary": "Créer ou modifier un modèle d'e-mail", "description": "Crée ou modifie un modèle d'e-mail avec les règles de l'éditeur de modèles.\n\n- Création : `name`, `subject`, `module` et `body` sont obligatoires.\n- Modification : seules les clés fournies changent. Le modèle visé est celui d'`id`, ou à défaut celui qui porte le même nom ; un nom partagé par plusieurs modèles est refusé (indiquez l'`id`).\n- Le sujet d'un modèle système ne peut pas être modifié.\n- Le module doit pouvoir porter des modèles d'e-mail (module avec un champ e-mail, comme dans l'éditeur). Les scripts du corps HTML sont retirés.\n\nLe droit de modifier les modèles d'e-mail est requis.", "x-kafinea-access": "user", "x-kafinea-scope": "configure", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "template": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "subject": { "type": "string" }, "module": { "type": "string" }, "body": { "type": "string" }, "description": { "type": "string" } }, "additionalProperties": false }, "description": "Texte JSON (objet). Définition du modèle : `id` (pour modifier), `name`, `subject`, `module`, `body` (HTML) et `description`.", "example": "{\"name\":\"Relance facture\",\"subject\":\"Facture en attente de règlement\",\"module\":\"Invoice\",\"body\":\"

Bonjour,

Nous n'avons pas reçu le règlement de votre facture.

\",\"description\":\"Première relance\"}" } }, "required": [ "template" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le modèle enregistré et l'action effectuée, `created` ou `modified`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=import_prepare": { "post": { "operationId": "import_prepare", "tags": [ "Imports" ], "summary": "Préparer un import de référentiel", "description": "Prépare un import durable de référentiel à partir d'un fichier CSV ou XLSX déposé avec `file_upload`. Réservé aux administrateurs.\n\nModules acceptés : `Accounts`, `Contacts`, `Vendors`, `Products`, `Services` et `PriceBooks`.\n\n- `mapping` associe chaque champ cible à une colonne source (`champ: colonne`) ; `keyFields` (1 à 5 champs) sont les clés métier exactes qui identifient un enregistrement ; `defaults` donne des valeurs scalaires par défaut.\n- `mode` : `create` refuse une clé qui existe déjà, `update` refuse une clé absente et ne crée jamais, `upsert` (défaut) accepte les deux.\n- Un champ de référence peut contenir un identifiant d'enregistrement ou un nom : le nom est rapproché, à la préparation, de l'unique enregistrement actif de ce nom (affiné par `references`). Un nom sans correspondance ou ambigu rend la ligne invalide, avec la liste des candidats.\n- Un CSV dans un encodage autre que UTF-8 demande `encoding`.\n\nLa préparation valide les lignes en arrière-plan sans enregistrer d'enregistrement. L'aperçu vérifie la correspondance des colonnes, les champs obligatoires, les clés et les métadonnées ; il ne rejoue ni les actions d'enregistrement ni les flux automatisés. Les points de reprise du fichier source et des lignes sont conservés 30 jours, 20 imports conservés au plus par utilisateur. Consultez le résultat avec `import_inspect`, puis lancez avec `import_control`.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "fileId": { "type": "string", "description": "Identifiant privé du fichier CSV ou XLSX déposé avec `file_upload`.", "example": "9a8b7c6d5e4f30211203f4e5d6c7b8a99a8b7c6d5e4f30211203f4e5d6c7b8a9" }, "elementType": { "type": "string", "description": "Module cible de l'import : `Accounts`, `Contacts`, `Vendors`, `Products`, `Services` ou `PriceBooks`.", "example": "Accounts" }, "mapping": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "description": "Texte JSON (objet). Correspondance `champ cible: colonne source`.", "example": "{\"accountname\":\"Raison sociale\",\"email1\":\"E-mail\"}" }, "keyFields": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array", "items": { "type": "string" } }, "description": "Texte JSON (liste). Champs servant de clé métier pour retrouver un enregistrement existant (1 à 5).", "example": "[\"accountname\"]" }, "defaults": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "default": "[]", "description": "Texte JSON (objet). Valeurs scalaires appliquées par défaut aux champs cibles.", "example": "{\"industry\":\"Services\"}" }, "delimiter": { "type": "string", "enum": [ ";", ",", "\t" ], "default": ";", "description": "Séparateur d'un fichier CSV : point-virgule, virgule ou tabulation." }, "mode": { "type": "string", "enum": [ "create", "update", "upsert" ], "default": "upsert", "description": "`create`, `update` ou `upsert` (défaut)." }, "references": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object", "additionalProperties": { "type": "object", "properties": { "module": { "type": "string" }, "filter": { "type": "object", "additionalProperties": { "type": "object", "properties": { "column": { "type": "string" }, "value": { "type": "string" } } } } } } }, "default": "[]", "description": "Texte JSON (objet). Par champ de référence, la manière de rapprocher un nom du fichier : `module` (si le champ en accepte plusieurs) et `filter` (champs de l'enregistrement référencé qui distinguent les homonymes, chacun avec `column` ou `value`). Toute valeur qui n'est pas un identifiant (`12x34`) est rapprochée par le nom de l'enregistrement, avec ou sans ce paramètre.", "example": "{\"uom\":{\"filter\":{\"uomcategoryid\":{\"column\":\"Catégorie\"}}}}" }, "encoding": { "type": "string", "enum": [ "UTF-8", "ISO-8859-15", "Windows-1252" ], "default": "UTF-8", "description": "Encodage d'un fichier CSV, converti en UTF-8 avant lecture. Un fichier XLSX est toujours en UTF-8." } }, "required": [ "fileId", "elementType", "mapping", "keyFields" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "L'identifiant de l'import, sa révision, son état et le nombre de lignes. La révision est à fournir à `import_control`.", "type": "object", "properties": { "jobId": { "type": "string" }, "revision": { "type": "string" }, "state": { "type": "string" }, "totalRows": { "type": "integer" }, "expiresAt": { "type": "string" }, "resolvedReferenceRows": { "type": "integer" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "jobId": "7d3a1f9c5b2e4a6081c3e5d7f9b1a3c57d3a1f9c5b2e4a6081c3e5d7f9b1a3c5", "revision": "b1f4e6a8c0d2f4a6b8c0d2e4f6a8b0c2d4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4", "state": "validating", "totalRows": 120, "expiresAt": "2026-12-15T10:15:00+00:00", "resolvedReferenceRows": 0 } } } } } } } }, "/webservice.php?operation=import_inspect": { "get": { "operationId": "import_inspect", "tags": [ "Imports" ], "summary": "Consulter un import de référentiel", "description": "Sans `jobId`, liste vos imports conservés (identifiant, fichier, module, état, nombre de lignes, dates). Avec `jobId`, renvoie un import qui vous appartient : définition, correspondance, compteurs par état, aperçu et résultat de chaque ligne, paginés (100 lignes au plus par appel, `nextOffset` jusqu'à `null`).\n\nLes états `invalid`, `completed_with_errors` et `executing` demandent une revue : ils ne signifient jamais qu'un import complet a réussi. Réservé aux administrateurs.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "jobId", "required": false, "schema": { "type": "string", "default": "" }, "example": "7d3a1f9c5b2e4a6081c3e5d7f9b1a3c57d3a1f9c5b2e4a6081c3e5d7f9b1a3c5", "description": "Identifiant de l'import. Omis, liste vos imports conservés." }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Position de la première ligne renvoyée." }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "default": 20 }, "description": "Nombre de lignes par page, de 1 à 100." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Sans `jobId` : `jobs`, `total` et `nextOffset`. Avec `jobId` : `revision`, `state`, `definition`, `counts`, `totalRows`, `rows` (valeurs, plan et résultat par ligne) et `nextOffset`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=import_control": { "post": { "operationId": "import_control", "tags": [ "Imports" ], "summary": "Piloter un import de référentiel", "description": "Agit sur un import durable qui vous appartient, avec la révision que vous avez relue. Réservé aux administrateurs.\n\n- `start` : démarre l'import ; il doit être préparé et sans ligne invalide.\n- `pause` : arrête avant la ligne suivante.\n- `resume` : reprend sans rejouer les lignes terminées ou incertaines.\n- `discard` : supprime les points de reprise conservés, uniquement après une pause ou la fin de l'import ; les enregistrements déjà écrits ne sont pas annulés.\n\nL'import s'exécute avec les droits de l'administrateur qui l'a lancé, revérifiés par le traitement en arrière-plan. Une révision périmée est refusée : relisez l'import avec `import_inspect`.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "jobId": { "type": "string", "description": "Identifiant de l'import.", "example": "7d3a1f9c5b2e4a6081c3e5d7f9b1a3c57d3a1f9c5b2e4a6081c3e5d7f9b1a3c5" }, "action": { "type": "string", "enum": [ "start", "pause", "resume", "discard" ], "description": "`start`, `pause`, `resume` ou `discard`." }, "revision": { "type": "string", "description": "Révision de l'import relue juste avant l'action.", "example": "b1f4e6a8c0d2f4a6b8c0d2e4f6a8b0c2d4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4" } }, "required": [ "jobId", "action", "revision" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "L'import dans son nouvel état (même forme qu'`import_inspect`, une ligne), ou, avec `discard`, la confirmation de suppression des points de reprise.", "type": "object", "properties": { "jobId": { "type": "string" }, "discarded": { "type": "boolean" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "jobId": "7d3a1f9c5b2e4a6081c3e5d7f9b1a3c57d3a1f9c5b2e4a6081c3e5d7f9b1a3c5", "discarded": true } } } } } } } }, "/webservice.php?operation=import_map_list": { "get": { "operationId": "import_map_list", "tags": [ "Imports" ], "summary": "Lister les correspondances d'import enregistrées", "description": "Liste les correspondances de colonnes enregistrées par l'écran d'import (identifiant, nom, module, propriétaire, présence d'un en-tête, date, correspondance colonne source vers champ). Un utilisateur voit ses propres correspondances, un administrateur toutes ; 500 au plus.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "moduleName", "required": false, "schema": { "type": "string", "default": "" }, "example": "Accounts", "description": "Ne liste que les correspondances de ce module." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La liste `maps`.", "type": "object", "properties": { "maps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "module": { "type": "string" }, "ownerId": { "type": "integer" }, "hasHeader": { "type": "boolean" }, "savedAt": { "type": "string" }, "mapping": { "type": "object", "properties": { "Raison sociale": { "type": "string" }, "E-mail": { "type": "string" } } } } } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "maps": [ { "id": 3, "name": "Import clients", "module": "Accounts", "ownerId": 5, "hasHeader": true, "savedAt": "2026-10-02 09:30:00", "mapping": { "Raison sociale": "accountname", "E-mail": "email1" } } ] } } } } } } } }, "/webservice.php?operation=import_map_delete": { "post": { "operationId": "import_map_delete", "tags": [ "Imports" ], "summary": "Supprimer une correspondance d'import", "description": "Supprime une correspondance d'import enregistrée, comme le fait l'écran d'import. Un utilisateur supprime ses propres correspondances, un administrateur n'importe laquelle. Les enregistrements déjà importés avec cette correspondance ne sont pas modifiés.\n\nUne correspondance inexistante ou appartenant à un autre utilisateur reçoit la même réponse d'erreur.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifiant de la correspondance, tel que renvoyé par `import_map_list`.", "example": "3" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La correspondance supprimée.", "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "module": { "type": "string" }, "deleted": { "type": "boolean" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "id": 3, "name": "Import clients", "module": "Accounts", "deleted": true } } } } } } } }, "/webservice.php?operation=bank_statement_analyze": { "get": { "operationId": "bank_statement_analyze", "tags": [ "Imports" ], "summary": "Analyser un relevé bancaire OFX", "description": "Lit un relevé bancaire ou de carte au format OFX (OFX 1 SGML ou OFX 2 XML, fichiers `.ofx` ou `.qfx`, plusieurs comptes par fichier) déposé avec `file_upload`, et indique ce que `bank_statement_import` ferait dans la société courante, **sans rien écrire**.\n\nPour chaque relevé : le compte bancaire Kafinea reconnu à partir de l'IBAN ou du numéro de compte (`bankAccount.match` vaut `iban`, `account_number` ou `chosen`, `bankAccounts` liste les choix possibles), l'état (`ready`, `needs_account`, `blocked`, `skipped`), la période, les soldes de clôture et d'ouverture déduit, les compteurs et totaux par statut, les anomalies avec des codes `OFX_` stables, et une page de transactions.\n\nStatuts des transactions :\n\n- `new` : sera importée.\n- `duplicate` : même identifiant bancaire (FITID) déjà présent dans ce compte, jamais importée.\n- `probable_duplicate` : même jour et même montant qu'une transaction du compte sans identifiant bancaire (par exemple issue de la synchronisation bancaire), importée seulement avec `includeProbableDuplicates`.\n- `repeat` et `invalid` : jamais importées.\n\nLes montants sont des entiers en centimes, négatifs pour un débit. Le droit de création sur les transactions bancaires est requis.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "fileId", "required": true, "schema": { "type": "string" }, "example": "9a8b7c6d5e4f30211203f4e5d6c7b8a99a8b7c6d5e4f30211203f4e5d6c7b8a9", "description": "Identifiant privé du relevé OFX déposé avec `file_upload`." }, { "in": "query", "name": "accounts", "required": false, "schema": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "default": "[]" }, "example": "[\"61x123\",\"skip\"]", "description": "Texte JSON (objet). Index du relevé dans le fichier vers identifiant du compte bancaire Kafinea (ou identifiant de service web), ou `skip` pour l'ignorer. Un relevé omis prend le compte reconnu à partir de son IBAN ou de son numéro." }, { "in": "query", "name": "includeProbableDuplicates", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Importe aussi les doublons probables." }, { "in": "query", "name": "status", "required": false, "schema": { "type": "string", "enum": [ "", "new", "duplicate", "probable_duplicate", "repeat", "invalid" ], "default": "" }, "description": "Ne renvoie que les transactions de ce statut : `new`, `duplicate`, `probable_duplicate`, `repeat` ou `invalid`. Vide, toutes." }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Position de la première transaction renvoyée." }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "default": 50 }, "description": "Nombre de transactions par page." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "L'analyse par relevé : compte reconnu, état, période, soldes, compteurs, anomalies et page de transactions." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=bank_statement_import": { "post": { "operationId": "bank_statement_import", "tags": [ "Imports" ], "summary": "Importer un relevé bancaire OFX", "description": "Crée les nouvelles transactions bancaires d'un relevé OFX analysé avec `bank_statement_analyze`, avec le même choix de comptes.\n\n- Chaque relevé doit être `ready` ou `skipped`, sinon `OFX_DECISION_REQUIRED`.\n- Chaque relevé est revérifié sous verrou sur son compte bancaire et créé dans une seule transaction de base de données.\n- Une transaction dont l'identifiant bancaire figure déjà dans le compte n'est jamais recréée : rappeler l'opération avec le même fichier ne crée rien.\n\nLe résultat donne, par relevé, le compte bancaire, le nombre et les identifiants des transactions créées et ce qui a été ignoré. Les transactions sont ensuite rapprochées dans Kafinea (comptabilité, banque). Le droit de création sur les transactions bancaires est requis.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "fileId": { "type": "string", "description": "Identifiant privé du relevé OFX déposé avec `file_upload`.", "example": "9a8b7c6d5e4f30211203f4e5d6c7b8a99a8b7c6d5e4f30211203f4e5d6c7b8a9" }, "accounts": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "default": "[]", "description": "Texte JSON (objet). Comme pour `bank_statement_analyze` : index du relevé vers identifiant du compte bancaire, ou `skip`.", "example": "[\"61x123\"]" }, "includeProbableDuplicates": { "type": "boolean", "default": false, "description": "Importe aussi les doublons probables." } }, "required": [ "fileId" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Par relevé : compte bancaire, nombre et identifiants des transactions créées, éléments ignorés." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=fec_import_prepare": { "post": { "operationId": "fec_import_prepare", "tags": [ "Imports" ], "summary": "Préparer un import de FEC", "description": "Crée un import de fichier des écritures comptables (FEC, article A47 A-1 du LPF) à partir d'un fichier déposé avec `file_upload`, dans la société courante de l'utilisateur (celle sélectionnée en haut de l'écran Kafinea). Un fichier nommé d'après un autre SIREN est bloqué.\n\nFormats acceptés : `.txt` ou `.csv` séparé par tabulation, barre verticale ou point-virgule, un `.zip` qui en contient un, ou un `.xlsx` issu de l'enregistrement du fichier.\n\nLe fichier est lu et analysé **sans écrire aucune donnée comptable** : format, écritures (regroupées quand le fichier numérote ligne par ligne), exercice, soldes d'ouverture, comptes, journaux et tiers, anomalies bloquantes et décisions restant à prendre. Les décisions facultatives utilisent les identifiants de `fec_import_configure`. Les gros fichiers sont analysés en arrière-plan : interrogez `fec_import_inspect` jusqu'à ce que l'état ne soit plus `analysing`.\n\nLe droit de création sur les imports comptables est requis, pas le statut d'administrateur.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "fileId": { "type": "string", "description": "Identifiant privé du fichier FEC déposé avec `file_upload`.", "example": "9a8b7c6d5e4f30211203f4e5d6c7b8a99a8b7c6d5e4f30211203f4e5d6c7b8a9" }, "decisions": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "default": "[]", "description": "Texte JSON (objet). Décisions facultatives dès la préparation, avec les identifiants et valeurs décrits pour `fec_import_configure`.", "example": "{\"encoding\":\"UTF-8\",\"separator\":\"tab\"}" } }, "required": [ "fileId" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "L'import créé : identifiant, état (`analysing` pour un gros fichier), révision et synthèse de l'analyse." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=fec_import_inspect": { "get": { "operationId": "fec_import_inspect", "tags": [ "Imports" ], "summary": "Consulter un import de FEC", "description": "Sans `importId`, liste les imports comptables que l'utilisateur peut lire (fichier, état, nombre de lignes, auteur et date, état de la reprise).\n\nAvec `importId`, renvoie un import :\n\n- l'état (`analysing`, `to_complete`, `ready`, `importing`, `paused`, `imported`, `validated`, `cancelled`, `failed`) et la révision ;\n- la synthèse (lignes, écritures, débit et crédit en centimes, dates, anomalies bloquantes, décisions en attente), l'exercice, l'ouverture ;\n- les anomalies avec des codes stables, les décisions à prendre avec leurs options, `allowedActions` et la progression ;\n- une fois importé, le contrôle de clôture : solde du fichier contre solde du grand livre, écart en centimes.\n\n`section` pagine le détail : `accounts`, `journals`, `parties`, `lines` (200 au plus), `control`, `created`.\n\nUne fois l'import terminé, le bloc `reprise` décrit la reprise des pièces de l'exercice (factures clients et fournisseurs, avoirs, règlements et affectations reconstitués à partir du fichier, créés sans aucune écriture comptable) : état (`absent`, `to_complete`, `ready`, `creating`, `paused`, `created`, `cancelling`, `cancelled`, `failed`), actions permises, synthèse par nature, anomalies, décisions, aperçu de ce qui sera créé et contrôle par tiers. Ses sections : `pieces` (filtres `kind`, `family`, `status`, `reason`, `party`, `month`, `search`), `piece` (filtre `pieceId` : lignes, taux, affectations, lignes sources, fichiers PDF), `allocations`, `attachments` (filtres `status`, `pieceId`), `reprise_control` (filtre `status=gap`) et `reprise_decisions`.\n\nLes montants sont des entiers en centimes.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "importId", "required": false, "schema": { "type": "string", "default": "" }, "example": "61x12", "description": "Identifiant de l'import (nombre ou identifiant de service web). Omis, liste les imports." }, { "in": "query", "name": "section", "required": false, "schema": { "type": "string", "enum": [ "summary", "decisions", "accounts", "journals", "parties", "lines", "control", "created", "pieces", "piece", "allocations", "attachments", "reprise_control", "reprise_decisions" ], "default": "summary" }, "description": "Détail à renvoyer : `summary` (défaut), `decisions`, `accounts`, `journals`, `parties`, `lines`, `control`, `created`, `pieces`, `piece`, `allocations`, `attachments`, `reprise_control` ou `reprise_decisions`." }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Position du premier élément de la section." }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "default": 50 }, "description": "Nombre d'éléments par page (200 au plus pour `lines`)." }, { "in": "query", "name": "filters", "required": false, "schema": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "default": "[]" }, "example": "{\"status\":\"gap\"}", "description": "Texte JSON (objet). Filtres de la section, selon les sections de la reprise : `kind`, `family`, `status`, `reason`, `party`, `month`, `search`, `pieceId`." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Sans `importId` : la liste des imports. Avec `importId` : l'import avec état, révision, synthèse, anomalies, décisions, `allowedActions`, progression, contrôle de clôture et bloc `reprise`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=fec_import_configure": { "post": { "operationId": "fec_import_configure", "tags": [ "Imports" ], "summary": "Enregistrer des décisions sur un import de FEC", "description": "Enregistre des décisions sur un import de FEC puis relance l'analyse ; renvoie le nouvel état et la nouvelle révision. Seules les options que `fec_import_inspect` propose pour une décision en attente sont acceptées. Une valeur `null` retire une décision. Ne prenez jamais une décision à la place de l'utilisateur.\n\nDécisions de l'import :\n\n- `overlap:` : `shift` ou `delete` (exercice vide que le fichier recouvre) ;\n- `replace` : `yes` remplace l'import précédent du même exercice ;\n- `opening` : `file`, `ordinary` ou `kafinea` ;\n- `accents` : `repair` ou `keep` ;\n- `journal:` : `create` ou `match:` ;\n- `family:` : `Accounts`, `Vendors`, `MdsPerson` ou `none` ;\n- `party:` : `create` ou `match:` ;\n- `accept_warnings` : `yes` ;\n- `period_start` et `period_end` : date `Y-m-d` ;\n- `encoding` : `UTF-8`, `ISO-8859-15` ou `Windows-1252` ;\n- `separator` : `tab`, `pipe` ou `semicolon`.\n\nDécisions de la reprise, une fois l'import terminé :\n\n- `reprise_scope:customers|vendors|persons|root:` : `yes` ou `no` ;\n- `reprise_article` : `per_account` ou `single` ;\n- `reprise_allocation:` : `automatic` ou `none` ;\n- `reprise_method:` : `match:` ou `create` ;\n- `reprise_vat:` : `a1`, `a2`... ou `undetailed` ;\n- `reprise_attach:` : `match:` ou `ignore` ;\n- `reprise_accept_rejections` et `reprise_accept_warnings` : `yes`.\n\nSi l'import a changé entre-temps, l'opération répond `FEC_REVISION_CHANGED`. Le droit de modification sur les imports comptables est requis.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "importId": { "type": "string", "description": "Identifiant de l'import (nombre ou identifiant de service web).", "example": "61x12" }, "revision": { "type": "integer", "description": "Révision courante de l'import, lue avec `fec_import_inspect`.", "example": 3 }, "decisions": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "description": "Texte JSON (objet). Décisions à enregistrer : identifiant de la décision vers sa valeur (`null` pour la retirer).", "example": "{\"opening\":\"file\",\"journal:VT\":\"create\",\"accept_warnings\":\"yes\"}" } }, "required": [ "importId", "revision", "decisions" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le nouvel état de l'import, avec sa nouvelle révision." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=fec_import_control": { "post": { "operationId": "fec_import_control", "tags": [ "Imports" ], "summary": "Piloter un import de FEC", "description": "Agit sur un import de FEC avec sa révision courante ; seules les actions listées dans `allowedActions` sont acceptées (`FEC_ACTION_NOT_ALLOWED` sinon).\n\nImport des écritures :\n\n- `start` (état `ready`) : crée l'exercice, les journaux, les comptes et les tiers, puis comptabilise toutes les lignes en arrière-plan. Interrogez `fec_import_inspect` jusqu'à l'état `imported`, puis vérifiez le contrôle de clôture.\n- `pause` et `resume` : entre deux mois.\n- `cancel` : supprime toutes les écritures importées, tant que l'import n'est pas validé.\n- `validate` : rend l'import définitif, il ne peut plus être annulé.\n- Après une annulation, `cleanup` supprime ce que l'import a créé et que rien n'utilise, `keep` le conserve.\n\nReprise des pièces, une fois l'import terminé :\n\n- `reprise_analyse` : construit ou reconstruit l'aperçu, sans écrire d'enregistrement.\n- `reprise_start` : crée en arrière-plan les documents, règlements et affectations, verrouillés, avec leurs numéros d'origine ; ils ne sont ni comptabilisés ni envoyés à la plateforme de facturation électronique.\n- `reprise_pause` et `reprise_resume`.\n- `reprise_cancel` : supprime ces éléments, sauf un document qu'un règlement saisi depuis lors solde (listé dans `reprise.kept`). Un import dont la reprise porte des documents ne peut pas être annulé.\n\nDroits requis : modification sur les imports comptables et création sur les modules que la reprise alimente. Démarrer, annuler et valider modifient les données.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "importId": { "type": "string", "description": "Identifiant de l'import (nombre ou identifiant de service web).", "example": "61x12" }, "action": { "type": "string", "enum": [ "start", "pause", "resume", "cancel", "validate", "cleanup", "keep", "reprise_analyse", "reprise_start", "reprise_pause", "reprise_resume", "reprise_cancel" ], "description": "`start`, `pause`, `resume`, `cancel`, `validate`, `cleanup`, `keep`, `reprise_analyse`, `reprise_start`, `reprise_pause`, `reprise_resume` ou `reprise_cancel`." }, "revision": { "type": "integer", "description": "Révision courante de l'import, lue avec `fec_import_inspect`.", "example": 4 } }, "required": [ "importId", "action", "revision" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "L'état de l'import après l'action, avec sa révision." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=fec_import_attach": { "post": { "operationId": "fec_import_attach", "tags": [ "Imports" ], "summary": "Rattacher les PDF d'origine à un import de FEC", "description": "Dépose les fichiers PDF d'origine d'une reprise de pièces : `fileId` désigne un `.zip` de PDF (ou un PDF seul) déposé avec `file_upload` ; plusieurs dépôts sont acceptés.\n\nChaque PDF est rapproché d'une pièce :\n\n- un Factur-X par son numéro de facture et son total ;\n- sinon par le nom du fichier (dossiers ignorés, majuscules, sans accents ni ponctuation), qui doit commencer par la référence de la pièce (la plus longue l'emporte) ;\n- un fichier `pieces.csv` à la racine (`fichier;référence de pièce[;tiers]`) remplace cette règle.\n\nSans `apply=true`, rien n'est rattaché : le résultat est l'aperçu par fichier (`matched`, `ambiguous` avec les candidats, `unmatched`, `not_pdf`, `duplicate`). Avec `apply=true`, chaque fichier rapproché est confirmé : rattaché immédiatement si la reprise est créée, à sa création sinon. `apply=true` sans `fileId` confirme ce que les dépôts précédents ont rapproché. Un fichier ambigu se règle avec la décision `reprise_attach:` de `fec_import_configure`.\n\nLe droit de modification sur les imports comptables est requis.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "importId": { "type": "string", "description": "Identifiant de l'import (nombre ou identifiant de service web).", "example": "61x12" }, "revision": { "type": "integer", "description": "Révision courante de l'import, lue avec `fec_import_inspect`.", "example": 5 }, "fileId": { "type": "string", "default": "", "description": "Identifiant privé d'un `.zip` de PDF, ou d'un PDF, déposé avec `file_upload`. Omis avec `apply=true`, confirme les rapprochements des dépôts précédents.", "example": "9a8b7c6d5e4f30211203f4e5d6c7b8a99a8b7c6d5e4f30211203f4e5d6c7b8a9" }, "apply": { "type": "string", "default": "", "description": "`true` confirme les fichiers rapprochés ; sinon, aperçu seul sans rattachement.", "example": "true" } }, "required": [ "importId", "revision" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "L'aperçu ou le résultat du rattachement par fichier : `matched`, `ambiguous`, `unmatched`, `not_pdf` ou `duplicate`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=sales_statement_inspect": { "get": { "operationId": "sales_statement_inspect", "tags": [ "Imports" ], "summary": "Consulter les relevés de ventes importés", "description": "Lit les imports de relevés de ventes des distributeurs et agents (Factures > Relevés de ventes), pour les expliquer. Lecture seule : les modifications se font sur l'écran d'import. Le droit de lecture sur les factures est requis.\n\nSans `importId`, liste les imports lisibles : partenaire et son `accountId`, mois, état, documents prévus et créés, net après commission en centimes.\n\nAvec `importId`, renvoie un import : l'état (`draft`, `to_complete`, `ready`, `creating`, `created`, `cancelled`), la révision, les fichiers, les réglages du partenaire utilisés (colonnes, zones, synthèse, mode de commission et articles, entrepôt, contrat, période des retours), les décisions, l'analyse (lignes lues, retenues, ignorées à zéro, exclues, articles ; anomalies avec des codes `SST_` stables et leur étape ; zones ; produits inconnus ; lignes illisibles ; contrôle par région fiscale et taux ; suggestions ; totaux), les documents prévus et créés, et `allowedActions`.\n\n`section` pagine le détail (200 éléments au plus) :\n\n- `lines` : filtres `document` (clé de document) et `search` ;\n- `rows` : les lignes laissées hors des documents avec leur motif, filtres `kind` (`skipped` ou `excluded`) et `search` ;\n- `articles` : chaque référence du relevé et l'article du catalogue rapproché, avec lignes, quantités vendues et retournées, montant net ; filtre `search` sur toutes les colonnes.\n\nLes montants sont des entiers en centimes. Si la fonction n'est pas activée sur l'instance, l'erreur est `SST_FEATURE_DISABLED`.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "importId", "required": false, "schema": { "type": "string", "default": "" }, "example": "61x8", "description": "Identifiant de l'import (nombre ou identifiant de service web). Omis, liste les imports." }, { "in": "query", "name": "section", "required": false, "schema": { "type": "string", "enum": [ "summary", "lines", "rows", "articles" ], "default": "summary" }, "description": "Détail à renvoyer : `summary` (défaut), `lines`, `rows` ou `articles`." }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Position du premier élément de la section." }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "default": 100 }, "description": "Nombre d'éléments par page, 200 au plus." }, { "in": "query", "name": "filters", "required": false, "schema": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "default": "[]" }, "example": "{\"kind\":\"excluded\"}", "description": "Texte JSON (objet). Filtres de la section : `document` et `search` (`lines`), `kind` et `search` (`rows`), `search` (`articles`)." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Sans `importId` : la liste des imports. Avec `importId` : l'import avec état, révision, fichiers, réglages du partenaire, analyse, documents et actions permises." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=sales_statement_profile": { "get": { "operationId": "sales_statement_profile", "tags": [ "Imports" ], "summary": "Lire les réglages de relevé d'un partenaire", "description": "Lit les réglages de relevé de ventes conservés pour un partenaire (enregistrement `Accounts`) : colonne du relevé qui porte chaque information, zone associée à chaque région fiscale, usage de la synthèse, mode de calcul de la commission (aucune, montants de la synthèse, pourcentage de colonnes choisies) et articles associés, entrepôt, référence de contrat et période des retours de ses documents, avec la révision, la date et l'auteur de la dernière sauvegarde, et les imports du partenaire.\n\n`profile` vaut `null` tant qu'aucun relevé de ce partenaire n'a été importé. Lecture seule. Le droit de lecture sur les factures est requis. Si la fonction n'est pas activée sur l'instance, l'erreur est `SST_FEATURE_DISABLED`.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "accountId", "required": true, "schema": { "type": "string" }, "example": "11x42", "description": "Partenaire concerné : identifiant de service web (`11x42`) ou identifiant numérique d'un enregistrement `Accounts`." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Les réglages du partenaire (`profile`, `null` si aucun), leur révision et les imports du partenaire." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=accounting_periods": { "get": { "operationId": "accounting_periods", "tags": [ "Comptabilité" ], "summary": "Lister les sociétés et leurs exercices", "description": "Liste les sociétés sur lesquelles l'utilisateur peut éditer des rapports, et les exercices comptables d'une société, du plus récent au plus ancien : identifiant, nom, début, fin, clôture, devise.\n\nC'est le point de départ pour transformer « l'exercice clos le 30/09/2025 » en `periodId` à passer aux autres rapports. Les exercices renvoyés appartiennent à la seule société désignée par `organizationId`.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "organizationId", "required": false, "schema": { "type": "string", "default": "" }, "example": "11x3", "description": "Société (`MdsOrganization`) de l'instance : identifiant webservice complet ou identifiant numérique. Par défaut, la société courante de l'utilisateur, ou la société principale si la société courante ne tient pas de comptabilité. La réponse nomme la société dans `meta.scope`." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La société retenue (`organization_id`, `organization_label`), la liste `organizations` des sociétés accessibles et la liste `periods` de ses exercices (identifiant, nom, début, fin, clôturé, devise)." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=accounting_key_figures": { "get": { "operationId": "accounting_key_figures", "tags": [ "Comptabilité" ], "summary": "Obtenir les chiffres clés comptables", "description": "Tableau de bord financier du début de l'exercice à `dateTo` : chiffre d'affaires (comptes 70), produits, charges, résultat, capitaux propres, fonds de roulement (classe 1 et résultat moins classe 2), besoin en fonds de roulement (classes 3 et 4), trésorerie nette (classe 5), créances clients, dettes fournisseurs, ainsi qu'un tableau mois par mois (chiffre d'affaires, charges, résultat, résultat cumulé, trésorerie en fin de mois).\n\nLecture seule. Comptabilité générale de la société entière, calculée à partir des écritures comptabilisées de toute origine (documents de gestion commerciale, banque, paie, saisies manuelles, imports). L'utilisateur doit avoir le droit sur les rapports de comptabilité générale et voir toutes les écritures du périmètre, sinon le rapport entier est refusé (`ACCESSDENIED`). La réponse contient `kpis` (indicateurs), `tables` (colonnes traduites, lignes de textes et de nombres) et `meta` (périmètre : société, exercice, dates, devise). Les montants sont des nombres décimaux dans la devise de la société.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "organizationId", "required": false, "schema": { "type": "string", "default": "" }, "example": "11x3", "description": "Société (`MdsOrganization`) de l'instance : identifiant webservice complet ou identifiant numérique. Par défaut, la société courante de l'utilisateur, ou la société principale si la société courante ne tient pas de comptabilité. La réponse nomme la société dans `meta.scope`." }, { "in": "query", "name": "periodId", "required": false, "schema": { "type": "string", "default": "" }, "example": "60x12", "description": "Exercice (`MdsAcPeriod`) de cette société, tel que renvoyé par `accounting_periods`. Par défaut, l'exercice qui contient `dateTo`, sinon l'exercice courant." }, { "in": "query", "name": "dateFrom", "required": false, "schema": { "type": "string", "default": "" }, "example": "2025-01-01", "description": "Premier jour (AAAA-MM-JJ), à l'intérieur d'un seul exercice. Par défaut, le premier jour de l'exercice." }, { "in": "query", "name": "dateTo", "required": false, "schema": { "type": "string", "default": "" }, "example": "2025-12-31", "description": "Dernier jour (AAAA-MM-JJ), dans le même exercice. Par défaut, le dernier jour de l'exercice." }, { "in": "query", "name": "compare", "required": false, "schema": { "type": "string", "enum": [ "", "previous_exercise" ], "default": "" }, "example": "previous_exercise", "description": "`previous_exercise` ajoute la même plage relative de l'exercice précédent tenu dans Kafinea." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Rapport sous forme de données : `kpis`, `tables` et `meta` (périmètre et contrôles). Les montants sont des nombres décimaux dans la devise de la société." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=accounting_trial_balance": { "get": { "operationId": "accounting_trial_balance", "tags": [ "Comptabilité" ], "summary": "Obtenir la balance générale", "description": "Balance générale : pour chaque compte (ou chaque compte et code auxiliaire), le solde d'ouverture (report à nouveau plus écritures de l'exercice antérieures à `dateFrom`), les mouvements au débit et au crédit de la plage et le solde de clôture débiteur ou créditeur. Totaux par classe ; `meta.balanced` indique l'équilibre.\n\nLes colonnes débit et crédit sont les mouvements de la plage : les débits d'un compte fournisseur sont ce qui a été payé (ou avoir reçu), les crédits ce qui a été facturé. Utilisez `sort` et `top` pour obtenir « les plus gros » côté serveur, et filtrez les comptes pour obtenir le solde d'un tiers (401, 411) ou d'un compte à une date.\n\nLecture seule. Comptabilité générale de la société entière, calculée à partir des écritures comptabilisées de toute origine (documents de gestion commerciale, banque, paie, saisies manuelles, imports). L'utilisateur doit avoir le droit sur les rapports de comptabilité générale et voir toutes les écritures du périmètre, sinon le rapport entier est refusé (`ACCESSDENIED`). La réponse contient `kpis` (indicateurs), `tables` (colonnes traduites, lignes de textes et de nombres) et `meta` (périmètre : société, exercice, dates, devise). Les montants sont des nombres décimaux dans la devise de la société.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "organizationId", "required": false, "schema": { "type": "string", "default": "" }, "example": "11x3", "description": "Société (`MdsOrganization`) de l'instance : identifiant webservice complet ou identifiant numérique. Par défaut, la société courante de l'utilisateur, ou la société principale si la société courante ne tient pas de comptabilité. La réponse nomme la société dans `meta.scope`." }, { "in": "query", "name": "periodId", "required": false, "schema": { "type": "string", "default": "" }, "example": "60x12", "description": "Exercice (`MdsAcPeriod`) de cette société, tel que renvoyé par `accounting_periods`. Par défaut, l'exercice qui contient `dateTo`, sinon l'exercice courant." }, { "in": "query", "name": "dateFrom", "required": false, "schema": { "type": "string", "default": "" }, "example": "2025-01-01", "description": "Premier jour (AAAA-MM-JJ), à l'intérieur d'un seul exercice. Par défaut, le premier jour de l'exercice." }, { "in": "query", "name": "dateTo", "required": false, "schema": { "type": "string", "default": "" }, "example": "2025-12-31", "description": "Dernier jour (AAAA-MM-JJ), dans le même exercice. Par défaut, le dernier jour de l'exercice." }, { "in": "query", "name": "accountFrom", "required": false, "schema": { "type": "string", "default": "" }, "example": "401", "description": "Premier compte ou préfixe de compte (`401` commence à 401...)." }, { "in": "query", "name": "accountTo", "required": false, "schema": { "type": "string", "default": "" }, "example": "409", "description": "Dernier compte ou préfixe de compte (`409` se termine après 409999...)." }, { "in": "query", "name": "accountPrefix", "required": false, "schema": { "type": "string", "default": "" }, "example": "6,7", "description": "Préfixes de comptes séparés par des virgules, par exemple `512` ou `6,7`." }, { "in": "query", "name": "auxCode", "required": false, "schema": { "type": "string", "default": "" }, "example": "CLIEXEMPLE", "description": "Un code auxiliaire (tiers) d'un compte collectif." }, { "in": "query", "name": "detail", "required": false, "schema": { "type": "string", "enum": [ "account", "auxiliary" ], "default": "account" }, "example": "auxiliary", "description": "`auxiliary` détaille les comptes collectifs par code auxiliaire de tiers ; `account` (défaut) s'arrête au compte." }, { "in": "query", "name": "includeZero", "required": false, "schema": { "type": "string", "enum": [ "0", "1" ], "default": "0" }, "example": "0", "description": "`1` pour lister aussi les comptes dont tous les montants sont nuls (`0` par défaut)." }, { "in": "query", "name": "compare", "required": false, "schema": { "type": "string", "enum": [ "", "previous_exercise" ], "default": "" }, "example": "previous_exercise", "description": "`previous_exercise` ajoute la même plage relative de l'exercice précédent tenu dans Kafinea." }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string", "enum": [ "account", "debit_balance", "credit_balance", "debit", "credit", "balance_abs", "variation_abs" ], "default": "account" }, "example": "debit_balance", "description": "Classement des lignes côté serveur : `account` (défaut), `debit_balance` (plus grosses créances), `credit_balance` (plus grosses dettes), `debit` ou `credit` (plus gros mouvements), `balance_abs`, `variation_abs` (plus forte variation par rapport à N-1, avec `compare` à `previous_exercise` ; un compte présent en N-1 seulement est listé à zéro)." }, { "in": "query", "name": "top", "required": false, "schema": { "type": "integer", "default": 0 }, "example": 10, "description": "Ne garde que les N premières lignes du classement (`0` : toutes)." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Rapport sous forme de données : `kpis`, `tables` et `meta` (périmètre et contrôles). Les montants sont des nombres décimaux dans la devise de la société." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=accounting_general_ledger": { "get": { "operationId": "accounting_general_ledger", "tags": [ "Comptabilité" ], "summary": "Obtenir le grand livre", "description": "Grand livre : pour chaque compte, le solde d'ouverture puis tous les mouvements de la plage (date, journal, pièce, libellé, code auxiliaire, débit, crédit, solde progressif) et le total du compte.\n\nRestreignez les comptes, journaux ou dates, et paginez avec `offset` et `limit`. Les filtres d'audit (`minAmount`, `roundTo`, `weekend`) sélectionnent les lignes côté serveur, ce qui évite de parcourir toutes les pages. Un code de journal inconnu est refusé (`ACCOUNTING_BAD_PARAMETER`) avec la liste des journaux qui contiennent des écritures.\n\nLecture seule. Comptabilité générale de la société entière, calculée à partir des écritures comptabilisées de toute origine (documents de gestion commerciale, banque, paie, saisies manuelles, imports). L'utilisateur doit avoir le droit sur les rapports de comptabilité générale et voir toutes les écritures du périmètre, sinon le rapport entier est refusé (`ACCESSDENIED`). La réponse contient `kpis` (indicateurs), `tables` (colonnes traduites, lignes de textes et de nombres) et `meta` (périmètre : société, exercice, dates, devise). Les montants sont des nombres décimaux dans la devise de la société.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "organizationId", "required": false, "schema": { "type": "string", "default": "" }, "example": "11x3", "description": "Société (`MdsOrganization`) de l'instance : identifiant webservice complet ou identifiant numérique. Par défaut, la société courante de l'utilisateur, ou la société principale si la société courante ne tient pas de comptabilité. La réponse nomme la société dans `meta.scope`." }, { "in": "query", "name": "periodId", "required": false, "schema": { "type": "string", "default": "" }, "example": "60x12", "description": "Exercice (`MdsAcPeriod`) de cette société, tel que renvoyé par `accounting_periods`. Par défaut, l'exercice qui contient `dateTo`, sinon l'exercice courant." }, { "in": "query", "name": "dateFrom", "required": false, "schema": { "type": "string", "default": "" }, "example": "2025-01-01", "description": "Premier jour (AAAA-MM-JJ), à l'intérieur d'un seul exercice. Par défaut, le premier jour de l'exercice." }, { "in": "query", "name": "dateTo", "required": false, "schema": { "type": "string", "default": "" }, "example": "2025-12-31", "description": "Dernier jour (AAAA-MM-JJ), dans le même exercice. Par défaut, le dernier jour de l'exercice." }, { "in": "query", "name": "accountFrom", "required": false, "schema": { "type": "string", "default": "" }, "example": "401", "description": "Premier compte ou préfixe de compte (`401` commence à 401...)." }, { "in": "query", "name": "accountTo", "required": false, "schema": { "type": "string", "default": "" }, "example": "409", "description": "Dernier compte ou préfixe de compte (`409` se termine après 409999...)." }, { "in": "query", "name": "accountPrefix", "required": false, "schema": { "type": "string", "default": "" }, "example": "6,7", "description": "Préfixes de comptes séparés par des virgules, par exemple `512` ou `6,7`." }, { "in": "query", "name": "auxCode", "required": false, "schema": { "type": "string", "default": "" }, "example": "CLIEXEMPLE", "description": "Un code auxiliaire (tiers) d'un compte collectif." }, { "in": "query", "name": "journalCode", "required": false, "schema": { "type": "string", "default": "" }, "example": "VE,BQ", "description": "Codes de journaux séparés par des virgules, par exemple `HA` ou `VE,BQ`. Un code inconnu est refusé, avec la liste des journaux qui contiennent des écritures." }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer", "default": 0 }, "example": 0, "description": "Rang de la première ligne de la page." }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "default": 500 }, "example": 500, "description": "Nombre de lignes par page, 50000 au maximum. `meta.lines_total` et `meta.truncated` indiquent s'il reste des pages." }, { "in": "query", "name": "minAmount", "required": false, "schema": { "type": "string", "default": "" }, "example": "1000", "description": "Filtre d'audit : lignes d'un montant au moins égal à cette valeur." }, { "in": "query", "name": "roundTo", "required": false, "schema": { "type": "integer", "default": 0 }, "example": 1000, "description": "Filtre d'audit : montants multiples exacts de cette valeur (`1000` pour les milliers ronds)." }, { "in": "query", "name": "weekend", "required": false, "schema": { "type": "string", "enum": [ "", "1" ], "default": "" }, "example": "1", "description": "Filtre d'audit : `1` pour les lignes datées d'un samedi ou d'un dimanche." }, { "in": "query", "name": "lettering", "required": false, "schema": { "type": "string", "enum": [ "", "all", "open", "partial", "full", "none" ], "default": "" }, "example": "open", "description": "Lettrage des lignes clients et fournisseurs (401, 411), dans leur état du jour : `open` (non lettrées, partie ouverte), `partial` (groupe encore partiellement payé), `full` (lettrées), `none` (ligne sans document ni règlement, saisie manuelle), `all`. Avec une valeur, le grand livre se lit de l'ouverture de l'exercice à `dateTo`, reports détaillés inclus. Chaque ligne d'un compte de tiers affiche sa lettre dans la colonne de lettrage (majuscule : lettré, minuscule : partiel)." }, { "in": "query", "name": "letteringCode", "required": false, "schema": { "type": "string", "default": "" }, "example": "A", "description": "Une lettre (casse indifférente) : les lignes de ce groupe de lettrage, tous comptes confondus, ouverture de l'exercice incluse." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Rapport sous forme de données : `kpis`, `tables` et `meta` (périmètre et contrôles). Les montants sont des nombres décimaux dans la devise de la société." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=accounting_journal": { "get": { "operationId": "accounting_journal", "tags": [ "Comptabilité" ], "summary": "Obtenir les journaux comptables", "description": "Journaux : totaux par journal (nombre de lignes, débit, crédit) et lignes d'écriture de la plage, journal par journal (date, pièce, compte, code auxiliaire, libellé, débit, crédit), reports à nouveau inclus.\n\nLes filtres d'audit (`minAmount`, `roundTo`, `weekend`) sélectionnent les lignes côté serveur. Un code de journal inconnu est refusé (`ACCOUNTING_BAD_PARAMETER`) avec la liste des journaux qui contiennent des écritures.\n\nLecture seule. Comptabilité générale de la société entière, calculée à partir des écritures comptabilisées de toute origine (documents de gestion commerciale, banque, paie, saisies manuelles, imports). L'utilisateur doit avoir le droit sur les rapports de comptabilité générale et voir toutes les écritures du périmètre, sinon le rapport entier est refusé (`ACCESSDENIED`). La réponse contient `kpis` (indicateurs), `tables` (colonnes traduites, lignes de textes et de nombres) et `meta` (périmètre : société, exercice, dates, devise). Les montants sont des nombres décimaux dans la devise de la société.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "organizationId", "required": false, "schema": { "type": "string", "default": "" }, "example": "11x3", "description": "Société (`MdsOrganization`) de l'instance : identifiant webservice complet ou identifiant numérique. Par défaut, la société courante de l'utilisateur, ou la société principale si la société courante ne tient pas de comptabilité. La réponse nomme la société dans `meta.scope`." }, { "in": "query", "name": "periodId", "required": false, "schema": { "type": "string", "default": "" }, "example": "60x12", "description": "Exercice (`MdsAcPeriod`) de cette société, tel que renvoyé par `accounting_periods`. Par défaut, l'exercice qui contient `dateTo`, sinon l'exercice courant." }, { "in": "query", "name": "dateFrom", "required": false, "schema": { "type": "string", "default": "" }, "example": "2025-01-01", "description": "Premier jour (AAAA-MM-JJ), à l'intérieur d'un seul exercice. Par défaut, le premier jour de l'exercice." }, { "in": "query", "name": "dateTo", "required": false, "schema": { "type": "string", "default": "" }, "example": "2025-12-31", "description": "Dernier jour (AAAA-MM-JJ), dans le même exercice. Par défaut, le dernier jour de l'exercice." }, { "in": "query", "name": "journalCode", "required": false, "schema": { "type": "string", "default": "" }, "example": "VE,BQ", "description": "Codes de journaux séparés par des virgules, par exemple `HA` ou `VE,BQ`. Un code inconnu est refusé, avec la liste des journaux qui contiennent des écritures." }, { "in": "query", "name": "accountPrefix", "required": false, "schema": { "type": "string", "default": "" }, "example": "6,7", "description": "Préfixes de comptes séparés par des virgules, par exemple `512` ou `6,7`." }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer", "default": 0 }, "example": 0, "description": "Rang de la première ligne de la page." }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "default": 500 }, "example": 500, "description": "Nombre de lignes par page, 50000 au maximum. `meta.lines_total` et `meta.truncated` indiquent s'il reste des pages." }, { "in": "query", "name": "minAmount", "required": false, "schema": { "type": "string", "default": "" }, "example": "1000", "description": "Filtre d'audit : lignes d'un montant au moins égal à cette valeur." }, { "in": "query", "name": "roundTo", "required": false, "schema": { "type": "integer", "default": 0 }, "example": 1000, "description": "Filtre d'audit : montants multiples exacts de cette valeur (`1000` pour les milliers ronds)." }, { "in": "query", "name": "weekend", "required": false, "schema": { "type": "string", "enum": [ "", "1" ], "default": "" }, "example": "1", "description": "Filtre d'audit : `1` pour les lignes datées d'un samedi ou d'un dimanche." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Rapport sous forme de données : `kpis`, `tables` et `meta` (périmètre et contrôles). Les montants sont des nombres décimaux dans la devise de la société." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=accounting_financial_statement": { "get": { "operationId": "accounting_financial_statement", "tags": [ "Comptabilité" ], "summary": "Obtenir le bilan ou le compte de résultat", "description": "Bilan ou compte de résultat selon les présentations légales françaises de l'écran des états financiers (mêmes postes, mêmes codes, même affectation des comptes), du début de l'exercice à `dateTo` (situation intermédiaire avant la fin de l'exercice).\n\n`meta.control` liste les comptes soldés qu'aucun poste n'inclut, les comptes comptés deux fois, l'écart actif/passif et le résultat de l'état comparé à celui des écritures des classes 6 et 7. Ces contrôles expliquent tout écart et sont à restituer à l'utilisateur.\n\nLecture seule. Comptabilité générale de la société entière, calculée à partir des écritures comptabilisées de toute origine (documents de gestion commerciale, banque, paie, saisies manuelles, imports). L'utilisateur doit avoir le droit sur les rapports de comptabilité générale et voir toutes les écritures du périmètre, sinon le rapport entier est refusé (`ACCESSDENIED`). La réponse contient `kpis` (indicateurs), `tables` (colonnes traduites, lignes de textes et de nombres) et `meta` (périmètre : société, exercice, dates, devise). Les montants sont des nombres décimaux dans la devise de la société.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "statement", "required": true, "schema": { "type": "string", "enum": [ "balance_sheet", "income_statement" ] }, "example": "balance_sheet", "description": "État à produire : `balance_sheet` (bilan) ou `income_statement` (compte de résultat). Toute autre valeur est refusée (`ACCOUNTING_BAD_PARAMETER`)." }, { "in": "query", "name": "organizationId", "required": false, "schema": { "type": "string", "default": "" }, "example": "11x3", "description": "Société (`MdsOrganization`) de l'instance : identifiant webservice complet ou identifiant numérique. Par défaut, la société courante de l'utilisateur, ou la société principale si la société courante ne tient pas de comptabilité. La réponse nomme la société dans `meta.scope`." }, { "in": "query", "name": "periodId", "required": false, "schema": { "type": "string", "default": "" }, "example": "60x12", "description": "Exercice (`MdsAcPeriod`) de cette société, tel que renvoyé par `accounting_periods`. Par défaut, l'exercice qui contient `dateTo`, sinon l'exercice courant." }, { "in": "query", "name": "dateTo", "required": false, "schema": { "type": "string", "default": "" }, "example": "2025-12-31", "description": "Dernier jour (AAAA-MM-JJ), dans le même exercice. Par défaut, le dernier jour de l'exercice." }, { "in": "query", "name": "simplified", "required": false, "schema": { "type": "string", "enum": [ "0", "1" ], "default": "0" }, "example": "0", "description": "`1` pour la présentation légale simplifiée." }, { "in": "query", "name": "compare", "required": false, "schema": { "type": "string", "enum": [ "", "previous_exercise" ], "default": "" }, "example": "previous_exercise", "description": "`previous_exercise` ajoute la même plage relative de l'exercice précédent tenu dans Kafinea." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Rapport sous forme de données : `kpis`, `tables` et `meta` (périmètre et contrôles). Les montants sont des nombres décimaux dans la devise de la société." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=accounting_opening_check": { "get": { "operationId": "accounting_opening_check", "tags": [ "Comptabilité" ], "summary": "Contrôler la continuité des à-nouveaux", "description": "Contrôle de continuité d'un exercice : le solde d'ouverture de chaque compte de bilan (classes 1 à 5) comparé à son solde de clôture dans l'exercice précédent tenu dans Kafinea, avec les écarts (ouverture moins clôture), le résultat de l'exercice précédent (qui revient par les capitaux propres, un écart sur les comptes de résultat est donc normal) et tout report porté sur un compte de charge ou de produit.\n\n`meta.status` vaut `continuous` (les comptes de bilan s'ouvrent sur leur clôture et les capitaux propres reprennent le résultat précédent), `gaps` ou `no_previous_exercise`. À préférer à une comparaison de soldes faite côté client pour répondre à une question de continuité d'un commissaire aux comptes ou d'un comptable.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "organizationId", "required": false, "schema": { "type": "string", "default": "" }, "example": "11x3", "description": "Société (`MdsOrganization`) de l'instance : identifiant webservice complet ou identifiant numérique. Par défaut, la société courante de l'utilisateur, ou la société principale si la société courante ne tient pas de comptabilité. La réponse nomme la société dans `meta.scope`." }, { "in": "query", "name": "periodId", "required": false, "schema": { "type": "string", "default": "" }, "example": "60x12", "description": "Exercice (`MdsAcPeriod`) de cette société, tel que renvoyé par `accounting_periods`. Par défaut, l'exercice qui contient `dateTo`, sinon l'exercice courant." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Rapport sous forme de données : `kpis`, `tables` et `meta`, dont `meta.status` (`continuous`, `gaps` ou `no_previous_exercise`)." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=accounting_bank_reconciliation": { "get": { "operationId": "accounting_bank_reconciliation", "tags": [ "Comptabilité" ], "summary": "Obtenir l'état de rapprochement bancaire", "description": "État de rapprochement bancaire d'un compte bancaire propre à une date : solde du compte comptable et solde bancaire, éléments en suspens des deux côtés un par un (comptabilisés mais non passés par la banque, passés par la banque mais non comptabilisés, avec leur motif), soldes ajustés et écart résiduel.\n\nL'origine du solde bancaire est donnée par `meta.bank_reconciliation.bank_balance_source` : relevé saisi par l'appelant, flux reconstitué à partir de la dernière synchronisation bancaire, ou `null` si aucun ne couvre la date. Un écart résiduel est décomposé : écart déjà présent à l'ouverture des livres du compte, soldes non reportés entre exercices, rapprochements dont les deux côtés diffèrent, opérations bancaires désactivées et reste à expliquer. `meta.bank_reconciliation` donne chaque montant en centimes ; `meta.status` vaut `balanced`, `gap` ou `no_bank_balance`.\n\nPour obtenir le PDF, utilisez `accounting_report_file` avec le rapport `bank_reconciliation`. Une valeur de `layout` inconnue est refusée (`ACCOUNTING_BAD_PARAMETER`).", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "organizationId", "required": false, "schema": { "type": "string", "default": "" }, "example": "11x3", "description": "Société (`MdsOrganization`) de l'instance : identifiant webservice complet ou identifiant numérique. Par défaut, la société courante de l'utilisateur, ou la société principale si la société courante ne tient pas de comptabilité. La réponse nomme la société dans `meta.scope`." }, { "in": "query", "name": "bankAccountId", "required": false, "schema": { "type": "string", "default": "" }, "example": "62x7", "description": "Compte bancaire propre (`MdsAcOwnBankAccount`) de cette société : identifiant webservice complet ou numérique. Par défaut, le compte bancaire par défaut de la société." }, { "in": "query", "name": "date", "required": false, "schema": { "type": "string", "default": "" }, "example": "2025-09-30", "description": "Date du relevé (AAAA-MM-JJ), à l'intérieur d'un exercice de la société. Par défaut, le dernier jour du mois précédent." }, { "in": "query", "name": "statementBalance", "required": false, "schema": { "type": "string", "default": "" }, "example": "12345.67", "description": "Solde que montre le relevé bancaire à cette date, avec le point comme séparateur décimal (`12345.67`, négatif pour un découvert). À ne passer que si l'appelant le connaît ; sinon le solde bancaire est reconstitué à partir de la dernière synchronisation bancaire (son solde moins les opérations postérieures à la date)." }, { "in": "query", "name": "layout", "required": false, "schema": { "type": "string", "default": "two_tables", "enum": [ "two_tables", "vertical" ] }, "example": "two_tables", "description": "Présentation de la synthèse : `two_tables` (défaut), deux tableaux symétriques (compte bancaire débit/crédit, relevé débit/crédit), ou `vertical`, la présentation verticale." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Rapport sous forme de données : `kpis`, `tables` et `meta`, dont `meta.bank_reconciliation` (chaque montant en centimes) et `meta.status` (`balanced`, `gap` ou `no_bank_balance`)." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=accounting_aged_balance": { "get": { "operationId": "accounting_aged_balance", "tags": [ "Comptabilité" ], "summary": "Obtenir la balance âgée", "description": "Balance âgée d'une société : montants encore dus sur les factures finalisées, avoirs et notes de débit clients (documents repris d'un FEC inclus) et règlements non affectés, de sorte que le solde d'un tiers est celui de son compte. Ventilation par ancienneté depuis l'échéance : non échu, 0-30, 30-60, 60-90, 90-180 et plus de 180 jours, avec les totaux.\n\nÀ la date du jour par défaut, ou à une date passée avec `asOf` (clôture d'exercice, audit). À utiliser pour les créances ou dettes par âge, les retards de paiement, une liste de relance ou les plus gros débiteurs par document. `meta.documents_without_due_date` compte les documents âgés à partir de leur date faute d'échéance.\n\nL'utilisateur doit être administrateur ou disposer du droit sur la balance âgée, sinon l'opération est refusée (`ACCESSDENIED`). Les tiers sont triés par solde décroissant et paginés avec `offset` et `limit`.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "organizationId", "required": false, "schema": { "type": "string", "default": "" }, "example": "11x3", "description": "Société (`MdsOrganization`) de l'instance : identifiant webservice complet ou identifiant numérique. Par défaut, la société courante de l'utilisateur, ou la société principale si la société courante ne tient pas de comptabilité. La réponse nomme la société dans `meta.scope`." }, { "in": "query", "name": "type", "required": false, "schema": { "type": "string", "default": "sales", "enum": [ "sales", "purchases" ] }, "example": "sales", "description": "`sales` (défaut) : ce que doivent les clients (factures, avoirs, notes de débit, règlements non affectés) ; `purchases` : ce que l'on doit aux fournisseurs (factures fournisseurs, avoirs, règlements non affectés). Toute autre valeur est refusée (`ACCOUNTING_BAD_PARAMETER`)." }, { "in": "query", "name": "detail", "required": false, "schema": { "type": "string", "default": "party", "enum": [ "party", "document" ] }, "example": "party", "description": "`party` (défaut) : une ligne par tiers (`party_id` : son identifiant webservice) ; `document` : chaque ligne liste aussi ses documents et règlements non affectés (numéro, date, échéance, ancienneté en jours, solde, identifiant webservice)." }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer", "default": 0 }, "example": 0, "description": "Rang du premier tiers de la page (tiers triés par solde décroissant)." }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "default": 200 }, "example": 200, "description": "Nombre de tiers par page, 2000 au maximum ; `meta.truncated` indique s'il en reste." }, { "in": "query", "name": "asOf", "required": false, "schema": { "type": "string", "default": "" }, "example": "2025-09-30", "description": "Date passée (AAAA-MM-JJ) : la balance âgée telle qu'elle était ce jour-là (documents et règlements datés d'alors, avec ce qui restait ouvert une fois écartées les affectations faites ensuite, ancienneté calculée à cette date). Par défaut, la date du jour. Une date non passée est refusée (`ACCOUNTING_BAD_PARAMETER`)." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "`meta` (société, type, date de référence, `documents_without_due_date`, `truncated`), `totals` (totaux par tranche d'ancienneté) et `parties` (`total`, `offset`, `items` : les tiers de la page avec leurs soldes par tranche)." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=accounting_condominium_annex": { "get": { "operationId": "accounting_condominium_annex", "tags": [ "Comptabilité" ], "summary": "Obtenir une annexe comptable de copropriété", "description": "Annexes comptables d'un syndicat de copropriétaires (décret n° 2005-240 du 14 mars 2005) pour un exercice, avec l'exercice précédent : annexe 1 état financier après répartition, annexe 2 compte de gestion général (opérations courantes hors travaux et opérations exceptionnelles), annexe 3 opérations courantes par catégories de charges, annexe 4 travaux et opérations exceptionnelles opération par opération, annexe 5 travaux votés non clôturés.\n\nLes colonnes de budget, les montants votés et les montants à recevoir ne sont pas tenus dans Kafinea et restent vides. `meta.control` contient les contrôles (deux côtés de l'annexe 1, résultat non réparti entre les copropriétaires, comptes hors plan comptable de copropriété, annexes 3 et 4 rapprochées de l'annexe 2, annexe 5 rapprochée des comptes 102 et 12) : à restituer à l'utilisateur. Disponible uniquement lorsque l'instance active les annexes de copropriété ; sinon l'opération est refusée (`ACCESSDENIED`).\n\nLecture seule. Comptabilité générale de la société entière, calculée à partir des écritures comptabilisées de toute origine (documents de gestion commerciale, banque, paie, saisies manuelles, imports). L'utilisateur doit avoir le droit sur les rapports de comptabilité générale et voir toutes les écritures du périmètre, sinon le rapport entier est refusé (`ACCESSDENIED`). La réponse contient `kpis` (indicateurs), `tables` (colonnes traduites, lignes de textes et de nombres) et `meta` (périmètre : société, exercice, dates, devise). Les montants sont des nombres décimaux dans la devise de la société.\n\n> Disponible lorsque la comptabilité de copropriété est activée sur l'instance.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "annex", "required": true, "schema": { "type": "string", "enum": [ "financial_position", "general_account", "current_operations", "works_account", "open_works" ] }, "example": "financial_position", "description": "Annexe demandée : `financial_position` (annexe 1, état financier après répartition), `general_account` (annexe 2, compte de gestion général), `current_operations` (annexe 3, opérations courantes par catégories de charges), `works_account` (annexe 4, travaux et opérations exceptionnelles), `open_works` (annexe 5, travaux et opérations exceptionnelles non clôturés)." }, { "in": "query", "name": "organizationId", "required": false, "schema": { "type": "string", "default": "" }, "example": "11x3", "description": "Société (`MdsOrganization`) de l'instance : identifiant webservice complet ou identifiant numérique. Par défaut, la société courante de l'utilisateur, ou la société principale si la société courante ne tient pas de comptabilité. La réponse nomme la société dans `meta.scope`." }, { "in": "query", "name": "periodId", "required": false, "schema": { "type": "string", "default": "" }, "example": "60x12", "description": "Exercice (`MdsAcPeriod`) de cette société, tel que renvoyé par `accounting_periods`. Par défaut, l'exercice qui contient `dateTo`, sinon l'exercice courant." }, { "in": "query", "name": "dateTo", "required": false, "schema": { "type": "string", "default": "" }, "example": "2025-12-31", "description": "Dernier jour (AAAA-MM-JJ), dans le même exercice. Par défaut, le dernier jour de l'exercice." }, { "in": "query", "name": "closingJournal", "required": false, "schema": { "type": "string", "default": "" }, "example": "CL", "description": "Code du journal dont les écritures datées du dernier jour de l'exercice sont les écritures de clôture du logiciel d'origine (elles soldent les comptes de travaux dans le compte 12) : elles sont écartées des chiffres réels des annexes 2 à 5. `meta.report_notice` nomme un tel journal quand aucun n'est donné." }, { "in": "query", "name": "categoryAxisId", "required": false, "schema": { "type": "string", "default": "" }, "example": "63x4", "description": "Annexe 3 uniquement : axe analytique (`MdsAcAxis`) dont les valeurs sont les catégories de charges du règlement de copropriété. Par défaut, une seule catégorie." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Rapport sous forme de données : `kpis`, `tables` et `meta` (périmètre et contrôles). Les montants sont des nombres décimaux dans la devise de la société." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=accounting_report_file": { "get": { "operationId": "accounting_report_file", "tags": [ "Comptabilité" ], "summary": "Produire un rapport comptable en PDF ou Excel", "description": "Produit un rapport de comptabilité générale ou analytique, ou la balance âgée des clients (`aged_receivables`) ou des fournisseurs (`aged_payables`), en PDF ou en classeur Excel, identique aux exports du centre de rapports. Le fichier est conservé comme fichier privé de l'utilisateur pendant sept jours (5 Mio au plus ; le classeur contient jusqu'à 50000 lignes, le PDF 10000).\n\nLes paramètres du rapport se passent dans `arguments`, sous la même forme que ceux de l'opération du même nom : ceux des opérations `accounting_*` (`organizationId`, `periodId`, `dateFrom`, `dateTo`, `accountPrefix`, `journalCode`, `detail`, `simplified`, `compare`, `closingJournal`, `categoryAxisId`...), ceux de l'état de rapprochement bancaire (`bankAccountId`, `dateTo` pour la date du relevé, `statementBalance`, `layout`) ou, pour un rapport `analytic_*`, ceux de l'opération analytique correspondante (`organizationId`, `dateFrom`, `dateTo`, `axisId`, `analyticValueId`, `rowAxisId`, `columnAxisId`, `comparison`...).\n\nErreurs : `ACCOUNTING_BAD_PARAMETER` (rapport, format ou arguments invalides), `ACCOUNTING_FILE_TOO_LARGE` (fichier trop volumineux : réduire les comptes, journaux ou dates). Les rapports d'annexes de copropriété ne sont disponibles que si l'instance les active. Les balances âgées exigent d'être administrateur ou de disposer du droit sur la balance âgée.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "report", "required": true, "schema": { "type": "string", "enum": [ "key_figures", "trial_balance", "general_ledger", "journal", "balance_sheet", "income_statement", "opening_check", "bank_reconciliation", "aged_receivables", "aged_payables", "condominium_financial_position", "condominium_general_account", "condominium_current_operations", "condominium_works_account", "condominium_open_works", "analytic_profit_and_loss", "analytic_general_ledger", "analytic_cross_axis", "analytic_tabular", "analytic_dashboard" ] }, "example": "trial_balance", "description": "Rapport à produire : `key_figures`, `trial_balance`, `general_ledger`, `journal`, `balance_sheet`, `income_statement`, `opening_check`, `bank_reconciliation`, `aged_receivables`, `aged_payables`, `condominium_financial_position`, `condominium_general_account`, `condominium_current_operations`, `condominium_works_account`, `condominium_open_works`, `analytic_profit_and_loss`, `analytic_general_ledger`, `analytic_cross_axis`, `analytic_tabular`, `analytic_dashboard`." }, { "in": "query", "name": "format", "required": true, "schema": { "type": "string", "enum": [ "pdf", "xlsx" ] }, "example": "pdf", "description": "Format du fichier : `pdf` ou `xlsx`." }, { "in": "query", "name": "arguments", "required": false, "schema": { "type": "string", "default": "" }, "example": { "organizationId": "11x3", "periodId": "60x12", "accountPrefix": "6,7" }, "description": "Objet JSON des paramètres du rapport, identiques à ceux de l'opération du même nom (voir la description de l'opération)." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le fichier produit : `fileId`, `filename`, `size`, `expiresAt`, `downloadUrl` (lien relatif de l'ERP, pour l'utilisateur connecté), `absoluteUrl` (le même lien pour un client extérieur à l'ERP, ouvert par l'utilisateur connecté), `report`, `format`, `truncated`, `lines_total` et `scope`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=manual_entry_save": { "post": { "operationId": "manual_entry_save", "tags": [ "Comptabilité" ], "summary": "Créer ou modifier un brouillon de saisie manuelle", "description": "Crée ou met à jour un brouillon de saisie manuelle avec toutes ses lignes, en un seul appel atomique : en-tête, comptes, tiers, choix analytiques. Les règles sont celles de l'écran de saisie, en un peu plus strictes : une ligne dont le compte ou le tiers ne peut pas être résolu, ou dont le montant est négatif ou des deux côtés à la fois, est refusée.\n\n- Sans `recordId`, un nouveau brouillon est créé : `date`, `description` et `journal` sont alors obligatoires.\n- Avec `recordId`, le brouillon est mis à jour et ses lignes sont remplacées par `lines`. Une saisie déjà validée est refusée (`MANUAL_ENTRY_NOT_DRAFT`) : enregistrez une écriture d'extourne. La société d'une saisie existante ne peut pas changer (`MANUAL_ENTRY_COMPANY_FIXED`).\n- Rien n'est enregistré si une ligne est refusée : `MANUAL_ENTRY_LINES_REFUSED`, avec les problèmes et leur numéro de ligne (codes de ligne : `MANUAL_ENTRY_LINE_INVALID`, `MANUAL_ENTRY_AMOUNT_INVALID`, `MANUAL_ENTRY_AMOUNT_ONE_SIDE`, `MANUAL_ENTRY_PARTY_INVALID`, `MANUAL_ENTRY_ANALYTIC_UNKNOWN`...). Autres erreurs : `MANUAL_ENTRY_BAD_PARAMETER`.\n- Un brouillon n'a pas besoin d'être équilibré et rien n'est comptabilisé. Le montant de la saisie est fixé au total des débits.\n\nIl faut le droit de création ou de modification sur les saisies manuelles, et sur les choix analytiques de ligne lorsque `analytic` est renseigné. Appelez ensuite `manual_entry_validate` pour comptabiliser.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "recordId": { "type": "string", "default": "", "description": "Brouillon de saisie manuelle (`MdsAcManualEntry`) à modifier : identifiant webservice ou numérique. Omettre pour créer un nouveau brouillon.", "example": "73x15" }, "date": { "type": "string", "default": "", "description": "Date comptable (AAAA-MM-JJ). Obligatoire à la création.", "example": "2025-09-30" }, "description": { "type": "string", "default": "", "description": "Libellé de la saisie, recopié sur chaque ligne comptabilisée. Obligatoire à la création.", "example": "Régularisation de charges" }, "journal": { "type": "string", "default": "", "description": "Code du journal (`OD`) ou identifiant d'un enregistrement `MdsAcJournal`. Obligatoire à la création ; un code inconnu est refusé avec la liste des codes.", "example": "OD" }, "currency": { "type": "string", "default": "", "description": "Code ISO de la devise (`EUR`). Par défaut à la création : la devise de base.", "example": "EUR" }, "organizationId": { "type": "string", "default": "", "description": "Société d'une nouvelle saisie (voir `accounting_periods`). Par défaut, la société courante de l'utilisateur. Ne peut pas changer à la mise à jour. Identifiant d'un enregistrement du module `MdsOrganization`.", "example": "11x3" }, "lines": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array", "items": { "type": "object", "properties": { "account": { "type": "string" }, "partyId": { "type": "string" }, "auxiliaryCode": { "type": "string" }, "debit": { "type": [ "number", "string" ] }, "credit": { "type": [ "number", "string" ] }, "analytic": { "type": "object" }, "lineKey": { "type": "string" } }, "additionalProperties": false } }, "description": "Texte JSON (liste). Toutes les lignes de la saisie (elles remplacent les lignes enregistrées), 500 au plus. Chaque ligne est un objet avec : `account` (numéro de compte du plan comptable ; facultatif avec `partyId` ou `auxiliaryCode`, c'est alors le compte collectif de ce tiers), `partyId` (identifiant du tiers client, fournisseur ou contact : la ligne va à son compte collectif et à son code auxiliaire), `auxiliaryCode` (code auxiliaire du tiers, à la place de `partyId`), `debit` et `credit` (montant positif, point décimal, 2 décimales au plus, par exemple `\"1234.56\"` ; un seul des deux est supérieur à zéro), `analytic` (choix analytique `{\"code d'axe\": \"code de valeur\"}`, une valeur active par axe à 100 % ; les axes omis restent automatiques, les codes inconnus sont refusés et jamais créés) et `lineKey` (clé renvoyée par un appel précédent, qui conserve l'identité analytique de la ligne).", "example": "[{\"account\":\"606000\",\"debit\":\"1200.00\",\"analytic\":{\"PROJET\":\"P-2025-01\"}},{\"account\":\"401000\",\"partyId\":\"4x58\",\"credit\":\"1200.00\"}]" } }, "required": [ "lines" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La saisie enregistrée : identifiant, numéro, brouillon ou non, date, libellé, journal, société, devise, montant, totaux (`debit`, `credit`, `balanced`) et lignes (avec `lineKey`, compte, tiers, codes analytiques), plus `warnings` (par exemple une date hors exercice ouvert).", "type": "object", "properties": { "id": { "type": "string" }, "recordId": { "type": "integer" }, "num": { "type": "string" }, "draft": { "type": "boolean" }, "date": { "type": "string" }, "description": { "type": "string" }, "journal": { "type": "object", "properties": { "id": { "type": "integer" }, "code": { "type": "string" } } }, "organizationId": { "type": "integer" }, "currency": { "type": "string" }, "amount": { "type": "string" }, "totals": { "type": "object", "properties": { "debit": { "type": "string" }, "credit": { "type": "string" }, "balanced": { "type": "boolean" } } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "line": { "type": "integer" }, "lineKey": { "type": "string" }, "account": { "type": "string" }, "partyId": { "type": "null" }, "partyName": { "type": "null" }, "auxiliaryCode": { "type": "null" }, "debit": { "type": "string" }, "credit": { "type": "string" }, "analytic": { "type": "object", "properties": { "PROJET": { "type": "string" } } } } } }, "warnings": { "type": "array" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "id": "73x15", "recordId": 15, "num": "OD-2025-0015", "draft": true, "date": "2025-09-30", "description": "Régularisation de charges", "journal": { "id": 4, "code": "OD" }, "organizationId": 3, "currency": "EUR", "amount": "1200.00", "totals": { "debit": "1200.00", "credit": "1200.00", "balanced": true }, "lines": [ { "line": 1, "lineKey": "k1a2b3", "account": "606000", "partyId": null, "partyName": null, "auxiliaryCode": null, "debit": "1200.00", "credit": "0.00", "analytic": { "PROJET": "P-2025-01" } }, { "line": 2, "lineKey": "k4d5e6", "account": "401000", "partyId": 58, "partyName": "Fournisseur Exemple SARL", "auxiliaryCode": "FOUEXEMPLE", "debit": "0.00", "credit": "1200.00", "analytic": [] } ], "warnings": [] } } } } } } } }, "/webservice.php?operation=manual_entry_validate": { "post": { "operationId": "manual_entry_validate", "tags": [ "Comptabilité" ], "summary": "Valider une saisie manuelle et la comptabiliser", "description": "Valide un brouillon de saisie manuelle et comptabilise ses écritures, avec les contrôles de l'écran de saisie sur les lignes enregistrées : chaque ligne imputée à un compte existant (ou à un tiers ayant un compte), débits égaux aux crédits, montant de la saisie égal au total de ses lignes.\n\nErreurs : `MANUAL_ENTRY_NOT_FOUND`, `MANUAL_ENTRY_NOT_DRAFT` (saisie déjà validée), `MANUAL_ENTRY_LINES_REFUSED` (désigne les lignes fautives et donne les totaux), `MANUAL_ENTRY_AMOUNT_MISMATCH`, `MANUAL_ENTRY_PERIOD_NOT_OPEN` (date hors exercice ouvert : rappelez avec `confirmPeriod` à `true` après confirmation par l'utilisateur ; aucune écriture n'est comptabilisée pour un exercice clos ou absent).\n\nUne saisie validée ne peut plus être modifiée : corrigez-la par une écriture d'extourne. Il faut le droit de modification sur les saisies manuelles.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "recordId": { "type": "string", "description": "Brouillon de saisie manuelle (`MdsAcManualEntry`) à valider : identifiant webservice ou numérique.", "example": "73x15" }, "confirmPeriod": { "type": "string", "enum": [ "", "true" ], "default": "", "description": "`true` une fois que l'utilisateur a confirmé une date hors exercice ouvert, comme le demande l'écran (`MANUAL_ENTRY_PERIOD_NOT_OPEN`). Par défaut, vide.", "example": "true" } }, "required": [ "recordId" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La saisie validée, au même format que `manual_entry_save` (`draft` à faux), avec `warnings` vide." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=analytic_activation": { "get": { "operationId": "analytic_activation", "tags": [ "Comptabilité analytique" ], "summary": "Lire l'activation de la comptabilité analytique", "description": "Retourne l'état d'activation de la comptabilité analytique pour une société : si elle est configurée, depuis quelle date et si elle est active.\n\nOpération réservée aux administrateurs. Le refus remonte l'erreur d'accès `ACCESS_DENIED` avec le message « reserved to administrators ».\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "organizationId", "required": true, "schema": { "type": "string" }, "example": "43x12", "description": "Identifiant de la société (`MdsOrganization`) au format webservice." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "État d'activation de la société. `start_date` est null tant que rien n'est configuré.", "type": "object", "properties": { "organization_id": { "type": "string" }, "configured": { "type": "boolean" }, "start_date": { "type": "string" }, "is_active": { "type": "boolean" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "organization_id": "43x12", "configured": true, "start_date": "2026-01-01", "is_active": true } } } } } } } }, "/webservice.php?operation=set_analytic_activation": { "post": { "operationId": "set_analytic_activation", "tags": [ "Comptabilité analytique" ], "summary": "Activer ou désactiver la comptabilité analytique", "description": "Enregistre la date de début et l'état d'activation de la comptabilité analytique d'une société, puis retourne l'état enregistré (même forme que `analytic_activation`).\n\n- `isActive` accepte uniquement `\"0\"` ou `\"1\"`, sinon l'erreur est un refus de paramètre.\n- Opération réservée aux administrateurs.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "configure", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "Identifiant de la société (`MdsOrganization`) au format webservice.", "example": "43x12" }, "startDate": { "type": "string", "description": "Date de début de la comptabilité analytique, au format AAAA-MM-JJ.", "example": "2026-01-01" }, "isActive": { "type": "string", "description": "`1` pour activer, `0` pour désactiver.", "example": "1" } }, "required": [ "organizationId", "startDate", "isActive" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "État d'activation enregistré.", "type": "object", "properties": { "organization_id": { "type": "string" }, "configured": { "type": "boolean" }, "start_date": { "type": "string" }, "is_active": { "type": "boolean" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "organization_id": "43x12", "configured": true, "start_date": "2026-01-01", "is_active": true } } } } } } } }, "/webservice.php?operation=analytic_axis_account_ranges": { "get": { "operationId": "analytic_axis_account_ranges", "tags": [ "Comptabilité analytique" ], "summary": "Lire les plages de comptes d'un axe", "description": "Retourne toutes les plages de comptes configurées pour un axe analytique, triées par compte de début. L'axe doit appartenir à la société demandée ou être commun à toutes les sociétés, sinon l'accès est refusé.\n\nOpération réservée aux administrateurs.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "organizationId", "required": true, "schema": { "type": "string" }, "example": "43x12", "description": "Identifiant de la société (`MdsOrganization`) au format webservice." }, { "in": "query", "name": "axisId", "required": true, "schema": { "type": "string" }, "example": "44x7", "description": "Identifiant de l'axe analytique (`MdsAcAxis`) au format webservice." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Plages de comptes de l'axe.", "type": "object", "properties": { "organization_id": { "type": "string" }, "axis_id": { "type": "string" }, "ranges": { "type": "array", "items": { "type": "object", "properties": { "account_from": { "type": "string" }, "account_to": { "type": "string" } } } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "organization_id": "43x12", "axis_id": "44x7", "ranges": [ { "account_from": "600000", "account_to": "699999" } ] } } } } } } } }, "/webservice.php?operation=set_analytic_axis_account_ranges": { "post": { "operationId": "set_analytic_axis_account_ranges", "tags": [ "Comptabilité analytique" ], "summary": "Remplacer les plages de comptes d'un axe", "description": "Remplace en bloc l'ensemble des plages de comptes d'un axe analytique, puis retourne la configuration enregistrée (même forme que `analytic_axis_account_ranges`).\n\n- Liste de 100 plages au plus, sans doublon, 65 536 caractères au plus une fois encodée.\n- Chaque plage comporte exactement `account_from` et `account_to`, deux chaînes de 32 caractères au plus, formant une plage valide.\n- Une liste vide supprime toutes les plages.\n- L'axe doit appartenir à la société ou être commun à toutes les sociétés.\n- Opération réservée aux administrateurs.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "configure", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "Identifiant de la société (`MdsOrganization`) au format webservice.", "example": "43x12" }, "axisId": { "type": "string", "description": "Identifiant de l'axe analytique (`MdsAcAxis`) au format webservice.", "example": "44x7" }, "rangesJson": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array" }, "description": "Texte JSON (liste). Liste des plages de comptes, chaque élément portant `account_from` et `account_to`.", "example": "[{\"account_from\":\"600000\",\"account_to\":\"699999\"}]" } }, "required": [ "organizationId", "axisId", "rangesJson" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Plages enregistrées, au même format que `analytic_axis_account_ranges`.", "type": "object", "properties": { "organization_id": { "type": "string" }, "axis_id": { "type": "string" }, "ranges": { "type": "array", "items": { "type": "object", "properties": { "account_from": { "type": "string" }, "account_to": { "type": "string" } } } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "organization_id": "43x12", "axis_id": "44x7", "ranges": [ { "account_from": "600000", "account_to": "699999" } ] } } } } } } } }, "/webservice.php?operation=analytic_axis_totals": { "get": { "operationId": "analytic_axis_totals", "tags": [ "Comptabilité analytique" ], "summary": "Totaux analytiques par valeur d'un axe", "description": "Regroupe les charges et produits comptabilisés d'une société par valeur d'un axe analytique, sur une période, avec en option un filtre sur un préfixe de compte.\n\nChaque ligne donne le débit, le crédit et le net (crédit moins débit) en décimal à deux chiffres, dans la devise comptable de la société. La ligne `value_id` null regroupe les montants non ventilés sur cet axe. `general_reference` rappelle les totaux de la comptabilité générale et `complete` indique si l'analytique les couvre entièrement.\n\nErreurs : la période doit être valide (`dateFrom` antérieure à `dateTo`), `accountPrefix` doit commencer par 6 ou 7 (8 chiffres au plus). L'accès exige le droit sur le rapport analytique croisé et la couverture complète du périmètre de l'utilisateur sur la société.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "organizationId", "required": true, "schema": { "type": "string" }, "example": "43x12", "description": "Identifiant de la société (`MdsOrganization`), au format webservice (`43x12`) ou numérique." }, { "in": "query", "name": "dateFrom", "required": true, "schema": { "type": "string" }, "example": "2026-01-01", "description": "Premier jour de la période, au format AAAA-MM-JJ." }, { "in": "query", "name": "dateTo", "required": true, "schema": { "type": "string" }, "example": "2026-12-31", "description": "Dernier jour de la période, au format AAAA-MM-JJ." }, { "in": "query", "name": "axisId", "required": true, "schema": { "type": "string" }, "example": "44x7", "description": "Identifiant de l'axe analytique (`MdsAcAxis`), au format webservice ou numérique." }, { "in": "query", "name": "accountPrefix", "required": false, "schema": { "type": "string", "default": "" }, "example": "6", "description": "Préfixe de compte de charges ou de produits (6 ou 7, 8 chiffres au plus). Vide : tous les comptes de classes 6 et 7." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Totaux par valeur d'axe, avec le total général et la référence de la comptabilité générale.", "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "integer" }, "label": { "type": "string" } } }, "axis": { "type": "object", "properties": { "id": { "type": "integer" }, "label": { "type": "string" } } }, "date_from": { "type": "string" }, "date_to": { "type": "string" }, "effective_date_from": { "type": "string" }, "activation_date": { "type": "string" }, "account_prefix": { "type": "string" }, "currency": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "value_id": { "type": "integer" }, "label": { "type": "string" }, "debit": { "type": "string" }, "credit": { "type": "string" }, "net": { "type": "string" } } } }, "total": { "type": "object", "properties": { "debit": { "type": "string" }, "credit": { "type": "string" }, "net": { "type": "string" } } }, "general_reference": { "type": "object", "properties": { "debit": { "type": "string" }, "credit": { "type": "string" }, "net": { "type": "string" } } }, "complete": { "type": "boolean" }, "scope": { "type": "string" }, "includes_closing_allocations": { "type": "boolean" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "organization": { "id": 43, "label": "Exemple SARL" }, "axis": { "id": 7, "label": "Activité" }, "date_from": "2026-01-01", "date_to": "2026-12-31", "effective_date_from": "2026-01-01", "activation_date": "2026-01-01", "account_prefix": "", "currency": "EUR", "rows": [ { "value_id": 101, "label": "Conseil", "debit": "12000.00", "credit": "0.00", "net": "-12000.00" }, { "value_id": null, "label": "Non ventilé", "debit": "0.00", "credit": "0.00", "net": "0.00" } ], "total": { "debit": "12000.00", "credit": "0.00", "net": "-12000.00" }, "general_reference": { "debit": "12000.00", "credit": "0.00", "net": "-12000.00" }, "complete": true, "scope": "posted_analytical_entries", "includes_closing_allocations": true } } } } } } } }, "/webservice.php?operation=analytic_cross_axis": { "get": { "operationId": "analytic_cross_axis", "tags": [ "Comptabilité analytique" ], "summary": "Croiser deux axes analytiques", "description": "Produit un tableau croisé de deux axes analytiques pour une société, sur une période : les lignes suivent les valeurs de `rowAxisId`, les colonnes celles de `columnAxisId`. La mesure est crédit moins débit.\n\nSans `accountPrefix`, le tableau nette charges et produits (une marge). La réponse contient les cellules (`cells`), le tableau prêt à afficher (`table` avec ses totaux de colonnes et le total général), le total, la référence de la comptabilité générale, `reconciled` et `complete`. Les montants sont des décimaux à deux chiffres.\n\nL'accès exige le droit sur le rapport analytique croisé.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "organizationId", "required": true, "schema": { "type": "string" }, "example": "43x12", "description": "Identifiant de la société (`MdsOrganization`), au format webservice (`43x12`) ou numérique." }, { "in": "query", "name": "dateFrom", "required": true, "schema": { "type": "string" }, "example": "2026-01-01", "description": "Premier jour de la période, au format AAAA-MM-JJ." }, { "in": "query", "name": "dateTo", "required": true, "schema": { "type": "string" }, "example": "2026-12-31", "description": "Dernier jour de la période, au format AAAA-MM-JJ." }, { "in": "query", "name": "rowAxisId", "required": true, "schema": { "type": "string" }, "example": "44x7", "description": "Axe des lignes du tableau (`MdsAcAxis`), au format webservice ou numérique." }, { "in": "query", "name": "columnAxisId", "required": true, "schema": { "type": "string" }, "example": "44x7", "description": "Axe des colonnes du tableau (`MdsAcAxis`), au format webservice ou numérique." }, { "in": "query", "name": "accountPrefix", "required": false, "schema": { "type": "string", "default": "" }, "example": "6", "description": "Préfixes de comptes des classes 6 ou 7, séparés par des virgules. Sans préfixe, le tableau nette charges et produits (marge) : produits 7, charges 6." }, { "in": "query", "name": "allocationView", "required": false, "schema": { "type": "string", "default": "after", "enum": [ "after", "before" ] }, "example": "after", "description": "`after` (défaut) inclut les ventilations de clôture comptabilisées ; `before` montre les montants tels que saisis, avant répartition des montants partagés." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Tableau croisé : `cells`, `table` (`columns`, `rows`, `column_totals`, `grand_total`), `total`, `reference`, `reconciled`, `general_reference`, `complete`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=analytic_dashboard": { "get": { "operationId": "analytic_dashboard", "tags": [ "Comptabilité analytique" ], "summary": "Tableau de bord analytique d'un axe", "description": "Tableau de bord d'un axe : pour chaque valeur (activité, site, projet...), produits (classe 7), charges (classe 6) et marge en centimes, mois par mois (`values[].months`). Les valeurs sont triées de la meilleure marge à la moins bonne, la part non ventilée (`value_id` null) en dernier. La réponse donne aussi le total, la référence de la comptabilité générale, l'écart de couverture (`coverage_gap`) et, en cas de comparaison, les marges de référence par identifiant de valeur (`reference_margins`).\n\nRépond aux questions de marge par activité, de résultat par site, de meilleures et pires valeurs. Exige le droit sur le compte de résultat analytique ou sur le croisement d'axes.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "organizationId", "required": true, "schema": { "type": "string" }, "example": "43x12", "description": "Identifiant de la société (`MdsOrganization`), au format webservice (`43x12`) ou numérique." }, { "in": "query", "name": "dateFrom", "required": true, "schema": { "type": "string" }, "example": "2026-01-01", "description": "Premier jour de la période, au format AAAA-MM-JJ." }, { "in": "query", "name": "dateTo", "required": true, "schema": { "type": "string" }, "example": "2026-12-31", "description": "Dernier jour de la période, au format AAAA-MM-JJ." }, { "in": "query", "name": "axisId", "required": true, "schema": { "type": "string" }, "example": "44x7", "description": "Identifiant de l'axe analytique (`MdsAcAxis`), au format webservice ou numérique." }, { "in": "query", "name": "comparison", "required": false, "schema": { "type": "string", "enum": [ "", "previous_period", "previous_year" ], "default": "" }, "example": "previous_year", "description": "`previous_period` : la période de même durée juste avant ; `previous_year` : les mêmes dates un an plus tôt. Vide : pas de comparaison." }, { "in": "query", "name": "allocationView", "required": false, "schema": { "type": "string", "default": "after", "enum": [ "after", "before" ] }, "example": "after", "description": "`after` (défaut) inclut les ventilations de clôture comptabilisées ; `before` montre les montants tels que saisis, avant répartition des montants partagés." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Libellés de la société et de l'axe, période effective, devise, indicateur de complétude (`complete`), notice éventuelle, puis le détail par valeur, le total et la référence. Les montants sont en centimes." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=analytic_profit_and_loss": { "get": { "operationId": "analytic_profit_and_loss", "tags": [ "Comptabilité analytique" ], "summary": "Compte de résultat analytique", "description": "Compte de résultat analytique d'une société sur une période et un axe, avec la référence complète de la comptabilité générale et l'écart de couverture séparé. Le résultat se présente sous la forme de trois blocs : `kpis` (indicateurs clés), `tables` (tableaux de lignes) et `meta` (périmètre, devise, notices).\n\nOn peut restreindre à une valeur (`analyticValueId`), comparer à une autre période et afficher les valeurs inactives. Exige le droit sur le compte de résultat analytique.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "organizationId", "required": true, "schema": { "type": "string" }, "example": "43x12", "description": "Identifiant de la société (`MdsOrganization`), au format webservice (`43x12`) ou numérique." }, { "in": "query", "name": "dateFrom", "required": true, "schema": { "type": "string" }, "example": "2026-01-01", "description": "Premier jour de la période, au format AAAA-MM-JJ." }, { "in": "query", "name": "dateTo", "required": true, "schema": { "type": "string" }, "example": "2026-12-31", "description": "Dernier jour de la période, au format AAAA-MM-JJ." }, { "in": "query", "name": "axisId", "required": true, "schema": { "type": "string" }, "example": "44x7", "description": "Identifiant de l'axe analytique (`MdsAcAxis`), au format webservice ou numérique." }, { "in": "query", "name": "analyticValueId", "required": false, "schema": { "type": "string", "default": "" }, "example": "45x101", "description": "Identifiant de la valeur d'axe (`MdsAcAxisValue`) à isoler, au format webservice ou numérique. Vide : toutes les valeurs." }, { "in": "query", "name": "comparison", "required": false, "schema": { "type": "string", "default": "" }, "example": "previous_year", "description": "Mode de comparaison avec une autre période (par exemple `previous_period` ou `previous_year`). Vide : pas de comparaison." }, { "in": "query", "name": "showInactive", "required": false, "schema": { "type": "string", "default": "0" }, "example": "0", "description": "`1` pour inclure les valeurs inactives, `0` (défaut) sinon." }, { "in": "query", "name": "allocationView", "required": false, "schema": { "type": "string", "default": "after", "enum": [ "after", "before" ] }, "example": "after", "description": "`after` (défaut) inclut les ventilations de clôture comptabilisées ; `before` montre les montants tels que saisis, avant répartition des montants partagés." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Objet `{kpis, tables, meta}` du rapport." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=analytic_general_ledger": { "get": { "operationId": "analytic_general_ledger", "tags": [ "Comptabilité analytique" ], "summary": "Grand livre analytique", "description": "Grand livre analytique d'une société sur une période : les écritures portant des ventilations, filtrables par valeur d'un premier axe (`analyticValueId`), éventuellement croisées avec une seconde valeur (`secondAxisId`, `secondValueId`), par préfixe de compte et par document d'origine (`sourceModule`, `sourceId`).\n\nPour retrouver les écritures sans ventilation sur un axe, passer `unallocated` dans `analyticValueId` ou `secondValueId`. Le résultat se présente sous la forme de trois blocs : `kpis`, `tables` et `meta`.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "organizationId", "required": true, "schema": { "type": "string" }, "example": "43x12", "description": "Identifiant de la société (`MdsOrganization`), au format webservice (`43x12`) ou numérique." }, { "in": "query", "name": "dateFrom", "required": true, "schema": { "type": "string" }, "example": "2026-01-01", "description": "Premier jour de la période, au format AAAA-MM-JJ." }, { "in": "query", "name": "dateTo", "required": true, "schema": { "type": "string" }, "example": "2026-12-31", "description": "Dernier jour de la période, au format AAAA-MM-JJ." }, { "in": "query", "name": "axisId", "required": true, "schema": { "type": "string" }, "example": "44x7", "description": "Identifiant de l'axe analytique (`MdsAcAxis`), au format webservice ou numérique." }, { "in": "query", "name": "analyticValueId", "required": false, "schema": { "type": "string", "default": "" }, "example": "45x101", "description": "Identifiant de la valeur d'axe (`MdsAcAxisValue`) au format webservice ou numérique. `unallocated` pour les écritures sans ventilation sur cet axe ; vide pour toutes les valeurs." }, { "in": "query", "name": "accountPrefix", "required": false, "schema": { "type": "string", "default": "" }, "example": "606", "description": "Préfixe de compte à filtrer. Vide : tous les comptes." }, { "in": "query", "name": "secondAxisId", "required": false, "schema": { "type": "string", "default": "" }, "example": "44x7", "description": "Second axe analytique (`MdsAcAxis`) pour croiser le filtre. Vide : aucun." }, { "in": "query", "name": "secondValueId", "required": false, "schema": { "type": "string", "default": "" }, "example": "45x203", "description": "Valeur du second axe (`MdsAcAxisValue`), ou `unallocated` pour les écritures sans ventilation sur ce second axe. Vide : toutes les valeurs." }, { "in": "query", "name": "sourceModule", "required": false, "schema": { "type": "string", "default": "" }, "example": "Invoice", "description": "Module du document d'origine à isoler (par exemple `Invoice`). Vide : tous les documents." }, { "in": "query", "name": "sourceId", "required": false, "schema": { "type": "string", "default": "" }, "example": "7x1520", "description": "Identifiant du document d'origine, au format webservice, à utiliser avec `sourceModule`. Vide : tous les documents." }, { "in": "query", "name": "allocationView", "required": false, "schema": { "type": "string", "default": "after", "enum": [ "after", "before" ] }, "example": "after", "description": "`after` (défaut) inclut les ventilations de clôture comptabilisées ; `before` montre les montants tels que saisis, avant répartition des montants partagés." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Objet `{kpis, tables, meta}` du grand livre analytique." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=analytic_entry": { "get": { "operationId": "analytic_entry", "tags": [ "Comptabilité analytique" ], "summary": "Lire les ventilations d'une écriture comptable", "description": "Retourne les ventilations analytiques enregistrées d'une écriture comptable (`MdsAcJournalEntry`) lisible par l'utilisateur : montant et sens de l'écriture, puis chaque portion avec son montant, son sens, son origine et ses dimensions (axe, valeur, origine de la dimension).\n\nErreurs : `INVALID_ID` si l'identifiant n'est pas celui d'une écriture comptable ; accès refusé si la comptabilité analytique est désactivée ou si l'utilisateur ne peut pas lire le montant, le document d'origine, les portions ou les axes concernés.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "id", "required": true, "schema": { "type": "string" }, "example": "46x3300", "description": "Identifiant webservice de l'écriture comptable (`MdsAcJournalEntry`)." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Objet avec `entry` (identifiant), `amount`, `debitcredit` et `portions` : une liste d'objets `id`, `amount`, `debitcredit`, `origin` et `dimensions` (liste de `axis`, `value`, `origin`)." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=analytic_line_preview": { "post": { "operationId": "analytic_line_preview", "tags": [ "Comptabilité analytique" ], "summary": "Prévisualiser des ventilations de lignes", "description": "Valide des choix de ventilation analytique non enregistrés sur les lignes d'un document source (`Invoice`, `MdsPayable` ou `MdsAcManualEntry`) et retourne la ventilation qui en résulterait, sans rien comptabiliser.\n\n- 100 lignes au plus, 65 536 caractères au plus pour `linesJson`.\n- Chaque ligne désigne une ligne enregistrée du document par `line_key` et peut porter des `intentions` indexées par identifiant numérique d'axe : `{\"mode\": \"automatic\"}` ou une répartition en parts.\n- Réponse : un `status` global, puis pour chaque ligne un `status` (`ready`, `no_applicable_axis`, `not_ready_account_context` ou `error` avec un message), le compte, le montant, la date d'écriture et les portions calculées.\n- Si la comptabilité analytique est désactivée ou pas encore active à la date du document, toutes les lignes reçoivent un statut en lecture seule ou « avant activation ».\n\nL'utilisateur doit pouvoir lire le document et la société.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "sourceId": { "type": "string", "description": "Identifiant webservice du document source (`Invoice`, `MdsPayable` ou `MdsAcManualEntry`).", "example": "7x1520" }, "linesJson": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array" }, "description": "Texte JSON (liste). Liste de lignes à prévisualiser : `line_key` (identité de la ligne enregistrée) et `intentions` optionnelles indexées par identifiant numérique d'axe.", "example": "[{\"line_key\":\"a1b2c3d4\",\"intentions\":{\"7\":{\"mode\":\"automatic\"}}}]" } }, "required": [ "sourceId", "linesJson" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Objet `{status, source_id, source_module, organization_id, date, lines}`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=analytic_key_distribution": { "get": { "operationId": "analytic_key_distribution", "tags": [ "Comptabilité analytique" ], "summary": "Lire la répartition d'une clé analytique", "description": "Retourne les parts d'une clé de répartition analytique (`MdsAcAllocationKey`) et les valeurs d'axe disponibles pour la compléter. L'utilisateur doit pouvoir lire la clé, son axe et les valeurs concernées.\n\nErreur `INVALID_ID` si l'identifiant n'est pas celui d'une clé de répartition.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "id", "required": true, "schema": { "type": "string" }, "example": "47x15", "description": "Identifiant webservice de la clé de répartition (`MdsAcAllocationKey`)." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La clé, ses parts et les valeurs disponibles.", "type": "object", "properties": { "key": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "axis_id": { "type": "string" }, "axis_name": { "type": "string" }, "organization_id": { "type": "string" }, "active": { "type": "boolean" } } }, "shares": { "type": "array", "items": { "type": "object", "properties": { "value_id": { "type": "string" }, "value_label": { "type": "string" }, "percentage": { "type": "string" } } } }, "available_values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "available": { "type": "boolean" } } } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "key": { "id": "47x15", "name": "Répartition par activité", "code": "REP-ACT", "axis_id": "44x7", "axis_name": "Activité", "organization_id": "43x12", "active": true }, "shares": [ { "value_id": "45x101", "value_label": "Conseil", "percentage": "60.00" }, { "value_id": "45x102", "value_label": "Formation", "percentage": "40.00" } ], "available_values": [ { "id": "45x101", "label": "Conseil", "available": true }, { "id": "45x102", "label": "Formation", "available": true } ] } } } } } } } }, "/webservice.php?operation=update_analytic_key_distribution": { "post": { "operationId": "update_analytic_key_distribution", "tags": [ "Comptabilité analytique" ], "summary": "Remplacer les parts d'une clé analytique", "description": "Remplace l'ensemble des parts d'une clé de répartition analytique, après contrôle du périmètre, des droits et d'un total exact de 100 %. Retourne la clé mise à jour au même format que `analytic_key_distribution`.\n\n- La liste est non vide et compte 100 parts au plus ; chaque part porte `value_id` (valeur d'axe, `MdsAcAxisValue`) et `percentage`.\n- `INVALID_ID` si `id` n'est pas une clé ou si un `value_id` n'est pas une valeur d'axe.\n- Les erreurs de contrôle (total différent de 100 %, valeur non éligible, droits insuffisants) sont refusées par la clé.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifiant webservice de la clé de répartition (`MdsAcAllocationKey`).", "example": "47x15" }, "sharesJson": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array" }, "description": "Texte JSON (liste). Liste complète des parts : `value_id` (valeur d'axe) et `percentage`, le total devant être exactement 100.", "example": "[{\"value_id\":\"45x101\",\"percentage\":\"60\"},{\"value_id\":\"45x102\",\"percentage\":\"40\"}]" } }, "required": [ "id", "sharesJson" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La clé après mise à jour, au même format que `analytic_key_distribution`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=update_analytic_line_choice": { "post": { "operationId": "update_analytic_line_choice", "tags": [ "Comptabilité analytique" ], "summary": "Modifier la ventilation d'une ligne source", "description": "Enregistre l'exception de ventilation analytique d'une ligne d'un document source (`Invoice`, `MdsPayable` ou `MdsAcManualEntry`) pour un axe, puis régénère l'écriture comptable du document. Le chemin de validation est celui de l'écran de saisie.\n\nValeurs de `mode` :\n- `automatic` : retour à la ventilation automatique ;\n- `unallocated` : aucune ventilation sur cet axe ;\n- `value` : toute la ligne sur une valeur d'axe, désignée par `targetId` (`MdsAcAxisValue`) ;\n- `key` : ventilation selon une clé, désignée par `targetId` (`MdsAcAllocationKey`) ;\n- `shares` : répartition libre, `targetId` portant alors la liste JSON des parts (`value` et `percentage`, `value` pouvant être null pour la part non ventilée).\n\nConditions : droit d'édition sur le document et sur les ventilations de ligne, comptabilité analytique active à la date du document, période comptable ouverte. Erreurs : `INVALID_ID` (document, axe ou cible incohérent), refus de paramètre pour un mode invalide ou une cible qui ne correspond pas au mode.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "sourceId": { "type": "string", "description": "Identifiant webservice du document source (`Invoice`, `MdsPayable` ou `MdsAcManualEntry`).", "example": "7x1520" }, "lineKey": { "type": "string", "description": "Identité stable de la ligne enregistrée du document.", "example": "a1b2c3d4" }, "axisId": { "type": "string", "description": "Identifiant de l'axe analytique (`MdsAcAxis`), au format webservice ou numérique.", "example": "44x7" }, "mode": { "type": "string", "description": "Mode de ventilation : `automatic`, `unallocated`, `value`, `key` ou `shares`.", "example": "value" }, "targetId": { "type": "string", "default": "", "description": "Cible du mode : identifiant de la valeur d'axe pour `value`, de la clé pour `key`, liste JSON des parts pour `shares` ; vide pour `automatic` et `unallocated`.", "example": "45x101" } }, "required": [ "sourceId", "lineKey", "axisId", "mode" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Objet `{source_module, source_id, line_key, choices, currency}` : les choix enregistrés de la ligne et la devise comptable." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=reclassify_analytic_allocation": { "post": { "operationId": "reclassify_analytic_allocation", "tags": [ "Comptabilité analytique" ], "summary": "Reclasser une ventilation analytique clôturée", "description": "Déplace une portion analytique d'une période close vers une autre valeur d'un axe, par une correction datée du jour et équilibrée ; l'écriture comptable clôturée n'est pas modifiée. Retourne la correction créée (identifiant, date, écriture et pièce, axe, valeur d'origine et de destination, montant, devise).\n\n- Réservée aux administrateurs.\n- `targetValueId` vide : la portion est retirée de l'axe (non ventilée).\n- `reason` : 5 à 255 caractères, conservé avec la correction.\n- La période du jour doit être ouverte et la comptabilité analytique active ; une portion déjà reclassée ne peut plus l'être.\n- `INVALID_ID` si la portion ou l'axe n'est pas du bon type.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "allocationId": { "type": "string", "description": "Identifiant webservice de la portion analytique (`MdsAcAllocation`).", "example": "48x9120" }, "axisId": { "type": "string", "description": "Identifiant de l'axe analytique (`MdsAcAxis`), au format webservice ou numérique.", "example": "44x7" }, "targetValueId": { "type": "string", "description": "Identifiant de la valeur d'axe de destination (`MdsAcAxisValue`). Vide pour retirer la portion de l'axe.", "example": "45x102" }, "reason": { "type": "string", "description": "Motif du reclassement, de 5 à 255 caractères.", "example": "Erreur d'imputation de la facture de décembre" } }, "required": [ "allocationId", "axisId", "targetValueId", "reason" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La correction créée : `id`, `date`, `journal_entry_id`, `voucher_id`, `axis_id`, `from_value_id`, `to_value_id`, `amount`, `currency`, `allocation_id`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=analytic_closing_cycles": { "get": { "operationId": "analytic_closing_cycles", "tags": [ "Comptabilité analytique" ], "summary": "Lister les cycles de répartition de clôture", "description": "Retourne les cycles de répartition de clôture d'une société, dans leur ordre d'exécution : axe et comptes répartis, valeurs émettrices (`unallocated` désigne les montants sans valeur), clé de répartition avec sa base (pourcentages fixes, indicateur statistique comme les ETP, ou montants comptabilisés) et son mode (cumulé depuis le début de l'exercice, ou périodique), ainsi que les problèmes qui empêchent un cycle de s'exécuter (`problems`). La réponse indique aussi le dernier lot comptabilisé (`latest_batch_id`).\n\nÀ lire avant une simulation. Les cycles, clés et indicateurs se créent et se modifient comme des enregistrements ordinaires (modules `MdsAcAllocationCycle`, `MdsAcAllocationKey`, `MdsAcStatIndicator`). Opération soumise à trois droits : lecture des cycles de répartition, compte de résultat analytique et accès à la société.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "organizationId", "required": true, "schema": { "type": "string" }, "example": "43x12", "description": "Identifiant de la société (`MdsOrganization`), au format webservice (`43x12`) ou numérique." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Objet `{organization_id, cycles, latest_batch_id}` ; chaque cycle porte `id`, `name`, `code`, `sequence`, `active`, `axis_id`, `axis_name`, `account_selection`, `sender_mode`, `sender_value_ids`, `period_mode`, `valid_from`, `valid_to`, `key`, `description`, `problems`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=analytic_closing_simulation": { "post": { "operationId": "analytic_closing_simulation", "tags": [ "Comptabilité analytique" ], "summary": "Simuler une répartition de clôture", "description": "Simule la répartition de clôture d'une société à la date `dateTo`, sans rien écrire. Pour chaque cycle : montant à répartir, montant déjà réparti plus tôt dans l'exercice, montant que la comptabilisation déplacerait, valeurs émettrices avec leurs montants, receveurs avec leur base (poids), pourcentage et montant, comptes concernés, avertissements (par exemple des quantités d'indicateur qui ne couvrent pas toute la période) et erreur à corriger le cas échéant.\n\n`postable` indique si `post_analytic_closing` réussirait. Les montants sont des chaînes décimales dans la devise comptable de la société. À présenter à l'utilisateur avant toute comptabilisation. Opération soumise à trois droits : lecture des cycles de répartition, compte de résultat analytique et accès à la société.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "Identifiant de la société (`MdsOrganization`), au format webservice (`43x12`) ou numérique.", "example": "43x12" }, "dateFrom": { "type": "string", "description": "Premier jour de la période de clôture, AAAA-MM-JJ. Les cycles périodiques répartissent à partir de ce jour ; les cycles cumulés partent toujours du début de l'exercice de `dateTo`.", "example": "2026-10-01" }, "dateTo": { "type": "string", "description": "Dernier jour de la période de clôture, AAAA-MM-JJ : la répartition est datée de ce jour et doit tomber dans une période comptable ouverte pour être comptabilisée.", "example": "2026-12-31" }, "cycleIdsJson": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array" }, "default": "[]", "description": "Texte JSON (liste). Liste facultative d'identifiants de cycles (`MdsAcAllocationCycle`, webservice ou numériques) à exécuter. Vide : tous les cycles actifs de la société, dans leur ordre.", "example": "[\"49x3\",\"49x4\"]" }, "replaceBatchId": { "type": "string", "default": "", "description": "Pour rejouer la dernière répartition : son `batch_id` issu de `analytic_closing_history`. Vide pour une nouvelle répartition.", "example": "12" } }, "required": [ "organizationId", "dateFrom", "dateTo" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Simulation par cycle, avec `postable`, les montants, receveurs, avertissements et erreurs ; `organization_id` et `replaced_batch_id` sont renvoyés." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=post_analytic_closing": { "post": { "operationId": "post_analytic_closing", "tags": [ "Comptabilité analytique" ], "summary": "Comptabiliser une répartition de clôture", "description": "Comptabilise la répartition de clôture simulée avec les mêmes arguments : des mouvements analytiques datés de `dateTo`, de somme nulle sur chaque compte, lus par tous les rapports analytiques. La comptabilité générale ne change pas. Retourne le lot avec ses receveurs et ses montants.\n\nRefusée dans les cas suivants : un cycle est en erreur, rien de nouveau ne serait déplacé, la période est close, ou le cycle est déjà réparti à cette date (utiliser `replaceBatchId` pour rejouer le dernier lot). Simuler d'abord avec `analytic_closing_simulation`. Exige en plus le droit d'édition des cycles de répartition.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "Identifiant de la société (`MdsOrganization`), au format webservice (`43x12`) ou numérique.", "example": "43x12" }, "dateFrom": { "type": "string", "description": "Premier jour de la période de clôture, AAAA-MM-JJ.", "example": "2026-10-01" }, "dateTo": { "type": "string", "description": "Dernier jour de la période de clôture, AAAA-MM-JJ : date des mouvements, dans une période comptable ouverte.", "example": "2026-12-31" }, "cycleIdsJson": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array" }, "default": "[]", "description": "Texte JSON (liste). Liste facultative d'identifiants de cycles (`MdsAcAllocationCycle`) à exécuter. Vide : tous les cycles actifs de la société.", "example": "[\"49x3\"]" }, "replaceBatchId": { "type": "string", "default": "", "description": "Pour rejouer la dernière répartition : son `batch_id` issu de `analytic_closing_history`. Vide pour une nouvelle répartition.", "example": "12" } }, "required": [ "organizationId", "dateFrom", "dateTo" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le lot comptabilisé : `batch_id`, `organization_id`, `posting_date`, `status`, `author`, `created`, `cancelled_by`, `cancelled` et `cycles` (par cycle : période lue, valeurs émettrices, receveurs avec base, pourcentage et montant, montant déplacé, avertissements)." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=analytic_closing_history": { "get": { "operationId": "analytic_closing_history", "tags": [ "Comptabilité analytique" ], "summary": "Historique des répartitions de clôture", "description": "Retourne les répartitions de clôture d'une société, de la plus récente à la plus ancienne : `batch_id`, date, statut (comptabilisée ou annulée), auteur, nombre de cycles, montant déplacé et `cancellable` (vrai pour le dernier lot, seul annulable ou rejouable).\n\n`latest_is_up_to_date` vaut false quand des écritures ont changé depuis la dernière répartition : la simuler de nouveau avec `replaceBatchId`. Opération soumise à trois droits : lecture des cycles de répartition, compte de résultat analytique et accès à la société.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "organizationId", "required": true, "schema": { "type": "string" }, "example": "43x12", "description": "Identifiant de la société (`MdsOrganization`), au format webservice (`43x12`) ou numérique." }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "string", "default": "20" }, "example": "20", "description": "Nombre de lots à retourner, de 1 à 100 (20 par défaut)." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Historique des lots.", "type": "object", "properties": { "organization_id": { "type": "string" }, "batches": { "type": "array", "items": { "type": "object", "properties": { "batch_id": { "type": "string" }, "posting_date": { "type": "string" }, "status": { "type": "string" }, "author": { "type": "string" }, "created": { "type": "string" }, "cancelled": { "type": "null" }, "cycles": { "type": "integer" }, "moved": { "type": "string" }, "cancellable": { "type": "boolean" } } } }, "latest_is_up_to_date": { "type": "boolean" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "organization_id": "43x12", "batches": [ { "batch_id": "12", "posting_date": "2026-12-31", "status": "posted", "author": "Marie Exemple", "created": "2027-01-05 09:30:00", "cancelled": null, "cycles": 2, "moved": "8450.00", "cancellable": true } ], "latest_is_up_to_date": true } } } } } } } }, "/webservice.php?operation=analytic_closing_batch": { "get": { "operationId": "analytic_closing_batch", "tags": [ "Comptabilité analytique" ], "summary": "Détail d'une répartition de clôture", "description": "Retourne une répartition de clôture : pour chaque cycle, la période lue, les valeurs émettrices, les receveurs avec leur base, leur pourcentage et leur montant, et les avertissements enregistrés à la comptabilisation. Sert à expliquer une répartition à un auditeur. Opération soumise à trois droits : lecture des cycles de répartition, compte de résultat analytique et accès à la société.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "batchId", "required": true, "schema": { "type": "string" }, "example": "12", "description": "Identifiant du lot (`batch_id`), tel que listé par `analytic_closing_history`." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le lot : `batch_id`, `organization_id`, `posting_date`, `status`, `author`, `created`, `cancelled_by`, `cancelled` et `cycles` (par cycle : `cycle_id`, `cycle_name`, `cycle_code`, `period_mode`, `range_from`, `range_to`, `moved`, `line_count`, `pool`, `already_allocated`, `senders`, `receivers`, `warnings`)." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=cancel_analytic_closing": { "post": { "operationId": "cancel_analytic_closing", "tags": [ "Comptabilité analytique" ], "summary": "Annuler la dernière répartition de clôture", "description": "Annule la dernière répartition de clôture de sa société tant que sa période comptable est ouverte. Les rapports analytiques reviennent aux montants d'avant ; le lot reste dans l'historique avec le statut annulé. Retourne le lot (même forme que `analytic_closing_batch`).\n\nSeul le dernier lot peut être annulé, car les répartitions cumulées suivantes se calculent à partir de lui. Exige en plus le droit d'édition des cycles de répartition.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "batchId": { "type": "string", "description": "`batch_id` du dernier lot de la société, issu de `analytic_closing_history`.", "example": "12" } }, "required": [ "batchId" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le lot annulé, avec `status` et les informations d'annulation (`cancelled_by`, `cancelled`)." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=analytic_indicator_quantities": { "get": { "operationId": "analytic_indicator_quantities", "tags": [ "Comptabilité analytique" ], "summary": "Lire les quantités d'un indicateur statistique", "description": "Retourne les quantités d'un indicateur statistique (ETP, m², heures ou montants à atteindre) saisies pour une société, par valeur de son axe et par période de l'année. Les quantités saisies sur d'autres périodes sont listées à part dans `other_entries`. L'utilisateur doit pouvoir lire l'indicateur, son axe et la société.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "indicatorId", "required": true, "schema": { "type": "string" }, "example": "50x2", "description": "Identifiant de l'indicateur statistique (`MdsAcStatIndicator`), au format webservice ou numérique." }, { "in": "query", "name": "organizationId", "required": true, "schema": { "type": "string" }, "example": "43x12", "description": "Identifiant de la société (`MdsOrganization`), au format webservice (`43x12`) ou numérique." }, { "in": "query", "name": "year", "required": true, "schema": { "type": "string" }, "example": "2026", "description": "Année civile, par exemple 2026." }, { "in": "query", "name": "granularity", "required": false, "schema": { "type": "string", "default": "quarter", "enum": [ "month", "quarter", "year" ] }, "example": "quarter", "description": "Colonnes de la grille : `month`, `quarter` (défaut) ou `year`." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Grille des quantités de l'indicateur.", "type": "object", "properties": { "indicator": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "unit": { "type": "string" }, "aggregation": { "type": "string" }, "axis_id": { "type": "string" } } }, "year": { "type": "integer" }, "granularity": { "type": "string" }, "periods": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" }, "label": { "type": "string" } } } }, "values": { "type": "array", "items": { "type": "object", "properties": { "value_id": { "type": "string" }, "code": { "type": "string" }, "label": { "type": "string" }, "active": { "type": "boolean" }, "quantities": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" }, "quantity": { "type": "string" } } } } } } }, "other_entries": { "type": "array" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "indicator": { "id": "50x2", "name": "ETP", "unit": "ETP", "aggregation": "average", "axis_id": "44x7" }, "year": 2026, "granularity": "quarter", "periods": [ { "start": "2026-01-01", "end": "2026-03-31", "label": "T1 2026" } ], "values": [ { "value_id": "45x101", "code": "CONSEIL", "label": "Conseil", "active": true, "quantities": [ { "start": "2026-01-01", "end": "2026-03-31", "quantity": "3.5" } ] } ], "other_entries": [] } } } } } } } }, "/webservice.php?operation=update_analytic_indicator_quantities": { "post": { "operationId": "update_analytic_indicator_quantities", "tags": [ "Comptabilité analytique" ], "summary": "Saisir les quantités d'un indicateur", "description": "Enregistre des quantités d'un indicateur statistique pour une société, par exemple les ETP de chaque activité pour un trimestre, puis retourne le nombre de quantités écrites.\n\n- Chaque élément porte `value_id` (valeur de l'axe de l'indicateur), `start` et `end` (AAAA-MM-JJ) et `quantity` (chaîne décimale ; chaîne vide pour supprimer la période de cette valeur).\n- Deux périodes d'une même valeur ne peuvent pas se chevaucher.\n- 2000 éléments au plus.\n- Droit d'édition sur l'indicateur exigé.\n\nLire d'abord la grille courante avec `analytic_indicator_quantities`.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "indicatorId": { "type": "string", "description": "Identifiant de l'indicateur statistique (`MdsAcStatIndicator`), au format webservice ou numérique.", "example": "50x2" }, "organizationId": { "type": "string", "description": "Identifiant de la société (`MdsOrganization`), au format webservice (`43x12`) ou numérique.", "example": "43x12" }, "quantitiesJson": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array" }, "description": "Texte JSON (liste). Liste de `{value_id, start, end, quantity}` : `value_id` de l'axe de l'indicateur, dates de période AAAA-MM-JJ, quantité en chaîne décimale (chaîne vide pour supprimer).", "example": "[{\"value_id\":\"45x101\",\"start\":\"2026-01-01\",\"end\":\"2026-03-31\",\"quantity\":\"3.5\"}]" } }, "required": [ "indicatorId", "organizationId", "quantitiesJson" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Résultat de l'écriture.", "type": "object", "properties": { "indicator_id": { "type": "string" }, "written": { "type": "integer" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "indicator_id": "50x2", "written": 1 } } } } } } } }, "/webservice.php?operation=update_analytic_cycle_senders": { "post": { "operationId": "update_analytic_cycle_senders", "tags": [ "Comptabilité analytique" ], "summary": "Remplacer les émetteurs d'un cycle de clôture", "description": "Remplace les valeurs émettrices d'un cycle de répartition de clôture, c'est-à-dire celles dont il répartit les montants. Retourne les valeurs enregistrées et les problèmes restants du cycle.\n\nLa liste contient des identifiants de valeurs de l'axe du cycle, et `unallocated` pour les montants sans valeur. Maximum 2000 éléments. Droit d'édition sur le cycle exigé.", "x-kafinea-access": "user", "x-kafinea-scope": "configure", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifiant du cycle de répartition (`MdsAcAllocationCycle`), au format webservice ou numérique.", "example": "49x3" }, "valueIdsJson": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array" }, "description": "Texte JSON (liste). Valeurs de l'axe du cycle dont il répartit les montants (identifiants webservice), et `unallocated` pour les montants sans valeur.", "example": "[\"45x101\",\"unallocated\"]" } }, "required": [ "id", "valueIdsJson" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Cycle mis à jour.", "type": "object", "properties": { "id": { "type": "string" }, "sender_value_ids": { "type": "array", "items": { "type": "string" } }, "problems": { "type": "array" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "id": "49x3", "sender_value_ids": [ "45x101", "unallocated" ], "problems": [] } } } } } } } }, "/webservice.php?operation=fixed_assets_overview": { "get": { "operationId": "fixed_assets_overview", "tags": [ "Immobilisations" ], "summary": "Synthèse du registre des immobilisations", "description": "Synthèse du registre d'une société : totaux à la date (valeur brute, amortissements, dépréciations, valeur nette comptable, amortissement dû mais non comptabilisé), nombre d'immobilisations par statut (`draft`, `active`, `disposed`, `scrapped`, entièrement amorties), catégories avec leurs comptes et leur plan par défaut, nombre de factures fournisseur comptabilisées sur un compte d'immobilisation et pas encore au registre (candidates), derniers lancements de comptabilisation (`runs`) et paramètres comptables.\n\nLes montants sont des entiers en centimes de la devise comptable de la société, les dates au format AAAA-MM-JJ. Point d'entrée recommandé avant les autres opérations du domaine.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "organizationId", "required": false, "schema": { "type": "string", "default": "" }, "example": "11x3", "description": "Société (`MdsOrganization`) concernée : identifiant complet (`11x3`) ou numérique. Par défaut, la société courante de l'utilisateur. Les écritures ne sont possibles que dans la société courante (erreur `FA_OTHER_COMPANY` sinon)." }, { "in": "query", "name": "date", "required": false, "schema": { "type": "string", "default": "" }, "example": "2026-12-31", "description": "Date des chiffres, au format AAAA-MM-JJ. Par défaut, aujourd'hui." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": [] } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=fixed_assets_list": { "get": { "operationId": "fixed_assets_list", "tags": [ "Immobilisations" ], "summary": "Lister les immobilisations du registre", "description": "Liste les immobilisations d'une société avec, à la date demandée : amortissement et dépréciation selon leur plan, valeur nette, date jusqu'à laquelle l'amortissement est comptabilisé (`postedThrough`), montant restant à comptabiliser (`toPost`), fin d'amortissement, avancement en pourcentage et, le cas échéant, le problème qui empêche le calcul (`issue`). Les totaux et les compteurs par statut sont fournis avec la liste.\n\nLes montants sont des entiers en centimes de la devise comptable de la société, les dates au format AAAA-MM-JJ.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "organizationId", "required": false, "schema": { "type": "string", "default": "" }, "example": "11x3", "description": "Société (`MdsOrganization`) concernée : identifiant complet (`11x3`) ou numérique. Par défaut, la société courante de l'utilisateur. Les écritures ne sont possibles que dans la société courante (erreur `FA_OTHER_COMPANY` sinon)." }, { "in": "query", "name": "date", "required": false, "schema": { "type": "string", "default": "" }, "example": "2026-12-31", "description": "Date des chiffres, au format AAAA-MM-JJ. Par défaut, aujourd'hui." }, { "in": "query", "name": "status", "required": false, "schema": { "type": "string", "default": "" }, "example": "draft,active", "description": "Statuts séparés par des virgules : `draft`, `active`, `disposed`, `scrapped`. Vide : tous." }, { "in": "query", "name": "categoryId", "required": false, "schema": { "type": "string", "default": "" }, "example": "78x4", "description": "Identifiant de la catégorie (`MdsAcFixedAssetCategory`). Vide : toutes." }, { "in": "query", "name": "search", "required": false, "schema": { "type": "string", "default": "" }, "example": "portable", "description": "Mots recherchés dans le nom, le numéro, le numéro de série ou l'emplacement." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Les immobilisations (`assets`), les totaux (`totals`) et les compteurs par statut (`counts`).", "type": "object", "properties": { "date": { "type": "string" }, "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "number": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "categoryId": { "type": "integer" }, "status": { "type": "string" }, "method": { "type": "string" }, "months": { "type": "integer" }, "acquisitionDate": { "type": "string" }, "serviceDate": { "type": "string" }, "value": { "type": "integer" }, "depreciation": { "type": "integer" }, "impairment": { "type": "integer" }, "netValue": { "type": "integer" }, "postedThrough": { "type": "string" }, "posted": { "type": "integer" }, "toPost": { "type": "integer" }, "endDate": { "type": "string" }, "fullyDepreciated": { "type": "boolean" }, "progress": { "type": "integer" }, "parentId": { "type": "null" }, "issue": { "type": "null" } } } }, "totals": { "type": "object", "properties": { "value": { "type": "integer" }, "depreciation": { "type": "integer" }, "impairment": { "type": "integer" }, "netValue": { "type": "integer" }, "toPost": { "type": "integer" } } }, "counts": { "type": "object", "properties": { "draft": { "type": "integer" }, "active": { "type": "integer" }, "disposed": { "type": "integer" }, "scrapped": { "type": "integer" }, "fullyDepreciated": { "type": "integer" }, "toPost": { "type": "integer" } } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "date": "2026-11-15", "assets": [ { "id": 12, "number": "IMM-0012", "name": "Ordinateur portable", "category": "Matériel informatique", "categoryId": 4, "status": "active", "method": "linear", "months": 36, "acquisitionDate": "2026-01-15", "serviceDate": "2026-01-15", "value": 120000, "depreciation": 36667, "impairment": 0, "netValue": 83333, "postedThrough": "2026-10-31", "posted": 30556, "toPost": 6111, "endDate": "2028-12-31", "fullyDepreciated": false, "progress": 31, "parentId": null, "issue": null } ], "totals": { "value": 120000, "depreciation": 36667, "impairment": 0, "netValue": 83333, "toPost": 6111 }, "counts": { "draft": 0, "active": 1, "disposed": 0, "scrapped": 0, "fullyDepreciated": 0, "toPost": 1 } } } } } } } } }, "/webservice.php?operation=fixed_asset_read": { "get": { "operationId": "fixed_asset_read", "tags": [ "Immobilisations" ], "summary": "Lire une immobilisation", "description": "Renvoie une immobilisation : ses champs (valeurs en centimes, méthode, durée, comptes, reprise, cession), son tableau d'amortissement par exercice (ouverture, dotation, dépréciation, clôture, valeur nette, dotation fiscale et amortissement dérogatoire), ses écritures (tranches d'amortissement, dépréciation, cession), ses révisions de plan et ses composants.\n\nLes montants sont des entiers en centimes de la devise comptable de la société, les dates au format AAAA-MM-JJ.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "assetId", "required": true, "schema": { "type": "string" }, "example": "77x12", "description": "Immobilisation (`MdsAcFixedAsset`) : identifiant complet ou numérique." }, { "in": "query", "name": "date", "required": false, "schema": { "type": "string", "default": "" }, "example": "2026-12-31", "description": "Date des chiffres, au format AAAA-MM-JJ. Par défaut, aujourd'hui." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le détail complet de l'immobilisation à la date demandée." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=fixed_asset_simulate": { "get": { "operationId": "fixed_asset_simulate", "tags": [ "Immobilisations" ], "summary": "Simuler un plan d'amortissement", "description": "Calcule un plan d'amortissement sans rien enregistrer, sur les exercices de la société : tableau par exercice et date de fin. Sert à montrer le résultat d'un plan avant de créer une immobilisation.\n\n- `linear` : amortissement linéaire à partir de la date de mise en service.\n- `declining` : dégressif fiscal français, durée minimale de 36 mois ; il démarre le premier jour du mois d'acquisition.\n- `none` : non amortissable.\n\nLorsque le plan fiscal diffère du plan comptable (`derogatory`), l'amortissement dérogatoire est calculé en plus.\n\nLes montants sont des entiers en centimes de la devise comptable de la société, les dates au format AAAA-MM-JJ. Les refus renvoient un code stable commençant par `FA_` (par exemple `FA_BAD_PARAMETER`, `FA_ACCESS_DENIED`) suivi de son explication.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "organizationId", "required": false, "schema": { "type": "string", "default": "" }, "example": "11x3", "description": "Société (`MdsOrganization`) concernée : identifiant complet (`11x3`) ou numérique. Par défaut, la société courante de l'utilisateur. Les écritures ne sont possibles que dans la société courante (erreur `FA_OTHER_COMPANY` sinon)." }, { "in": "query", "name": "value", "required": true, "schema": { "type": "integer" }, "example": 120000, "description": "Coût hors taxes, en centimes." }, { "in": "query", "name": "residual", "required": false, "schema": { "type": "integer", "default": 0 }, "example": 0, "description": "Valeur résiduelle non amortie, en centimes." }, { "in": "query", "name": "method", "required": false, "schema": { "type": "string", "default": "linear", "enum": [ "linear", "declining", "none" ] }, "example": "linear", "description": "`linear`, `declining` (dégressif fiscal, 36 mois minimum) ou `none`." }, { "in": "query", "name": "months", "required": false, "schema": { "type": "integer", "default": 0 }, "example": 36, "description": "Durée d'utilisation, en mois." }, { "in": "query", "name": "acquisitionDate", "required": true, "schema": { "type": "string" }, "example": "2026-01-15", "description": "Date d'acquisition, AAAA-MM-JJ." }, { "in": "query", "name": "serviceDate", "required": false, "schema": { "type": "string", "default": "" }, "example": "2026-02-01", "description": "Date de mise en service, AAAA-MM-JJ : début de l'amortissement linéaire. Par défaut, la date d'acquisition." }, { "in": "query", "name": "derogatory", "required": false, "schema": { "type": "string", "default": "" }, "example": "false", "description": "`true` lorsque le plan fiscal diffère du plan comptable." }, { "in": "query", "name": "fiscalMethod", "required": false, "schema": { "type": "string", "default": "" }, "example": "declining", "description": "Méthode fiscale si dérogatoire : `linear` ou `declining`." }, { "in": "query", "name": "fiscalMonths", "required": false, "schema": { "type": "integer", "default": 0 }, "example": 24, "description": "Durée fiscale en mois si dérogatoire." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le plan : tableau par exercice et date de fin d'amortissement." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=fixed_assets_candidates": { "get": { "operationId": "fixed_assets_candidates", "tags": [ "Immobilisations" ], "summary": "Lister les factures fournisseur à immobiliser", "description": "Liste les factures fournisseur (`MdsPayable`) comptabilisées sur un compte d'immobilisation (classe 2, hors comptes 26 à 29) pour un montant supérieur à celui des immobilisations déjà créées à partir d'elles. Pour chaque facture : `payableId`, numéro, fournisseur, date, compte, montant et montant restant, catégorie correspondant au compte, indicateur `lowValue` lorsque le reste est inférieur au seuil de faible valeur (la dépense peut alors être passée en charge), et lignes de la facture (`lineId`, article, montant, lien éventuel).\n\nSeules les factures que l'utilisateur a le droit de lire sont renvoyées. Les immobilisations se créent ensuite avec `fixed_asset_create_from_invoice`.\n\nLes montants sont des entiers en centimes de la devise comptable de la société, les dates au format AAAA-MM-JJ.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "organizationId", "required": false, "schema": { "type": "string", "default": "" }, "example": "11x3", "description": "Société (`MdsOrganization`) concernée : identifiant complet (`11x3`) ou numérique. Par défaut, la société courante de l'utilisateur. Les écritures ne sont possibles que dans la société courante (erreur `FA_OTHER_COMPANY` sinon)." }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "default": 50 }, "example": 50, "description": "Nombre maximal de factures renvoyées (50 par défaut)." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": [] } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=fixed_assets_report": { "get": { "operationId": "fixed_assets_report", "tags": [ "Immobilisations" ], "summary": "Obtenir un état des immobilisations", "description": "Chiffres des états d'immobilisations du centre de rapports, calculés à partir des plans du registre :\n\n- `register` : chaque immobilisation à la date `dateTo`.\n- `movements` : valeurs brutes et amortissements de la période par catégorie (ouverture, augmentations, diminutions, clôture), cadre des tableaux fiscaux 2054 et 2055.\n- `forecast` : dotations de l'exercice de `dateTo` et des quatre suivants.\n- `disposals` : immobilisations cédées ou mises au rebut sur la période, avec leur plus ou moins-value.\n- `reconciliation` : rapprochement du registre et du grand livre à `dateTo`, compte par compte ; il exige en plus le droit de lire les états comptables.\n\nUne valeur de `report` inconnue renvoie `FA_BAD_PARAMETER`. Les montants sont des entiers en centimes de la devise comptable de la société, les dates au format AAAA-MM-JJ.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "report", "required": true, "schema": { "type": "string", "enum": [ "register", "movements", "forecast", "disposals", "reconciliation" ] }, "example": "movements", "description": "Type d'état : `register`, `movements`, `forecast`, `disposals` ou `reconciliation`." }, { "in": "query", "name": "organizationId", "required": false, "schema": { "type": "string", "default": "" }, "example": "11x3", "description": "Société (`MdsOrganization`) concernée : identifiant complet (`11x3`) ou numérique. Par défaut, la société courante de l'utilisateur. Les écritures ne sont possibles que dans la société courante (erreur `FA_OTHER_COMPANY` sinon)." }, { "in": "query", "name": "dateFrom", "required": false, "schema": { "type": "string", "default": "" }, "example": "2026-01-01", "description": "Premier jour, AAAA-MM-JJ. Par défaut, le début de l'exercice de `dateTo`." }, { "in": "query", "name": "dateTo", "required": false, "schema": { "type": "string", "default": "" }, "example": "2026-12-31", "description": "Dernier jour, AAAA-MM-JJ. Par défaut, la fin de l'exercice courant." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": [] } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=fixed_assets_depreciation_preview": { "get": { "operationId": "fixed_assets_depreciation_preview", "tags": [ "Immobilisations" ], "summary": "Prévisualiser la comptabilisation des amortissements", "description": "Montre ce que produirait la comptabilisation des amortissements jusqu'à `dateTo`, sans rien écrire : pour chaque immobilisation en service, les tranches à partir du lendemain de la dernière comptabilisation (une par exercice, jamais à cheval sur une fin d'exercice) avec amortissement et amortissement dérogatoire, les totaux, le débit et le crédit par compte, et les immobilisations écartées avec la raison (exercice clos, compte manquant, plan incomplet...).\n\nLes montants sont des entiers en centimes de la devise comptable de la société, les dates au format AAAA-MM-JJ.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "organizationId", "required": false, "schema": { "type": "string", "default": "" }, "example": "11x3", "description": "Société (`MdsOrganization`) concernée : identifiant complet (`11x3`) ou numérique. Par défaut, la société courante de l'utilisateur. Les écritures ne sont possibles que dans la société courante (erreur `FA_OTHER_COMPANY` sinon)." }, { "in": "query", "name": "dateTo", "required": true, "schema": { "type": "string" }, "example": "2026-11-30", "description": "Comptabiliser jusqu'à ce jour inclus, AAAA-MM-JJ (en général une fin de mois ou d'exercice)." }, { "in": "query", "name": "assetIds", "required": false, "schema": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array" }, "default": "[]" }, "example": "[\"77x12\",\"77x13\"]", "description": "Texte JSON (liste). Liste facultative d'identifiants d'immobilisations auxquelles limiter l'aperçu. Vide : toutes les immobilisations en service." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": [] } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=fixed_assets_depreciation_post": { "post": { "operationId": "fixed_assets_depreciation_post", "tags": [ "Immobilisations" ], "summary": "Comptabiliser les amortissements", "description": "Comptabilise les amortissements aperçus avec les mêmes arguments dans le journal des opérations diverses, une écriture par immobilisation et par tranche, l'immobilisation servant de pièce (dotation 6811 / 28, et 6872 / 145 ou 145 / 7872 pour l'amortissement dérogatoire). Les immobilisations en difficulté sont laissées de côté et listées dans la réponse. L'opération est refusée lorsque rien n'est dû.\n\nLa réponse contient l'identifiant du lancement, annulable tant qu'il est le dernier de la société et que ses exercices sont ouverts (`fixed_assets_run_cancel`). L'écriture ne se fait que dans la société courante. Les montants sont des entiers en centimes de la devise comptable de la société, les dates au format AAAA-MM-JJ. Les refus renvoient un code stable commençant par `FA_` (par exemple `FA_BAD_PARAMETER`, `FA_ACCESS_DENIED`) suivi de son explication.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "organizationId": { "type": "string", "default": "", "description": "Société (`MdsOrganization`) concernée : identifiant complet (`11x3`) ou numérique. Par défaut, la société courante de l'utilisateur. Les écritures ne sont possibles que dans la société courante (erreur `FA_OTHER_COMPANY` sinon).", "example": "11x3" }, "dateTo": { "type": "string", "description": "Comptabiliser jusqu'à ce jour inclus, AAAA-MM-JJ.", "example": "2026-11-30" }, "assetIds": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array" }, "default": "[]", "description": "Texte JSON (liste). Liste facultative d'identifiants d'immobilisations. Vide : toutes les immobilisations en service.", "example": "[\"77x12\"]" } }, "required": [ "dateTo" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le lancement créé (identifiant, totaux, écritures par compte) et les immobilisations écartées avec leur motif." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=fixed_assets_run_cancel": { "post": { "operationId": "fixed_assets_run_cancel", "tags": [ "Immobilisations" ], "summary": "Annuler le dernier lancement de comptabilisation", "description": "Annule le dernier lancement de comptabilisation de la société : ses lignes d'écriture sont supprimées ; pour une cession, l'immobilisation est remise en service ; pour une dépréciation, la révision correspondante est retirée.\n\nL'opération est refusée pour un lancement plus ancien que le dernier ou lorsqu'un exercice concerné est clos. Elle ne s'applique qu'à la société courante.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "organizationId": { "type": "string", "default": "", "description": "Société (`MdsOrganization`) concernée : identifiant complet (`11x3`) ou numérique. Par défaut, la société courante de l'utilisateur. Les écritures ne sont possibles que dans la société courante (erreur `FA_OTHER_COMPANY` sinon).", "example": "11x3" }, "runId": { "type": "string", "description": "Identifiant du lancement, tel que listé dans `runs` de `fixed_assets_overview`.", "example": "15" } }, "required": [ "runId" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": [] } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=fixed_asset_create": { "post": { "operationId": "fixed_asset_create", "tags": [ "Immobilisations" ], "summary": "Créer une immobilisation", "description": "Crée une immobilisation au registre. Un brouillon ne calcule ni ne comptabilise rien ; une immobilisation en service est amortie par les prochaines comptabilisations. L'acquisition elle-même n'est jamais comptabilisée par le registre : elle provient de la facture fournisseur, ou des à-nouveaux pour une immobilisation ancienne. Il est conseillé de montrer d'abord le plan avec `fixed_asset_simulate`.\n\nClés de `fields` (montants en centimes) : `name`, `categoryId`, `value`, `acquisitionDate`, `serviceDate`, `method` (`linear`, `declining`, `none`), `months`, `residual`, `derogatory`, `fiscalMethod`, `fiscalMonths`, `serialNumber`, `location`, `vendorId`, `productId`, `equipmentId`, `parentId` (composant de), `description`, et `priorDate` avec `priorAccounting` et `priorFiscal` (amortissement déjà constaté avant la tenue de la comptabilité dans l'ERP, en général à la fin de l'exercice précédant le premier exercice tenu ici). La méthode et la durée prennent par défaut celles de la catégorie.\n\nL'immobilisation se crée dans la société courante. Les refus renvoient un code stable commençant par `FA_` (par exemple `FA_BAD_PARAMETER`, `FA_ACCESS_DENIED`) suivi de son explication.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "organizationId": { "type": "string", "default": "", "description": "Société (`MdsOrganization`) concernée : identifiant complet (`11x3`) ou numérique. Par défaut, la société courante de l'utilisateur. Les écritures ne sont possibles que dans la société courante (erreur `FA_OTHER_COMPANY` sinon).", "example": "11x3" }, "fields": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "description": "Texte JSON (objet). Champs de l'immobilisation, listés dans la description de l'opération. Les montants sont en centimes.", "example": "{\"name\":\"Ordinateur portable\",\"categoryId\":\"78x4\",\"value\":120000,\"acquisitionDate\":\"2026-01-15\",\"method\":\"linear\",\"months\":36}" }, "activate": { "type": "string", "default": "", "description": "`true` pour mettre l'immobilisation en service immédiatement (elle doit alors être complète) ; sinon un brouillon est créé.", "example": "false" } }, "required": [ "fields" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "L'immobilisation créée : `assetId` (identifiant complet) suivi de son détail, identique à celui de `fixed_asset_read`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=fixed_asset_create_from_invoice": { "post": { "operationId": "fixed_asset_create_from_invoice", "tags": [ "Immobilisations" ], "summary": "Créer une immobilisation depuis une facture fournisseur", "description": "Crée l'immobilisation d'une ligne de facture fournisseur, ou du reste de la facture sur un compte d'immobilisation. Le nom, la valeur hors taxes dans la devise de la société, la date d'acquisition, le fournisseur, l'article et la catégorie sont proposés à partir de la facture ; les valeurs données dans `fields` prévalent. Les factures candidates sont listées par `fixed_assets_candidates`.\n\nL'immobilisation se crée dans la société courante. Les refus renvoient un code stable commençant par `FA_` (par exemple `FA_BAD_PARAMETER`, `FA_ACCESS_DENIED`) suivi de son explication.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "organizationId": { "type": "string", "default": "", "description": "Société (`MdsOrganization`) concernée : identifiant complet (`11x3`) ou numérique. Par défaut, la société courante de l'utilisateur. Les écritures ne sont possibles que dans la société courante (erreur `FA_OTHER_COMPANY` sinon).", "example": "11x3" }, "payableId": { "type": "string", "description": "Facture fournisseur (`MdsPayable`) issue de `fixed_assets_candidates`.", "example": "45x310" }, "lineId": { "type": "string", "default": "", "description": "Ligne de facture (`lineId`) à immobiliser. Vide : le montant restant du compte.", "example": "2" }, "account": { "type": "string", "default": "", "description": "Compte d'immobilisation du candidat, utilisé pour proposer la catégorie.", "example": "2183" }, "fields": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "default": "[]", "description": "Texte JSON (objet). Valeurs qui remplacent celles proposées (mêmes clés que `fixed_asset_create`) : nom, catégorie, valeur, dates, durée...", "example": "{\"name\":\"Serveur\",\"months\":60}" }, "activate": { "type": "string", "default": "", "description": "`true` pour mettre l'immobilisation en service immédiatement.", "example": "false" } }, "required": [ "payableId" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "L'immobilisation créée : `assetId` suivi de son détail, identique à celui de `fixed_asset_read`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=fixed_asset_activate": { "post": { "operationId": "fixed_asset_activate", "tags": [ "Immobilisations" ], "summary": "Mettre une immobilisation en service", "description": "Fait passer un brouillon en service. Il doit avoir une catégorie, une valeur, une date d'acquisition, une durée (sauf s'il n'est pas amortissable) et ses comptes, et son plan doit pouvoir être calculé. La date de mise en service est par défaut la date d'acquisition. Les refus renvoient un code stable commençant par `FA_` (par exemple `FA_BAD_PARAMETER`, `FA_ACCESS_DENIED`) suivi de son explication.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "assetId": { "type": "string", "description": "Immobilisation (`MdsAcFixedAsset`) : identifiant complet ou numérique.", "example": "77x12" } }, "required": [ "assetId" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": [] } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=fixed_asset_disposal_preview": { "get": { "operationId": "fixed_asset_disposal_preview", "tags": [ "Immobilisations" ], "summary": "Prévisualiser une cession ou une mise au rebut", "description": "Montre ce que comptabiliserait la vente ou la mise au rebut d'une immobilisation, sans rien écrire : amortissement jusqu'à la date, sortie du bilan (valeur brute, amortissements, valeur nette comptable sur le compte de valeur comptable des éléments cédés : 657 pour les exercices ouverts depuis le 1er janvier 2025 sous le plan comptable révisé, sinon 675), produit sur 462 et 757/775 lorsqu'aucune facture de vente ne le porte, reprise de l'amortissement dérogatoire restant, plus ou moins-value.\n\nLes montants sont des entiers en centimes de la devise comptable de la société, les dates au format AAAA-MM-JJ.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "assetId", "required": true, "schema": { "type": "string" }, "example": "77x12", "description": "Immobilisation (`MdsAcFixedAsset`) : identifiant complet ou numérique." }, { "in": "query", "name": "date", "required": true, "schema": { "type": "string" }, "example": "2026-11-30", "description": "Date de cession, AAAA-MM-JJ." }, { "in": "query", "name": "type", "required": false, "schema": { "type": "string", "default": "sale", "enum": [ "sale", "scrap" ] }, "example": "sale", "description": "`sale` (vente) ou `scrap` (mise au rebut)." }, { "in": "query", "name": "price", "required": false, "schema": { "type": "integer", "default": 0 }, "example": 50000, "description": "Prix de vente hors taxes, en centimes." }, { "in": "query", "name": "invoiceId", "required": false, "schema": { "type": "string", "default": "" }, "example": "7x2045", "description": "Facture de vente (`Invoice`) qui porte le prix, le cas échéant." }, { "in": "query", "name": "invoiced", "required": false, "schema": { "type": "string", "default": "" }, "example": "false", "description": "`true` lorsque la vente est facturée dans l'ERP : le registre ne comptabilise alors pas le produit." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": [] } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=fixed_asset_dispose": { "post": { "operationId": "fixed_asset_dispose", "tags": [ "Immobilisations" ], "summary": "Céder ou mettre au rebut une immobilisation", "description": "Vend ou met au rebut une immobilisation comme l'aperçu de `fixed_asset_disposal_preview` avec les mêmes arguments, et la comptabilise : l'immobilisation sort du registre (statut `disposed` ou `scrapped`). La plus ou moins-value figure dans l'aperçu, à vérifier avant de lancer cette opération. L'opération est annulable via `fixed_assets_run_cancel` tant que le lancement est le dernier de la société.\n\nLes montants sont des entiers en centimes de la devise comptable de la société, les dates au format AAAA-MM-JJ. Les refus renvoient un code stable commençant par `FA_` (par exemple `FA_BAD_PARAMETER`, `FA_ACCESS_DENIED`) suivi de son explication.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "assetId": { "type": "string", "description": "Immobilisation (`MdsAcFixedAsset`) : identifiant complet ou numérique.", "example": "77x12" }, "date": { "type": "string", "description": "Date de cession, AAAA-MM-JJ.", "example": "2026-11-30" }, "type": { "type": "string", "default": "sale", "enum": [ "sale", "scrap" ], "description": "`sale` (vente) ou `scrap` (mise au rebut).", "example": "sale" }, "price": { "type": "integer", "default": 0, "description": "Prix de vente hors taxes, en centimes.", "example": 50000 }, "invoiceId": { "type": "string", "default": "", "description": "Facture de vente (`Invoice`) qui porte le prix, le cas échéant.", "example": "7x2045" }, "invoiced": { "type": "string", "default": "", "description": "`true` lorsque la vente est facturée dans l'ERP.", "example": "false" } }, "required": [ "assetId", "date" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": [] } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=fixed_asset_revision_preview": { "get": { "operationId": "fixed_asset_revision_preview", "tags": [ "Immobilisations" ], "summary": "Prévisualiser une révision de plan", "description": "Montre ce que changerait une révision de plan, sans rien écrire : fin d'amortissement avant et après, les deux tableaux, et l'écriture de dépréciation éventuelle. Une révision est prospective : l'amortissement passé est conservé et la valeur amortissable restante est étalée de façon linéaire sur la durée restante.\n\nLes montants sont des entiers en centimes de la devise comptable de la société, les dates au format AAAA-MM-JJ.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "assetId", "required": true, "schema": { "type": "string" }, "example": "77x12", "description": "Immobilisation (`MdsAcFixedAsset`) : identifiant complet ou numérique." }, { "in": "query", "name": "date", "required": true, "schema": { "type": "string" }, "example": "2026-11-30", "description": "Date de révision, AAAA-MM-JJ : le nouveau plan s'applique à partir du lendemain." }, { "in": "query", "name": "months", "required": false, "schema": { "type": "string", "default": "" }, "example": 24, "description": "Nouvelle durée d'utilisation restante en mois, à partir du lendemain. Vide : inchangée." }, { "in": "query", "name": "residual", "required": false, "schema": { "type": "string", "default": "" }, "example": 0, "description": "Nouvelle valeur résiduelle, en centimes. Vide : inchangée." }, { "in": "query", "name": "impairment", "required": false, "schema": { "type": "integer", "default": 0 }, "example": 10000, "description": "Dépréciation en centimes (négative pour en reprendre une)." }, { "in": "query", "name": "reason", "required": false, "schema": { "type": "string", "default": "" }, "example": "Obsolescence", "description": "Motif, conservé avec la révision." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": [] } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=fixed_asset_revise": { "post": { "operationId": "fixed_asset_revise", "tags": [ "Immobilisations" ], "summary": "Réviser le plan d'une immobilisation", "description": "Applique la révision de plan aperçue avec les mêmes arguments. Une dépréciation est comptabilisée (6816 / 29, ou 29 / 7816 pour une reprise). La révision est refusée avant la date jusqu'à laquelle l'amortissement est déjà comptabilisé. Elle s'écrit dans la société courante.\n\nLes montants sont des entiers en centimes de la devise comptable de la société, les dates au format AAAA-MM-JJ. Les refus renvoient un code stable commençant par `FA_` (par exemple `FA_BAD_PARAMETER`, `FA_ACCESS_DENIED`) suivi de son explication.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "assetId": { "type": "string", "description": "Immobilisation (`MdsAcFixedAsset`) : identifiant complet ou numérique.", "example": "77x12" }, "date": { "type": "string", "description": "Date de révision, AAAA-MM-JJ.", "example": "2026-11-30" }, "months": { "type": "string", "default": "", "description": "Nouvelle durée restante en mois. Vide : inchangée.", "example": 24 }, "residual": { "type": "string", "default": "", "description": "Nouvelle valeur résiduelle en centimes. Vide : inchangée.", "example": 0 }, "impairment": { "type": "integer", "default": 0, "description": "Dépréciation en centimes (négative pour en reprendre une).", "example": 10000 }, "reason": { "type": "string", "default": "", "description": "Motif de la révision.", "example": "Obsolescence" } }, "required": [ "assetId", "date" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": [] } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=fixed_asset_categories_seed": { "post": { "operationId": "fixed_asset_categories_seed", "tags": [ "Immobilisations" ], "summary": "Créer les catégories d'immobilisations usuelles", "description": "Crée les catégories usuelles du plan comptable français qui manquent (logiciels, véhicules, matériel informatique, mobilier, constructions...), avec leurs comptes (créés dans le plan comptable s'ils manquent), leur méthode et leur durée habituelle. Les catégories existantes sont conservées. La réponse liste les catégories et comptes créés, ainsi que toutes les catégories.\n\nL'utilisateur doit être autorisé à configurer les catégories d'immobilisations et, pour créer les comptes, à créer des comptes.", "x-kafinea-access": "user", "x-kafinea-scope": "configure", "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Les noms de catégories et les comptes créés, et la liste de toutes les catégories (`categories`)." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=fixed_assets_settings_update": { "post": { "operationId": "fixed_assets_settings_update", "tags": [ "Immobilisations" ], "summary": "Modifier les paramètres comptables des immobilisations", "description": "Modifie les paramètres comptables des immobilisations de l'instance. Seules les clés données changent ; les valeurs actuelles figurent dans `settings` de `fixed_assets_overview`.\n\nClés de `settings` : `basis` (`360` ou `actual`), `expense_account`, `derogatory_account`, `derogatory_expense_account`, `derogatory_income_account`, `impairment_expense_account`, `impairment_income_account`, `receivable_account`, `disposal_cost_account`, `disposal_income_account`, `former_disposal_cost_account`, `former_disposal_income_account`, `chart_switch_date` (les exercices ouverts à partir de cette date utilisent les comptes de cession, les précédents les anciens comptes), `low_value_threshold` (en unités de la devise). Une valeur invalide renvoie `FA_SETTING_INVALID`.", "x-kafinea-access": "user", "x-kafinea-scope": "configure", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "settings": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "description": "Texte JSON (objet). Clés à modifier, listées dans la description de l'opération.", "example": "{\"basis\":\"360\",\"low_value_threshold\":500}" } }, "required": [ "settings" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Les paramètres après modification." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=expense_context": { "get": { "operationId": "expense_context", "tags": [ "Notes de frais" ], "summary": "Obtenir le contexte de saisie des notes de frais", "description": "Renvoie ce dont l'utilisateur connecté a besoin avant de saisir des dépenses :\n\n- sa fiche personne (`null` lorsque son utilisateur n'est lié à aucune personne) ;\n- l'identifiant de sa note de frais ouverte (`currentReportId`) et ce que serait une nouvelle note (`currentPeriod`, `currentPeriodSubject`) ;\n- le regroupement des dépenses (`grouping` : `mode` `MONTH`, `WEEK`, `TRIP` ou `EXPENSE`, `byProject`, `autoSubmit`, `delayDays`), avec les projets ouverts à utiliser lors d'un regroupement par projet ;\n- ses notes de frais et ses véhicules ;\n- les catégories actives et leurs règles (type `REAL`, `MILEAGE` ou `ALLOWANCE`, règle de TVA, plafond, seuil de justificatif) ;\n- la disponibilité de la lecture des justificatifs par l'IA ;\n- ses droits (`can` : gérer les notes des autres, rembourser, configurer) et le nombre de notes à approuver et à rembourser.\n\nIl est conseillé de l'appeler avant `expense_add`.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le contexte décrit ci-dessus (`person`, `currentReportId`, `grouping`, `categories`, `vehicles`, `can`, `counts`...)." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=expense_report_list": { "get": { "operationId": "expense_report_list", "tags": [ "Notes de frais" ], "summary": "Lister les notes de frais", "description": "Liste les notes de frais sous forme de synthèses, selon la boîte demandée :\n\n- `mine` : celles de la personne de l'utilisateur connecté ;\n- `to_approve` : celles qui attendent son approbation ;\n- `to_reimburse` : celles qui sont approuvées avec un solde, avec le contrôle de l'IBAN de chaque personne (réservé à la comptabilité) ;\n- `all` : toutes celles que l'utilisateur peut voir.\n\nChaque synthèse indique le statut, le total, le montant payé, le solde, l'état du remboursement (`none`, `pending`, `partial`, `full`), le nombre de dépenses, de dépenses signalées et de justificatifs en cours de lecture.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "box", "required": false, "schema": { "type": "string", "enum": [ "mine", "to_approve", "to_reimburse", "all" ], "default": "mine" }, "example": "to_approve", "description": "Boîte à lister : `mine` (par défaut), `to_approve`, `to_reimburse` ou `all`." }, { "in": "query", "name": "personId", "required": false, "schema": { "type": "string" }, "example": "12x8", "description": "Avec `box` à `all` : les notes d'une seule personne (identifiant complet)." }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "default": 50 }, "example": 50, "description": "Nombre maximal de notes renvoyées (50 par défaut, 200 au plus)." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Les synthèses de notes de frais dans `reports`.", "type": "object", "properties": { "reports": { "type": "array", "items": { "type": "object", "properties": { "reportId": { "type": "string" }, "number": { "type": "string" }, "subject": { "type": "string" }, "period": { "type": "object", "properties": { "grouping": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" } } }, "month": { "type": "string" }, "projectId": { "type": "null" }, "projectName": { "type": "null" }, "date": { "type": "string" }, "status": { "type": "string" }, "statusLabel": { "type": "string" }, "personId": { "type": "string" }, "personName": { "type": "string" }, "total": { "type": "number" }, "paid": { "type": "integer" }, "balance": { "type": "number" }, "reimbursement": { "type": "string" }, "legacy": { "type": "boolean" }, "autoSubmitAt": { "type": "null" }, "submittedOn": { "type": "string" }, "approvedOn": { "type": "string" }, "itemCount": { "type": "integer" }, "flaggedCount": { "type": "integer" }, "readingCount": { "type": "integer" }, "url": { "type": "string" } } } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "reports": [ { "reportId": "77x120", "number": "NDF-0120", "subject": "Notes de frais de novembre 2026", "period": { "grouping": "MONTH", "start": "2026-11-01", "end": "2026-11-30" }, "month": "2026-11", "projectId": null, "projectName": null, "date": "2026-11-01", "status": "EXPENSE_REPORT_SUBMITTED", "statusLabel": "Soumise", "personId": "12x8", "personName": "Camille Exemple", "total": 148.5, "paid": 0, "balance": 148.5, "reimbursement": "none", "legacy": false, "autoSubmitAt": null, "submittedOn": "2026-11-12", "approvedOn": "", "itemCount": 3, "flaggedCount": 1, "readingCount": 0, "url": "index.php?module=MdsAcExpenseReport&view=Expenses&record=120" } ] } } } } } } } }, "/webservice.php?operation=expense_report_read": { "get": { "operationId": "expense_report_read", "tags": [ "Notes de frais" ], "summary": "Lire une note de frais", "description": "Renvoie une note de frais avec ses dépenses (catégorie, date, commerçant, montant TTC, TVA par taux et TVA récupérable, justificatif, lecture du justificatif, décision de l'approbateur, alertes avec leur message), les totaux par catégorie, le total refusé, les commentaires des approbateurs, les étapes d'approbation lorsqu'un circuit s'applique, et ce que l'utilisateur connecté peut faire maintenant (`can` : modifier, soumettre, retirer, approuver, rembourser).\n\nUne note inconnue ou non visible renvoie `EXPENSE_REPORT_UNKNOWN`.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "recordId", "required": true, "schema": { "type": "string" }, "example": "77x120", "description": "Note de frais (identifiant complet ou numéro)." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "`report` (synthèse, avec `byCategory`, `refusedTotal`, `recoverableVat`), `items` (dépenses), `approval`, `comments` et `can`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=expense_add": { "post": { "operationId": "expense_add", "tags": [ "Notes de frais" ], "summary": "Ajouter une dépense", "description": "Ajoute une dépense pour l'utilisateur connecté (ou, pour un utilisateur qui gère les notes des autres, pour `personId`). Elle est rangée dans la note de frais ouverte de sa période, selon le regroupement choisi par l'administrateur (mois, semaine, déplacement ou une note par dépense ; une note par projet lorsque le regroupement est par projet : fournir `projectId`). La note est créée si elle n'existe pas.\n\nAvec un justificatif et sans autre champ, le justificatif est lu par l'IA et la dépense remplie à partir de lui (catégorie parmi les actives, date, montant, TVA par taux, commerçant, couverts). Les champs fournis ne sont jamais écrasés par la lecture. Désactiver la lecture avec `readReceipt` à `false`.\n\nPour `MILEAGE`, le montant vient du barème kilométrique daté et des kilomètres déjà parcourus dans l'année avec ce véhicule ; pour les forfaits, des montants forfaitaires datés.\n\nLa réponse contient la dépense avec ses alertes (plafond, justificatif manquant, doublon, dépense ancienne...) et la synthèse de la note. Un refus renvoie une erreur `EXPENSE_REFUSED` dont le message commence par un code stable (par exemple `EXPENSE_REPORT_LOCKED`, `EXPENSE_NOT_ADMIN`, `EXPENSE_REPORT_UNKNOWN`) suivi de son explication.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": false, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "category": { "type": "string", "description": "Code ou nom d'une catégorie active, parmi celles de `expense_context` (par exemple `MEAL`, `HOTEL`, `TRAIN`, `FUEL`, `MILEAGE`, `MEAL_ALLOWANCE`). Facultatif avec un justificatif : sa lecture propose la catégorie.", "example": "MEAL" }, "date": { "type": "string", "description": "Date de la dépense, AAAA-MM-JJ.", "example": "2026-11-10" }, "amount": { "type": "string", "description": "Montant payé toutes taxes comprises, avec un point décimal. Inutile pour `MILEAGE` et les forfaits, qui sont calculés.", "example": "27.20" }, "merchant": { "type": "string", "description": "Commerçant ou fournisseur de la dépense.", "example": "Restaurant Exemple" }, "description": { "type": "string", "description": "Objet de la dépense.", "example": "Déjeuner client Exemple" }, "vat": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array" }, "default": "[]", "description": "Texte JSON (liste). TVA figurant sur le justificatif, une entrée par taux. La catégorie détermine la part récupérable.", "example": "[{\"rate\":10,\"vat\":2.47}]" }, "km": { "type": "string", "description": "Catégorie `MILEAGE` : distance en km (aller simple si `roundTrip` vaut `true` sur un nouveau trajet ; distance totale lors d'une modification).", "example": "120" }, "roundTrip": { "type": "boolean", "default": false, "description": "Catégorie `MILEAGE` : `true` si la distance donnée est celle d'un aller simple, à doubler pour l'aller-retour.", "example": true }, "vehicleId": { "type": "string", "description": "Catégorie `MILEAGE` : un des véhicules de `expense_context`. Véhicule par défaut si vide.", "example": "5" }, "trip": { "type": "string", "description": "Catégorie `MILEAGE` : trajet et motif (départ, arrivée, client visité).", "example": "Lyon - Grenoble, visite client Exemple" }, "quantity": { "type": "string", "description": "Forfait : nombre de forfaits.", "example": "2" }, "guestCount": { "type": "string", "description": "Nombre de couverts d'un repas.", "example": "3" }, "guests": { "type": "string", "description": "Invités d'un repas : noms et sociétés.", "example": "Marie Exemple (Exemple SARL)" }, "projectId": { "type": "string", "description": "Projet concerné par la dépense (identifiant complet).", "example": "58x14" }, "paidByCompany": { "type": "boolean", "default": false, "description": "`true` si la dépense est réglée avec une carte de l'entreprise : elle est alors considérée comme justifiée et n'est pas remboursée.", "example": false }, "personId": { "type": "string", "description": "Réservé à l'utilisateur qui gère les notes des autres : la personne concernée (identifiant complet). Par défaut, la personne de l'utilisateur connecté.", "example": "12x8" }, "recordId": { "type": "string", "description": "Note de frais ouverte donnée. Par défaut, la note ouverte de la personne pour la période de la dépense, créée si elle manque.", "example": "77x120" }, "fileId": { "type": "string", "description": "Justificatif (photo ou PDF) déposé avec `file_upload`.", "example": "f3a9c1d2" }, "fileName": { "type": "string", "description": "Nom du fichier du justificatif. Par défaut, celui du fichier déposé.", "example": "ticket.jpg" }, "fileContents": { "type": "string", "description": "Justificatif encodé en base64, à la place de `fileId`. Un contenu invalide est refusé.", "example": "JVBERi0xLjQK..." }, "readReceipt": { "type": "boolean", "default": true, "description": "Lire le justificatif maintenant (quelques secondes) et remplir ce qui manque. `true` par défaut ; la lecture exige que la passerelle IA de l'instance soit configurée (`EXPENSE_AI_UNAVAILABLE` sinon).", "example": true } } } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "`item` (la dépense avec ses alertes) et `report` (synthèse de la note)." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=expense_update": { "post": { "operationId": "expense_update", "tags": [ "Notes de frais" ], "summary": "Modifier une dépense", "description": "Modifie une dépense d'une note ouverte (brouillon ou à corriger) : seuls les champs fournis changent. Une correction rouvre la décision de l'approbateur sur cette dépense. Lorsque `km` est fourni, il désigne la distance totale. Un refus renvoie une erreur `EXPENSE_REFUSED` dont le message commence par un code stable (par exemple `EXPENSE_REPORT_LOCKED`, `EXPENSE_NOT_ADMIN`, `EXPENSE_REPORT_UNKNOWN`) suivi de son explication.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "expenseId": { "type": "string", "description": "Identifiant (numéro) de la dépense, tel que renvoyé par `expense_report_read`.", "example": "4512" }, "category": { "type": "string", "description": "Code ou nom d'une catégorie active, parmi celles de `expense_context` (par exemple `MEAL`, `HOTEL`, `TRAIN`, `FUEL`, `MILEAGE`, `MEAL_ALLOWANCE`). Facultatif avec un justificatif : sa lecture propose la catégorie.", "example": "MEAL" }, "date": { "type": "string", "description": "Date de la dépense, AAAA-MM-JJ.", "example": "2026-11-10" }, "amount": { "type": "string", "description": "Montant payé toutes taxes comprises, avec un point décimal. Inutile pour `MILEAGE` et les forfaits, qui sont calculés.", "example": "27.20" }, "merchant": { "type": "string", "description": "Commerçant ou fournisseur de la dépense.", "example": "Restaurant Exemple" }, "description": { "type": "string", "description": "Objet de la dépense.", "example": "Déjeuner client Exemple" }, "vat": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array" }, "default": "[]", "description": "Texte JSON (liste). TVA figurant sur le justificatif, une entrée par taux. La catégorie détermine la part récupérable.", "example": "[{\"rate\":10,\"vat\":2.47}]" }, "km": { "type": "string", "description": "Catégorie `MILEAGE` : distance en km (aller simple si `roundTrip` vaut `true` sur un nouveau trajet ; distance totale lors d'une modification).", "example": "120" }, "roundTrip": { "type": "boolean", "default": false, "description": "Catégorie `MILEAGE` : `true` si la distance donnée est celle d'un aller simple, à doubler pour l'aller-retour.", "example": true }, "vehicleId": { "type": "string", "description": "Catégorie `MILEAGE` : un des véhicules de `expense_context`. Véhicule par défaut si vide.", "example": "5" }, "trip": { "type": "string", "description": "Catégorie `MILEAGE` : trajet et motif (départ, arrivée, client visité).", "example": "Lyon - Grenoble, visite client Exemple" }, "quantity": { "type": "string", "description": "Forfait : nombre de forfaits.", "example": "2" }, "guestCount": { "type": "string", "description": "Nombre de couverts d'un repas.", "example": "3" }, "guests": { "type": "string", "description": "Invités d'un repas : noms et sociétés.", "example": "Marie Exemple (Exemple SARL)" }, "projectId": { "type": "string", "description": "Projet concerné par la dépense (identifiant complet).", "example": "58x14" }, "paidByCompany": { "type": "boolean", "default": false, "description": "`true` si la dépense est réglée avec une carte de l'entreprise : elle est alors considérée comme justifiée et n'est pas remboursée.", "example": false }, "fileId": { "type": "string", "description": "Justificatif (photo ou PDF) déposé avec `file_upload`.", "example": "f3a9c1d2" }, "fileName": { "type": "string", "description": "Nom du fichier du justificatif. Par défaut, celui du fichier déposé.", "example": "ticket.jpg" }, "fileContents": { "type": "string", "description": "Justificatif encodé en base64, à la place de `fileId`. Un contenu invalide est refusé.", "example": "JVBERi0xLjQK..." } }, "required": [ "expenseId" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "`item` (la dépense avec ses alertes) et `report` (synthèse de la note)." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=expense_delete": { "post": { "operationId": "expense_delete", "tags": [ "Notes de frais" ], "summary": "Supprimer une dépense", "description": "Supprime une dépense d'une note ouverte (brouillon ou à corriger). Un refus renvoie une erreur `EXPENSE_REFUSED` dont le message commence par un code stable (par exemple `EXPENSE_REPORT_LOCKED`, `EXPENSE_NOT_ADMIN`, `EXPENSE_REPORT_UNKNOWN`) suivi de son explication.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "expenseId": { "type": "string", "description": "Identifiant (numéro) de la dépense.", "example": "4512" } }, "required": [ "expenseId" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "L'identifiant supprimé (`deleted`) et la synthèse de la note (`report`).", "type": "object", "properties": { "deleted": { "type": "integer" }, "report": { "type": "object", "properties": { "reportId": { "type": "string" }, "number": { "type": "string" }, "subject": { "type": "string" }, "period": { "type": "object", "properties": { "grouping": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" } } }, "month": { "type": "string" }, "projectId": { "type": "null" }, "projectName": { "type": "null" }, "date": { "type": "string" }, "status": { "type": "string" }, "statusLabel": { "type": "string" }, "personId": { "type": "string" }, "personName": { "type": "string" }, "total": { "type": "number" }, "paid": { "type": "integer" }, "balance": { "type": "number" }, "reimbursement": { "type": "string" }, "legacy": { "type": "boolean" }, "autoSubmitAt": { "type": "null" }, "submittedOn": { "type": "string" }, "approvedOn": { "type": "string" }, "itemCount": { "type": "integer" }, "flaggedCount": { "type": "integer" }, "readingCount": { "type": "integer" }, "url": { "type": "string" } } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "deleted": 4512, "report": { "reportId": "77x120", "number": "NDF-0120", "subject": "Notes de frais de novembre 2026", "period": { "grouping": "MONTH", "start": "2026-11-01", "end": "2026-11-30" }, "month": "2026-11", "projectId": null, "projectName": null, "date": "2026-11-01", "status": "EXPENSE_REPORT_SUBMITTED", "statusLabel": "Soumise", "personId": "12x8", "personName": "Camille Exemple", "total": 148.5, "paid": 0, "balance": 148.5, "reimbursement": "none", "legacy": false, "autoSubmitAt": null, "submittedOn": "2026-11-12", "approvedOn": "", "itemCount": 3, "flaggedCount": 1, "readingCount": 0, "url": "index.php?module=MdsAcExpenseReport&view=Expenses&record=120" } } } } } } } } }, "/webservice.php?operation=expense_receipt_read": { "post": { "operationId": "expense_receipt_read", "tags": [ "Notes de frais" ], "summary": "Lire le justificatif d'une dépense", "description": "Lit maintenant le justificatif d'une dépense avec l'IA (de nouveau après un échec) et remplit ce qui est encore vide. Renvoie `EXPENSE_AI_UNAVAILABLE` si la passerelle IA de l'instance n'est pas configurée.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "expenseId": { "type": "string", "description": "Identifiant (numéro) de la dépense.", "example": "4512" } }, "required": [ "expenseId" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La dépense (`item`), avec la lecture conservée dans `ai.proposal`, et la synthèse de la note (`report`)." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=expense_submit": { "post": { "operationId": "expense_submit", "tags": [ "Notes de frais" ], "summary": "Soumettre une note de frais", "description": "Soumet une note ouverte de l'utilisateur connecté. L'opération est refusée lorsqu'une dépense n'a pas sa catégorie, sa date ou son montant, ou lorsqu'un justificatif est encore en cours de lecture. Avec un circuit d'approbation actif, l'approbation est demandée et son premier approbateur prévenu ; sinon, le gestionnaire des notes de frais de la personne est prévenu. Il est conseillé de relire la note et ses alertes (`expense_report_read`) avant de soumettre. Un refus renvoie une erreur `EXPENSE_REFUSED` dont le message commence par un code stable (par exemple `EXPENSE_REPORT_LOCKED`, `EXPENSE_NOT_ADMIN`, `EXPENSE_REPORT_UNKNOWN`) suivi de son explication.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "recordId": { "type": "string", "description": "Note de frais à soumettre (identifiant complet ou numéro).", "example": "77x120" } }, "required": [ "recordId" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La note de frais après soumission, au format de `expense_report_read`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=expense_withdraw": { "post": { "operationId": "expense_withdraw", "tags": [ "Notes de frais" ], "summary": "Retirer une note de frais soumise", "description": "Reprend une note soumise sur laquelle personne n'a encore décidé (par son auteur ou un administrateur) : elle redevient un brouillon. Une note déjà décidée renvoie `EXPENSE_REPORT_NOT_WITHDRAWABLE`.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "recordId": { "type": "string", "description": "Note de frais soumise (identifiant complet ou numéro).", "example": "77x120" } }, "required": [ "recordId" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La note de frais après retrait, au format de `expense_report_read`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=expense_decide": { "post": { "operationId": "expense_decide", "tags": [ "Notes de frais" ], "summary": "Accepter ou refuser une dépense", "description": "L'approbateur de l'étape ouverte accepte ou refuse une dépense d'une note soumise. Les dépenses refusées sortent de la note, qui suit alors son approbation finale pour le reste. La décision est toujours celle de l'utilisateur connecté, qui ne peut pas décider de ses propres dépenses. Un refus exige un motif. Un refus renvoie une erreur `EXPENSE_REFUSED` dont le message commence par un code stable (par exemple `EXPENSE_REPORT_LOCKED`, `EXPENSE_NOT_ADMIN`, `EXPENSE_REPORT_UNKNOWN`) suivi de son explication.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "expenseId": { "type": "string", "description": "Identifiant (numéro) de la dépense.", "example": "4512" }, "decision": { "type": "string", "enum": [ "approve", "refuse" ], "description": "`approve` ou `refuse`.", "example": "refuse" }, "reason": { "type": "string", "description": "Obligatoire pour refuser : la personne concernée le lit.", "example": "Dépense personnelle" } }, "required": [ "expenseId", "decision" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La dépense après décision (`item`)." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=expense_answer": { "post": { "operationId": "expense_answer", "tags": [ "Notes de frais" ], "summary": "Répondre à une note de frais", "description": "L'approbateur répond pour la note entière :\n\n- `approve` : les dépenses non encore décidées sont acceptées ; à la dernière étape, la note est approuvée et comptabilisée ;\n- `changes` : la note est renvoyée à la personne pour correction ;\n- `refuse` : la note est refusée.\n\nPersonne ne répond pour ses propres dépenses. Les réponses `changes` et `refuse` exigent un motif. Une autre valeur renvoie `EXPENSE_ANSWER_INVALID`.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "recordId": { "type": "string", "description": "Note de frais concernée (identifiant complet ou numéro).", "example": "77x120" }, "answer": { "type": "string", "enum": [ "approve", "changes", "refuse" ], "description": "`approve`, `changes` ou `refuse`.", "example": "changes" }, "reason": { "type": "string", "description": "Obligatoire pour `changes` et `refuse` : la personne le lit.", "example": "Justificatif manquant sur l'hôtel" } }, "required": [ "recordId", "answer" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La note de frais après réponse, au format de `expense_report_read`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=expense_reimburse": { "post": { "operationId": "expense_reimburse", "tags": [ "Notes de frais" ], "summary": "Rembourser des notes de frais approuvées", "description": "Comptabilité : rembourse le solde de notes approuvées, avec un règlement salarié par personne, affecté à chaque note et comptabilisé (compte de la personne contre la banque). L'utilisateur doit avoir le droit de créer des règlements de salariés. Avec `sepa`, chaque personne doit avoir un compte bancaire valide et la société un compte bancaire par défaut : tout est vérifié avant toute écriture (`EXPENSE_IBAN_MISSING`, `EXPENSE_IBAN_INVALID`, `EXPENSE_COMPANY_BANK_MISSING`). Rien à rembourser renvoie `EXPENSE_NOTHING_TO_REIMBURSE`.\n\nLa réponse contient les règlements (`payments`), le total (`total`) et, avec `sepa`, le fichier de virement (`sepa`) dont le contenu (`sepa.content`) est encodé en base64. Un refus renvoie une erreur `EXPENSE_REFUSED` dont le message commence par un code stable (par exemple `EXPENSE_REPORT_LOCKED`, `EXPENSE_NOT_ADMIN`, `EXPENSE_REPORT_UNKNOWN`) suivi de son explication.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "recordIds": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array" }, "description": "Texte JSON (liste). Notes approuvées à rembourser (identifiants complets ou numéros).", "example": "[\"77x120\",\"77x121\"]" }, "paymentDate": { "type": "string", "description": "Date de paiement, AAAA-MM-JJ. Par défaut, aujourd'hui.", "example": "2026-11-30" }, "sepa": { "type": "boolean", "default": true, "description": "Construire le fichier de virement SEPA (pain.001.001.09), renvoyé en base64. `true` par défaut.", "example": true } }, "required": [ "recordIds" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "`payments`, `total` et `sepa` (fichier de virement, contenu en base64) ou `null` sans `sepa`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=expense_vehicle_save": { "post": { "operationId": "expense_vehicle_save", "tags": [ "Notes de frais" ], "summary": "Enregistrer un véhicule", "description": "Ajoute ou modifie un véhicule de la personne de l'utilisateur connecté. Il est nécessaire pour les indemnités kilométriques : la ligne du barème dépend de son type et de sa puissance fiscale, et un véhicule électrique bénéficie de la majoration du barème. Sans `vehicleId`, un véhicule est ajouté. Gérer le véhicule d'une autre personne exige le droit de gérer les notes des autres (`EXPENSE_NOT_YOURS` sinon).", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": false, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "vehicleId": { "type": "string", "description": "Identifiant du véhicule à modifier. Vide pour en ajouter un.", "example": "5" }, "label": { "type": "string", "description": "Libellé du véhicule.", "example": "Citadine de service" }, "vehicleType": { "type": "string", "enum": [ "CAR", "MOTORCYCLE", "MOPED" ], "default": "CAR", "description": "Type de véhicule : `CAR` (par défaut), `MOTORCYCLE` ou `MOPED`.", "example": "CAR" }, "fiscalPower": { "type": "string", "description": "Puissance fiscale en CV, telle qu'elle figure sur la carte grise.", "example": "5" }, "electric": { "type": "boolean", "default": false, "description": "`true` pour un véhicule électrique.", "example": false }, "isDefault": { "type": "boolean", "default": false, "description": "`true` pour en faire le véhicule par défaut.", "example": true }, "personId": { "type": "string", "description": "Pour un utilisateur qui gère les notes des autres : la personne concernée (identifiant complet).", "example": "12x8" } } } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le véhicule enregistré (`vehicle`) et la liste des véhicules de la personne (`vehicles`)." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=expense_settings": { "get": { "operationId": "expense_settings", "tags": [ "Notes de frais" ], "summary": "Lire la configuration des notes de frais", "description": "Administrateur : renvoie toutes les catégories de dépenses (actives ou non) avec leurs règles, les barèmes datés (kilométriques par type de véhicule et puissance, forfaits repas), les barèmes de forfait qu'une catégorie peut utiliser, et le regroupement des dépenses (`grouping`). Un non-administrateur reçoit `EXPENSE_NOT_ADMIN`.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "read", "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "`categories`, `scales`, `allowanceScales` et `grouping`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=expense_grouping_save": { "post": { "operationId": "expense_grouping_save", "tags": [ "Notes de frais" ], "summary": "Configurer le regroupement des notes de frais", "description": "Administrateur : règle la façon dont les dépenses sont regroupées en notes de frais et si les brouillons sont soumis automatiquement. Seules les valeurs fournies changent. Les brouillons existants gardent leur regroupement. Un non-administrateur reçoit `EXPENSE_NOT_ADMIN`.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "configure", "requestBody": { "required": false, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "MONTH", "WEEK", "TRIP", "EXPENSE" ], "description": "`MONTH` : une note par mois civil (par défaut). `WEEK` : une note par semaine, du lundi au dimanche. `TRIP` : le brouillon ouvert reçoit toutes les dépenses jusqu'à sa soumission. `EXPENSE` : une note par dépense.", "example": "MONTH" }, "byProject": { "type": "boolean", "description": "Une note par projet sur la période ; le projet de la dépense devient celui de la note.", "example": false }, "autoSubmit": { "type": "boolean", "description": "Les brouillons jamais soumis partent d'eux-mêmes en approbation une fois échus, la personne étant prévenue la veille ; un brouillon incomplet reste brouillon.", "example": true }, "delayDays": { "type": "string", "description": "De 0 à 30 : jours après la fin de la période (après la dernière modification pour un déplacement ou une dépense seule) avant la soumission automatique. 2 par défaut.", "example": 2 } } } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La configuration après modification, au format de `expense_settings`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=expense_category_save": { "post": { "operationId": "expense_category_save", "tags": [ "Notes de frais" ], "summary": "Créer ou modifier une catégorie de dépenses", "description": "Administrateur : crée ou modifie une catégorie de dépenses. Une catégorie utilisée est désactivée, jamais supprimée. Une nouvelle catégorie reçoit son propre article, comptabilisé comme un achat ordinaire.\n\nClés de `category` : `categoryid` (pour en modifier une ; vide pour créer), `label`, `kind` (`REAL` ou `ALLOWANCE`), `vatrule` (`RECOVERABLE`, `PARTIAL` avec `vatratio`, `NON_RECOVERABLE`), `ceilingamount` et `ceilingunit` (`EXPENSE`, `DAY`, `GUEST`), `receiptthreshold` (vide : justificatif jamais exigé), `requireguests`, `scalecode` pour un forfait, `keywords` (mots de commerçant qui rangent un justificatif dans la catégorie), `active`. Un non-administrateur reçoit `EXPENSE_NOT_ADMIN`.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "configure", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "category": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "description": "Texte JSON (objet). Catégorie à créer ou modifier, avec les clés listées dans la description de l'opération.", "example": "{\"label\":\"Parking\",\"kind\":\"REAL\",\"vatrule\":\"RECOVERABLE\",\"ceilingamount\":30,\"ceilingunit\":\"DAY\",\"receiptthreshold\":10,\"active\":true}" } }, "required": [ "category" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La configuration après modification, au format de `expense_settings`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=expense_scale_save": { "post": { "operationId": "expense_scale_save", "tags": [ "Notes de frais" ], "summary": "Ajouter une version de barème de frais", "description": "Administrateur : ajoute une version datée d'un barème (barème kilométrique d'une nouvelle année, forfait repas). Les dépenses antérieures gardent la version de leur date. Un non-administrateur reçoit `EXPENSE_NOT_ADMIN`.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "configure", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "scaleCode": { "type": "string", "enum": [ "MILEAGE_CAR", "MILEAGE_MOTORCYCLE", "MILEAGE_MOPED", "MEAL_WORKPLACE", "MEAL_OUTSIDE", "MEAL_TRAVEL" ], "description": "Barème : `MILEAGE_CAR`, `MILEAGE_MOTORCYCLE`, `MILEAGE_MOPED`, `MEAL_WORKPLACE`, `MEAL_OUTSIDE` ou `MEAL_TRAVEL`.", "example": "MEAL_OUTSIDE" }, "validFrom": { "type": "string", "description": "AAAA-MM-JJ : la version s'applique à partir de cette date, jusqu'à la suivante.", "example": "2027-01-01" }, "label": { "type": "string", "description": "Libellé de la version.", "example": "Forfait repas 2027" }, "data": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "description": "Texte JSON (objet). Forfait : `{\"amount\":21.4}`. Kilométrique : `{\"bands\":[5000,20000],\"powers\":{\"3\":[[0.529,0],[0.316,1065],[0.37,0]],...},\"electricBonusPercent\":20}`, chaque ligne étant indexée par la plus petite puissance qu'elle couvre.", "example": "{\"amount\":21.4}" }, "source": { "type": "string", "description": "Référence du barème publié.", "example": "Arrêté du 1er janvier 2027" } }, "required": [ "scaleCode", "validFrom", "data" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La configuration après modification, au format de `expense_settings`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=approval_circuit_read": { "get": { "operationId": "approval_circuit_read", "tags": [ "Approbations" ], "summary": "Lire les circuits d'approbation", "description": "Lit les circuits d'approbation (Réglages > Approbations) : pour chaque module, quels enregistrements doivent être approuvés (condition) et qui approuve, étape par étape, avec la révision du circuit, des textes lisibles et le contrat de la définition.\n\n- Sans `moduleName`, renvoie tous les circuits ainsi que les modules qui peuvent en avoir un.\n- Avec `moduleName`, renvoie le circuit de ce module (ou `null` s'il n'en a pas), le nombre de demandes en attente et les modèles de départ.\n\nLa `revision` renvoyée doit être transmise à `approval_circuit_configure` pour toute écriture. Cette opération ne demande ni ne répond à aucune approbation. Réservée aux administrateurs (`ACCESSDENIED` sinon). Un module qui ne peut pas avoir de circuit est refusé avec `APPROVAL_CIRCUIT_INVALID`.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "moduleName", "required": false, "schema": { "type": "string", "default": "" }, "example": "Invoice", "description": "Nom API du module dont on veut le circuit et les modèles de départ. Vide pour obtenir tous les circuits et la liste des modules concernés." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Pour un module : `featureEnabled`, `moduleName`, `circuit` (ou `null`), `templates` et `contract`. Sans module : `featureEnabled`, `circuits`, `approvableModules` et `contract`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=approval_circuit_configure": { "post": { "operationId": "approval_circuit_configure", "tags": [ "Approbations" ], "summary": "Configurer le circuit d'approbation d'un module", "description": "Configuration par un administrateur du circuit d'approbation d'un module, avec la même validation que l'écran Réglages > Approbations.\n\nActions possibles :\n\n- `validate` (par défaut) : n'écrit rien et liste les problèmes de la définition.\n- `save` : enregistre le circuit complet, avec la `revision` lue par `approval_circuit_read` (0 pour créer le circuit d'un module qui n'en a pas).\n- `activate` / `deactivate` : active ou désactive le circuit existant.\n- `delete` : supprime le circuit (les demandes déjà faites restent).\n\nUne écriture dont la révision n'est plus celle du circuit est refusée avec `APPROVAL_CIRCUIT_REVISION_CHANGED` : relisez le circuit puis recommencez. Une définition invalide est refusée avec `APPROVAL_CIRCUIT_INVALID`, les problèmes étant listés un par ligne dans le message. Testez le circuit avec `approval_circuit_simulate` avant de l'activer. Réservée aux administrateurs.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "configure", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "moduleName": { "type": "string", "description": "Nom API du module dont on configure le circuit.", "example": "Invoice" }, "action": { "type": "string", "enum": [ "validate", "save", "activate", "deactivate", "delete" ], "default": "validate", "description": "Action à effectuer : `validate`, `save`, `activate`, `deactivate` ou `delete`." }, "revision": { "type": "integer", "default": 0, "description": "Révision du circuit lue avec `approval_circuit_read`. 0 pour créer le circuit d'un module qui n'en a pas.", "example": 3 }, "definition": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "default": "[]", "description": "Texte JSON (objet). Circuit complet pour `validate` et `save`, tel que `approval_circuit_read` le renvoie (conservez le `stepId` de chaque étape). Vide pour `activate`, `deactivate` et `delete`.", "example": "{\"label\":\"Approbation des factures\",\"active\":true,\"condition\":[],\"steps\":[{\"label\":\"Responsable financier\",\"approver\":{\"mode\":\"fixed\",\"ownerId\":\"19x5\"},\"dueDays\":3}]}" } }, "required": [ "moduleName" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Pour `validate` : `valid`, `problems`, `circuit` et `saved` (faux). Pour `save`, `activate` et `deactivate` : `circuit` et `saved` (vrai). Pour `delete` : `deleted` et `moduleName`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=approval_circuit_simulate": { "get": { "operationId": "approval_circuit_simulate", "tags": [ "Approbations" ], "summary": "Simuler un circuit d'approbation", "description": "Simulation à blanc d'un circuit d'approbation sur des enregistrements existants : indique si la condition du circuit est remplie, puis, pour chaque étape applicable, son approbateur ou la raison pour laquelle personne ne peut répondre. Rien n'est enregistré, demandé ni envoyé.\n\n- Sans `definition`, simule le circuit enregistré du module (`APPROVAL_CIRCUIT_NOT_FOUND` s'il n'en a pas).\n- Avec `definition`, simule un brouillon non enregistré.\n- 1 à 20 enregistrements du module indiqué, lisibles par l'appelant.\n- `requesterId` permet de simuler la demande d'un autre utilisateur actif : l'approbateur « responsable hiérarchique » et la règle interdisant d'approuver sa propre demande en dépendent.\n\nRéservée aux administrateurs.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "moduleName", "required": true, "schema": { "type": "string" }, "example": "Invoice", "description": "Nom API du module des enregistrements simulés." }, { "in": "query", "name": "recordIds", "required": true, "schema": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array", "items": { "type": "string" } } }, "example": "[\"15x230\",\"15x231\"]", "description": "Texte JSON (liste). De 1 à 20 enregistrements du module (identifiants webservice)." }, { "in": "query", "name": "definition", "required": false, "schema": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "default": "[]" }, "example": "[]", "description": "Texte JSON (objet). Circuit non encore enregistré à tester. Vide pour utiliser le circuit enregistré." }, { "in": "query", "name": "requesterId", "required": false, "schema": { "type": "string", "default": "" }, "example": "19x5", "description": "Utilisateur qui ferait la demande (`19x5`). Vide pour l'appelant." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "`source` (`saved` ou `definition`), `active`, `requester`, `records` (pour chaque enregistrement : `recordId`, `label` et le détail des étapes applicables) et `notice`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=approval_inbox": { "get": { "operationId": "approval_inbox", "tags": [ "Approbations" ], "summary": "Lister les approbations de l'utilisateur", "description": "Liste les approbations de l'utilisateur connecté, comme le widget de la page d'accueil.\n\n- `toAnswer` : étapes en attente de sa réponse, directement ou via un groupe. Chaque étape porte son `lineId`, à transmettre à `approval_answer`.\n- `requested` : les demandes qu'il a faites.\n- `others` : les autres demandes en attente qu'il peut lire.\n\nSans `box`, les trois listes sont renvoyées. `limit` est borné entre 1 et 100. Un `box` inconnu est refusé.\n\n> Disponible lorsque les circuits d'approbation sont activés sur l'instance.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "box", "required": false, "schema": { "type": "string", "enum": [ "", "toAnswer", "requested", "others" ], "default": "" }, "example": "toAnswer", "description": "Boîte à lire : `toAnswer`, `requested` ou `others`. Vide pour les trois." }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "default": 30 }, "example": 30, "description": "Nombre maximal d'éléments par boîte (1 à 100, 30 par défaut)." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Un objet dont les clés sont les boîtes demandées.", "type": "object", "properties": { "toAnswer": { "type": "array", "items": { "type": "object", "properties": { "lineId": { "type": "string" }, "approvalId": { "type": "string" }, "recordId": { "type": "string" }, "moduleName": { "type": "string" }, "recordLabel": { "type": "string" }, "step": { "type": "string" }, "stepPosition": { "type": "integer" }, "stepCount": { "type": "integer" }, "approvedBy": { "type": "string" }, "summary": { "type": "string" }, "requester": { "type": "string" }, "dueDate": { "type": "string" }, "overdue": { "type": "boolean" }, "waitingSince": { "type": "string" } } } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "toAnswer": [ { "lineId": "88x1204", "approvalId": "87x310", "recordId": "15x230", "moduleName": "Invoice", "recordLabel": "FAC-2026-0042", "step": "Responsable financier", "stepPosition": 1, "stepCount": 2, "approvedBy": "Exemple SARL", "summary": "Facture Exemple SARL", "requester": "Camille Martin", "dueDate": "2026-11-20", "overdue": false, "waitingSince": "2026-11-15 09:30:00" } ] } } } } } } } }, "/webservice.php?operation=approval_request_read": { "get": { "operationId": "approval_request_read", "tags": [ "Approbations" ], "summary": "Lire l'approbation d'un enregistrement", "description": "Renvoie l'approbation d'un enregistrement telle que son panneau la montre à l'appelant :\n\n- la demande en cours (`request`, `null` s'il n'y en a pas) ;\n- les étapes (`steps`) avec leur approbateur, leur réponse et son motif, et `canAnswer` qui indique l'étape à laquelle l'appelant peut répondre ;\n- ce qu'une nouvelle demande déclencherait (`wouldAsk`) et si l'appelant peut la faire (`canRequest`).\n\nL'enregistrement doit être lisible par l'appelant.\n\n> Disponible lorsque les circuits d'approbation sont activés sur l'instance.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "recordId", "required": true, "schema": { "type": "string" }, "example": "15x230", "description": "Enregistrement lisible par l'appelant (identifiant webservice)." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "`recordId`, `moduleName`, `hasCircuit`, `request`, `steps`, `wouldAsk` et `canRequest`.", "type": "object", "properties": { "recordId": { "type": "string" }, "moduleName": { "type": "string" }, "hasCircuit": { "type": "boolean" }, "request": { "type": "object", "properties": { "approvalId": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string" }, "statusLabel": { "type": "string" }, "requester": { "type": "string" }, "requestedOn": { "type": "string" }, "decidedOn": { "type": "null" }, "finalizeOnApproval": { "type": "boolean" }, "previousRequests": { "type": "integer" }, "canCancel": { "type": "boolean" } } }, "steps": { "type": "array", "items": { "type": "object", "properties": { "lineId": { "type": "string" }, "order": { "type": "integer" }, "label": { "type": "string" }, "approver": { "type": "string" }, "state": { "type": "string" }, "respondedBy": { "type": "null" }, "respondedOn": { "type": "null" }, "reason": { "type": "null" }, "summary": { "type": "string" }, "dueDate": { "type": "string" }, "canAnswer": { "type": "boolean" } } } }, "wouldAsk": { "type": "array" }, "canRequest": { "type": "boolean" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "recordId": "15x230", "moduleName": "Invoice", "hasCircuit": true, "request": { "approvalId": "87x310", "number": "APP-0012", "status": "APPROVAL_STATUS_PENDING", "statusLabel": "En attente", "requester": "Camille Martin", "requestedOn": "2026-11-15 09:30:00", "decidedOn": null, "finalizeOnApproval": false, "previousRequests": 0, "canCancel": true }, "steps": [ { "lineId": "88x1204", "order": 1, "label": "Responsable financier", "approver": "Alex Dupont", "state": "open", "respondedBy": null, "respondedOn": null, "reason": null, "summary": "Facture Exemple SARL", "dueDate": "2026-11-20", "canAnswer": true } ], "wouldAsk": [], "canRequest": false } } } } } } } }, "/webservice.php?operation=approval_request": { "post": { "operationId": "approval_request", "tags": [ "Approbations" ], "summary": "Demander l'approbation d'un enregistrement", "description": "Demande l'approbation d'un enregistrement au nom de l'appelant, comme le bouton « Demander l'approbation » : une ligne est créée pour chaque étape du circuit qui s'applique, la première étape s'ouvre et ses approbateurs sont notifiés.\n\nL'appelant doit pouvoir modifier l'enregistrement. La demande est refusée (`APPROVAL_REFUSED`) lorsque rien n'exige d'approbation pour cet enregistrement ou lorsqu'une demande est déjà en attente. L'enregistrement est ensuite figé tant que la demande attend.\n\n> Disponible lorsque les circuits d'approbation sont activés sur l'instance.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "recordId": { "type": "string", "description": "Enregistrement que l'appelant peut modifier (identifiant webservice).", "example": "15x230" } }, "required": [ "recordId" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "`stepsAdded` (nombre d'étapes créées) suivi du contenu renvoyé par `approval_request_read` pour cet enregistrement." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=approval_answer": { "post": { "operationId": "approval_answer", "tags": [ "Approbations" ], "summary": "Répondre à une étape d'approbation", "description": "Enregistre la réponse de l'appelant à une étape ouverte qui lui est assignée, directement ou via l'un de ses groupes. L'appelant est toujours celui qui répond : la réponse est tracée comme donnée depuis l'API ou un assistant.\n\n- Personne ne répond à sa propre demande, et un administrateur ne peut pas répondre à la place d'un autre.\n- Les réponses `refuse` et `changes` exigent un `reason`.\n- Une réponse impossible (étape déjà fermée, appelant non approbateur, motif manquant) est refusée avec `APPROVAL_REFUSED`.\n- Un `lineId` qui n'est pas une ligne d'approbation est refusé avec `INVALIDID` : prenez-le dans `approval_inbox` ou `approval_request_read`.\n\n> Disponible lorsque les circuits d'approbation sont activés sur l'instance.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "lineId": { "type": "string", "description": "Ligne de l'étape, issue de `approval_inbox` ou `approval_request_read`.", "example": "88x1204" }, "answer": { "type": "string", "enum": [ "approve", "refuse", "changes" ], "description": "Réponse : `approve` pour approuver, `refuse` pour refuser, `changes` pour demander des modifications." }, "reason": { "type": "string", "default": "", "description": "Motif de la réponse, obligatoire pour refuser ou demander des modifications.", "example": "Le montant dépasse le budget validé." } }, "required": [ "lineId", "answer" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "`answered` (la réponse donnée) suivi du contenu renvoyé par `approval_request_read` pour l'enregistrement concerné." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=approval_cancel": { "post": { "operationId": "approval_cancel", "tags": [ "Approbations" ], "summary": "Annuler une demande d'approbation", "description": "Retire une demande d'approbation en attente. Elle peut l'être par son demandeur ou par un administrateur. L'enregistrement n'est plus figé par la demande.\n\nUne annulation impossible (demande déjà décidée, appelant non autorisé) est refusée avec `APPROVAL_REFUSED`. Un `approvalId` qui n'est pas une demande d'approbation est refusé avec `INVALIDID`.\n\n> Disponible lorsque les circuits d'approbation sont activés sur l'instance.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "approvalId": { "type": "string", "description": "Demande en attente, issue de `approval_request_read` ou `approval_inbox`.", "example": "87x310" } }, "required": [ "approvalId" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "`cancelled` (vrai) suivi du contenu renvoyé par `approval_request_read` pour l'enregistrement concerné." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=getStockCountLines": { "get": { "operationId": "getStockCountLines", "tags": [ "Stocks et catalogue" ], "summary": "Lire les lignes d'un inventaire physique", "description": "Lit, page par page, les lignes enregistrées d'un inventaire physique (`MdsStockCount`), dans l'ordre de leur numéro de séquence. Les droits de lecture de l'appelant sur l'inventaire s'appliquent.\n\n- `id` doit désigner un inventaire physique, sinon l'opération est refusée (`INVALIDID`).\n- `limit` vaut 100 par défaut et est plafonné à 200 ; `offset` vaut 0 par défaut. Ce sont des entiers positifs ou nuls (`limit` strictement positif) : toute autre valeur est refusée.\n- Chaque ligne porte la référence et le nom du produit, l'emplacement et le lot, ainsi que les cumuls du groupe produit, emplacement et lot auquel elle appartient (quantité comptée, quantité théorique, écart).", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "id", "required": true, "schema": { "type": "string" }, "example": "74x512", "description": "Inventaire physique (identifiant webservice)." }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "string", "default": "" }, "example": "100", "description": "Nombre de lignes par page (100 par défaut, 200 au maximum)." }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "string", "default": "" }, "example": "0", "description": "Nombre de lignes à ignorer avant la page (0 par défaut)." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "`total` (nombre de lignes de l'inventaire), `limit`, `offset`, `has_more` (vrai s'il reste des lignes après cette page) et `lines`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=inventory_stock_sync_status": { "get": { "operationId": "inventory_stock_sync_status", "tags": [ "Stocks et catalogue" ], "summary": "Lire l'origine des documents de stock d'une pièce", "description": "Indique d'où viennent les documents de stock générés (bons de livraison, mouvements de stock, bons de réception) à partir d'une facture ou d'un avoir de vente, et si leur suivi est synchronisé.\n\nVous pouvez passer :\n\n- la pièce d'origine (facture ou avoir de vente) ;\n- ou l'un des documents de stock générés, l'opération remonte alors à la pièce d'origine (`source_resolution` indique comment elle a été trouvée).\n\nLa réponse contient la pièce d'origine, l'état du suivi (`tracking`), la dernière erreur de génération le cas échéant (`failure`), la possibilité de relancer la génération ou la reconstruction (`retry`) et la liste des documents générés (`documents`). Seuls les enregistrements actifs et les champs lisibles par l'appelant sont renvoyés. Tout autre type de document est refusé.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "id", "required": true, "schema": { "type": "string" }, "example": "15x230", "description": "Facture, avoir de vente, bon de livraison, mouvement de stock ou bon de réception (identifiant webservice)." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Origine, suivi et documents générés d'une pièce.", "type": "object", "properties": { "requested_document": { "type": "object", "properties": { "id": { "type": "string" }, "module": { "type": "string" }, "url": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string" } } }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "module": { "type": "string" }, "url": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string" } } }, "source_resolution": { "type": "string" }, "tracking": { "type": "object", "properties": { "registered": { "type": "boolean" }, "mode": { "type": "string" }, "warehouse_mode": { "type": "null" }, "generation_kind": { "type": "null" }, "synchronization_enabled": { "type": "boolean" }, "synchronization_active": { "type": "boolean" }, "generated_at": { "type": "string" }, "synchronized_at": { "type": "string" } } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "module": { "type": "string" }, "url": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string" } } } }, "documents_scope": { "type": "string" }, "failure": { "type": "null" }, "retry": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "reason": { "type": "string" }, "kind": { "type": "string" } } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "requested_document": { "id": "15x230", "module": "Invoice", "url": "index.php?module=Invoice&view=Detail&record=230", "number": "FAC-2026-0042", "status": "Paid" }, "source": { "id": "15x230", "module": "Invoice", "url": "index.php?module=Invoice&view=Detail&record=230", "number": "FAC-2026-0042", "status": "Paid" }, "source_resolution": "direct", "tracking": { "registered": true, "mode": "synchronized", "warehouse_mode": null, "generation_kind": null, "synchronization_enabled": true, "synchronization_active": true, "generated_at": "2026-11-15 09:30:00", "synchronized_at": "2026-11-15 09:30:02" }, "documents": [ { "id": "40x118", "module": "MdsDeliveryNote", "url": "index.php?module=MdsDeliveryNote&view=Detail&record=118", "number": "BL-2026-0031", "status": "Created" } ], "documents_scope": "readable_active_records", "failure": null, "retry": { "allowed": false, "reason": "not_eligible", "kind": "reconstruction" } } } } } } } } }, "/webservice.php?operation=product_kit_get_components": { "get": { "operationId": "product_kit_get_components", "tags": [ "Stocks et catalogue" ], "summary": "Lire la composition d'un kit", "description": "Renvoie les composants directs d'un kit produit (`Products`) avec leur quantité. L'appelant doit pouvoir lire le kit et chacun de ses composants, sinon l'opération est refusée (`ACCESSDENIED`). Les liaisons dont le produit n'existe plus ou est supprimé ne sont pas listées comme composants : elles sont signalées dans `integrityIssues`.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "kitId", "required": true, "schema": { "type": "string" }, "example": "14x1001", "description": "Kit produit (identifiant webservice d'un enregistrement `Products`)." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "`kitId`, `components` (identifiant, code, nom et quantité de chaque composant) et `integrityIssues` (liaisons orphelines, avec leur raison : `missing_product` ou `deleted_product`).", "type": "object", "properties": { "kitId": { "type": "string" }, "components": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productcode": { "type": "string" }, "productname": { "type": "string" }, "quantity": { "type": "integer" } } } }, "integrityIssues": { "type": "array" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "kitId": "14x1001", "components": [ { "id": "14x1002", "productcode": "VIS-10", "productname": "Vis 10 mm", "quantity": 4 }, { "id": "14x1003", "productcode": "PLQ-01", "productname": "Plaque support", "quantity": 1 } ], "integrityIssues": [] } } } } } } } }, "/webservice.php?operation=product_kit_set_components": { "post": { "operationId": "product_kit_set_components", "tags": [ "Stocks et catalogue" ], "summary": "Remplacer la composition d'un kit", "description": "Remplace la composition directe complète d'un kit produit : les composants absents de la liste sont retirés, les nouveaux sont ajoutés et les quantités différentes sont mises à jour. Les liaisons orphelines (produit supprimé) sont nettoyées au passage. Le prix du kit est ensuite recalculé.\n\nRègles :\n\n- l'appelant doit pouvoir modifier le kit et lire chaque composant ;\n- chaque élément de `components` porte un `id` (produit) et une `quantity` strictement positive ; un composant ne peut apparaître qu'une fois ;\n- un produit standard, ou une variante d'un produit, ne peut pas devenir un kit ;\n- un composant qui créerait un cycle (le kit contenu directement ou indirectement dans lui-même) est refusé ;\n- une liste vide est valide et vide le kit.\n\nLes erreurs de saisie renvoient `QUERYSYNTAX`.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "kitId": { "type": "string", "description": "Kit produit à modifier (identifiant webservice d'un enregistrement `Products`).", "example": "14x1001" }, "components": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array" }, "description": "Texte JSON (liste). Composition complète voulue : liste d'objets `id` (produit composant) et `quantity` (nombre strictement positif).", "example": "[{\"id\":\"14x1002\",\"quantity\":4},{\"id\":\"14x1003\",\"quantity\":1}]" } }, "required": [ "kitId", "components" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Bilan des changements (`added`, `removed`, `removedOrphans`, `updated`, `unchanged`), résultat du recalcul du prix (`pricing`) et composition finale (`components`).", "type": "object", "properties": { "kitId": { "type": "string" }, "added": { "type": "integer" }, "removed": { "type": "integer" }, "removedOrphans": { "type": "integer" }, "updated": { "type": "integer" }, "unchanged": { "type": "integer" }, "pricing": { "type": "object", "properties": { "success": { "type": "boolean" }, "status": { "type": "string" }, "old_price": { "type": "integer" }, "new_price": { "type": "number" }, "old_purchase_cost": { "type": "integer" }, "new_purchase_cost": { "type": "number" }, "mode": { "type": "string" }, "message": { "type": "string" } } }, "components": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productcode": { "type": "string" }, "productname": { "type": "string" }, "quantity": { "type": "integer" } } } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "kitId": "14x1001", "added": 1, "removed": 0, "removedOrphans": 0, "updated": 1, "unchanged": 0, "pricing": { "success": true, "status": "updated", "old_price": 10, "new_price": 12.5, "old_purchase_cost": 6, "new_purchase_cost": 7.5, "mode": "sum", "message": "" }, "components": [ { "id": "14x1002", "productcode": "VIS-10", "productname": "Vis 10 mm", "quantity": 4 }, { "id": "14x1003", "productcode": "PLQ-01", "productname": "Plaque support", "quantity": 1 } ] } } } } } } } }, "/webservice.php?operation=product_kit_add_component": { "post": { "operationId": "product_kit_add_component", "tags": [ "Stocks et catalogue" ], "summary": "Ajouter un composant à un kit", "description": "Ajoute un composant à un kit produit, ou met à jour sa quantité s'il en fait déjà partie. Le prix du kit est ensuite recalculé.\n\nL'appelant doit pouvoir modifier le kit et lire le composant. La quantité doit être un nombre strictement positif. Sont refusés : un produit standard ou une variante comme kit, et un composant qui créerait un cycle.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "kitId": { "type": "string", "description": "Kit produit (identifiant webservice d'un enregistrement `Products`).", "example": "14x1001" }, "componentId": { "type": "string", "description": "Produit à ajouter comme composant (identifiant webservice d'un enregistrement `Products`).", "example": "14x1003" }, "quantity": { "type": "number", "description": "Quantité du composant dans le kit, strictement positive.", "example": 2 } }, "required": [ "kitId", "componentId", "quantity" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "`kitId`, `componentId`, `outcome` (`added` ou `updated`), `quantity` et `pricing` (résultat du recalcul du prix du kit).", "type": "object", "properties": { "kitId": { "type": "string" }, "componentId": { "type": "string" }, "outcome": { "type": "string" }, "quantity": { "type": "integer" }, "pricing": { "type": "object", "properties": { "success": { "type": "boolean" }, "status": { "type": "string" }, "old_price": { "type": "integer" }, "new_price": { "type": "number" }, "old_purchase_cost": { "type": "integer" }, "new_purchase_cost": { "type": "number" }, "mode": { "type": "string" }, "message": { "type": "string" } } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "kitId": "14x1001", "componentId": "14x1003", "outcome": "added", "quantity": 2, "pricing": { "success": true, "status": "updated", "old_price": 10, "new_price": 12.5, "old_purchase_cost": 6, "new_purchase_cost": 7.5, "mode": "sum", "message": "" } } } } } } } } }, "/webservice.php?operation=product_kit_remove_component": { "post": { "operationId": "product_kit_remove_component", "tags": [ "Stocks et catalogue" ], "summary": "Retirer un composant d'un kit", "description": "Retire un composant d'un kit produit, puis recalcule le prix du kit. L'opération est idempotente : si le produit n'était pas un composant du kit, rien n'est modifié et `outcome` vaut `unchanged`. L'appelant doit pouvoir modifier le kit et lire le produit retiré.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "kitId": { "type": "string", "description": "Kit produit (identifiant webservice d'un enregistrement `Products`).", "example": "14x1001" }, "componentId": { "type": "string", "description": "Composant à retirer (identifiant webservice d'un enregistrement `Products`).", "example": "14x1003" } }, "required": [ "kitId", "componentId" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "`kitId`, `componentId`, `outcome` (`removed` ou `unchanged`) et `pricing` (résultat du recalcul du prix du kit)." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=onlinestore_refresh_order": { "post": { "operationId": "onlinestore_refresh_order", "tags": [ "Stocks et catalogue" ], "summary": "Rafraîchir des documents depuis la boutique en ligne", "description": "Rejoue l'import de documents déjà téléchargés depuis une boutique en ligne, comme le bouton « Rafraîchir depuis la boutique ». Le document existant est mis à jour, jamais dupliqué.\n\n- Réservée aux administrateurs.\n- 1 à 100 documents par appel, de modules différents si besoin (commandes, factures) ; le module est déduit de chaque identifiant.\n- Un document qui ne vient pas d'une boutique (sans référence externe) est refusé.\n- Un document finalisé ou avancé dans Kafinea n'est jamais modifié.\n- Un document en échec n'interrompt pas les autres : il est listé dans `errors` avec sa position dans la liste, pour pouvoir le rejouer seul.\n\nUne liste vide, mal formée ou de plus de 100 éléments est refusée en entier (`QUERYSYNTAX`).\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "ids": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array" }, "description": "Texte JSON (liste). Documents à rafraîchir (identifiants webservice), de 1 à 100.", "example": "[\"21x98832\",\"21x98833\"]" } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "`processed`, `refreshed`, `documents` (position, identifiant, module, référence externe et boutique de chaque document rafraîchi) et `errors` (position, identifiant et message).", "type": "object", "properties": { "processed": { "type": "integer" }, "refreshed": { "type": "integer" }, "documents": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "id": { "type": "string" }, "module": { "type": "string" }, "externalRef": { "type": "string" }, "storeId": { "type": "integer" } } } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "id": { "type": "string" }, "message": { "type": "string" } } } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "processed": 1, "refreshed": 1, "documents": [ { "index": 0, "id": "21x98832", "module": "SalesOrder", "externalRef": "1042", "storeId": 3 } ], "errors": [ { "index": 1, "id": "21x98833", "message": "Record [21x98833] does not come from an online store: no external reference to refresh." } ] } } } } } } } }, "/webservice.php?operation=onlinestore_convert_order_incl_tax": { "post": { "operationId": "onlinestore_convert_order_incl_tax", "tags": [ "Stocks et catalogue" ], "summary": "Convertir des documents de boutique en TTC", "description": "Fait passer des documents importés d'une boutique en ligne, encore en prix hors taxes, en prix toutes taxes comprises sur leurs propres lignes. Contrairement à `onlinestore_refresh_order`, rien n'est rejoué depuis la boutique : les lignes, adresses et statuts modifiés après l'import restent tels quels. Seul le montant payé est lu sur la boutique, et le document doit tomber exactement dessus, sinon il est laissé intact avec la raison.\n\n- Réservée aux administrateurs.\n- 1 à 100 documents par appel ; une liste vide, mal formée ou trop longue est refusée en entier (`QUERYSYNTAX`).\n- Un document en échec n'interrompt pas les autres : il est listé dans `errors` avec sa position. `locked` vaut vrai lorsque le document est finalisé, ce qui le distingue d'une vraie panne : un document finalisé n'est jamais réécrit.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "ids": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array", "items": { "type": "string" } }, "description": "Texte JSON (liste). Documents à convertir (identifiants webservice), de 1 à 100. Transmis sous forme de chaîne JSON.", "example": "[\"21x98832\"]" } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "`documents` (position, identifiant et `converted` pour chaque document traité) et `errors` (position, identifiant, message et `locked`).", "type": "object", "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "id": { "type": "string" }, "converted": { "type": "boolean" } } } }, "errors": { "type": "array" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "documents": [ { "index": 0, "id": "21x98832", "converted": true } ], "errors": [] } } } } } } } }, "/webservice.php?operation=inventory_reapply_region_taxes": { "post": { "operationId": "inventory_reapply_region_taxes", "tags": [ "Stocks et catalogue" ], "summary": "Réappliquer les taux de TVA de la région fiscale", "description": "Remet les taux de TVA des lignes de documents enregistrés en accord avec la région fiscale du document, sans reconstruire les lignes, puis recalcule les montants enregistrés.\n\n- Réservée aux administrateurs.\n- Par défaut, simulation : chaque document répond avec les lignes et les taux qui changeraient. Seul `apply` égal à `1` écrit, document par document.\n- 1 à 100 documents par appel ; une liste vide, mal formée ou trop longue est refusée en entier (`QUERYSYNTAX`).\n- Un document en échec n'interrompt pas les autres : il est listé dans `errors` avec sa position.\n- Seuls les commandes et devis sont réparés ainsi. Un document verrouillé, sans région fiscale, en prix toutes taxes comprises, dont les montants enregistrés sont incohérents ou qui garde le calcul historique n'est jamais modifié et est signalé dans `errors`.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "ids": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array", "items": { "type": "string" } }, "description": "Texte JSON (liste). Documents à traiter (identifiants webservice), de 1 à 100. Transmis sous forme de chaîne JSON.", "example": "[\"5x157832\"]" }, "apply": { "type": "string", "default": "", "description": "`1` pour écrire les corrections. Toute autre valeur, ou l'absence du paramètre, donne une simulation.", "example": "1" } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "`applied` (vrai si les corrections ont été écrites), `documents` (position, identifiant et détail de chaque document traité, dont les lignes qui changent avec l'ancien et le nouveau taux) et `errors` (position, identifiant et message)." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=inventory_kit_stock_repair": { "post": { "operationId": "inventory_kit_stock_repair", "tags": [ "Stocks et catalogue" ], "summary": "Réparer l'historique de stock des kits", "description": "Rapporte puis répare l'historique de stock écrit pour des kits vendus comme composants, avant que les kits ne déplacent leurs composants. Cette opération reconstruit du stock : elle est réservée aux administrateurs.\n\n- Sans `ids` : rapport seul. Il liste les lignes de kit dont la composition a été enregistrée multipliée par la quantité de la ligne (`compositions`) et les documents de stock actifs qui déplacent encore un kit vendu comme composants (`documents`). `since` limite les mouvements aux documents datés de ce jour ou après.\n- Avec `ids` (1 à 100 documents) sans `apply` : le même rapport, limité à ces documents.\n- Avec `ids` et `apply` égal à `1` : chaque document est réparé séparément, en tout ou rien (compositions rétablies, puis mouvements de stock rejoués). La réponse indique ce qui a été fait et combien de mouvements de kit subsistent. Un document refusé n'interrompt pas les autres : il figure dans `errors` avec sa position.\n\nRéparer sans `ids` est refusé (`QUERYSYNTAX`) : lisez d'abord le rapport, puis réparez ses documents par lots.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "requestBody": { "required": false, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "ids": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array", "items": { "type": "string" } }, "description": "Texte JSON (liste). Documents à traiter (identifiants webservice), de 1 à 100. Vide pour obtenir le rapport complet. Transmis sous forme de chaîne JSON.", "example": "[\"73x152940\"]" }, "since": { "type": "string", "default": "", "description": "Date au format `AAAA-MM-JJ` : ne rapporter que les mouvements de kit datés de ce jour ou après. Sans effet lors d'une réparation.", "example": "2026-10-01" }, "apply": { "type": "string", "default": "", "description": "`1` pour réparer les documents de `ids`. Toute autre valeur donne le rapport.", "example": "1" } } } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Pour un rapport : `applied` (faux), `kits`, `compositions` et `documents`. Pour une réparation : `applied` (vrai), `results` (position, identifiant, `compositionsFixed`, `replayed` et `kitMovementsLeft` par document) et `errors` (position, identifiant et message)." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=tax_region_configuration": { "get": { "operationId": "tax_region_configuration", "tags": [ "Fiscalité" ], "summary": "Lire la configuration des régions fiscales", "description": "Réservé aux administrateurs : sinon l'opération est refusée (`ACCESSDENIED`). Lit la configuration fiscale : régions fiscales, grilles générales de taxes produits et frais de port, frais supplémentaires avec leurs montants par région, correspondances par pays et par territoire, surcharges par profil de client et périmètre de la sélection automatique.\n\nPour chaque taxe, la réponse donne `taxId`, `active`, `method`, `type` et `compoundOn`, taxes inactives comprises, ainsi qu'un bloc `diagnostics` avec `configurationIssues` (code et libellés) et `missingRates`. Les grilles actuelles ne prouvent ni les taux historiques des lignes de documents ni l'éligibilité légale.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "read", "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La configuration fiscale courante (régions, grilles, frais supplémentaires, correspondances pays et territoires, réglages de sélection) et `diagnostics` (`configurationIssues`, `missingRates`)." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=tax_region_configure": { "post": { "operationId": "tax_region_configure", "tags": [ "Fiscalité" ], "summary": "Modifier la configuration des régions fiscales", "description": "Réservé aux administrateurs : sinon l'opération est refusée (`ACCESSDENIED`). Applique une modification de la configuration fiscale. Chaque appel porte une modification complète et relue, choisie par `kind`. La modification est validée puis enregistrée atomiquement ; la réponse ne contient que `saved` et les identifiants concernés. Lisez la configuration avec `tax_region_configuration` et simulez avec `tax_region_preview` après chaque changement : un enregistrement ultérieur peut remplacer des valeurs précédentes du même élément.\n\nNature des modifications (`kind`) :\n- `settings`, `country`, `rule` : réglages de sélection automatique, correspondance d'un pays, règle typée. `settings` exige `enabled`, `departure_country`, `operation_kind` et `organization_ids` ; une règle exige un critère typé, une priorité et une correspondance complète.\n- `country` : soit `country_id` avec la correspondance complète, soit `isocodes` (1 à 300 codes ISO) avec seulement les parties à modifier, appliquées à tous ces pays dans la même transaction (`result.isocodes` les liste ; chaque pays conserve ses autres parties).\n- `region` : création, renommage (`action` `save`) ou suppression (`delete`, uniquement d'une région inutilisée).\n- `tax_grid` : remplace les taux d'une taxe produit ou frais de port active, sans changer sa méthode ni les surcharges produit.\n- `tax` : crée ou redéfinit une catégorie de taxe (la création ajoute sa colonne de ligne, est irréversible et s'exécute hors transaction). Une taxe est désactivée, jamais supprimée.\n- `tax_status` : active ou désactive une taxe.\n- `charge` : crée ou redéfinit un frais supplémentaire avec ses montants par région.\n- `charge_delete` : supprime un frais (il va à la corbeille comme dans les réglages, les documents enregistrés gardent leurs montants ; un rejeu renvoie `alreadyDeleted`).\n- `french_baseline` : exécute la configuration française idempotente de l'écran des taxes. Elle crée uniquement les régions, taux et pays livrés qui manquent, n'écrase jamais une décision et renvoie ce qu'elle a créé.\n\nChaque changement est enregistré dans l'historique des réglages fiscaux (`tax_region_history`) avec son canal ; la réponse donne son `operationId`, `null` si rien n'a changé. Erreur de saisie : `QUERYSYNTAX` avec l'explication.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "configure", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "settings", "country", "rule", "region", "tax_grid", "tax", "tax_status", "charge", "charge_delete", "french_baseline" ], "description": "Nature de la modification : `settings`, `country`, `rule`, `region`, `tax_grid`, `tax`, `tax_status`, `charge`, `charge_delete` ou `french_baseline`.", "example": "tax_grid" }, "input": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "description": "Texte JSON (objet). Objet JSON de la modification complète, dont le contenu dépend de `kind`. `region` : `action` (`save` ou `delete`), `region_id` facultatif à la création, `name` pour `save`. `tax_grid` : `appliesTo` (`product` ou `shipping`), `taxId`, `defaultRate` (3 décimales au plus) et objet complet `ratesByRegionId` ; un zéro explicite est conservé. `tax` : `appliesTo`, `name`, `active`, `method` (`Simple`, `Compound` ou `Deducted`, figée après la création ; `Deducted` uniquement pour les produits, toujours en `Fixed`), `type` (`Fixed` ou `Variable`), `defaultRate`, `ratesByRegionId` (`Variable` uniquement), `compoundOn` (liste d'identifiants de taxes simples actives, `Compound` uniquement) ; sans `taxId`, la taxe est créée. `tax_status` : `appliesTo`, `taxId`, `active`. `charge` : `name`, `format` (`Flat` ou `Percent`), `type` (`Fixed` ou `Variable`), `defaultValue`, `valuesByRegionId` (`Variable` uniquement), `taxable`, `taxIds` (taxes de frais de port actives) ; sans `chargeId`, le frais est créé. `charge_delete` : `chargeId`. `french_baseline` : objet vide. `settings`, `country` et `rule` reprennent les champs de correspondance renvoyés par `tax_region_configuration` ; `enabled` et `active` doivent être de vrais booléens JSON. `country` : `isocodes` avec les seules parties à modifier (`mdstaxregionid`, `mdsindividualtaxregionid`, ou `mdsprofessionaltaxregionid` avec `mdsprofessionaltaxcondition`).", "example": "{\"appliesTo\":\"product\",\"taxId\":3,\"defaultRate\":20,\"ratesByRegionId\":{\"1\":20,\"2\":8.5}}" }, "operationId": { "type": "string", "default": "", "description": "Identifiant facultatif (1 à 64 caractères : lettres, chiffres, point, tiret, deux-points, tiret bas ; commence par une lettre ou un chiffre) partagé par les lignes d'historique de cette modification. Réutilisez-le pour regrouper plusieurs appels.", "example": "maj-tva-2025-09" }, "comment": { "type": "string", "default": "", "description": "Motif facultatif (500 caractères au plus) conservé avec chaque ligne d'historique de cette modification.", "example": "Alignement sur les nouveaux taux" }, "revision": { "type": "string", "description": "Accepté pour compatibilité avec les intégrations existantes, sans effet." } }, "required": [ "kind", "input" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "`saved` (confirmation), `result` (identifiants des éléments enregistrés) et `operationId` des lignes d'historique (`null` si rien n'a changé)." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=tax_region_history": { "get": { "operationId": "tax_region_history", "tags": [ "Fiscalité" ], "summary": "Lire l'historique des réglages fiscaux", "description": "Réservé aux administrateurs : sinon l'opération est refusée (`ACCESSDENIED`). Lit le journal des réglages fiscaux, du plus récent au plus ancien : une ligne par région, taxe, frais, correspondance de pays, exception territoriale, réglage de sélection ou politique de taxe de boutique modifié, avec `changedAt` (UTC), `userId`, `channel`, `operationId`, `action` (`create`, `update`, `delete`, `activate`, `deactivate`), valeurs avant et après, `revisionAfter` et `comment`. `nextBeforeAuditId` permet de paginer vers le passé.\n\nLes identifiants de connexion des boutiques n'apparaissent jamais. Le journal commence à son installation ; les modifications de documents restent dans l'historique propre à chaque enregistrement. Un filtre inconnu est refusé (`QUERYSYNTAX`).\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "filters", "required": false, "schema": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "default": "[]" }, "example": "{\"objectType\":\"tax\",\"channel\":\"api\",\"limit\":20}", "description": "Texte JSON (objet). Filtres facultatifs : `from` et `to` (UTC, `AAAA-MM-JJ` ou `AAAA-MM-JJ HH:MM:SS`), `objectType` (`settings`, `region`, `tax`, `charge`, `country`, `exception`, `store`), `key` (clé naturelle : nom d'une région, `product:`, code ISO, clé d'exception), `objectId`, `operationId`, `channel` (`screen`, `api`, `mcp`, `assistant`, `setup`, `script`, `preset`, `store`), `limit` (1 à 200, 50 par défaut) et `beforeAuditId` (page suivante)." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Les lignes d'historique, la plus récente d'abord, et `nextBeforeAuditId` pour la page suivante." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=tax_region_preview": { "get": { "operationId": "tax_region_preview", "tags": [ "Fiscalité" ], "summary": "Simuler la région fiscale d'une adresse", "description": "Réservé aux administrateurs : sinon l'opération est refusée (`ACCESSDENIED`). Simulation en lecture seule de la région fiscale d'une adresse et, au choix, du profil d'un client, avec les mêmes services de sélection que l'écran des taxes. Elle n'inspecte ni un document enregistré, ni les taux propres à un produit, ni les preuves légales.\n\nAvec `documentTest` à `true`, la simulation porte sur un nouveau document à partir des faits fournis (nature du tiers, qualification intra-communautaire, numéro de TVA, société, opération, biens ou services, pays de départ). Une société manquante, inconnue ou ambiguë est signalée dans `inputIssues` ; `UNSUPPORTED_TAX_CONTEXT` s'accompagne de `document.advisory_details` (cause, valeur réelle, valeur attendue, message). La nature du client et sa qualification ne sont pas déduites.\n\n`configurationPreview` accepte un candidat complet de `settings`, `country` ou `rule` (avec `configurationKind`) et renvoie ses diagnostics sans l'enregistrer. Une entrée invalide est refusée (`QUERYSYNTAX`).\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "input", "required": true, "schema": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" } }, "example": "{\"country\":\"FR\",\"postcode\":\"69001\",\"state\":\"\",\"documentTest\":true,\"module\":\"Invoice\",\"partyNature\":\"professional\",\"intravatApproved\":false,\"operation\":\"sale\"}", "description": "Texte JSON (objet). Objet JSON. Adresse : `country`, `postcode`, `state`. Avec `documentTest` à `true`, faits du document simulé : `module`, `partyNature`, `intravatApproved`, `vatNumber` (numéro de TVA du client, chaîne, pour la condition de numéro de TVA), `organizationId` (identifiant ou nom exact ; `organizationName` est aussi accepté), `operation`, `goodsOrServices`, `departureCountry` et `partyRegionId`. Par défaut : `operation` vaut `sale`, `module` vaut `PurchaseOrder` pour un achat et `Quotes` sinon, `goodsOrServices` et `departureCountry` reprennent la configuration ; une valeur vide explicite reste vide. `configurationPreview` : candidat de réglage complet avec `configurationKind`. Les champs booléens exigent de vrais booléens JSON." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La région retenue pour l'adresse, les diagnostics, et pour un document simulé la proposition de taxes avec `inputIssues` et `document.advisory_details` le cas échéant." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=action_link_actions": { "get": { "operationId": "action_link_actions", "tags": [ "Automatisation" ], "summary": "Lister les actions des liens par e-mail", "description": "Liste les actions qu'un lien d'action par e-mail peut exécuter : module concerné (`*` pour tous les modules), nom de l'action, libellé, attributs conservés dans le lien et durée de validité en jours.\n\nAvec `module`, la réponse contient aussi `settableFields` : les champs de type liste de choix ou case à cocher que l'action `set-field` peut modifier sur ce module, avec leurs valeurs possibles. Seuls les champs que vous avez le droit de modifier sont listés.\n\nUn lien d'action ouvre une page de confirmation : l'action n'est exécutée que lorsque le destinataire confirme, sans avoir à se connecter.\n\nErreur `ACCESS_DENIED` si votre profil n'autorise pas la lecture du module demandé.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "module", "required": false, "schema": { "type": "string", "default": "" }, "example": "Quotes", "description": "Nom API du module à examiner. Laissez vide pour obtenir toutes les actions sans la liste des champs modifiables." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Les actions disponibles et, lorsqu'un module est donné, les champs modifiables par l'action `set-field`.", "type": "object", "properties": { "actions": { "type": "array", "items": { "type": "object", "properties": { "module": { "type": "string" }, "action": { "type": "string" }, "label": { "type": "string" }, "attributes": { "type": "array", "items": { "type": "string" } }, "expiresAfterDays": { "type": "integer" }, "description": { "type": "string" } } } }, "settableFields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } } } } } } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "actions": [ { "module": "*", "action": "set-field", "label": "Modifier un champ", "attributes": [ "record", "field", "value", "question" ], "expiresAfterDays": 30, "description": "Sets a picklist or checkbox field of the record to the value given when the link was created." } ], "settableFields": [ { "field": "quotestage", "label": "Étape du devis", "values": [ { "value": "Accepted", "label": "Accepté" }, { "value": "Rejected", "label": "Refusé" } ] } ] } } } } } } } }, "/webservice.php?operation=action_link_create": { "post": { "operationId": "action_link_create", "tags": [ "Automatisation" ], "summary": "Créer un lien d'action par e-mail", "description": "Crée un lien d'action sur un enregistrement et retourne son adresse (`url`) et sa date d'expiration (`expiresAt`, `null` si le lien n'expire pas).\n\nPour l'action `set-field`, `attributes` contient `field` et `value` (à prendre dans `settableFields` de `action_link_actions`) et, en option, un court texte `question` affiché sur la page de confirmation. Les autres actions n'acceptent aucun attribut. Les valeurs d'`attributes` sont des textes.\n\nUn lien ne donne jamais plus de droits que son créateur : vous devez pouvoir faire vous-même la modification, comme à l'écran (droit de modification sur l'enregistrement et sur le champ, ou modification partielle d'un devis, d'une commande ou d'une facture finalisés).\n\nToute personne qui détient l'adresse peut confirmer l'action une seule fois, sans se connecter, jusqu'à l'expiration du lien. Transmettez-la uniquement à son destinataire et ne la publiez pas dans un espace partagé. Rien n'est modifié tant que le destinataire n'a pas confirmé.\n\nTout refus, y compris un droit insuffisant, est retourné avec le code `ACTION_LINK_INVALID`.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifiant webservice de l'enregistrement visé par le lien.", "example": "13x42" }, "action": { "type": "string", "description": "Nom de l'action, tel que retourné par `action_link_actions`.", "example": "set-field" }, "attributes": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "default": "[]", "description": "Texte JSON (objet). Attributs de l'action, sous forme d'objet de valeurs textuelles. Le lien ne peut pas viser un autre enregistrement que `id`.", "example": "{\"field\":\"quotestage\",\"value\":\"Accepted\",\"question\":\"Acceptez-vous ce devis ?\"}" } }, "required": [ "id", "action" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "L'adresse du lien, sa date d'expiration (format ISO 8601, `null` si le lien n'expire pas), le module, l'action et l'enregistrement.", "type": "object", "properties": { "url": { "type": "string" }, "expiresAt": { "type": "string" }, "module": { "type": "string" }, "action": { "type": "string" }, "id": { "type": "string" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "url": "https://erp.exemple.fr/shorturl.php?id=a1b2c3d4e5", "expiresAt": "2026-12-15T10:30:00+00:00", "module": "Quotes", "action": "set-field", "id": "13x42" } } } } } } } }, "/webservice.php?operation=workflow_configure": { "post": { "operationId": "workflow_configure", "tags": [ "Automatisation" ], "summary": "Configurer un workflow", "description": "Crée, modifie, active, désactive, copie ou supprime un workflow. Réservé aux administrateurs. Lisez d'abord `capabilities` avec `workflow_read` : la réponse décrit les déclencheurs, les opérateurs de condition et les types de tâches acceptés.\n\n- Création : `workflowId` à 0 et `definition` avec `module`, `name` (100 caractères au plus), `description` (400 au plus, optionnelle), `trigger`, `conditions` et `tasks`. Le workflow est créé inactif.\n- Toute autre action exige la `revision` obtenue par `workflow_read` et porte sur un workflow non protégé.\n- `draft` modifie un workflow inactif, `update` modifie un workflow actif de façon atomique (il reste actif).\n- Sur un workflow existant, seules les clés envoyées changent. Un élément renvoyé tel qu'il a été lu, ou une tâche renvoyée avec son `taskId` et des paramètres inchangés, reste exactement tel qu'il est stocké (les identifiants de tâche restent stables). Une tâche absente de la liste envoyée est supprimée.\n- Les conditions suivent la forme de l'éditeur à l'écran (`groupid` 0 : toutes doivent être vraies, 1 : l'une d'elles suffit) et peuvent porter sur un champ direct ou lié (`ref : (Module) champ`).\n- Testez avec `workflow_simulate`, puis activez avec `activate` et une `definition` vide (seuls la révision et les expressions sont vérifiées).\n- `clone` copie le workflow dans le module `definition.module` en brouillon inactif, et refuse la copie si un champ manque dans ce module.\n- `delete` est refusé tant qu'une tâche est en file d'attente.\n\nLes autres types de tâches, les expressions de condition, les délais et les planifications sont conservés tels quels mais ne se modifient que dans l'éditeur à l'écran. Chaque action est journalisée (qui, quand, canal, révisions).\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "configure", "requestBody": { "required": false, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "workflowId": { "type": "integer", "default": 0, "description": "Identifiant du workflow, ou 0 pour en créer un nouveau.", "example": 12 }, "revision": { "type": "string", "default": "", "description": "Révision lue avec `workflow_read`, obligatoire pour toute action sur un workflow existant. Elle est refusée si le workflow a changé entre-temps : relisez-le alors.", "example": "3f9a1c0d5e7b..." }, "action": { "type": "string", "enum": [ "draft", "update", "activate", "deactivate", "clone", "delete" ], "default": "draft", "description": "Action à effectuer : `draft`, `update`, `activate`, `deactivate`, `clone` ou `delete`.", "example": "draft" }, "definition": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "default": "[]", "description": "Texte JSON (objet). Définition du workflow (`module`, `name`, `description`, `trigger`, `conditions`, `tasks`). Vide pour activer, désactiver ou supprimer ; pour `clone`, seuls `module` (obligatoire), `name` et `description` sont acceptés.", "example": "{\"module\":\"Accounts\",\"name\":\"Exemple\",\"description\":\"Ce que fait le workflow\",\"trigger\":3,\"conditions\":[{\"fieldname\":\"accountname\",\"operation\":\"starts with\",\"value\":\"Exemple\",\"valuetype\":\"rawtext\",\"groupid\":0}],\"tasks\":[{\"type\":\"VTUpdateFieldsTask\",\"summary\":\"Exemple d'affectation\",\"active\":true,\"parameters\":{\"field_value_mapping\":[{\"fieldname\":\"description\",\"value\":\"Valeur d'exemple\",\"valuetype\":\"rawtext\"}]}}]}" } } } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La définition du workflow après l'action, avec sa nouvelle `revision`. Pour `delete`, un objet `{ workflowId, module, name, deleted: true, revision }`. Pour `clone`, la copie inactive et un message d'information." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=workflow_expression_check": { "post": { "operationId": "workflow_expression_check", "tags": [ "Automatisation" ], "summary": "Vérifier une expression de workflow", "description": "Vérifie la syntaxe d'une expression de workflow avec l'analyseur utilisé par les écrans d'enregistrement. Réservé aux administrateurs.\n\nLa réponse indique si l'expression est valide (`valid`), le problème bloquant (code, message traduit, position, ligne et colonne ; `null` si l'expression est valide) et des avertissements non bloquants, par exemple une chaîne calculée de droite à gauche (`a / b * c` est évalué comme `a / (b * c)` : mettez des parenthèses).\n\nL'opération ne lit aucun enregistrement.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "read", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "expression": { "type": "string", "description": "Texte de l'expression à vérifier.", "example": "total / ( part / 100 )" } }, "required": [ "expression" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le résultat de la vérification : `valid`, `problem` et `warnings`.", "type": "object", "properties": { "valid": { "type": "boolean" }, "problem": { "type": "null" }, "warnings": { "type": "array" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "valid": true, "problem": null, "warnings": [] } } } } } } } }, "/webservice.php?operation=workflow_expression_evaluate": { "post": { "operationId": "workflow_expression_evaluate", "tags": [ "Automatisation" ], "summary": "Évaluer une expression de workflow à blanc", "description": "Évalue une expression de workflow sur 1 à 20 enregistrements existants que vous pouvez lire, avec le moteur des tâches de mise à jour. Réservé aux administrateurs. Rien n'est enregistré.\n\nLa réponse contient la valeur brute obtenue pour chaque enregistrement, ou l'erreur propre à cet enregistrement (un identifiant inconnu ou illisible n'échoue que sur sa ligne), ainsi que le résultat de la vérification de syntaxe.\n\nTypes de valeurs : un champ donne sa valeur stockée (dates `AAAA-MM-JJ`, nombres sous forme de texte, cases à cocher 0/1) ; un champ de référence donne le libellé de l'enregistrement lié ; un champ d'affectation donne l'identifiant de l'utilisateur ou du groupe ; un calcul donne un nombre. Avec `fieldName`, les conversions de ce champ cible sont appliquées.\n\nUtile pour comparer une ancienne et une nouvelle expression sur les mêmes enregistrements avant de remplacer l'une par l'autre.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "read", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "expression": { "type": "string", "description": "Texte de l'expression à évaluer.", "example": "total / ( part / 100 )" }, "recordIds": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array", "items": { "type": "string" } }, "description": "Texte JSON (liste). Identifiants webservice des enregistrements de test (1 à 20).", "example": "[\"13x42\",\"13x43\"]" }, "fieldName": { "type": "string", "default": "", "description": "Champ cible dont les conversions sont appliquées à la valeur. Laissez vide pour obtenir la valeur brute.", "example": "description" } }, "required": [ "expression", "recordIds" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le résultat de la vérification (`check`), une entrée par enregistrement (`records`, avec `value` ou `error`), `saved` à `false` et une note d'information.", "type": "object", "properties": { "check": { "type": "object", "properties": { "valid": { "type": "boolean" }, "problem": { "type": "null" }, "warnings": { "type": "array" } } }, "records": { "type": "array", "items": { "type": "object", "properties": { "recordId": { "type": "string" }, "module": { "type": "string" }, "value": { "type": "integer" } } } }, "saved": { "type": "boolean" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "check": { "valid": true, "problem": null, "warnings": [] }, "records": [ { "recordId": "13x42", "module": "Quotes", "value": 1250 }, { "recordId": "13x99", "module": null, "error": "Record not found" } ], "saved": false } } } } } } } }, "/webservice.php?operation=workflow_expression_format": { "post": { "operationId": "workflow_expression_format", "tags": [ "Automatisation" ], "summary": "Mettre en forme une expression de workflow", "description": "Met en page une expression de workflow sur des lignes indentées (une branche `if` par ligne, commentaires conservés). Réservé aux administrateurs. Seuls les espaces changent : le texte mis en forme est vérifié pour donner exactement les mêmes éléments que l'original. Dans le cas contraire, l'original est retourné avec une raison. Rien n'est enregistré.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "read", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "expression": { "type": "string", "description": "Texte de l'expression à mettre en forme.", "example": "if total > 1000 then 10 else 0 end" } }, "required": [ "expression" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le texte mis en forme (`formatted`), `changed` (le texte a-t-il été modifié) et `reason` (`null`, ou la raison pour laquelle l'original est retourné tel quel).", "type": "object", "properties": { "formatted": { "type": "string" }, "changed": { "type": "boolean" }, "reason": { "type": "null" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "formatted": "if total > 1000\n then 10\n else 0\nend", "changed": true, "reason": null } } } } } } } }, "/webservice.php?operation=workflow_read": { "get": { "operationId": "workflow_read", "tags": [ "Automatisation" ], "summary": "Lire les workflows", "description": "Liste ou détaille les workflows de l'instance. Réservé aux administrateurs. N'exécute aucune action.\n\n- Sans `workflowId` : liste paginée des workflows actifs et inactifs (identifiant, module, nom, description, état actif, protégé, déclencheur) avec le total, `nextOffset` (`null` à la dernière page) et `capabilities`, qui décrit ce que `workflow_configure` accepte. `limit` va de 1 à 100.\n- Avec `workflowId` : conditions, tâches, planification, `revision` à transmettre à `workflow_configure`, `editorReadable` et `editorReadableReasons` (l'éditeur à l'écran affiche-t-il et enregistre-t-il les conditions sans les modifier), `executionContext` (utilisateur et société pour lesquels le workflow s'exécute) et `history` (les 20 dernières modifications de configuration et exécutions faites avec `workflow_run`).\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "workflowId", "required": false, "schema": { "type": "integer", "default": 0 }, "example": 12, "description": "Identifiant du workflow à détailler. Laissez à 0 pour lister les workflows." }, { "in": "query", "name": "moduleName", "required": false, "schema": { "type": "string", "default": "" }, "example": "Accounts", "description": "Ne lister que les workflows de ce module (nom API)." }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer", "default": 0 }, "example": 0, "description": "Rang du premier workflow listé." }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "default": 20 }, "example": 20, "description": "Nombre maximal de workflows listés (1 à 100)." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Sans `workflowId` : `workflows`, `total`, `nextOffset` et `capabilities`. Avec `workflowId` : la définition complète du workflow, son rapport de lisibilité par l'éditeur, son contexte d'exécution, son historique et `capabilities`.", "type": "object", "properties": { "workflows": { "type": "array", "items": { "type": "object", "properties": { "workflowId": { "type": "integer" }, "module": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "active": { "type": "boolean" }, "protected": { "type": "boolean" }, "trigger": { "type": "integer" } } } }, "total": { "type": "integer" }, "nextOffset": { "type": "null" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "workflows": [ { "workflowId": 12, "module": "Accounts", "name": "Exemple", "description": "Ce que fait le workflow", "active": false, "protected": false, "trigger": 3 } ], "total": 1, "nextOffset": null } } } } } } } }, "/webservice.php?operation=workflow_run": { "post": { "operationId": "workflow_run", "tags": [ "Automatisation" ], "summary": "Exécuter un workflow sur des enregistrements", "description": "Exécute un workflow actif sur 1 à 100 enregistrements de son module, avec le moteur du déclencheur d'enregistrement : mêmes conditions, même suivi « une fois par enregistrement » (déclencheur 2) et mêmes tâches, exécutées comme lors d'un enregistrement, sous l'identité de l'administrateur actif. Un workflow manuel (déclencheur 7) ne s'exécute que par cette opération.\n\nPar défaut (`dryRun` à `true`), seules les conditions sont évaluées et rien n'est exécuté. Avec `dryRun` à `false`, les tâches sont exécutées et chaque exécution est journalisée (workflow, tâches, enregistrement, utilisateur, société, résultat).\n\nStatut par enregistrement : `wouldRun`, `executed`, `conditionsNotMet`, `alreadyCompleted`, `refused` (pas de droit de modification, ou enregistrement d'un autre module) ou `failed`.\n\nTout utilisateur authentifié peut l'appeler : les droits habituels sur les enregistrements s'appliquent. Un workflow inactif est refusé, et chaque identifiant ne doit apparaître qu'une fois.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "workflowId": { "type": "integer", "description": "Identifiant du workflow actif à exécuter.", "example": 12 }, "recordIds": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array", "items": { "type": "string" } }, "description": "Texte JSON (liste). Identifiants webservice des enregistrements (1 à 100, sans doublon), tous du module du workflow.", "example": "[\"6x101\",\"6x102\"]" }, "dryRun": { "type": "boolean", "default": true, "description": "`true` (par défaut) : évaluer les conditions sans rien exécuter. `false` : exécuter les tâches.", "example": true } }, "required": [ "workflowId", "recordIds" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le workflow, l'indicateur `dryRun`, le statut de chaque enregistrement, les tâches actives, l'identité d'exécution (`runsAs`) et une note d'information.", "type": "object", "properties": { "workflowId": { "type": "integer" }, "module": { "type": "string" }, "name": { "type": "string" }, "dryRun": { "type": "boolean" }, "records": { "type": "array", "items": { "type": "object", "properties": { "recordId": { "type": "string" }, "status": { "type": "string" } } } }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "integer" }, "type": { "type": "string" }, "summary": { "type": "string" } } } }, "runsAs": { "type": "object", "properties": { "userId": { "type": "integer" }, "userName": { "type": "string" } } }, "notice": { "type": "string" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "workflowId": 12, "module": "Accounts", "name": "Exemple", "dryRun": true, "records": [ { "recordId": "6x101", "status": "wouldRun" }, { "recordId": "6x102", "status": "conditionsNotMet" } ], "tasks": [ { "taskId": 31, "type": "VTUpdateFieldsTask", "summary": "Exemple d'affectation" } ], "runsAs": { "userId": 1, "userName": "Admin Exemple" }, "notice": "Dry run: conditions were evaluated, nothing was executed. Call again with dryRun false to execute." } } } } } } } }, "/webservice.php?operation=workflow_simulate": { "get": { "operationId": "workflow_simulate", "tags": [ "Automatisation" ], "summary": "Simuler les conditions d'un workflow", "description": "Évalue en lecture seule les conditions d'un workflow sur 1 à 20 enregistrements existants. Réservé aux administrateurs.\n\nLa réponse donne chaque condition (champs d'enregistrements liés compris, évalués par le moteur de workflow) et la correspondance globale, la révision et les tâches déclarées. Les tâches ne sont jamais exécutées, aucun e-mail n'est envoyé et les traitements liés à l'enregistrement ne sont pas simulés. Les expressions ou historiques d'événements non pris en charge sont explicitement refusés.\n\nTous les enregistrements de test doivent appartenir au module du workflow.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "workflowId", "required": true, "schema": { "type": "integer" }, "example": 12, "description": "Identifiant du workflow à simuler (actif ou non)." }, { "in": "query", "name": "recordIds", "required": true, "schema": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array", "items": { "type": "string" } } }, "example": "[\"6x101\",\"6x102\"]", "description": "Texte JSON (liste). Identifiants webservice des enregistrements de test (1 à 20), du module du workflow." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Pour chaque enregistrement : `conditionsMatch`, le détail des conditions et, pour un déclencheur « une fois », `onceAlreadyCompleted`. Avec la `revision`, l'état `active`, les tâches déclarées (`declaredTasks`), `actionsExecuted` à `false` et une note.", "type": "object", "properties": { "workflowId": { "type": "integer" }, "revision": { "type": "string" }, "active": { "type": "boolean" }, "records": { "type": "array", "items": { "type": "object", "properties": { "recordId": { "type": "string" }, "conditionsMatch": { "type": "boolean" }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "condition": { "type": "object", "properties": { "fieldname": { "type": "string" }, "operation": { "type": "string" }, "value": { "type": "string" }, "valuetype": { "type": "string" }, "groupid": { "type": "integer" } } }, "matches": { "type": "boolean" } } } }, "onceAlreadyCompleted": { "type": "null" } } } }, "actionsExecuted": { "type": "boolean" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "workflowId": 12, "revision": "3f9a1c0d5e7b...", "active": false, "records": [ { "recordId": "6x101", "conditionsMatch": true, "conditions": [ { "condition": { "fieldname": "accountname", "operation": "starts with", "value": "Exemple", "valuetype": "rawtext", "groupid": 0 }, "matches": true } ], "onceAlreadyCompleted": null } ], "actionsExecuted": false } } } } } } } }, "/webservice.php?operation=changePassword": { "post": { "operationId": "changePassword", "tags": [ "Administration" ], "summary": "Changer le mot de passe d'un utilisateur", "description": "Change le mot de passe d'un compte utilisateur. Un utilisateur peut changer le sien ; un administrateur peut changer celui de n'importe quel compte.\n\n- Pour un utilisateur non administrateur, l'ancien mot de passe est obligatoire et vérifié.\n- Le nouveau mot de passe doit respecter la règle de robustesse de l'instance et être identique à sa confirmation.\n\nUn changement refusé (mot de passe trop faible, confirmation différente, ancien mot de passe incorrect) retourne une erreur.", "x-kafinea-access": "user", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifiant webservice du compte utilisateur concerné.", "example": "19x5" }, "oldPassword": { "type": "string", "description": "Mot de passe actuel. Obligatoire sauf pour un administrateur." }, "newPassword": { "type": "string", "description": "Nouveau mot de passe, conforme à la règle de robustesse de l'instance." }, "confirmPassword": { "type": "string", "description": "Confirmation du nouveau mot de passe, identique à `newPassword`." } }, "required": [ "id", "newPassword", "confirmPassword" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Un message de confirmation.", "type": "object", "properties": { "message": { "type": "string" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "message": "Changed password successfully" } } } } } } } }, "/webservice.php?operation=deleteUser": { "post": { "operationId": "deleteUser", "tags": [ "Administration" ], "summary": "Supprimer un compte utilisateur", "description": "Supprime un compte utilisateur et transfère à un autre utilisateur la propriété de ses enregistrements. Réservé aux administrateurs.\n\nSi `newOwnerId` est vide, les enregistrements sont attribués à l'administrateur par défaut de l'instance. Erreur `INVALID_ID_ATTRIBUTE` lorsque `id` ne désigne pas un utilisateur.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifiant webservice du compte à supprimer.", "example": "19x7" }, "newOwnerId": { "type": "string", "description": "Identifiant webservice de l'utilisateur qui reprend les enregistrements du compte supprimé. Par défaut, l'administrateur principal.", "example": "19x1" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le statut de la suppression.", "type": "object", "properties": { "status": { "type": "string" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "status": "successful" } } } } } } } }, "/webservice.php?operation=instance_settings": { "get": { "operationId": "instance_settings", "tags": [ "Administration" ], "summary": "Lire les réglages d'instance", "description": "Lit les réglages d'instance exposés et leurs domaines de valeurs autorisés, avec le libellé que porte la fonctionnalité dans Paramètres > Fonctionnalités (dans la langue de l'utilisateur). Réservé aux administrateurs.\n\nLisez un réglage avant de le modifier avec `set_instance_setting`. Une clé inconnue ou non exposée n'est pas ignorée : elle est retournée dans `unknown`. Chaque réglage indique son type, son groupe, s'il est modifiable (`writable`), sa valeur courante et, selon le cas, ses valeurs autorisées (`values`), ses bornes (`min`, `max`) et `irreversible` lorsque la fonctionnalité ne peut plus être désactivée une fois activée.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "keys", "required": false, "schema": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array" }, "default": "[]" }, "example": "[\"FEATURE_GENERIC_PRODUCTS\"]", "description": "Texte JSON (liste). Clés des réglages à lire. Laissez vide pour lire tous les réglages exposés." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Les réglages demandés (`settings`) et les clés inconnues (`unknown`).", "type": "object", "properties": { "settings": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string" }, "group": { "type": "string" }, "writable": { "type": "boolean" }, "value": { "type": "string" }, "label": { "type": "string" } } } }, "unknown": { "type": "array" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "settings": [ { "key": "FEATURE_GENERIC_PRODUCTS", "type": "bool", "group": "GROUP_OTHER_FEATURES", "writable": true, "value": "1", "label": "Produits génériques" } ], "unknown": [] } } } } } } } }, "/webservice.php?operation=leave_balance_drift": { "get": { "operationId": "leave_balance_drift", "tags": [ "Administration" ], "summary": "Détecter les soldes de congés incohérents", "description": "Signale les soldes de congés dont les montants enregistrés diffèrent des totaux de leurs mouvements, sans rien modifier. Réservé aux administrateurs.\n\nChaque solde indique les montants enregistrés (`stored`) et ceux calculés d'après les mouvements (`fromMovements`), le nombre de mouvements, un conseil (`advice`) et une indication (`hint`) :\n\n- `no_movement` : le solde a été saisi à la main. Enregistrez le montant sous forme de mouvement, car un recalcul le mettrait à 0.\n- `repeated_movements` : un workflow s'est exécuté deux fois. Supprimez les mouvements répétés (`repeatedMovementIds`), le solde suit.\n- `recalculate` : le solde peut être recalculé.\n\nTransmettez ensuite les identifiants des soldes choisis à `leave_balance_recalculate`.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "personId", "required": false, "schema": { "type": "string", "default": "" }, "example": "46x12", "description": "Ne retenir que les soldes de cette personne (identifiant de l'enregistrement). Par défaut, toutes les personnes." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La liste des soldes incohérents et leur nombre.", "type": "object", "properties": { "balances": { "type": "array", "items": { "type": "object", "properties": { "balanceId": { "type": "integer" }, "personId": { "type": "integer" }, "typeId": { "type": "integer" }, "organizationId": { "type": "integer" }, "leaveYearStart": { "type": "string" }, "leaveYearEnd": { "type": "string" }, "stored": { "type": "object", "properties": { "posted": { "type": "integer" }, "reserved": { "type": "integer" }, "accrued": { "type": "integer" }, "consumed": { "type": "integer" } } }, "fromMovements": { "type": "object", "properties": { "posted": { "type": "number" }, "reserved": { "type": "integer" }, "accrued": { "type": "integer" }, "consumed": { "type": "number" } } }, "movements": { "type": "integer" }, "hint": { "type": "string" }, "repeatedMovementIds": { "type": "array" }, "advice": { "type": "string" } } } }, "total": { "type": "integer" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "balances": [ { "balanceId": 301, "personId": 12, "typeId": 4, "organizationId": 2, "leaveYearStart": "2026-06-01", "leaveYearEnd": "2027-05-31", "stored": { "posted": 25, "reserved": 0, "accrued": 25, "consumed": 0 }, "fromMovements": { "posted": 22.5, "reserved": 0, "accrued": 25, "consumed": 2.5 }, "movements": 6, "hint": "recalculate", "repeatedMovementIds": [], "advice": "Recalculate this balance." } ], "total": 1 } } } } } } } }, "/webservice.php?operation=leave_balance_recalculate": { "post": { "operationId": "leave_balance_recalculate", "tags": [ "Administration" ], "summary": "Recalculer des soldes de congés", "description": "Recalcule les soldes de congés indiqués à partir de leurs mouvements, un par un, et uniquement ceux-là. Réservé aux administrateurs. Il n'existe volontairement pas de recalcul global : un solde saisi à la main tomberait à 0 et un mouvement répété serait compté deux fois.\n\nUn solde sans aucun mouvement est refusé. La réponse contient `recalculated` (nouveaux montants et montants précédents) et `refused` (identifiant et raison). Cette opération modifie des données de ressources humaines : choisissez les soldes d'après `leave_balance_drift`, et au plus 100 à la fois.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "balanceIds": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "array", "items": { "type": "string" } }, "description": "Texte JSON (liste). Identifiants des soldes de congés à recalculer (1 à 100), issus de `leave_balance_drift`.", "example": "[301,302]" } }, "required": [ "balanceIds" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Les soldes recalculés, avec leurs montants précédents, et les soldes refusés avec la raison du refus." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=permissions_diagnostic": { "get": { "operationId": "permissions_diagnostic", "tags": [ "Administration" ], "summary": "Diagnostiquer les droits et les profils", "description": "Diagnostics en lecture seule des profils, rôles, groupes, règles de partage, accès par champ et par enregistrement, et des écarts entre les droits configurés et les droits effectivement appliqués. Réservé aux administrateurs actifs. Ne modifie aucun droit.\n\nLa réponse contient des constats et des problèmes. Un diagnostic refusé ou en échec n'est pas un contrôle d'accès réussi.\n\nActions disponibles : `diagnose_user`, `profile_details`, `module_access`, `list_users`, `list_all_profiles`, `list_all_roles`, `check_health`, `sharing_rules`, `list_groups`, `group_details`, `role_details`, `list_all_users`, `record_access`, `module_menu_visibility`, `default_org_sharing`, `module_utilities`, `field_access`, `profile_field_permissions`, `picklist_access`, `user_login_diagnostic`, `effective_role_chain`, `role_hierarchy`, `record_visibility`, `who_can_do`, `compare_profiles`, `user_privileges_dump`, `sharing_privileges_dump`, `tabdata_dump`, `flat_files_vs_db`, `flat_files_freshness` et `group`.\n\n`role_hierarchy` (avec `roleName` en option pour une sous-arborescence) retourne aussi `roles` : chaque rôle en profondeur d'abord, avec identifiant, nom, parent, profondeur, chemin, profils et utilisateurs, ainsi que `usersWithoutRole`. `record_visibility` (`userName` et `moduleName`) retourne `visibility` : l'étendue `none` (aucun accès au module), `all` (administrateur, vue ou modification globale, ou partage public) ou `owners` (les utilisateurs et groupes dont l'utilisateur voit les enregistrements dans les listes, avec la raison : lui-même, rôle subordonné, groupe ou règle de partage). Les modules Calendar et Events sont refusés.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "action", "required": false, "schema": { "type": "string", "enum": [ "diagnose_user", "profile_details", "module_access", "list_users", "list_all_profiles", "list_all_roles", "check_health", "sharing_rules", "list_groups", "group_details", "role_details", "list_all_users", "record_access", "module_menu_visibility", "default_org_sharing", "module_utilities", "field_access", "profile_field_permissions", "picklist_access", "user_login_diagnostic", "effective_role_chain", "role_hierarchy", "record_visibility", "who_can_do", "compare_profiles", "user_privileges_dump", "sharing_privileges_dump", "tabdata_dump", "flat_files_vs_db", "flat_files_freshness", "group" ], "default": "diagnose_user" }, "example": "diagnose_user", "description": "Diagnostic à exécuter (par défaut `diagnose_user`)." }, { "in": "query", "name": "parameters", "required": false, "schema": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "default": "[]" }, "example": "{\"userName\":\"jdupont\",\"moduleName\":\"Invoice\"}", "description": "Texte JSON (objet). Entrées nommées du diagnostic, toutes de type texte : `userName`, `moduleName`, `profileName`, `profileName2`, `roleName`, `groupName`, `subjectType`, `subjectName`, `recordNumber`, `accessType`, `fieldName`, `blockName`, `actionName`. `userName` accepte aussi un identifiant d'utilisateur (`5` ou `19x5`), `roleName` un identifiant de rôle (`H7`). Cherchez les noms avant de diagnostiquer. La clé `action` n'est pas acceptée ici." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Les constats et problèmes du diagnostic demandé ; la forme dépend de `action`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=profile_configuration": { "get": { "operationId": "profile_configuration", "tags": [ "Administration" ], "summary": "Lire la configuration d'un profil sur un module", "description": "Lit la configuration d'un profil pour un module : révision, accès au module, état de chaque champ (masqué, lecture seule, modifiable), actions autorisées, droits globaux et rôles liés. Réservé aux administrateurs.\n\nRetrouvez les identifiants de profil avec `permissions_diagnostic` (`list_all_profiles`). Les droits configurés ne sont pas les droits effectifs d'un utilisateur : diagnostiquez aussi l'utilisateur concerné. La `revision` retournée est à transmettre à `profile_configure`.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "profileId", "required": true, "schema": { "type": "integer" }, "example": 4, "description": "Identifiant du profil." }, { "in": "query", "name": "moduleName", "required": true, "schema": { "type": "string" }, "example": "Invoice", "description": "Nom API du module (actif)." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La configuration du profil pour le module, avec sa `revision`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=profile_configure": { "post": { "operationId": "profile_configure", "tags": [ "Administration" ], "summary": "Modifier les droits d'un profil sur un module", "description": "Met à jour un profil existant pour un module, par le même chemin que l'écran des paramètres, avec la révision relue et la régénération des droits appliqués. Réservé aux administrateurs.\n\n- Les droits de champ non cités restent inchangés.\n- Un champ obligatoire ne peut pas être masqué ni passé en lecture seule.\n- Le droit d'enregistrement (`Save`) est déduit de `Create` et `Edit`.\n- Le profil 1, les modules système et les modules de calendrier couplés ne se modifient que depuis l'écran des paramètres.\n- La réponse `applied: true` avec `success: false` signifie que la base est enregistrée mais que la régénération des droits appliqués a échoué.\n\nVérifiez ensuite l'accès effectif de l'utilisateur concerné avec `permissions_diagnostic`.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "configure", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "profileId": { "type": "integer", "description": "Identifiant du profil à modifier.", "example": 4 }, "moduleName": { "type": "string", "description": "Nom API du module concerné.", "example": "Invoice" }, "revision": { "type": "string", "description": "Révision lue avec `profile_configuration`. Elle est refusée si le profil a changé entre-temps : relisez-le alors.", "example": "9c1e7a..." }, "changes": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "description": "Texte JSON (objet). Modifications explicites (200 au plus) : `moduleAllowed` (booléen), `fields` (objet associant un nom de champ à `hidden`, `read` ou `write`) et `actions` (objet associant un nom d'action à un booléen).", "example": "{\"moduleAllowed\":true,\"fields\":{\"description\":\"read\"},\"actions\":{\"Delete\":false}}" } }, "required": [ "profileId", "moduleName", "revision", "changes" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La configuration après modification, avec sa nouvelle `revision`." } } }, { "$ref": "#/components/schemas/Erreur" } ] } } } } } } }, "/webservice.php?operation=set_instance_setting": { "post": { "operationId": "set_instance_setting", "tags": [ "Administration" ], "summary": "Modifier un réglage d'instance", "description": "Modifie un réglage d'instance déclaré. Réservé aux administrateurs. Un seul réglage par appel : chaque appel écrit, ou explique pourquoi il ne l'a pas fait.\n\n- La valeur est validée selon le domaine déclaré pour la clé ; une valeur hors domaine est refusée, jamais remplacée par une valeur par défaut.\n- L'opération est idempotente : demander l'état qu'a déjà le réglage retourne `changed: false`.\n- Une fonctionnalité irréversible ne peut pas être désactivée une fois activée, comme à l'écran.\n- Une clé non exposée est refusée ; la liste des clés valides vient de `instance_settings`.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "configure", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Clé du réglage, telle que retournée par `instance_settings`.", "example": "FEATURE_GENERIC_PRODUCTS" }, "value": { "type": "string", "description": "Nouvelle valeur, au type déclaré pour la clé (par exemple `0` ou `1` pour un booléen).", "example": "1" } }, "required": [ "key", "value" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La clé, son type, la valeur précédente, la nouvelle valeur et `changed`.", "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string" }, "previous": { "type": "string" }, "value": { "type": "string" }, "changed": { "type": "boolean" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "key": "FEATURE_GENERIC_PRODUCTS", "type": "bool", "previous": "0", "value": "1", "changed": true } } } } } } } }, "/webservice.php?operation=smtp_settings_configure": { "post": { "operationId": "smtp_settings_configure", "tags": [ "Administration" ], "summary": "Modifier le serveur de messagerie sortante", "description": "Modifie les réglages du serveur de messagerie sortante, comme l'écran « Serveur sortant ». Réservé aux administrateurs.\n\nLes nouveaux réglages sont vérifiés par une connexion (avec authentification) au serveur, sans envoyer de message : une connexion refusée n'enregistre rien et retourne la raison donnée par le serveur. Les réglages omis sont conservés, ainsi que le mot de passe s'il est omis ou vide. Le serveur est obligatoire.\n\nTous les e-mails de l'instance passent par ce serveur : une erreur de réglage les bloque. Confirmez ensuite avec `smtp_test`.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "configure", "requestBody": { "required": false, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "settings": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object", "properties": { "server": { "type": "string" }, "serverPort": { "type": [ "integer", "string" ] }, "username": { "type": "string" }, "smtpAuth": { "type": [ "boolean", "string" ] }, "fromEmail": { "type": "string" } }, "additionalProperties": false }, "default": "[]", "description": "Texte JSON (objet). Réglages à modifier : `server` (hôte ou hôte:port, préfixe `tls://` pour STARTTLS, `ssl://` pour SSL), `serverPort`, `username`, `smtpAuth` (authentification activée) et `fromEmail` (adresse imposée comme expéditeur, ou vide pour envoyer depuis l'adresse de l'utilisateur). Les réglages omis sont conservés.", "example": "{\"server\":\"tls://smtp.exemple.fr\",\"serverPort\":587,\"username\":\"envoi@exemple.fr\",\"smtpAuth\":true,\"fromEmail\":\"ne-pas-repondre@exemple.fr\"}" }, "password": { "type": "string", "default": "", "description": "Mot de passe du serveur, en écriture seule : omis ou vide, il conserve le mot de passe enregistré. Il est stocké protégé et n'est jamais retourné." } } } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Les réglages comme `smtp_settings_read` les retourne, et `changed` : la liste des réglages modifiés.", "type": "object", "properties": { "configured": { "type": "boolean" }, "server": { "type": "string" }, "serverPort": { "type": "integer" }, "username": { "type": "string" }, "smtpAuth": { "type": "boolean" }, "fromEmail": { "type": "string" }, "passwordSet": { "type": "boolean" }, "changed": { "type": "array", "items": { "type": "string" } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "configured": true, "server": "tls://smtp.exemple.fr", "serverPort": 587, "username": "envoi@exemple.fr", "smtpAuth": true, "fromEmail": "ne-pas-repondre@exemple.fr", "passwordSet": true, "changed": [ "serverPort" ] } } } } } } } }, "/webservice.php?operation=smtp_settings_read": { "get": { "operationId": "smtp_settings_read", "tags": [ "Administration" ], "summary": "Lire le serveur de messagerie sortante", "description": "Lit les réglages du serveur de messagerie sortante. Réservé aux administrateurs. Le mot de passe n'est jamais retourné : `passwordSet` indique seulement si un mot de passe est enregistré.\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "read", "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le serveur (hôte:port, préfixe `tls://` pour TLS), le port, l'utilisateur, l'authentification, l'adresse d'expédition imposée, `configured` et `passwordSet`.", "type": "object", "properties": { "configured": { "type": "boolean" }, "server": { "type": "string" }, "serverPort": { "type": "integer" }, "username": { "type": "string" }, "smtpAuth": { "type": "boolean" }, "fromEmail": { "type": "string" }, "passwordSet": { "type": "boolean" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "configured": true, "server": "tls://smtp.exemple.fr", "serverPort": 587, "username": "envoi@exemple.fr", "smtpAuth": true, "fromEmail": "ne-pas-repondre@exemple.fr", "passwordSet": true } } } } } } } }, "/webservice.php?operation=smtp_test": { "post": { "operationId": "smtp_test", "tags": [ "Administration" ], "summary": "Envoyer un e-mail de test", "description": "Envoie un message de diagnostic par le serveur sortant, comme le bouton de test de l'écran des paramètres. Réservé aux administrateurs. Cette opération envoie un vrai e-mail : vérifiez le destinataire.\n\nLa réponse indique le succès, le message d'erreur du serveur le cas échéant, et `logRecordId`, l'identifiant du journal technique (échange SMTP, identifiants masqués).\n\n> Réservée aux administrateurs de l'instance.", "x-badges": [ { "name": "Administrateur", "color": "var(--scalar-color-orange)" } ], "x-kafinea-access": "admin", "x-kafinea-scope": "configure", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "recipient": { "type": "string", "description": "Destinataire explicite du message de test.", "example": "technique@exemple.fr" }, "sender": { "type": "string", "enum": [ "default", "user", "support" ], "default": "default", "description": "Adresse d'expédition : `default` (la vôtre), `user` (celle de l'utilisateur `senderUserId`) ou `support` (l'adresse de support de l'instance).", "example": "default" }, "senderUserId": { "type": "string", "default": "", "description": "Identifiant numérique de l'utilisateur expéditeur, pour `sender` à `user`.", "example": "5" } }, "required": [ "recipient" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le succès, le message du serveur, l'identifiant du journal technique, l'expéditeur utilisé et le destinataire.", "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "logRecordId": { "type": "integer" }, "from": { "type": "string" }, "destination": { "type": "string" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "success": true, "message": "", "logRecordId": 8812, "from": "admin@exemple.fr", "destination": "technique@exemple.fr" } } } } } } } }, "/webservice.php?operation=user_preferences_update": { "post": { "operationId": "user_preferences_update", "tags": [ "Administration" ], "summary": "Modifier les préférences d'un utilisateur", "description": "Modifie les préférences d'affichage d'un compte utilisateur (fuseau horaire, langue, formats de date, d'heure et de nombre), comme l'écran « Mes préférences ». Rien d'autre sur le compte (rôle, droit d'administration, statut, mot de passe) ne peut être modifié ici.\n\nSans `userId`, la modification porte sur votre propre compte ; modifier le compte d'un autre utilisateur exige d'être administrateur. Les valeurs sont celles de l'écran des préférences (consultez la description du module `Users` pour les listes). Une préférence déjà à la valeur demandée est retournée dans `unchanged`.", "x-kafinea-access": "user", "x-kafinea-scope": "write", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "preferences": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "description": "Texte JSON (objet). Préférences à modifier, sous forme de champ => valeur parmi `time_zone`, `language`, `date_format`, `hour_format`, `currency_grouping_pattern`, `currency_decimal_separator`, `currency_grouping_separator`, `currency_symbol_placement`, `no_of_currency_decimals` et `truncate_trailing_zeros`.", "example": "{\"time_zone\":\"Europe/Paris\",\"language\":\"fr_fr\",\"hour_format\":\"24\"}" }, "userId": { "type": "string", "default": "", "description": "Identifiant webservice du compte à modifier. Vide pour votre propre compte ; un autre compte exige un administrateur.", "example": "19x5" } }, "required": [ "preferences" ] } } } }, "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le compte modifié, les préférences modifiées (`updated`), celles déjà à la valeur demandée (`unchanged`) et l'ensemble des préférences obtenues.", "type": "object", "properties": { "userId": { "type": "string" }, "updated": { "type": "object", "properties": { "time_zone": { "type": "string" } } }, "unchanged": { "type": "array", "items": { "type": "string" } }, "preferences": { "type": "object", "properties": { "time_zone": { "type": "string" }, "language": { "type": "string" }, "date_format": { "type": "string" }, "hour_format": { "type": "string" }, "currency_grouping_pattern": { "type": "string" }, "currency_decimal_separator": { "type": "string" }, "currency_grouping_separator": { "type": "string" }, "currency_symbol_placement": { "type": "string" }, "no_of_currency_decimals": { "type": "string" }, "truncate_trailing_zeros": { "type": "string" } } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "userId": "19x5", "updated": { "time_zone": "Europe/Paris" }, "unchanged": [ "language", "hour_format" ], "preferences": { "time_zone": "Europe/Paris", "language": "fr_fr", "date_format": "dd-mm-yyyy", "hour_format": "24", "currency_grouping_pattern": "123,456,789", "currency_decimal_separator": ",", "currency_grouping_separator": " ", "currency_symbol_placement": "1.0$", "no_of_currency_decimals": "2", "truncate_trailing_zeros": "0" } } } } } } } } }, "/webservice.php?operation=list_operations": { "get": { "operationId": "list_operations", "tags": [ "Assistant et découverte" ], "summary": "Découvrir les opérations disponibles", "description": "Renvoie le catalogue des opérations proposées aux assistants et aux intégrations : nom, catégorie (`scope` : `read`, `write` ou `configure`) et description. Sans `operationName`, la réponse est paginée et résumée ; avec un nom exact, elle contient le schéma complet de l'opération (`inputSchema`). Une opération liée à une fonction désactivée sur l'instance n'est pas listée.\n\n- `query` filtre sur le nom et la description : tous les mots saisis doivent apparaître.\n- `scope` restreint à une catégorie.\n- `detail` vaut `summary` (défaut) ou `full` pour inclure les schémas.\n- `limit` va de 1 à 100 et `offset` est positif ou nul ; `query` ne dépasse pas 200 caractères. Des filtres hors bornes sont refusés.\n- Un nom d'opération inconnu est refusé.\n\nLa réponse contient aussi le catalogue des guides lisibles avec `read_skill` (`skills`).", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "operationName", "required": false, "schema": { "type": "string", "default": "" }, "example": "customview_list", "description": "Nom exact d'une opération pour obtenir son schéma complet. Vide : résumé paginé du catalogue." }, { "in": "query", "name": "query", "required": false, "schema": { "type": "string", "default": "" }, "example": "liste", "description": "Mots recherchés dans le nom et la description des opérations (200 caractères au plus)." }, { "in": "query", "name": "scope", "required": false, "schema": { "type": "string", "default": "" }, "example": "read", "description": "Catégorie à lister : `read`, `write` ou `configure`. Vide : toutes." }, { "in": "query", "name": "detail", "required": false, "schema": { "type": "string", "default": "summary" }, "example": "summary", "description": "Niveau de détail : `summary` (défaut) ou `full` (avec les schémas de paramètres)." }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "default": 50 }, "description": "Nombre d'opérations par page, de 1 à 100." }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Rang de la première opération de la page." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "`operations` : opérations de la page, indexées par nom. `total` : nombre d'opérations correspondantes. `nextOffset` : décalage de la page suivante, ou `null`. `skills` : guides disponibles. Le membre `success` est repris dans le résultat.", "type": "object", "properties": { "success": { "type": "boolean" }, "operations": { "type": "object", "properties": { "customview_list": { "type": "object", "properties": { "scope": { "type": "string" }, "description": { "type": "string" } } } } }, "total": { "type": "integer" }, "nextOffset": { "type": "null" }, "skills": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "uri": { "type": "string" }, "requiredOperations": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "success": true, "operations": { "customview_list": { "scope": "read", "description": "The list views (filters) of a module the connected user may open." } }, "total": 1, "nextOffset": null, "skills": [ { "slug": "working-with-kafinea", "title": "Travailler avec Kafinea", "description": "Guide général de l'API.", "uri": "kafinea://skills/working-with-kafinea", "requiredOperations": [ "list_operations" ] } ] } } } } } } } }, "/webservice.php?operation=read_skill": { "get": { "operationId": "read_skill", "tags": [ "Assistant et découverte" ], "summary": "Lire un guide partagé", "description": "Renvoie le texte d'un guide métier partagé, à partir de son identifiant (`slug`) découvert dans le membre `skills` de `list_operations`. Un guide dont une opération requise n'est pas disponible sur l'instance, ou un identifiant inconnu, est refusé.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "slug", "required": true, "schema": { "type": "string" }, "example": "working-with-kafinea", "description": "Identifiant du guide, tel que renvoyé par `list_operations`." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Le texte du guide, au format Markdown.", "type": "object", "properties": { "content": { "type": "string" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "content": "# Travailler avec Kafinea\n\n..." } } } } } } } }, "/webservice.php?operation=search_documentation": { "get": { "operationId": "search_documentation", "tags": [ "Assistant et découverte" ], "summary": "Rechercher dans la documentation publiée", "description": "Recherche dans les articles de la documentation publique livrée avec l'instance, à partir de termes métier. La recherche porte sur le titre et le contenu ; les titres pèsent davantage dans le classement.\n\nChaque résultat donne le titre, l'identifiant (`slug`, à passer à `read_documentation`), l'adresse de l'article sur le site, l'URI interne et un extrait. Les extraits ne remplacent pas l'article : lisez-le en entier avant de vous y fier. La documentation décrit l'interface et ne garantit pas qu'une opération d'API équivalente existe : consultez `list_operations` avant de promettre une action.\n\nLimites : `query` de 300 caractères au plus, `limit` de 1 à 10, `offset` de 0 à 10000. Des valeurs hors bornes sont refusées.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "query", "required": false, "schema": { "type": "string", "default": "" }, "example": "avoir de facture", "description": "Termes recherchés. Vide : liste des articles dans l'ordre alphabétique des identifiants." }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "default": 5 }, "description": "Nombre de résultats par page, de 1 à 10." }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Rang du premier résultat de la page." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "La requête, le nombre total de résultats (`total`), la page de résultats (`results`) et `nextOffset` (`null` à la dernière page).", "type": "object", "properties": { "query": { "type": "string" }, "total": { "type": "integer" }, "offset": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "uri": { "type": "string" }, "onlineVerified": { "type": "boolean" }, "excerpt": { "type": "string" } } } }, "nextOffset": { "type": "null" }, "source": { "type": "string" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "query": "avoir de facture", "total": 1, "offset": 0, "results": [ { "slug": "creer-un-avoir", "title": "Créer un avoir", "url": "https://www.kafinea.com/fr/documentation/ventes/creer-un-avoir/", "uri": "kafinea://documentation/creer-un-avoir", "onlineVerified": false, "excerpt": "Un avoir annule tout ou partie d'une facture..." } ], "nextOffset": null, "source": "Shipped public documentation; UI instructions do not imply MCP action availability." } } } } } } } }, "/webservice.php?operation=read_documentation": { "get": { "operationId": "read_documentation", "tags": [ "Assistant et découverte" ], "summary": "Lire un article de la documentation", "description": "Renvoie le contenu d'un article de la documentation publique, par tranches de caractères. L'identifiant (`slug`) vient de `search_documentation`.\n\n- `length` va de 1 à 20000 caractères (12000 par défaut) ; `offset` est positif ou nul et ne dépasse pas la longueur de l'article.\n- Tant que `nextOffset` n'est pas `null`, rappelez l'opération avec cette valeur pour `offset`.\n- `sha256` est l'empreinte de l'article entier : elle permet de vérifier que deux lectures successives portent sur la même version.\n- Un identifiant mal formé ou inconnu est refusé.\n\nLes liens internes de l'article sont convertis en adresses du site lorsque l'article cible est publié, et `relatedArticles` les liste.", "x-kafinea-access": "user", "x-kafinea-scope": "read", "parameters": [ { "in": "query", "name": "slug", "required": true, "schema": { "type": "string" }, "example": "creer-un-avoir", "description": "Identifiant de l'article, tel que renvoyé par `search_documentation`." }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Position du premier caractère à lire (0 pour le début)." }, { "in": "query", "name": "length", "required": false, "schema": { "type": "integer", "default": 12000 }, "description": "Nombre de caractères à lire, de 1 à 20000." } ], "responses": { "200": { "description": "Enveloppe de réponse : `result` si `success` vaut `true`, sinon `error`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "type": "boolean", "const": true }, "result": { "description": "Les métadonnées de l'article (`slug`, `title`, `url`, `uri`, `relatedArticles`), la tranche de contenu lue et les éléments de pagination (`offset`, `totalCharacters`, `nextOffset`, `sha256`).", "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "uri": { "type": "string" }, "onlineVerified": { "type": "boolean" }, "relatedArticles": { "type": "array" }, "content": { "type": "string" }, "offset": { "type": "integer" }, "totalCharacters": { "type": "integer" }, "nextOffset": { "type": "null" }, "sha256": { "type": "string" } } } } }, { "$ref": "#/components/schemas/Erreur" } ] }, "example": { "success": true, "result": { "slug": "creer-un-avoir", "title": "Créer un avoir", "url": "https://www.kafinea.com/fr/documentation/ventes/creer-un-avoir/", "uri": "kafinea://documentation/creer-un-avoir", "onlineVerified": false, "relatedArticles": [], "content": "Un avoir annule tout ou partie d'une facture...", "offset": 0, "totalCharacters": 2480, "nextOffset": null, "sha256": "9f2c1e5a7d3b4c68a0e1f2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f7" } } } } } } } } }, "components": { "securitySchemes": { "session": { "type": "apiKey", "in": "query", "name": "sessionName", "description": "Identifiant de session renvoyé par `login`. Il peut aussi être envoyé dans le corps d'une requête POST." } }, "schemas": { "Erreur": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Code stable de l'erreur, par exemple `ACCESS_DENIED` ou `INVALID_SESSIONID`." }, "message": { "type": "string", "description": "Message lisible, en anglais." } } } } } } } }