Clients (commercial billing)
Clients are the recipients of a company's commercial documents. Each client belongs to a tenant (companyId) and can optionally be linked to a user who is a member of that company; the client remains the billable entity.
Key concepts
- Multi-tenant isolation: a company never sees or modifies another company's clients (404 on cross-tenant access).
- Recipient fiscal identity: legal name, tax identifier, address and country (same vocabulary as the company fiscal identity).
- Optional user link:
userIdmust be a member of the issuing company; unknown or other-tenant ids answer 404 (no cross-tenant probing). It does not turn the user into the legal recipient. - RBAC: MEMBER and VIEWER read only; OWNER/ADMIN create, update and delete.
Endpoints
All require Authorization: Bearer <token> and a company context (X-Company-Id or a JWT with companyId).
Create
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
}Requires OWNER or ADMIN. Responds 201.
List
http
GET /clients?page=1&limit=20Any authenticated role of the tenant (including MEMBER/VIEWER). Paginated response { data, total, page, limit }.
Get / update / delete
| Method | Route | Roles |
|---|---|---|
GET | /clients/:id | Any role of the tenant |
PATCH | /clients/:id | OWNER, ADMIN |
DELETE | /clients/:id | OWNER, ADMIN — 204 |
Related
- Companies — issuer fiscal identity
- Roles and permissions