Gestión de Clientes

El recurso /customers permite consultar, crear, modificar y actualizar parcialmente fichas de clientes en BaseGes ERP.

Seguridad y Permisos

Todos los endpoints requieren autorización válida mediante cabecera HTTP:

• X-Api-Key: {tu_clave_api}
• O bien Authorization: Bearer {tu_token_jwt}

---

Resumen de Operaciones

Método	Endpoint	Acción	Cuerpo de Petición	Código Éxito
GET	/customers	Listado paginado con búsqueda	Ninguno	200 OK
GET	/customers/{code}	Detalle completo de un cliente	Ninguno	200 OK
POST	/customers	Alta de nuevo cliente	JSON (CreateCustomerCommand)	201 Created
PUT	/customers/{code}	Actualización completa de la ficha	JSON (UpdateCustomerCommand)	200 OK
PATCH	/customers/{code}	Actualización parcial de campos	JSON (PartialUpdateCustomerCommand)	200 OK

---

1. Alta de un Nuevo Cliente (POST)

POST /customers

Crea una nueva ficha de cliente en la base de datos de BaseGes validando la estructura del NIF/CIF y evitando duplicidades.

Comportamiento del Código (Code) y Cuenta Contable (accountingAccount)

• Código (code): Si se omite o se envía como null, el ERP asigna automáticamente el siguiente código numérico disponible de 8 dígitos según el contador de la empresa. Si se indica manualmente, comprueba que no exista previamente.
• Cuenta Contable (accountingAccount):
  • Automática (si se omite): Al igual que el ERP, genera la subcuenta 43 + los últimos 7 dígitos del código de cliente (9 dígitos, ej. código 00000042 → 430000042) y valida que no esté asignada a otro cliente ni exista ya en la tabla contable {YEAR}Ccuentas del ejercicio vigente. Si ya existe, la petición devuelve un error/aviso indicando el conflicto para que se defina una manualmente.
  • Manual (si se informa en el payload): Se valida que no esté asignada a ningún otro cliente.

Campos del Payload JSON

Campo	Tipo	Obligatorio	Descripción
name	string	Sí	Razón social o nombre fiscal completo del cliente.
vatNumber	string	Sí	Documento fiscal (NIF, CIF, NIE o pasaporte).
code	string	No	Código manual. Si se omite, el ERP lo autonumera.
usualName	string	No	Nombre comercial o alias habitual.
email	string	No	Correo electrónico principal de facturación/contacto.
phone	string	No	Teléfono de contacto.
address	string	No	Dirección fiscal (calle, número, piso).
postalCode	string	No	Código postal (ej. "08006").
city	string	No	Población o municipio.
state	string	No	Provincia.
countryCode	string	No	Código de país (ISO o código interno del ERP, ej. "ES").
customerGroupCode	string	No	Grupo de clientes al que pertenece.
customerTypeCode	string	No	Tipo de cliente para clasificación comercial.
accountingAccount	string	No	Subcuenta contable de 9 dígitos (ej. "430000120"). Si se omite, se deriva como 43 + últimos 7 dígitos de code.
paymentMethod	string	No	Código de la forma de pago (ej. "TRANSF", "REC30").
paymentDay1	number	No	Primer día de pago del mes (1 a 31).
paymentDay2	number	No	Segundo día de pago del mes (1 a 31).
nonPaymentMonth	string	No	Mes en el que el cliente no atiende cobros (ej. "08" para agosto).
observations	string	No	Notas internas no visibles en facturas.

Ejemplo de Petición (Crear Cliente)

JSON Body

{
  "name": "Instalaciones y Proyectos Mediterráneo S.L.",
  "vatNumber": "B12345678",
  "usualName": "Instalaciones Mediterráneo",
  "email": "facturas@instalacionesmediterraneo.com",
  "phone": "+34 963 888 777",
  "address": "Calle Industria, 24, Polígono Fuente del Jarro",
  "postalCode": "46988",
  "city": "Paterna",
  "state": "Valencia",
  "countryCode": "ES",
  "paymentMethod": "TR30",
  "paymentDay1": 15,
  "paymentDay2": 30,
  "nonPaymentMonth": "08",
  "observations": "Cliente captado a través de la campaña web 2026"
}

cURL

curl -X POST "http://localhost:5000/customers" \
     -H "Content-Type: application/json" \
     -H "X-Api-Key: tu-api-key-secreta" \
     -d '{
       "name": "Instalaciones y Proyectos Mediterráneo S.L.",
       "vatNumber": "B12345678",
       "email": "facturas@instalacionesmediterraneo.com",
       "phone": "+34 963 888 777",
       "city": "Paterna"
     }'

Respuesta Exitosa (201 Created)

{
  "code": "000142",
  "name": "Instalaciones y Proyectos Mediterráneo S.L.",
  "vatNumber": "B12345678",
  "email": "facturas@instalacionesmediterraneo.com",
  "phone": "+34 963 888 777",
  "city": "Paterna"
}

---

2. Actualización Completa (PUT)

PUT /customers/{code}

Reemplaza todos los datos comerciales y de contacto del cliente identificado por {code}.

Sobrescritura de campos opcionales

Al utilizar PUT, si un campo opcional (como phone u observations) se omite o se envía vacío, se interpretará que debe eliminarse o resetearse en la ficha del ERP. Si solo desea modificar campos específicos, utilice PATCH.

Ejemplo de Petición PUT

PUT /customers/000142 HTTP/1.1
Host: localhost:5000
Content-Type: application/json
X-Api-Key: tu-api-key-secreta

{
  "name": "Instalaciones Mediterráneo Renovables S.L.",
  "vatNumber": "B12345678",
  "usualName": "Mediterráneo Renovables",
  "email": "administracion@mediterraneorenovables.com",
  "phone": "+34 963 999 000",
  "address": "Calle Industria, 26",
  "postalCode": "46988",
  "city": "Paterna",
  "state": "Valencia",
  "countryCode": "ES",
  "accountingAccount": "430000142"
}

---

3. Actualización Parcial (PATCH)

PATCH /customers/{code}

Permite modificar únicamente los campos enviados en el JSON, preservando intacto el resto de la ficha (dirección, bancos, condiciones fiscales, etc.).

Casos de Uso Frecuentes de PATCH

A. Actualizar solo datos de contacto y dirección

{
  "address": "Nueva Avenida Principal, 100",
  "postalCode": "46001",
  "city": "Valencia",
  "phone": "+34 960 112 233"
}

B. Modificar cuenta bancaria e IBAN para domiciliaciones

{
  "bank1": "Banco Santander",
  "iban1": "ES9121000418450200051332"
}

C. Cambiar condiciones comerciales o estado activo/baja

{
  "isActive": 1,
  "generalDiscount": 5.5,
  "applyEquivalentSurcharge": false
}

Respuestas y Códigos de Error

• 200 OK: Modificación aplicada con éxito.
• 400 Bad Request: Datos inválidos (NIF incorrecto, códigos foráneos no existentes).

  "El código de forma de pago especificado 'TR99' no existe en BaseGes."

• 404 Not Found: El código {code} indicado no existe en la base de datos.

---

4. Consultas y Listados (GET)

GET /customers

Para consultar el maestro de clientes con paginación y búsqueda predictiva:

GET /customers?page=1&pageSize=50&search=Mediterraneo&IsActive=1 HTTP/1.1
Host: localhost:5000
X-Api-Key: tu-api-key-secreta

Para sincronizar de forma incremental los clientes creados o modificados recientemente:

GET /customers?updatedAfter=2026-10-15T00:00:00Z HTTP/1.1