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.

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 :

1. Ouvrez l'utilisateur qui fera les appels.
2. Dans la section « Accès API », cliquez sur « Générer des clés ».
3. 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.

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 :

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

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. L'utilisateur doit avoir l'autorisation Écriture sur le document. Sinon, Dodock refuse la requête avec une erreur de permission (403) avant d'appliquer les champs.

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 GET pour une méthode qui lit seulement des données.
• Utilisez POST pour une méthode qui modifie des données. Après une requête POST, PUT, PATCH ou DELETE ré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é exception contient 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.