L'API publique : relier un outil du cabinet

L'API publique permet à un outil du cabinet de lire, et si vous l'autorisez de créer ou de modifier, les dossiers, contacts, prestations, factures et rendez-vous d'un espace. Elle s'ouvre espace par espace : tant qu'elle n'est pas ouverte pour le vôtre, la carte « Clés d'API » n'apparaît pas.

Créer une clé

1. Dans Réglages, ouvrez l'espace puis l'onglet « Sécurité et données ». Seul un associé voit la carte « Clés d'API ».
2. Cliquez sur « Créer une clé », donnez-lui un nom (l'outil qui l'utilisera), cochez les données accessibles et, si l'outil doit écrire, « Autoriser l'écriture ».
3. Copiez la clé affichée et collez-la dans l'outil : elle ne sera plus jamais affichée. Seule son empreinte est conservée.

Attention. Une clé donne accès aux données de l'espace sans mot de passe ni double authentification : confiez-la seulement à un outil de confiance et révoquez-la dès qu'il ne sert plus. La révocation est immédiate et définitive.

Appeler l'API

• chaque appel porte l'en-tête « Authorization: Bearer dlg_… » ;
• GET /api/v1/<ressource> liste les objets du plus récent au plus ancien (paramètres « limite », 100 au plus, et « curseur », repris du champ « suivant » de la page précédente) ;
• GET /api/v1/<ressource>/<id> lit un objet, POST /api/v1/<ressource> en crée un, PATCH /api/v1/<ressource>/<id> le modifie ; rien ne se supprime par l'API ;
• ressources : dossiers, contacts, prestations, factures, agenda ;
• les factures ne se créent qu'en brouillon (comme « Préparer une facture ») : l'émission, l'avoir et le paiement restent dans l'application ;
• les dates sont en ISO 8601 (UTC), les montants en texte, jamais en nombre à virgule.

Exemple : curl -H "Authorization: Bearer dlg_…" <adresse de Diligence>/api/v1/dossiers?limite=20 (la même adresse que celle de l'application). La réponse est { "data": [...], "suivant": ... }.

Erreurs

• 401 : clé absente, inconnue ou révoquée ;
• 403 : donnée hors du périmètre de la clé, clé en lecture seule, API fermée pour l'espace ou licence en lecture seule ;
• 404 : objet introuvable dans l'espace de la clé (une clé ne voit jamais un autre espace) ;
• 405 : opération non prévue (modifier une facture) ;
• 409 : dossier clos, mois clos ou prestation déjà facturée ;
• 422 : données invalides, avec le détail par champ dans « error.details ».

Astuce. Les 30 derniers appels, réussis ou refusés, s'affichent sous la liste des clés : c'est le premier endroit à regarder quand une intégration ne fonctionne pas.

Astuce. Pour qu'un outil soit prévenu d'un dossier créé, d'une facture émise ou d'un paiement reçu sans interroger l'API en boucle, voyez l'article « Les webhooks : prévenir un outil du cabinet ».

Tous les articles