Clientes

Clientes

Prefijo: /api/clientes
Requiere Auth: Sí
Permiso requerido: clientes, *

Módulo de clientes para gestionar el directorio de clientes del POS. Incluye búsqueda por documento y nombre.

Nota: Los clientes utilizan soft delete — al eliminar un cliente se marca como eliminado sin borrarse físicamente.

GET /api/clientes/

Descripción: Lista todos los clientes con paginación
Requiere Auth: Sí
Permiso requerido: clientes, leer

Respuesta exitosa: 200 OK

Response:

[
  {
    "id": 1,
    "dni": 123456789,
    "nombre": "Cliente Ejemplo",
    "telefono": 3001234567,
    "direccion": "Calle 1 #2-3",
    "razon": "Cliente Ejemplo",
    "fecha": "2025-01-15",
    "hora": "10:00:00",
    "tipoId": "CC",
    "resposabilidadTrib": "R-99-PN",
    "tenant_id": "uuid-tenant"
  }
]

cURL:

curl "http://localhost/api/clientes/?skip=0&limit=10" -H "Authorization: Bearer <token>"

Python:

import httpx
resp = httpx.get("http://localhost/api/clientes/",
    headers={"Authorization": f"Bearer {token}"})
clientes = resp.json()

JavaScript:

const resp = await fetch('http://localhost/api/clientes/', {
  headers: {'Authorization': `Bearer ${token}`}
});
const clientes = await resp.json();

---

GET /api/clientes/{cliente_id}

Descripción: Obtiene un cliente por ID
Requiere Auth: Sí
Permiso requerido: clientes, leer

Respuesta exitosa: 200 OK
Errores: 404 (no encontrado)

cURL:

curl http://localhost/api/clientes/1 -H "Authorization: Bearer <token>"

---

POST /api/clientes/

Descripción: Crea un nuevo cliente
Requiere Auth: Sí
Permiso requerido: clientes, crear

Request:

{
  "dni": 123456789,
  "nombre": "Nuevo Cliente",
  "telefono": 3007654321,
  "direccion": "Calle 10 #20-30",
  "razon": "Nuevo Cliente",
  "tipoId": "CC",
  "resposabilidadTrib": "R-99-PN"
}

Respuesta exitosa: 201 Created

cURL:

curl -X POST http://localhost/api/clientes/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"dni":123456789,"nombre":"Nuevo Cliente","telefono":3007654321,"direccion":"Calle 10 #20-30","razon":"Nuevo Cliente","tipoId":"CC","resposabilidadTrib":"R-99-PN"}'

Python:

import httpx
resp = httpx.post("http://localhost/api/clientes/",
    json={"dni": 123456789, "nombre": "Nuevo Cliente", "telefono": 3007654321, "direccion": "Calle 10 #20-30", "razon": "Nuevo Cliente", "tipoId": "CC", "resposabilidadTrib": "R-99-PN"},
    headers={"Authorization": f"Bearer {token}"})
cliente = resp.json()

JavaScript:

const resp = await fetch('http://localhost/api/clientes/', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'Authorization': `Bearer ${token}`},
  body: JSON.stringify({dni: 123456789, nombre: 'Nuevo Cliente', telefono: 3007654321, direccion: 'Calle 10 #20-30', razon: 'Nuevo Cliente', tipoId: 'CC', resposabilidadTrib: 'R-99-PN'})
});

---

PUT /api/clientes/{cliente_id}

Descripción: Actualiza un cliente existente
Requiere Auth: Sí
Permiso requerido: clientes, actualizar

Respuesta exitosa: 200 OK
Errores: 404 (no encontrado)

cURL:

curl -X PUT http://localhost/api/clientes/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"nombre":"Cliente Actualizado","telefono":3009998877}'

---

DELETE /api/clientes/{cliente_id}

Descripción: Elimina (soft delete) un cliente
Requiere Auth: Sí
Permiso requerido: clientes, eliminar

Respuesta exitosa: 204 No Content
Errores: 404 (no encontrado)

cURL:

curl -X DELETE http://localhost/api/clientes/1 -H "Authorization: Bearer <token>"

---

Búsqueda

GET /api/clientes/search/dni

Descripción: Busca un cliente por número de documento
Requiere Auth: Sí
Permiso requerido: clientes, leer

Parámetros query:

Parámetro	Tipo	Obligatorio	Descripción
dni	int	✅	Número de documento

Respuesta exitosa: 200 OK
Errores: 404 (no encontrado)

cURL:

curl "http://localhost/api/clientes/search/dni?dni=123456789" -H "Authorization: Bearer <token>"

---

GET /api/clientes/search/nombre

Descripción: Busca clientes por nombre (búsqueda parcial)
Requiere Auth: Sí
Permiso requerido: clientes, leer

Parámetros query:

Parámetro	Tipo	Obligatorio	Descripción
nombre	string	✅	Texto parcial del nombre

Respuesta exitosa: 200 OK

cURL:

curl "http://localhost/api/clientes/search/nombre?nombre=Cliente" -H "Authorization: Bearer <token>"