Gestión de Proveedores

El recurso /providers gestiona el catálogo de proveedores, suministradores y acreedores en BaseGes ERP. Es el maestro indispensable para asociar albaranes de compra, recepciones de material y facturas de gasto.

Seguridad

Requiere autorización mediante cabecera HTTP:

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

---

Resumen de Operaciones

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

---

1. Alta de un Nuevo Proveedor (POST)

POST /providers

Da de alta una nueva ficha de proveedor en el maestro de compras.

Comportamiento de la Cuenta Contable (account)

• Automática (si se omite): Al igual que el ERP, genera la subcuenta 40 + los últimos 7 dígitos del código de proveedor (9 dígitos, ej. código 00000015 → 400000015) y valida que no esté asignada a otro proveedor ni exista ya en la tabla contable {YEAR}Ccuentas del ejercicio vigente. Si ya existe, la petición devuelve un error/aviso para que se informe manualmente.
• Manual (si se informa en el payload): Se valida que no esté asignada a ningún otro proveedor.

Parámetros del Cuerpo JSON

Campo	Tipo	Obligatorio	Descripción
name	string	Sí	Nombre fiscal o razón social del proveedor.
vatNumber	string	Sí	CIF / NIF del proveedor o documento identificativo.
code	string	No	Código manual. Si se omite, BaseGes genera el siguiente código disponible.
usualName	string	No	Nombre comercial habitual o marca.
email	string	No	Email para envío de órdenes de compra o consultas de facturas.
phone	string	No	Teléfono de contacto.
address	string	No	Dirección fiscal o sede central.
postalCode	string	No	Código postal.
city	string	No	Población.
province	string	No	Provincia.
countryCode	string	No	Código de país (ej. "ES").
account	string	No	Subcuenta contable de 9 dígitos del proveedor (ej. "400000015"). Si se omite, se deriva como 40 + últimos 7 dígitos de code.
providerGroupCode	string	No	Grupo de compras / familia de proveedores.
isCarrier	number	No	Indicar 1 si el proveedor actúa como transportista.
isCommissionAgent	number	No	Indicar 1 si actúa como comisionista o intermediario.
currency	string	No	Moneda predeterminada (ej. "EUR").
observations	string	No	Notas internas de gestión.

Ejemplo de Petición POST

POST /providers HTTP/1.1
Host: localhost:5000
Content-Type: application/json
X-Api-Key: tu-api-key-secreta

{
  "name": "Distribuciones de Fontanería y Clima S.A.",
  "vatNumber": "A99887766",
  "usualName": "Fontanería y Clima",
  "email": "pedidos@fontaneriayclima.com",
  "phone": "+34 912 345 678",
  "address": "Camino de las Huertas, 12",
  "postalCode": "28223",
  "city": "Pozuelo de Alarcón",
  "province": "Madrid",
  "countryCode": "ES",
  "currency": "EUR"
}

Respuesta Exitosa (201 Created)

{
  "code": "PRV00054",
  "name": "Distribuciones de Fontanería y Clima S.A.",
  "vatNumber": "A99887766"
}

---

2. Actualización Completa (PUT)

PUT /providers/{code}

Reemplaza todos los datos del proveedor identificado por {code}.

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

{
  "name": "Distribuciones de Fontanería, Clima y Renovables S.A.",
  "vatNumber": "A99887766",
  "email": "administracion@fontaneriayclima.com",
  "phone": "+34 912 345 679",
  "address": "Camino de las Huertas, 14",
  "postalCode": "28223",
  "city": "Pozuelo de Alarcón",
  "province": "Madrid",
  "countryCode": "ES"
}

---

3. Actualización Parcial (PATCH)

PATCH /providers/{code}

Permite modificar campos concretos sin necesidad de enviar la ficha completa (por ejemplo, cambiar el email de pedidos o el teléfono):

PATCH /providers/PRV00054 HTTP/1.1
Host: localhost:5000
Content-Type: application/json
X-Api-Key: tu-api-key-secreta

{
  "email": "nuevo-pedidos@fontaneriayclima.com",
  "phone": "+34 910 000 111"
}

---

4. Consultas y Filtros (GET)

GET /providers

Filtros habituales disponibles en query string:

• search: Búsqueda predictiva en código, nombre, NIF, dirección, población, teléfono y email.
• updatedAfter: Obtener únicamente los proveedores dados de alta o modificados a partir de una fecha determinada.
• page y pageSize: Control de paginación (máximo 100 por página).