API REST

Health del servicio

GET /health

Respuesta:

{
  "status": true,
  "service": "suppliers-api",
  "msg": "OK"
}

Campos del body:

Campo	Obligatorio	Nota
tenantId	Si	Identifica al tenant propietario
name	Si	Nombre comercial
contactName	Si	Contacto principal
email	Si	Debe ser email válido
phone	Si	Teléfono
status	Si	active o inactive
requiresInvoice	Si	Define si se requieren datos fiscales
legalName	Condicional	Requerido si requiresInvoice es true
taxId	Condicional	Requerido si requiresInvoice es true
taxRegime	Condicional	Requerido si requiresInvoice es true
billingEmail	Condicional	Requerido si requiresInvoice es true; debe ser email válido
fiscalAddress	Condicional	Requerido si requiresInvoice es true
postalCode	Condicional	Requerido si requiresInvoice es true
website	No	Opcional
paymentTerms	No	Opcional
leadTimeDays	No	Opcional; entero entre 0 y 365
notes	No	Opcional

Health del módulo

GET /suppliers/health

Respuesta:

{
  "status": true,
  "msg": "OK"
}

Crear proveedor

POST /suppliers
Content-Type: application/json

Body:

{
  "tenantId": "tenant-123",
  "name": "Proveedor Demo",
  "contactName": "Ana Perez",
  "email": "ana@example.com",
  "phone": "5512345678",
  "status": "active",
  "requiresInvoice": true,
  "legalName": "Proveedor Demo SA de CV",
  "taxId": "abc010203xyz",
  "taxRegime": "601",
  "billingEmail": "facturacion@example.com",
  "fiscalAddress": "Av. Reforma 123",
  "postalCode": "01000",
  "website": "https://example.com",
  "paymentTerms": "30 dias",
  "leadTimeDays": 7,
  "notes": "Proveedor preferente"
}

Respuesta 201:

{
  "id": "665f1f000000000000000001",
  "tenantId": "tenant-123",
  "name": "Proveedor Demo",
  "contactName": "Ana Perez",
  "email": "ana@example.com",
  "phone": "5512345678",
  "status": "active",
  "requiresInvoice": true,
  "legalName": "Proveedor Demo SA de CV",
  "taxId": "ABC010203XYZ",
  "taxRegime": "601",
  "billingEmail": "facturacion@example.com",
  "fiscalAddress": "Av. Reforma 123",
  "postalCode": "01000",
  "website": "https://example.com",
  "paymentTerms": "30 dias",
  "leadTimeDays": 7,
  "notes": "Proveedor preferente",
  "createdAt": "2026-06-24T19:30:00.000Z",
  "updatedAt": "2026-06-24T19:30:00.000Z"
}

Listar proveedores

GET /suppliers?tenantId=tenant-123

Parámetros query:

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

Ejemplo con búsqueda:

GET /suppliers?tenantId=tenant-123&search=demo

Respuesta:

{
  "items": [
    {
      "id": "665f1f000000000000000001",
      "tenantId": "tenant-123",
      "name": "Proveedor Demo",
      "contactName": "Ana Perez",
      "email": "ana@example.com",
      "phone": "5512345678",
      "status": "active",
      "requiresInvoice": true,
      "legalName": "Proveedor Demo SA de CV",
      "taxId": "ABC010203XYZ",
      "taxRegime": "601",
      "billingEmail": "facturacion@example.com",
      "fiscalAddress": "Av. Reforma 123",
      "postalCode": "01000",
      "website": "https://example.com",
      "paymentTerms": "30 dias",
      "leadTimeDays": 7,
      "notes": "Proveedor preferente",
      "createdAt": "2026-06-24T19:30:00.000Z",
      "updatedAt": "2026-06-24T19:30:00.000Z"
    }
  ],
  "total": 1
}

Obtener proveedor

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

Si no existe un proveedor con ese id y tenantId, la API lanza NotFoundException con mensaje Supplier not found.

Actualizar proveedor

PATCH /suppliers/:id
Content-Type: application/json

tenantId es requerido en el body porque el caso de uso lo utiliza para localizar el registro actual.

Body parcial:

{
  "tenantId": "tenant-123",
  "phone": "5599999999",
  "status": "inactive",
  "requiresInvoice": false
}

Cuando requiresInvoice queda en false, se limpian los campos fiscales en la persistencia.

Campos del body:

Campo	Obligatorio	Nota
tenantId	Si	Requerido para localizar el registro por tenant
name	No	Opcional
contactName	No	Opcional
email	No	Opcional; debe ser email válido si se envía
phone	No	Opcional
status	No	Opcional; active o inactive
requiresInvoice	No	Opcional
legalName	Condicional	Requerido si requiresInvoice se envía como true
taxId	Condicional	Requerido si requiresInvoice se envía como true
taxRegime	Condicional	Requerido si requiresInvoice se envía como true
billingEmail	Condicional	Requerido si requiresInvoice se envía como true; debe ser email válido
fiscalAddress	Condicional	Requerido si requiresInvoice se envía como true
postalCode	Condicional	Requerido si requiresInvoice se envía como true
website	No	Opcional
paymentTerms	No	Opcional
leadTimeDays	No	Opcional; entero entre 0 y 365
notes	No	Opcional

Eliminar proveedor

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

Respuesta:

{
  "deleted": true
}

Si no existe un proveedor con ese id y tenantId, la API lanza NotFoundException con mensaje Supplier not found.

Contrato de respuesta Supplier

Todas las respuestas de proveedor usan este shape:

{
  "id": "string",
  "tenantId": "string",
  "name": "string",
  "contactName": "string",
  "email": "string",
  "phone": "string",
  "status": "active",
  "requiresInvoice": true,
  "legalName": "string",
  "taxId": "string",
  "taxRegime": "string",
  "billingEmail": "string",
  "fiscalAddress": "string",
  "postalCode": "string",
  "website": "string",
  "paymentTerms": "string",
  "leadTimeDays": 0,
  "notes": "string",
  "createdAt": "string",
  "updatedAt": "string"
}