---
title: API REST – Approbations
description: "L'API couvre tout le cycle des [approbations](https://www.kafinea.com/fr/documentation/automatisation/les-approbations/) : configurer le circuit d'un module, demander l'approbation d'une fiche, répondre aux étapes et suivre les demandes. Les contrôles sont ceux des écrans : ce qu'un écran refuse, l'API le refuse avec le…"
url: "https://www.kafinea.com/fr/documentation/api/api-rest-approbations/"
updated: "2026-10-29"
category: Intégrations / API
---

# API REST – Approbations

L'API couvre tout le cycle des [approbations](https://www.kafinea.com/fr/documentation/automatisation/les-approbations/) : configurer le circuit d'un module, demander l'approbation d'une fiche, répondre aux étapes et suivre les demandes. Les contrôles sont ceux des écrans : ce qu'un écran refuse, l'API le refuse avec le même motif. Les mêmes opérations sont proposées à l'assistant IA de Kafinea et aux assistants [connectés à Kafinea](https://www.kafinea.com/fr/documentation/intelligence-artificielle/connecter-une-ia-externe-mcp/).

Toutes utilisent la session de l'[API REST](https://www.kafinea.com/fr/documentation/api/api-rest-introduction/). Les identifiants sont ceux de l'API (`89x47808`) ; un simple numéro est aussi accepté.

| Opération | Méthode | Qui | Effet |
| --- | --- | --- | --- |
| `approval_circuit_read` | GET | administrateur | Les circuits, ou le circuit d'un module avec ses modèles et le format attendu |
| `approval_circuit_configure` | POST | administrateur | Vérifier, enregistrer, activer, désactiver ou supprimer un circuit |
| `approval_circuit_simulate` | GET | administrateur | Ce qu'un circuit demanderait pour 1 à 20 fiches, sans rien enregistrer |
| `approval_inbox` | GET | chacun | Ce qui attend sa réponse, ses demandes, les demandes des autres qu'il peut consulter |
| `approval_request_read` | GET | chacun | L'approbation d'une fiche, telle que son panneau la montre |
| `approval_request` | POST | chacun | Demander l'approbation d'une fiche qu'il peut modifier |
| `approval_answer` | POST | l'approbateur | Sa propre réponse à une étape qui lui est confiée |
| `approval_cancel` | POST | demandeur ou administrateur | Annuler une demande en attente |

Les opérations des demandes et des réponses sont disponibles quand la fonctionnalité **Approbations** est active.

---

## 1. Configurer un circuit

`approval_circuit_read` sans paramètre liste les circuits et les modules qui peuvent en recevoir un. Avec `moduleName`, il renvoie le circuit du module (`circuit`, avec sa `revision`), les modèles de départ (`templates`) et le format d'un circuit (`contract`).

```bash
curl -G 'https://apps.kafinea.com/YourKafinea/webservice.php' 
  --data-urlencode 'operation=approval_circuit_read' 
  --data-urlencode 'sessionName=YOUR_SESSION_ID' 
  --data-urlencode 'moduleName=Quotes'
```

Un circuit se décrit en entier :

```json
{
  "label": "Devis au-delà de 5 000 € HT",
  "active": true,
  "condition": [{"fieldname": "pre_tax_total", "operation": "greater than", "value": "5000", "groupid": "0"}],
  "finalizeOnApproval": true,
  "steps": [{
    "label": "Responsable commercial",
    "condition": [],
    "approver": {"mode": "manager", "managerOf": "requester"},
    "dueDays": 2,
    "summaryTemplate": "Devis $subject : $pre_tax_total € HT"
  }]
}
```

| Élément | Contenu |
| --- | --- |
| `condition` | Les fiches qui doivent être approuvées, au format des conditions des flux de travail ; `[]` pour toutes. `groupid` `0` : tous ces critères ; `1` : au moins l'un d'eux |
| `steps[].approver` | `fixed` avec `ownerId` (un utilisateur ou un groupe), `manager` avec `managerOf` (`requester` ou `owner`), ou `field` avec `expression` (par exemple `assigned_user_id`) |
| `steps[].condition` | Facultative : une étape dont la condition n'est pas remplie est passée |
| `steps[].stepId` | À renvoyer tel que lu : les demandes déjà faites continuent de nommer leur étape |
| `watchedFields` | Les champs dont la modification après l'approbation la rend caduque, en plus de ceux que lisent les conditions (toujours surveillés) ; `watchedLabels` les liste tous, avec leur libellé |

`approval_circuit_configure` reçoit `moduleName`, `action` et, selon l'action, `definition` (le circuit en JSON) et `revision` :

| `action` | Effet |
| --- | --- |
| `validate` | Vérifie `definition` sans rien enregistrer et renvoie `valid` et la liste `problems` (chacun avec `path`, `code` et `message`) |
| `save` | Enregistre `definition` en entier ; `revision` est celle lue, `0` pour créer le circuit d'un module qui n'en a pas |
| `activate`, `deactivate` | Active ou désactive le circuit de la `revision` lue |
| `delete` | Supprime le circuit ; les demandes déjà faites restent |

