Vos données, depuis votre code

Un seul moteur, deux façades. Le serveur MCP parle aux assistants IA en outils métier prêts à l’emploi. L’API de données, elle, parle à votre code : elle expose les modèles bruts de l’espace, leurs champs et leurs méthodes. Un client, un devis, une écriture comptable, un mouvement de stock : tout est lisible et modifiable.

01Laquelle des deux choisir

Les deux partagent la même clé d’API et les mêmes droits. Rien n’interdit de les utiliser ensemble.

02Adresse & base

Deux informations suffisent pour appeler un espace.

Adresse

https://<espace>.madata.app : celle par laquelle vous vous connectez tous les jours.

Base

prod_<espace>. Pour kouassi.madata.app, la base est prod_kouassi.

Utilisateur

Un uid numérique, renvoyé à la connexion. Ce n’est pas votre adresse email : c’est son identifiant interne.

Mot de passe

Une clé d’API. Jamais votre mot de passe de connexion.

03Trois protocoles, un seul moteur

Les trois attaquent le même moteur et respectent les mêmes droits. XML-RPC et JSON-RPC sont sans état : chaque appel porte ses identifiants, il n’y a pas de session à entretenir.

04Le premier appel

Trois étapes : vérifier la version, se connecter, compter des enregistrements.

import xmlrpc.client

URL = "https://<espace>.madata.app"
DB  = "prod_<espace>"
CLE = "votre-cle-d-api"
LOGIN = "[email protected]"

common = xmlrpc.client.ServerProxy(f"{URL}/xmlrpc/2/common")
print(common.version())
# {'server_version': '17.0', 'server_serie': '17.0', 'protocol_version': 1}

uid = common.authenticate(DB, LOGIN, CLE, {})
print("uid =", uid)          # 7  (False si la cle est refusee)

models = xmlrpc.client.ServerProxy(f"{URL}/xmlrpc/2/object")
nb = models.execute_kw(DB, uid, CLE, 'res.partner', 'search_count', [[]])
print(nb, "contacts")

curl -s https://<espace>.madata.app/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"call","params":{
        "service":"object","method":"execute_kw",
        "args":["prod_<espace>", 7, "votre-cle-d-api",
                "res.partner","search_count",[[]]]}}'

# {"jsonrpc": "2.0", "id": null, "result": 143}

05La forme d’un appel

Tout passe par execute_kw, sur le service object. Sept arguments, toujours les mêmes.

models.execute_kw(
    db,          # nom de la base de l'espace
    uid,         # identifiant numerique de l'utilisateur
    cle,         # cle d'API
    'res.partner',   # modele
    'search_read',   # methode
    [[['customer_rank', '>', 0]]],          # arguments positionnels
    {'fields': ['name', 'email'], 'limit': 10},  # arguments nommes
)

Les deux derniers sont la clé de lecture : une liste d’arguments positionnels, puis un dictionnaire d’arguments nommés. Une méthode sans argument nommé reçoit {}, ou rien du tout.

06Conventions de types

07Ce qui reste fermé

• La gestion des bases (/web/database/*, création, duplication, restauration, liste) répond 403 depuis l’extérieur. Aucune clé ne l’ouvre.
• La liste des bases du serveur n’est pas publiée : db.list répond « accès refusé ». Vous connaissez déjà la vôtre, c’est la seule qui vous concerne.
• Utilisateurs, sociétés, abonnement, applications : ce sont des ressources facturées, pilotées par le portail (madata.africa/portail). Les créer par l’API désaligne l’espace et la facturation. Le serveur MCP les refuse d’ailleurs explicitement.

08Limites & bonnes manières

Durée d’un appel

Environ 300 secondes. Un appel qui dépasse est coupé : découpez plutôt que d’insister.

Volume

Pas de plafond de lignes, mais un search_read sans limit sur un gros modèle ramène tout. Paginez.

Cadence

Pas de quota publié sur l’API de données. Une boucle serrée qui sature l’espace pénalise d’abord vos propres utilisateurs : groupez vos appels.

Groupez

create, write et read acceptent des listes. Cent contacts en un appel valent mieux que cent appels.

Maintenance

Pendant une mise à jour de l’espace, l’API répond 503 avec un en-tête Retry-After. Respectez-le et reprenez : rien n’est perdu.