Customers

Clientes/empresas — raiz do multi-tenancy. Base path: /api/customers · autenticação de usuário.

Método	Rota	Scope	Resource	Ação (role)	Sucesso
`POST`	`/api/customers`	`create`	`resource:customers`	`create`	`201`
`GET`	`/api/customers`	`read`	`resource:customers`	`read`	`200`
`GET`	`/api/customers/:id`	`read`	`resource:customers_id`	`read`	`200`
`PUT`	`/api/customers/:id`	`update`	`resource:customers_id`	`update`	`200`
`DELETE`	`/api/customers/:id`	`delete`	`resource:customers_id`	`delete`	`204`

Controle de acesso por persona. Módulo customers é exclusivo da persona global — nem tenant-admin, technician nem viewer entram por padrão (só via role de exceção customers:acao). Token sem role suficiente → 403 NOT_ALLOWED.

Criar customer

POST /api/customers

Corpo

Campo	Tipo	Obrigatório	Regras
`federalTaxId`	string	sim	11 a 14 caracteres, único
`name`	string	sim	mín. 1 caractere
`alias`	string	não	pode ser `null`
`email`	string	não	e-mail válido ou `null`
`phone`	string	não	pode ser `null`
`logoPath`	string	não	pode ser `null`
`active`	boolean	não	padrão `true`

curl -X POST http://localhost:3000/api/customers \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "federalTaxId": "12345678000199",
    "name": "Customer Exemplo",
    "alias": "exemplo",
    "email": "contato@exemplo.com",
    "phone": "11999999999",
    "active": true
  }'

201 Created

{
  "id": "c1b2c3d4-e5f6-4789-a123-456789abcdef",
  "federalTaxId": "12345678000199",
  "name": "Customer Exemplo",
  "alias": "exemplo",
  "email": "contato@exemplo.com",
  "phone": "11999999999",
  "active": true
}

Erros

Status	`code`	Quando
`409`	`CUSTOMER_ALREADY_EXISTS`	Já existe um customer com esse `federalTaxId`

Listar customers

GET /api/customers — lista paginada (page, limit). Envelope padrão de paginação.

Obter customer por id

GET /api/customers/:id

Erros

Status	`code`	Quando
`404`	`CUSTOMER_NOT_FOUND`	Customer não existe

Editar customer

PUT /api/customers/:id — atualização parcial.

Campo	Tipo	Regras
`name`	string	mín. 1 caractere
`alias`	string	ou `null`
`email`	string	e-mail válido ou `null`
`phone`	string	ou `null`
`logoPath`	string	ou `null`
`active`	boolean

Retorna 200.

Erros

Status	`code`	Quando
`404`	`CUSTOMER_NOT_FOUND`	Customer não existe

Remover customer

DELETE /api/customers/:id — retorna 204 No Content.

Erros

Status	`code`	Quando
`404`	`CUSTOMER_NOT_FOUND`	Customer não existe

Criar customer

Listar customers

Obter customer por id

Editar customer

Remover customer

On this page