Skip to main content
GET
/
api
/
clientes
Listar Clientes
curl --request GET \
  --url https://api.example.com/api/clientes
{
  "500": {},
  "success": true,
  "data": [
    {
      "id_cliente": 123,
      "documento": "<string>",
      "datos": "<string>",
      "direccion": "<string>",
      "direccion2": "<string>",
      "telefono": "<string>",
      "telefono2": "<string>",
      "email": "<string>",
      "foto_url": "<string>",
      "ubigeo": "<string>",
      "departamento": "<string>",
      "provincia": "<string>",
      "distrito": "<string>",
      "ultima_venta": "<string>",
      "total_venta": 123,
      "empresa": {
        "id_empresa": 123,
        "comercial": "<string>",
        "ruc": "<string>"
      }
    }
  ]
}

​
Autenticación

Este endpoint requiere autenticación mediante token Bearer y el permiso clientes.view.

​
Parámetros de Query

​
search
string
Término de búsqueda para filtrar clientes por documento o datos (nombre/razón social)
​
empresa_id
integer
ID de la empresa. Si no se proporciona, se usa la empresa del usuario autenticado

​
Respuesta

La respuesta incluye información detallada de cada cliente con estadísticas calculadas:
​
success
boolean
Indica si la operación fue exitosa
​
data
array
Lista de clientes con sus estadísticas

​
Ejemplo de Respuesta

{
  "success": true,
  "data": [
    {
      "id_cliente": 1,
      "documento": "20612706702",
      "datos": "CORPORACION XYZ S.A.C.",
      "direccion": "Av. Los Pinos 123",
      "direccion2": "Urb. Los Jardines",
      "telefono": "01-4567890",
      "telefono2": "987654321",
      "email": "[email protected]",
      "foto_url": "/storage/clientes/cliente_1234567890.jpg",
      "id_empresa": 1,
      "ubigeo": "150101",
      "departamento": "Lima",
      "provincia": "Lima",
      "distrito": "Lima",
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z",
      "ultima_venta": "2024-03-05 15:30:00",
      "total_venta": "15840.50",
      "empresa": {
        "id_empresa": 1,
        "comercial": "Santo Domingo",
        "ruc": "20612706702"
      }
    },
    {
      "id_cliente": 2,
      "documento": "12345678",
      "datos": "Juan Pérez García",
      "direccion": "Jr. Las Flores 456",
      "direccion2": null,
      "telefono": "987654321",
      "telefono2": null,
      "email": "[email protected]",
      "foto_url": null,
      "id_empresa": 1,
      "ubigeo": "150132",
      "departamento": "Lima",
      "provincia": "Lima",
      "distrito": "San Isidro",
      "created_at": "2024-02-20T14:15:00.000000Z",
      "updated_at": "2024-02-20T14:15:00.000000Z",
      "ultima_venta": "2024-03-01 09:15:00",
      "total_venta": "3250.00",
      "empresa": {
        "id_empresa": 1,
        "comercial": "Santo Domingo",
        "ruc": "20612706702"
      }
    }
  ]
}

​
Notas de Implementación

  • El endpoint filtra automáticamente por la empresa del usuario autenticado (id_empresa)
  • Las estadísticas de ventas excluyen ventas anuladas (estado ‘2’ y ‘A’)
  • El campo tipo_doc se detecta automáticamente: ‘6’ para RUC (11 dígitos), ‘1’ para DNI (8 dígitos), ‘4’ para otros
  • Los resultados se ordenan por fecha de creación descendente
  • El campo search realiza búsqueda parcial en documento y datos mediante el scope search() del modelo

​
Códigos de Error

​
500
object
Error interno del servidor
{
  "success": false,
  "message": "Error al obtener clientes",
  "error": "Mensaje de error específico"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us