```bash
curl -X POST 'https://apps.kafinea.com/YourKafinea/webservice.php' 
  --data-urlencode 'operation=approval_circuit_configure' 
  --data-urlencode 'sessionName=YOUR_SESSION_ID' 
  --data-urlencode 'moduleName=Quotes' 
  --data-urlencode 'action=save' 
  --data-urlencode 'revision=3' 
  --data-urlencode 'definition={"label":"Devis au-delà de 5 000 € HT","active":true,…}'
```

Un circuit actif doit pouvoir être approuvé : chaque étape a un approbateur valable. Un circuit inactif peut rester un brouillon.

Avant d'activer, `approval_circuit_simulate` montre, pour des fiches enregistrées (`recordIds`, une liste JSON) et un demandeur (`requesterId`, l'utilisateur connecté par défaut), si la condition du circuit est remplie et qui serait sollicité à chaque étape, ou pourquoi personne ne pourrait répondre (`error`). Passez `definition` pour tester un circuit avant de l'enregistrer. Rien n'est enregistré ni envoyé.

---

## 2. Demander, répondre, suivre

`approval_inbox` renvoie, selon `box` : `toAnswer` (les étapes qui attendent la réponse de l'utilisateur, directement ou par l'un de ses groupes), `requested` (ses demandes) ou `others` (les autres demandes en attente qu'il peut consulter). Sans `box`, les trois. Chaque étape à traiter porte son `lineId`.

`approval_request_read` avec `recordId` renvoie la demande en cours de la fiche, ses étapes (approbateur, réponse, motif, `canAnswer` pour celle à laquelle l'utilisateur peut répondre) et `wouldAsk` : ce qu'une nouvelle demande solliciterait.

`approval_request` avec `recordId` demande l'approbation au nom de l'utilisateur connecté. Elle est refusée quand rien ne demande d'approbation ou qu'une demande attend déjà.

`approval_answer` reçoit `lineId`, `answer` (`approve`, `refuse` ou `changes`) et `reason`, obligatoire pour refuser ou demander des modifications :

```bash
curl -X POST 'https://apps.kafinea.com/YourKafinea/webservice.php' 
  --data-urlencode 'operation=approval_answer' 
  --data-urlencode 'sessionName=YOUR_SESSION_ID' 
  --data-urlencode 'lineId=194x48180' 
  --data-urlencode 'answer=approve'
```

La réponse est toujours celle de l'utilisateur connecté : aucun paramètre ne désigne un autre utilisateur. Elle est refusée quand l'étape n'est pas confiée à cet utilisateur ou à l'un de ses groupes (administrateurs compris), quand c'est sa propre demande, ou quand un autre membre du groupe a déjà répondu.

`approval_cancel` avec `approvalId` annule une demande en attente : son demandeur ou un administrateur.

---

## 3. Le statut d'approbation des fiches

Chaque fiche d'un module qui a un circuit porte le champ en lecture seule `mdsapprovalstatus` : vide tant qu'aucune approbation n'a été demandée, puis `APPROVAL_STATUS_PENDING`, `APPROVAL_STATUS_APPROVED`, `APPROVAL_STATUS_REFUSED`, `APPROVAL_STATUS_CHANGES_REQUESTED`, `APPROVAL_STATUS_CANCELLED` ou `APPROVAL_STATUS_OBSOLETE` (approbation caduque). Il se lit comme tout champ, avec `retrieve` ou `query` :

```bash
curl -G 'https://apps.kafinea.com/YourKafinea/webservice.php' 
  --data-urlencode 'operation=query' 
  --data-urlencode 'sessionName=YOUR_SESSION_ID' 
  --data-urlencode "query=SELECT potentialname, amount FROM Potentials WHERE mdsapprovalstatus = 'APPROVAL_STATUS_APPROVED';"
```

Seules les approbations l'écrivent. Une approbation devient caduque quand un champ surveillé de la fiche change ensuite ; la demande garde alors le motif dans sa description.

---

## 4. Refus

Un refus commence par son code, suivi du motif lisible :

| Code | Signification |
| --- | --- |
| `APPROVAL_CIRCUIT_INVALID` | Le circuit n'est pas valable ; chaque problème suit, une ligne par problème, avec son chemin et son code |
| `APPROVAL_CIRCUIT_REVISION_CHANGED` | Le circuit a changé depuis sa lecture : relisez-le, puis refaites la modification |
| `APPROVAL_CIRCUIT_NOT_FOUND`, `APPROVAL_CIRCUIT_EXISTS` | Le module n'a pas de circuit, ou en a déjà un |
| `APPROVAL_REFUSED` | La demande, la réponse ou l'annulation n'est pas permise ; le motif est celui que l'écran affiche |
| `APPROVAL_FEATURE_DISABLED` | La fonctionnalité **Approbations** n'est pas active |
| `ACCESS_DENIED` | L'opération est réservée aux administrateurs |