API REST – Approbations

L’API couvre tout le cycle des 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.

Toutes utilisent la session de l’API REST. Les identifiants sont ceux de l’API (89x47808) ; un simple numéro est aussi accepté.

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).

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 :

{
  "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"
  }]
}

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

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 :

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 :

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 :