Skip to main content

​
GET /api/clientes

Lista todos los clientes de la empresa activa.

​
Autenticación

Requiere autenticación con token Bearer y permiso clientes.view.

​
Parámetros de Consulta

​
search
string
Término de búsqueda (busca en documento, nombre, email, teléfono)

​
Respuesta

​
success
boolean
Indica si la operación fue exitosa
​
data
array
Lista de clientes

​
Ejemplo de Uso

curl -X GET "https://api.ejemplo.com/api/clientes?search=juan" \
  -H "Authorization: Bearer {token}"

​
POST /api/clientes

Crea un nuevo cliente.

​
Autenticación

Requiere autenticación con token Bearer y permiso clientes.create.

​
Parámetros del Body

​
documento
string
required
DNI o RUC del cliente (máximo 11 caracteres). Debe ser único por empresa.
​
datos
string
required
Nombre o razón social (máximo 245 caracteres)
​
direccion
string
Dirección principal (máximo 245 caracteres)
​
direccion2
string
Dirección secundaria (máximo 220 caracteres)
​
telefono
string
Teléfono principal (máximo 200 caracteres)
​
telefono2
string
Teléfono secundario (máximo 200 caracteres)
​
email
string
Correo electrónico (formato válido, máximo 200 caracteres)
​
id_empresa
integer
required
ID de la empresa a la que pertenece el cliente
​
ubigeo
string
Código ubigeo de 6 dígitos
​
departamento
string
Nombre del departamento (máximo 100 caracteres)
​
provincia
string
Nombre de la provincia (máximo 100 caracteres)
​
distrito
string
Nombre del distrito (máximo 100 caracteres)

​
Respuesta

​
success
boolean
Indica si el cliente fue creado exitosamente
​
message
string
Mensaje confirmando la creación
​
data
object
Cliente creado con sus relaciones

​
Ejemplo de Uso

curl -X POST "https://api.ejemplo.com/api/clientes" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "documento": "12345678",
    "datos": "Juan Pérez García",
    "direccion": "Av. Principal 123",
    "telefono": "987654321",
    "email": "[email protected]",
    "id_empresa": 1,
    "ubigeo": "150101",
    "departamento": "Lima",
    "provincia": "Lima",
    "distrito": "Lima"
  }'

​
GET /api/clientes/

Obtiene el detalle de un cliente específico.

​
Autenticación

Requiere autenticación con token Bearer y permiso clientes.view.

​
Parámetros de Ruta

​
id
integer
required
ID del cliente

​
Respuesta

​
success
boolean
Indica si la operación fue exitosa
​
data
object
Cliente con sus relaciones (empresa, ventas)

​
Ejemplo de Uso

curl -X GET "https://api.ejemplo.com/api/clientes/45" \
  -H "Authorization: Bearer {token}"

​
PUT /api/clientes/

Actualiza un cliente existente.

​
Autenticación

Requiere autenticación con token Bearer y permiso clientes.edit.

​
Parámetros de Ruta

​
id
integer
required
ID del cliente

​
Parámetros del Body

Los mismos que en POST (todos opcionales). El documento debe seguir siendo único por empresa.

​
Respuesta

​
success
boolean
Indica si la actualización fue exitosa
​
message
string
Mensaje confirmando la actualización
​
data
object
Cliente actualizado

​
Ejemplo de Uso

curl -X PUT "https://api.ejemplo.com/api/clientes/45" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "telefono": "999888777",
    "email": "[email protected]"
  }'

​
DELETE /api/clientes/

Elimina un cliente.

​
Autenticación

Requiere autenticación con token Bearer y permiso clientes.delete.

​
Parámetros de Ruta

​
id
integer
required
ID del cliente

​
Validación

No se puede eliminar un cliente que tiene ventas asociadas. En ese caso, retorna error 409 (Conflict).

​
Respuesta

​
success
boolean
Indica si la eliminación fue exitosa
​
message
string
Mensaje confirmando la eliminación o indicando el conflicto

​
Ejemplo de Uso

curl -X DELETE "https://api.ejemplo.com/api/clientes/45" \
  -H "Authorization: Bearer {token}"

​
POST /api/clientes/buscar-documento

Busca un cliente por número de documento.

​
Autenticación

Requiere autenticación con token Bearer.

​
Parámetros del Body

​
documento
string
required
Número de documento a buscar
​
empresa_id
integer
required
ID de la empresa donde buscar

​
Respuesta

​
success
boolean
Indica si se encontró el cliente
​
data
object
Cliente encontrado (si existe)
​
message
string
Mensaje indicando si no se encontró

​
Ejemplo de Uso

curl -X POST "https://api.ejemplo.com/api/clientes/buscar-documento" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "documento": "12345678",
    "empresa_id": 1
  }'

​
Códigos de Error

  • 404 Not Found: Cliente no encontrado.
  • 409 Conflict: No se puede eliminar porque tiene ventas asociadas.
  • 422 Unprocessable Entity: Error de validación (documento duplicado, email inválido, etc.).
  • 500 Internal Server Error: Error en el servidor.

​
Notas Importantes

  • El documento debe ser único por empresa. No puede haber dos clientes con el mismo documento en la misma empresa.
  • Los clientes se crean automáticamente al registrar una venta si no existen.
  • Los campos ultima_venta y total_venta se calculan dinámicamente desde la tabla ventas.
  • Solo se pueden eliminar clientes sin ventas asociadas.
  • Todos los clientes están asociados a una empresa específica.

Build docs developers (and LLMs) love

Get started for freeTalk to us