Importer un lot de clients | VillaSlot Documentation

POST /api/v1/customers/bulk

Crée un lot de clients en un seul appel. Deux règles appartiennent à cet endpoint et à aucun autre :

Un lot au-delà de la limite refuse toute la requête avec 413, en nommant la limite. Il n’y a pas de troncature silencieuse — vous croiriez que tout le fichier est passé et vous en perdriez la fin.
Une ligne invalide n’annule pas les bonnes. Les lignes sont validées une par une ; celles qui passent sont créées, celles qui échouent reviennent avec leur index et leur raison.

Autorisation

Rôle dans l’organisation	Cet endpoint
`owner`	Autorisé
`admin`	Autorisé
`member`	Autorisé

Corps de la requête

Champ	Type	Obligatoire	Description
`customers`	tableau	oui	De 1 à 200 lignes
`customers[].name`	chaîne	oui
`customers[].email`	chaîne	non	Unique au sein de l’organisation
`customers[].phone`	chaîne	non
`customers[].notes`	chaîne	non

Exemple

bash

curl -X POST -H "x-api-key: $VILLASLOT_API_KEY" -H "content-type: application/json" \
  -d '{"customers":[{"name":"Tomas"},{"name":"Lina","email":"lina@example.com"}]}' \
  "https://villaslot.app/api/v1/customers/bulk"

Réponse

200 OK — le rapport. summary.failed n’est pas une erreur : lisez failed et corrigez ces lignes.

json

{
  "success": true,
  "data": {
    "summary": {"received": 3, "created": 2, "failed": 1},
    "created": [{"id": "8d3e…", "name": "Tomas"}],
    "failed": [
      {"index": 1, "error": "Erreur de validation : le nom est obligatoire."}
    ]
  }
}

Ce qu’il refuse

413 Payload Too Large — plus de 200 lignes. Rien n’a été créé ; découpez le lot.
422 Unprocessable Entity — customers est absent ou n’est pas une liste.
401 Unauthorized — clé absente ou invalide, ou clé dont le porteur a quitté l’organisation.
404 Not Found — identifiant inconnu, ou identifiant appartenant à une autre organisation. Les deux sont volontairement indiscernables.
429 Too Many Requests — plus de 120 requêtes en une minute pour cette clé.

Notes

Le plafond de l’offre s’applique ligne par ligne : un lot qui le dépasse crée des lignes jusqu’à la limite et signale le reste comme en échec.
index est la position dans le tableau que vous avez envoyé : vous pouvez ainsi rattacher un échec à votre fichier source.