View Categories

API REST – Introduction

2 minutes

Profitez des API REST exposées sur HTTP(s) pour pousser ou tirer des données de Kafinea et les intégrer à des applications tierces. Vous êtes libre de choisir la bibliothèque de votre choix pour travailler avec ces API.

Principes généraux #

L’API Kafinea est une API REST : vous communiquez directement avec votre instance Kafinea et chaque requête est unique et indépendante. Rien n’est stocké en cache.

  • Protocole : HTTP(s)
  • Méthodes : GET et POST
  • Format de réponse : JSON
  • URL de base : https://apps.kafinea.com/{VotreInstance}/webservice.php

Format des réponses #

Réponse positive #

{
  "success": true,
  "result": {
    // ...
  }
}

Réponse négative #

{
  "success": false,
  "error": {
    "message": "[STRING]",
    "code": "[STRING]"
  }
}

Récapitulatif des opérations #

Opération Méthode Description
getchallenge GET Obtenir un token de connexion
login POST Se connecter
logout POST Se déconnecter
extendsession GET Prolonger la session
listtypes GET Lister les modules disponibles
describe GET Décrire les champs d’un module
create POST Créer une entité
retrieve GET Récupérer une entité
update POST Mettre à jour une entité
delete POST Supprimer une entité
query GET Interroger la base de données
query_related GET Interroger les listes connexes
add_related POST Ajouter une relation entre entités
getPicklistValues GET Récupérer les valeurs d’une liste déroulante
setPicklistValues POST Modifier les valeurs d’une liste déroulante
FileUpload POST Télécharger un fichier
files_retrieve GET Récupérer un fichier
document_pdf GET Récupérer le PDF d’un document
invoice_facturx GET Récupérer le XML Factur-X d’une facture
mass_upsert POST Importer un lot d’enregistrements par clef métier
mass_delete POST Mettre un lot d’enregistrements à la corbeille
set_field_visibility POST Activer ou désactiver des champs d’un module

Noms d’opération : plus de préfixe #

Les noms d’opération ne portent aucun préfixe : ils s’écrivent en minuscules, les mots séparés par
des tirets bas. Rien à retenir de particulier, une opération ajoutée par Kafinea se nomme comme une
opération standard.

Deux opérations ont changé de nom et répondent aux deux noms pendant la période de transition :

Ancien nom Nouveau nom Ancien nom accepté jusqu’au
mds_document_pdf document_pdf 30 novembre 2026
mds_invoice_facturx invoice_facturx 30 novembre 2026

Les paramètres et les réponses sont identiques : il suffit de changer la valeur de operation dans
vos appels. Passé cette date, l’ancien nom n’est plus publié.

Qui peut appeler quoi #

Les opérations courantes (describe, query, retrieve, create, update, delete, les
relations, les fichiers) sont ouvertes à tout compte disposant d’une clef d’accès. Chacune applique
les droits du compte utilisé : profil, rôle, partage des enregistrements. Un compte restreint ne
voit et n’écrit à travers l’API que ce qu’il verrait et écrirait dans l’interface.

Les opérations d’intégration sont en revanche réservées aux comptes administrateurs :

Opération Pourquoi administrateur
mass_upsert, mass_delete Elles agissent sur beaucoup d’enregistrements à la fois : c’est un travail de reprise de données, pas de la saisie
set_field_visibility, getPicklistValues, setPicklistValues Elles portent sur le paramétrage de l’instance, pas sur ses données
describe avec fieldStatus La liste des champs non activés décrit le paramétrage : elle n’est pas montrée à un compte restreint (voir Champs d’un module)

Un compte non administrateur qui appelle l’une de ces opérations reçoit un refus explicite nommant
l’opération, et aucune donnée. Écrire un enregistrement à la fois reste possible pour lui avec
create, update et delete, qui appliquent ses propres droits.

Références associées 🔗 #