API REST

Health Del Servicio

GET /health

Respuesta:

{
  "ok": true,
  "service": "customers-api",
  "timestamp": "2026-06-24T19:30:00.000Z"
}

Crear Cliente

POST /customers
Content-Type: application/json

Body:

{
  "tenantId": "tenant-123",
  "firstName": "Ana",
  "lastName": "Perez",
  "email": "ana@example.com",
  "phone": "5512345678",
  "city": "Ciudad de Mexico",
  "status": "active",
  "segment": "general",
  "notes": "Cliente frecuente en sucursal centro",
  "allowCredit": false
}

Campos del body:

Campo	Obligatorio	Nota
tenantId	Si	String no vacío, máximo 80 caracteres
firstName	Si	String no vacío, máximo 80 caracteres
lastName	Si	String no vacío, máximo 80 caracteres
email	Si	Debe ser email válido
phone	Si	String no vacío, máximo 30 caracteres
city	Si	String no vacío, máximo 80 caracteres
status	Si	active o inactive
segment	Si	general, frequent o vip
notes	No	Opcional, máximo 500 caracteres
allowCredit	No	Opcional; default false

Respuesta:

{
  "id": "665f1f000000000000000001",
  "tenantId": "tenant-123",
  "firstName": "Ana",
  "lastName": "Perez",
  "email": "ana@example.com",
  "phone": "5512345678",
  "city": "Ciudad de Mexico",
  "status": "active",
  "segment": "general",
  "notes": "Cliente frecuente en sucursal centro",
  "totalOrders": 0,
  "registeredAt": "2026-06-24T19:30:00.000Z",
  "updatedAt": "2026-06-24T19:30:00.000Z",
  "allowCredit": false
}

Listar Clientes

GET /customers?tenantId=tenant-123

Parámetros query:

Parámetro	Requerido	Descripción
tenantId	Si	Tenant propietario
search	No	Busca en nombre, apellido, email, teléfono y ciudad

Obtener Cliente

GET /customers/:id?tenantId=tenant-123

Si tenantId no se envía o viene vacío, la API responde BadRequestException con mensaje tenantId is required.

Si no existe un cliente con ese id y tenantId, la API responde NotFoundException.

Actualizar Cliente

PATCH /customers/:id?tenantId=tenant-123
Content-Type: application/json

Body parcial:

{
  "phone": "5599999999",
  "segment": "vip",
  "allowCredit": true
}

Todos los campos del body son opcionales en actualización. tenantId es requerido como query param para localizar el registro.

Incrementar Total De Órdenes

PATCH /customers/:id/orders/increment?tenantId=tenant-123

Incrementa totalOrders en 1 y actualiza updatedAt.

Eliminar Cliente

DELETE /customers/:id?tenantId=tenant-123

Respuesta:

{
  "deleted": true
}

Contrato De Respuesta Customer

Todas las respuestas de cliente usan este shape:

{
  "id": "string",
  "tenantId": "string",
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "phone": "string",
  "city": "string",
  "status": "active",
  "segment": "general",
  "notes": "string",
  "totalOrders": 0,
  "registeredAt": "string",
  "updatedAt": "string",
  "allowCredit": false
}