Clients (Clientes)

Listar clientes

GET /v1/clients

Retorna una lista paginada de clientes. Soporta el sistema de filtrado, incluyendo filtros por campos personalizados.

Respuesta exitosa: 200 OK

{
  "total": 150,
  "items": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "firstname": "Juan",
      "lastname": "Pérez",
      "email": "juan@example.com",
      "phone": "+593991234568",
      "doc_type": "cedula",
      "doc_number": "1234567890",
      "birthdate": "1990-05-15",
      "address": "Av. Principal 123",
      "city": "Quito",
      "state": "Pichincha",
      "country": "Ecuador",
      "business_account_id": "aa0e8400-e29b-41d4-a716-446655440005",
      "custom_fields": [
        { "id": "dd0e8400-e29b-41d4-a716-446655440009", "value": "premium" },
        { "id": "ee0e8400-e29b-41d4-a716-446655440010", "value": "referido" }
      ]
    }
  ]
}

Obtener cliente

GET /v1/clients/{id}

Parámetro	Tipo	Descripción
id	string (UUID)	ID del cliente

Respuesta exitosa: 200 OK — Un único objeto Client.

Respuesta error: 404 Not Found — { "message": "Client not found." }

Crear cliente

POST /v1/clients

Campo	Tipo	Requerido	Descripción
firstname	string	Si	Nombre (máx. 255)
lastname	string	Si	Apellido (máx. 255)
email	string	Si	Email válido (máx. 255)
phone	string	Si	Teléfono internacional (máx. 50)
docType	string	No	Tipo de documento (máx. 50)
docNumber	string	No	Número de documento (máx. 100)
birthdate	string	No	Fecha de nacimiento (YYYY-MM-DD)
address	string	No	Dirección (máx. 500)
city	string	No	Ciudad (máx. 255)
state	string	No	Estado/Provincia (máx. 255)
country	string	No	País (máx. 255)
customFields	array	No	Valores de campos personalizados
customFields[].fieldId	string (UUID)	Si*	UUID del campo personalizado
customFields[].value	string	Si*	Valor del campo

*Requerido cuando se envía customFields.

Ejemplo:

{
  "firstname": "Juan",
  "lastname": "Pérez",
  "email": "juan@example.com",
  "phone": "+593991234568",
  "docType": "cedula",
  "docNumber": "1234567890",
  "birthdate": "1990-05-15",
  "address": "Av. Principal 123",
  "city": "Quito",
  "state": "Pichincha",
  "country": "Ecuador",
  "customFields": [{ "fieldId": "dd0e8400-e29b-41d4-a716-446655440009", "value": "premium" }]
}

Respuesta exitosa: 201 Created — { "id": "ff0e8400-e29b-41d4-a716-446655440011" }

Actualizar cliente

PUT /v1/clients/{id}

Body: mismo schema que la creación. Todos los campos requeridos deben enviarse.

Respuesta exitosa: 204 No Content

Eliminar cliente

DELETE /v1/clients/{id}

Realiza un soft-delete del cliente.

Respuesta exitosa: 204 No Content