➜︎ Retour - Menu API, webhooks et mailhooks

Démarrer avec l'API

Menu de la documentation

API

Démarrer Rechercher un client Lister les clients Créer un client Modifier un client La fiche client en JSON Les erreurs OpenAPI et Postman

Webhooks et mailhooks

Fonctionnement Vente : validation Article : stock mis à jour Les webhooks Client

Votre adresse API et votre clé

Adresse API Clé API

Renseignez-les une fois : tous les exemples de ces pages les utilisent, et les boutons « Copier » copient la requête prête à l'emploi. Ils ne quittent pas votre navigateur. La clé n'est gardée que le temps de cette session, sauf si vous cochez cette case : . Dans ce cas, la clé sera aussi conservée dans ce navigateur web. Votre adresse et votre clé sont dans Réglages → API & Make.

Cette page présente l'API de Melkal. L'adresse et la clé de l'API se trouvent dans le menu
Réglages → API & Make, vue Clé et adresse de l'API.

L'API de Melkal permet à un service extérieur (Make, Zapier, votre site, un script...) de lire, créer et modifier les fiches clients.

L'API ne couvre aujourd'hui que les clients. Les autres données (ventes, stock...) ne se lisent pas par l'API : Melkal vous les envoie par des webhooks et mailhooks.

L'essentiel#

Caractéristique	Valeur
Style	REST
Format	JSON, en UTF-8
Authentification	La clé API, dans le paramètre api_key de l'adresse. Pas d'en-tête d'autorisation.
Version	V1 : toutes les routes commencent par /api/V1/ (avec un V majuscule).
Ressource	Les clients : rechercher, lister, créer ou mettre à jour, modifier.

Démarrage rapide#

Dans Réglages → API & Make, ouvrez « Clé et adresse de l'API ». Vérifiez que API activée est sur Oui, puis notez la clé API et l'adresse API.
Testez la connexion avec la route hello (voir ci-dessous).
Faites un premier appel : rechercher un client.

Gagnez du temps : renseignez votre adresse et votre clé dans le cadre en haut de la page. Les exemples s'adaptent, les boutons « Copier » copient la requête prête à l'emploi, et les boutons « Essayer » (sur les requêtes qui ne modifient rien) l'envoient depuis votre navigateur. Pour travailler dans un outil, importez le fichier OpenAPI ou la collection Postman : voir OpenAPI et Postman.

L'adresse de l'API#

Chaque application Melkal a sa propre adresse, de la forme https://appNNapi.votre-domaine, où NN est le numéro de votre application. Copiez-la telle qu'elle est affichée dans « Adresse API ». Les routes se placent à la suite de cette adresse :

ADRESSE_API/api/V1/hello?api_key=VOTRE_CLE

Dans tous les exemples de cette documentation, ADRESSE_API est à remplacer par votre adresse, et VOTRE_CLE par votre clé API.

L'authentification#

Toutes les requêtes, y compris les POST et PUT, portent la clé dans l'adresse : ?api_key=VOTRE_CLE. Il n'y a pas d'en-tête Authorization.

Protégez votre clé. Elle donne accès à tous vos clients. Ne la mettez jamais dans une page web ou une application que vos clients peuvent lire. Si elle est compromise, régénérez-la : voir Clé et adresse de l'API. Joignez toujours api_key : une requête qui n'en a pas n'est pas traitée normalement et ne reçoit pas de réponse JSON claire.

Particularités de cette API#

Quelques points surprennent souvent quand on connaît d'autres API. Les voici tous ensemble :

La clé est dans l'adresse (api_key), pas dans un en-tête.
Tous les refus renvoient 401, y compris pour un paramètre ou un JSON invalide. C'est le message qui dit la cause.
Une liste vide ou une page au-delà de la dernière renvoie 404 (« aucun client trouvé »), pas un tableau vide. C'est le signal de fin d'une extraction.
Les dates sont du texte AAAA-MM-JJ ou AAAA-MM-JJ HH:MM:SS, à l'heure locale de l'entreprise, sans fuseau horaire (ce n'est pas de l'ISO 8601).
Une liste se demande en deux temps : un appel prépare la liste et donne un token, un second lit les pages (à partir de 1).
Une recherche renvoie un seul client, le premier qui correspond.
Des propriétés peuvent être ajoutées aux réponses : ignorez celles que vous ne connaissez pas.

Les routes#

Action	Méthode et route	Détail
Tester la connexion	GET /api/V1/hello	Ci-dessous
Rechercher un client	GET /api/V1/client	Rechercher un client
Lister les clients, étape 1	GET /api/V1/clients_initial	Lister les clients
Lister les clients, étape 2	GET /api/V1/clients_token	Lister les clients
Créer, ou créer / mettre à jour	POST /api/V1/client	Créer un client
Modifier	PUT /api/V1/client	Modifier un client

La route /api/V1/client sert aux trois actions « rechercher », « créer » et « modifier » : c'est la méthode HTTP (GET, POST, PUT) qui les distingue.

Tester la connexion : hello#

Cette route vérifie que le serveur répond, que l'API est activée et que votre clé est la bonne. Elle ne renvoie aucune donnée.

curl "ADRESSE_API/api/V1/hello?api_key=VOTRE_CLE"

Réponse quand tout va bien (code HTTP 200) :

{
  "code": "hello",
  "message": "Message de Melkal: La connexion s'est bien faite avec notre serveur et votre clé API a bien été reconnue.",
  "status": 200
}

Si la clé est fausse ou si l'API n'est pas activée, la réponse est une erreur 401 : voir Les erreurs de l'API.

Bonnes pratiques#

Encodez les valeurs dans l'adresse (un « @ » devient %40, un espace %20...). Les outils comme curl avec --data-urlencode ou les modules Make le font pour vous.
Gardez l'identifiant de Melkal (id ou uuid) de chaque client que vous créez : c'est la façon la plus fiable de le retrouver ensuite.
Évitez les doublons avec un identifiant à vous, idExterne, que vous envoyez à chaque création : voir Créer un client.
Lisez le message d'erreur : il dit précisément ce qui ne va pas. Le code HTTP seul ne suffit pas (voir Les erreurs de l'API).

Make#

Melkal fournit des modules Make officiels, qui utilisent cette API pour les clients. Ils ne couvrent que les clients, comme l'API. Les envois de Melkal vers Make (ventes, stock) passent par les webhooks et un module « Custom webhook » de Make.

← PrécédentAccueil API Suivant →Rechercher un client

Dernière mise à jour : 13 octobre 2026

Retour - Sommaire - Centre d'aide - Assistance