API Rest
Dodock crée des points d'accès REST pour chaque type de document. Il donne aussi accès aux méthodes Python décorées avec @frappe.whitelist(), par leur chemin pointé.
Cette page décrit l'API v1. Ses points d'accès répondent sous /api/ et sous /api/v1/. Pour l'API v2 (/api/v2/), voir API REST v2.
En version next, les points d'accès GET /api/resource/:doctype et POST /api/resource/:doctype/:name acceptent aussi la méthode HTTP QUERY. Voir Méthode HTTP QUERY.
Authentification
Deux méthodes existent : par mot de passe (session) ou par jeton.
Authentification par mot de passe
Cette méthode ouvre une session. Dodock renvoie un cookie sid, que le client renvoie dans les requêtes suivantes. Si votre client HTTP ne garde pas les cookies, utilisez un jeton.
fetch("https://<url-du-site>/api/method/login", {
method: "POST",
headers: {
Accept: "application/json",
"Content-Type": "application/json",
},
body: JSON.stringify({
usr: "identifiant ou e-mail",
pwd: "mot de passe",
}),
})
.then((r) => r.json())
.then((r) => console.log(r));
Authentification par jeton
Un jeton est une paire « Clé API » et « Secret API ». Pour l'obtenir :
- Ouvrez l'utilisateur qui fera les appels.
- Dans la section « Accès API », cliquez sur « Générer des clés ».
- Copiez la clé et le secret dans la fenêtre « Clés API ». Dodock n'affiche le secret qu'une fois.
Le jeton est api_key:api_secret. Envoyez-le dans l'en-tête Authorization, précédé de token :
fetch("https://<url-du-site>/api/method/frappe.auth.get_logged_user", {
headers: {
Authorization: "token <api_key>:<api_secret>",
},
})
.then((r) => r.json())
.then((r) => console.log(r));
Les appels ont les autorisations de cet utilisateur. Créez un utilisateur dédié avec les seuls rôles nécessaires.
Indiquer l'agent IA à l'origine d'un appel
Un agent IA qui appelle l'API au nom d'un utilisateur peut se déclarer avec l'en-tête X-Frappe-Agent. Sa valeur est le nom de l'agent. Dodock l'enregistre dans les versions des documents modifiés, et la chronologie du document l'affiche. Voir Historique d'activité des documents.
curl -X PUT "https://<url-du-site>/api/resource/ToDo/af2e2d0e33" \
-H "Authorization: token <api_key>:<api_secret>" \
-H "X-Frappe-Agent: Assistant Achats" \
-H "Content-Type: application/json" \
-d '{"description": "Nouvelle description"}'
- L'en-tête n'est lu que pour une requête authentifiée par clé API ou par jeton OAuth. Une session par cookie l'ignore, pour que l'agent ne reste pas dans une session enregistrée.
- Avec un jeton OAuth, si le nom de l'application OAuth (OAuth Client) diffère de la valeur de l'en-tête, Dodock enregistre « nom de l'application (valeur de l'en-tête) ».
- Le canal enregistré est
API. Le nom est tronqué à 140 caractères. - Pour un type de document qui suit les modifications, une création faite avec cet en-tête crée aussi une version.
Liste de documents
Envoyez une requête GET à /api/resource/:doctype. Par défaut, Dodock renvoie 20 documents et seulement leur nom.
GET /api/resource/ToDo
Réponse :
{
"data": [
{ "name": "b57566801d" },
{ "name": "b63b71df37" }
]
}
Les paramètres de requête sont ceux de frappe.client.get_list :
| Paramètre | Format | Effet |
|---|---|---|
fields | Liste JSON | Champs à renvoyer, par exemple ["name", "status"] |
filters | Liste ou dictionnaire JSON | Filtres [champ, opérateur, valeur], combinés par ET |
or_filters | Liste ou dictionnaire JSON | Filtres combinés par OU |
order_by | Texte | Tri, par exemple modified desc (espace encodé %20) |
group_by | Texte | Regroupement |
limit_start | Nombre | Rang du premier document renvoyé |
limit_page_length ou limit | Nombre | Nombre de documents (20 par défaut, 0 pour tous) |
as_dict | true / false | false renvoie des listes au lieu d'objets |
expand | Liste JSON | Champs Lien à remplacer par le document lié |
parent | Texte | Type de document parent, pour lire une table enfant |
Exemples :
GET /api/resource/ToDo?fields=["name","description","status"]
GET /api/resource/ToDo?filters=[["status","=","Open"],["date",">","2026-09-01"]]
GET /api/resource/ToDo?order_by=date%20desc
GET /api/resource/ToDo?limit_start=20&limit_page_length=20
GET /api/resource/ToDo?fields=["status",{"COUNT":"name","as":"total"}]&group_by=status
fields, comme "count(name)". Utilisez la syntaxe dictionnaire {"COUNT": "name"}.Opérations sur un document
Créer
Envoyez une requête POST à /api/resource/:doctype, avec le document en JSON dans le corps.
POST /api/resource/ToDo
# Corps
{"description": "Nouvelle tâche"}
Réponse :
{
"data": {
"name": "af2e2d0e33",
"owner": "Administrator",
"creation": "2026-11-03 14:19:00.281026",
"modified": "2026-11-03 14:19:00.281026",
"modified_by": "Administrator",
"docstatus": 0,
"status": "Open",
"priority": "Medium",
"description": "Nouvelle tâche",
"doctype": "ToDo"
}
}
Lire
Envoyez une requête GET à /api/resource/:doctype/:name. La réponse contient tous les champs et les lignes des tables enfants.
GET /api/resource/ToDo/af2e2d0e33
Modifier
Envoyez une requête PUT à /api/resource/:doctype/:name. Envoyez seulement les champs à modifier. Dodock exécute save(), donc les validations du contrôleur s'appliquent.
PUT /api/resource/ToDo/af2e2d0e33
# Corps
{"description": "Nouvelle description"}
La réponse contient le document complet après modification.
Supprimer
Envoyez une requête DELETE à /api/resource/:doctype/:name.
DELETE /api/resource/ToDo/af2e2d0e33
Réponse :
{"data": "ok"}
Appeler une méthode du document
Envoyez une requête POST à /api/resource/:doctype/:name?run_method=<méthode>. La méthode du contrôleur doit être décorée avec @frappe.whitelist(). Les autres paramètres sont passés à la méthode.
Appeler une méthode Python
Dodock exécute une méthode Python décorée avec @frappe.whitelist() à l'adresse /api/method/<chemin.pointé>.
GET /api/method/frappe.auth.get_logged_user
Réponse :
{"message": "jean@example.com"}
- Utilisez
GETpour une méthode qui lit seulement des données. - Utilisez
POSTpour une méthode qui modifie des données. Après une requêtePOST,PUT,PATCHouDELETEréussie, Dodock valide la transaction (frappe.db.commit()). - La valeur renvoyée par la méthode, convertie en JSON, est dans la clé
message. - En cas d'erreur, la réponse contient
exc_type(le nom de l'exception) et le code HTTP de l'erreur. Les messages affichés à l'utilisateur sont dans_server_messages. En mode développeur, la cléexceptioncontient aussi la dernière ligne de la trace.
Exemple de méthode :
import frappe
@frappe.whitelist()
def taches_ouvertes(utilisateur: str):
return frappe.get_list(
"ToDo",
filters={"allocated_to": utilisateur, "status": "Open"},
fields=["name", "description"],
)
Si cette fonction est dans mon_app/api.py, appelez GET /api/method/mon_app.api.taches_ouvertes?utilisateur=jean@example.com.
Envoyer un fichier
La méthode /api/method/upload_file reçoit un fichier binaire et crée un document Fichier.
curl -X POST \
https://<url-du-site>/api/method/upload_file \
-H 'Accept: application/json' \
-H 'Authorization: token <api_key>:<api_secret>' \
-F file=@/chemin/vers/le/fichier.png \
-F doctype=ToDo \
-F docname=af2e2d0e33 \
-F is_private=1
Les champs doctype et docname attachent le fichier à un document. is_private=1 crée un fichier privé. En JavaScript, ajoutez le fichier et ces champs à un objet FormData, puis envoyez-le en POST.