Skip to content

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: userId must 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=20

Any authenticated role of the tenant (including MEMBER/VIEWER). Paginated response { data, total, page, limit }.

Get / update / delete ​

MethodRouteRoles
GET/clients/:idAny role of the tenant
PATCH/clients/:idOWNER, ADMIN
DELETE/clients/:idOWNER, ADMIN — 204