Skip to content

Clientes (facturación comercial) ​

Los clientes son los destinatarios de documentos comerciales de una empresa. Cada cliente pertenece a un tenant (companyId) y puede enlazarse de forma opcional a un usuario miembro de esa empresa; el cliente sigue siendo la entidad facturable.

Conceptos clave ​

  • Aislamiento multi-tenant: una empresa nunca ve ni modifica los clientes de otra (404 en acceso cruzado).
  • Identidad fiscal del receptor: nombre/razón social, identificador fiscal, dirección y país (mismo vocabulario que la identidad fiscal de empresa).
  • Enlace opcional a usuario: userId debe ser un miembro de la empresa emisora; ids desconocidos o de otro tenant → 404 (sin sondeo cross-tenant). No convierte al usuario en el receptor legal.
  • RBAC: MEMBER y VIEWER solo leen; OWNER/ADMIN crean, actualizan y borran.

Endpoints ​

Todos requieren Authorization: Bearer <token> y contexto de empresa (X-Company-Id o JWT con companyId).

Crear ​

http
POST /clients
Content-Type: application/json

{
  "name": "Cliente Demo S.L.",
  "taxId": "B87654321",
  "fiscalAddress": "Calle Ejemplo 1, 08001 Barcelona",
  "fiscalCountryCode": "ES",
  "email": "billing@cliente.example",
  "phone": "+34 600 000 000",
  "userId": null
}

Requiere OWNER o ADMIN. Respuesta 201.

Listar ​

http
GET /clients?page=1&limit=20

Cualquier rol autenticado del tenant (incl. MEMBER/VIEWER). Respuesta paginada { data, total, page, limit }.

Obtener / actualizar / eliminar ​

MétodoRutaRoles
GET/clients/:idCualquier rol del tenant
PATCH/clients/:idOWNER, ADMIN
DELETE/clients/:idOWNER, ADMIN — 204

Relacionado ​