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:
userIddebe 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=20Cualquier rol autenticado del tenant (incl. MEMBER/VIEWER). Respuesta paginada { data, total, page, limit }.
Obtener / actualizar / eliminar
| Método | Ruta | Roles |
|---|---|---|
GET | /clients/:id | Cualquier rol del tenant |
PATCH | /clients/:id | OWNER, ADMIN |
DELETE | /clients/:id | OWNER, ADMIN — 204 |
Relacionado
- Empresas — identidad fiscal del emisor
- Roles y permisos