melkal
Manuel d'utilisation
 Sommaire - Centre d'aide - Assistance

➜︎ Retour - Menu API, webhooks et mailhooks

API : créer un client

Menu de la documentation
Accueil API
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é

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 décrit la création d'un client par l'API. Réglage de l'API : Réglages → API & Make.
POST/api/V1/client?api_key=VOTRE_CLE
Cette route crée un client. Avec "clientModif": true, elle fait une création ou une mise à jour : si le client existe déjà, il est modifié au lieu d'être refusé. Le corps de la requête est un JSON, et l'en-tête Content-Type: application/json est à joindre.

Exemple#

curl -X POST "ADRESSE_API/api/V1/client?api_key=VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "nom": "Dupont",
    "prenom": "Martin",
    "idExterne": "CRM-4821",
    "sectionEntreprise": { "entreprise": "Dupont Services" },
    "sectionSocial": {
      "email": "achats@dupont-sarl.fr",
      "emailPub": true,
      "mobile": "0612345678"
    },
    "sectionAdresse": {
      "adresse1": "3 rue des Écoles",
      "cp": "29000",
      "ville": "Quimper"
    }
  }'

Le corps de la requête#

Toutes les propriétés sont facultatives, mais le client doit être identifiable : il faut au moins un nom, un prénom, une entreprise ou un contact (email, mobile...).

Les propriétés de la fiche

PropriétéTypeExplications
clientModif boolean false : le client est créé, et refusé s'il existe déjà. true : s'il existe déjà, il est mis à jour ; sinon il est créé. Par défaut false.
nom string Le nom de famille (80 caractères au maximum).
prenom string Le prénom (80 caractères au maximum).
anniversaire string L'anniversaire, jour puis mois, 4 chiffres : 1503 pour le 15 mars. Invalide s'il n'y a pas 4 chiffres, si le jour n'est pas de 1 à 31 ou le mois de 1 à 12.
type string Le libellé du type de client, tel que dans Melkal (par exemple « PROFESSIONNEL »). S'il est absent, le type par défaut est utilisé. Un libellé inconnu est refusé.
tarif string Le libellé du tarif du client. S'il est absent, c'est le tarif du type de client. Un libellé inconnu est refusé.
suivi string Le nom du vendeur qui suit ce client. Un nom inconnu est refusé.
compte string Le compte comptable du client. Il doit commencer par 411 (ou par 9 ou 0).
uuid string L'identifiant unique du client (UUID version 4). S'il est absent, Melkal en crée un. Il permet de retrouver le client.
idExterne string L'identifiant que votre application donne au client (200 caractères au maximum). Il permet d'éviter les doublons et de retrouver le client.
ean string Le code-barre interne de la carte du client : un EAN 8 valide commençant par 8. S'il est absent, Melkal en crée un.
sectionEntreprise

PropriétéTypeExplications
entreprise string Le nom de l'entreprise (150 caractères au maximum).
idTva string Le numéro de TVA intracommunautaire.
adresseLivr string L'adresse de livraison.
sectionSocial : les contacts du client

PropriétéTypeExplications
email
emailPub		 string
boolean		 L'adresse email, et true si le client accepte de recevoir de la publicité (opt-in).
mobile
mobilePub		 string
boolean		 Le numéro de mobile, et son opt-in.
tel string Le numéro de téléphone fixe.
instagram
tiktok
facebook
x		 string Les identifiants sur les réseaux sociaux.
sectionAdresse

PropriétéTypeExplications
remarques string Des indications sur l'adresse (code du portail...).
adresse1
adresse2		 string Les deux lignes d'adresse.
cp
ville		 string Le code postal et la ville.
sectionNotes

PropriétéTypeExplications
descriptif string Le descriptif du client.
note1 ... note6 string Les six notes de la fiche (leurs titres sont ceux que vous avez choisis dans Melkal).

Créer ou mettre à jour : comment Melkal retrouve le client#

Avec "clientModif": true, Melkal cherche si le client existe déjà, dans cet ordre, et s'arrête au premier trouvé :
  1. l'UUID ;
  2. l'idExterne ;
  3. le code-barre (ean) ;
  4. le compte comptable ;
  5. l'email, puis le mobile, le téléphone, et les identifiants Facebook, X, Instagram et TikTok.
Si un client est trouvé, il est mis à jour avec les propriétés envoyées ; sinon il est créé. Avec "clientModif": false (ou sans cette propriété), un client déjà existant est refusé avec un message du type « un client existe déjà avec cette adresse email ».

Conseil pour éviter les doublons : envoyez toujours votre propre idExterne avec "clientModif": true. Un client déjà créé est alors mis à jour, jamais dupliqué.

La réponse#

Code 200 : le client est créé (ou mis à jour). La réponse donne ses identifiants. 
{
  "uuid": "38D13BD6-4836-4115-B829-B55AC2537B09",
  "ean": "80003128",
  "id": 312,
  "idExterne": "CRM-4821",
  "code": "312",
  "clientCree": true
}
PropriétéTypeExplications
id integer L'identifiant du client dans Melkal.
code string Le numéro (code) du client.
uuid string L'UUID du client.
ean string Le code-barre interne du client.
idExterne string Votre identifiant, s'il y en a un.
clientCree boolean true si le client vient d'être créé. Absente quand le client existait déjà et a été mis à jour.
clientModifie boolean true si un client existant a été mis à jour. Présente à la place de clientCree dans ce cas.
Les erreurs (doublon, JSON incorrect, type de client inconnu...) sont dans Les erreurs de l'API.

← PrécédentLister les clients Suivant →Modifier un client
Dernière mise à jour : 13 octobre 2026
Retour - Sommaire - Centre d'aide - Assistance