Importar un lote de clientes | VillaSlot Documentation

POST /api/v1/customers/bulk

Crea un lote de clientes en una llamada. Dos reglas son propias de este endpoint y de ningún otro:

Un lote por encima del límite rechaza toda la petición con 413, indicando el límite. No hay truncamiento silencioso — creerías que todo el archivo ha pasado y perderías el final.
Una fila errónea no anula las correctas. Las filas se validan una a una; las que pasan se crean, las que fallan vuelven con su índice y su motivo.

Autorización

Rol en la organización	Este endpoint
`owner`	Permitido
`admin`	Permitido
`member`	Permitido

Cuerpo de la petición

Campo	Tipo	Obligatorio	Descripción
`customers`	array	sí	De 1 a 200 filas
`customers[].name`	cadena	sí
`customers[].email`	cadena	no	Único dentro de la organización
`customers[].phone`	cadena	no
`customers[].notes`	cadena	no

Ejemplo

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"

Respuesta

200 OK — el informe. summary.failed no es un error: lee failed y corrige esas filas.

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."}
    ]
  }
}

Qué rechaza

413 Payload Too Large — más de 200 filas. No se ha creado nada; divide el lote.
422 Unprocessable Entity — customers falta o no es una lista.
401 Unauthorized — clave ausente o no válida, o clave cuyo portador ha dejado la organización.
404 Not Found — identificador desconocido, o identificador que pertenece a otra organización. Los dos son deliberadamente indistinguibles.
429 Too Many Requests — más de 120 peticiones en un minuto para esta clave.

Notas

El límite del plan se aplica fila a fila: un lote que lo supera crea filas hasta el límite e informa del resto como fallidas.
index es la posición en el array que enviaste, para que puedas relacionar un fallo con tu archivo de origen.