API REST – Opérations CRUD

---

ListTypes – Lister les modules disponibles #

Cette opération retourne tous les modules accessibles via l’API.

GET https://apps.kafinea.com/{instance}/webservice.php

Exemple curl :

curl "https://apps.kafinea.com/YourKafinea/webservice.php?operation=listtypes&sessionName=YOUR_SESSION_ID"

---

Describe – Décrire un module #

Cette opération permet de connaître les champs d’un module (type, caractère obligatoire) et les actions disponibles.

GET https://apps.kafinea.com/{instance}/webservice.php

Exemple curl :

curl "https://apps.kafinea.com/YourKafinea/webservice.php?operation=describe&sessionName=YOUR_SESSION_ID&elementType=Contacts"

---

Retrieve – Récupérer une entité #

Récupère une entité spécifique par son ID Webservice (ex : 21x3456).

GET https://apps.kafinea.com/{instance}/webservice.php

Exemple curl :

curl "https://apps.kafinea.com/YourKafinea/webservice.php?operation=retrieve&sessionName=YOUR_SESSION_ID&id=21x3456"

Bons de réduction répartis sur les lignes #

La lecture détaillée d’un devis, d’un bon de commande ou d’une facture directement importé d’une boutique peut contenir une propriété supplémentaire en lecture seule. Elle est disponible dans les réponses détaillées de retrieve, retrieve_inventory, create, update et revise lorsque les droits de lecture du document et de sa remise le permettent. Les réponses de liste n’en contiennent pas.

{
  "LineItems": [{"id": "31x12345", "discount_amount": "9.11"}],
  "OnlineStoreVoucherAudit": [{
    "lineItemId": "31x12345",
    "mdsdiscountbeforevoucheramount": "2.00",
    "mdsdiscountbeforevoucherpercent": null,
    "mdsvoucherdiscountamount": "7.11",
    "mdsvoucherdiscountamountttc": "7.50",
    "mdsvoucherlabel": "BIENVENUE10",
    "isCurrent": true
  }]
}

Rapprochez lineItemId et l’identifiant de la ligne. Les montants sont des chaînes décimales dans la devise du document : la remise article et la part du bon sont hors taxes, la part TTC inclut la taxe. Ces valeurs décrivent l’import ; isCurrent indique si la remise actuelle de la ligne correspond encore à leur somme. Pour un PDF externe, vous pouvez afficher « Bon de réduction BIENVENUE10 : −7,50 € TTC » sur cette ligne lorsque isCurrent est vrai. La remise native de la ligne contient déjà cette part : ne la soustrayez pas une seconde fois. Cette propriété ne peut être ni créée ni modifiée par l’API.

---

Create – Créer une entité #

Crée une nouvelle entité dans un module. Tous les champs obligatoires doivent être inclus. Les valeurs de champs liées à d’autres modules doivent utiliser le format Webservice IDs (ex : 21x3456).

POST https://apps.kafinea.com/{instance}/webservice.php

Exemple curl :

curl -X POST https://apps.kafinea.com/YourKafinea/webservice.php \
  -d "operation=create" \
  -d "sessionName=YOUR_SESSION_ID" \
  -d 'element={"lastname":"Dupont","email":"dupont@example.com","assigned_user_id":"19x1"}' \
  -d "elementType=Contacts"

Attention ! Pour les modules de type inventaire (factures, devis, commandes, etc.), il est obligatoire d’inclure les champs suivants dans l’objet element :

• productid – ID Webservice du produit
• hdnTaxType – Individual ou Group
• LineItems – Tableau des produits ou services

---

Update – Mettre à jour une entité #

Met à jour une entité existante. Tous les champs doivent être inclus (pas seulement ceux modifiés). L’objet element doit contenir l’ID Webservice de l’entité (ex : "id": "21x3456").

POST https://apps.kafinea.com/{instance}/webservice.php

Exemple curl :

curl -X POST https://apps.kafinea.com/YourKafinea/webservice.php \
  -d "operation=update" \
  -d "sessionName=YOUR_SESSION_ID" \
  -d 'element={"id":"21x3456","lastname":"Dupont","email":"nouveau@example.com","assigned_user_id":"19x1"}' \
  -d "elementType=Contacts"

Mise à jour partielle (Partial Edit) sur les entités verrouillées #

Si vous devez modifier certains champs sur des entités verrouillées (Permanent Lock, comme une facture validée), vous pouvez utiliser l’édition partielle sans déverrouiller l’enregistrement.

POST https://apps.kafinea.com/{instance}/webservice.php

Fonctionnement et restrictions :

• Champs autorisés : statuts, utilisateur assigné, références de commande et tous les champs personnalisés (custom fields).
• Lignes de produits bloquées : toute modification des articles, prix ou quantités (Line Items) est ignorée en mode édition partielle.
• Gestion des erreurs : sans le flag partial_edit=1, l’API retourne ACCESSDENIED. Si le module ne supporte pas ce mode : ACCESSDENIED – Partial edit is not supported for module X.

Attention ! Même en mode partial_edit, l’objet element doit contenir tous les champs obligatoires du module, exactement comme pour une mise à jour classique.

Exemple curl :

curl -X POST https://apps.kafinea.com/YourKafinea/webservice.php \
  -d "operation=update" \
  -d "sessionName=YOUR_SESSION_ID" \
  -d "partial_edit=1" \
  -d 'element={"id":"7x1234","invoicestatus":"Paid","assigned_user_id":"19x1"}' \
  -d "elementType=Invoice"

---

Delete – Supprimer une entité #

Supprime une entité spécifique par son ID Webservice (ex : 21x3456).

POST https://apps.kafinea.com/{instance}/webservice.php

Exemple curl :

curl -X POST https://apps.kafinea.com/YourKafinea/webservice.php \
  -d "operation=delete" \
  -d "sessionName=YOUR_SESSION_ID" \
  -d "id=21x3456"

---

Références associées 🔗 #

• Introduction API
• Authentification
• Opérations liées
• Requêtes et interrogation