Referência

Estética e beleza

A camada de negócio do salão sobre a agenda das Marcações: o catálogo de serviços de beleza com as suas exigências de segurança, a configuração, a próxima visita (rebook), o material esterilizado (kits) e os relatórios de higiene e de indicadores. O serviço, o tempo e o preço continuam a ser das Marcações. As fichas dos clientes e o que lhes diz respeito estão na área «Fichas de beleza».

Operação	O que faz
GET `/api/beleza/modelos`	Os modelos de serviço de beleza de partida.
GET `/api/beleza/servicos`	Os serviços da agenda com os atributos de beleza.
PUT `/api/beleza/servicos/{servicoId}`	Define (ou redefine) os atributos de beleza de um serviço da agenda.
POST `/api/beleza/servicos/de-modelo`	Cria o serviço da agenda a partir de um modelo de partida e liga-o a um artigo do tipo Serviço que a empresa já tem.
GET `/api/beleza/configuracao`	A configuração da beleza: segmentos, avisos do ciclo, janela do briefing e validade da esterilização.
PUT `/api/beleza/configuracao`	Define a configuração da beleza.
GET `/api/beleza/rebooks`	As próximas visitas propostas aos clientes (rebooks).
POST `/api/beleza/marcacoes/{marcacaoId}/rebook`	Propõe a próxima visita de um serviço feito: na data do ciclo do serviço (ou na que se disser), com o profissional que o fez.
POST `/api/beleza/rebooks/{id}/aceitar`	O cliente aceita a próxima visita: cria a marcação na hora indicada.
POST `/api/beleza/rebooks/{id}/recusar`	O cliente recusa a próxima visita proposta.
GET `/api/beleza/kits`	Os kits de material (esterilizado, em uso, sujo, em esterilização).
POST `/api/beleza/kits`	Cria um kit de material.
PUT `/api/beleza/kits/{id}`	Altera um kit de material.
POST `/api/beleza/kits/ler`	Lê o código de um kit para começar um serviço: se está esterilizado e dentro da validade passa a «em uso»; senão a leitura fica recusada e registada.
POST `/api/beleza/kits/{id}/sujo`	Marca um kit como sujo.
POST `/api/beleza/kits/{id}/esterilizacao/iniciar`	Inicia a esterilização de um kit.
POST `/api/beleza/kits/{id}/esterilizacao/concluir`	Conclui a esterilização de um kit, com o lote, o aparelho e a validade.
GET `/api/beleza/higiene/relatorio`	O relatório de higiene de um período.
GET `/api/beleza/indicadores`	Os indicadores da beleza de um período.

GET/api/beleza/modelos#

Os modelos de serviço de beleza de partida.

Permissão Beleza.Ler

segmento limita a um segmento (Cabeleireiro, Barbearia, Trancas, Estetica ou Spa).

Parâmetros

Nome	Onde	Tipo	Obrigatório
`segmento`	na pesquisa	texto

Pedido

curl

curl 'https://<endereço-da-API>/api/beleza/modelos' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/beleza/servicos#

Os serviços da agenda com os atributos de beleza.

Permissão Beleza.Ler

apenasActivos (por omissão, verdadeiro).

Parâmetros

Nome	Onde	Tipo	Obrigatório
`apenasActivos`	na pesquisa	verdadeiro/falso

Pedido

curl

curl 'https://<endereço-da-API>/api/beleza/servicos' \
  -H 'X-Api-Key: <a-sua-chave>'

PUT/api/beleza/servicos/{servicoId}#

Define (ou redefine) os atributos de beleza de um serviço da agenda.

Permissão Beleza.CatalogoEditar

O serviço, o tempo e o preço continuam a ser das Marcações.

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`servicoId`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · AtributosInput)

Campo	Tipo	Obrigatório	Significado
`familia`	texto	sim
`patchTest`	texto ou nulo
`patchTestValidadeDias`	número inteiro	sim
`patchTestAntecedenciaHoras`	número inteiro	sim
`contraIndicacoes`	lista de texto ou nulo
`quimicaIncompativelDias`	número inteiro ou nulo
`exigeRegistoTecnico`	verdadeiro/falso	sim
`tipoDeRegisto`	texto ou nulo
`exigeFotos`	verdadeiro/falso	sim
`exigeKit`	verdadeiro/falso	sim
`consultaPrevia`	verdadeiro/falso	sim
`cicloDias`	número inteiro ou nulo
`cuidadosEmCasa`	texto ou nulo
`modeloOrigem`	texto ou nulo
`doses`	lista de objectos ou nulo
`doses[].produtoId`	identificador (UUID)	sim	O artigo.
`doses[].quantidade`	número	sim	A quantidade.
`doses[].unidade`	texto	sim
`doses[].descartavel`	verdadeiro/falso	sim

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/beleza/servicos/<servicoId>' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "familia": "texto",
  "patchTestValidadeDias": 1,
  "patchTestAntecedenciaHoras": 1,
  "exigeRegistoTecnico": false,
  "exigeFotos": false,
  "exigeKit": false,
  "consultaPrevia": false
}'

POST/api/beleza/servicos/de-modelo#

Cria o serviço da agenda a partir de um modelo de partida e liga-o a um artigo do tipo Serviço que a empresa já tem.

Permissão Beleza.CatalogoEditar
Idempotência aceita Idempotency-Key

modeloChave, produtoId, nome e preco. O IVA e o preço são do artigo, nunca do modelo. O profissional e os recursos ligam-se depois, nas Marcações.

Corpo do pedido (JSON · CriarServicoDeModeloCommand)

Campo	Tipo	Obrigatório	Significado
`modeloChave`	texto	sim
`produtoId`	identificador (UUID)	sim	O artigo.
`nome`	texto ou nulo		O nome.
`preco`	número ou nulo

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/beleza/servicos/de-modelo' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "modeloChave": "texto",
  "produtoId": "00000000-0000-0000-0000-000000000000"
}'

GET/api/beleza/configuracao#

A configuração da beleza: segmentos, avisos do ciclo, janela do briefing e validade da esterilização.

Permissão Beleza.Ler

Pedido

curl

curl 'https://<endereço-da-API>/api/beleza/configuracao' \
  -H 'X-Api-Key: <a-sua-chave>'

PUT/api/beleza/configuracao#

Define a configuração da beleza.

Permissão Beleza.Configurar

segmentos, avisoDoCicloDias, toleranciaDoCicloDias, janelaDoBriefingHoras, relacaoComAFichaDias e validadeDaEsterilizacaoDias.

Devolve 204, sem corpo.

Corpo do pedido (JSON · DefinirConfiguracaoDaBelezaCommand)

Campo	Tipo	Obrigatório
`segmentos`	lista de texto	sim
`avisoDoCicloDias`	número inteiro	sim
`toleranciaDoCicloDias`	número inteiro	sim
`janelaDoBriefingHoras`	número inteiro	sim
`relacaoComAFichaDias`	número inteiro	sim
`validadeDaEsterilizacaoDias`	número inteiro	sim

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/beleza/configuracao' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "segmentos": [
    "texto"
  ],
  "avisoDoCicloDias": 1,
  "toleranciaDoCicloDias": 1,
  "janelaDoBriefingHoras": 1,
  "relacaoComAFichaDias": 1,
  "validadeDaEsterilizacaoDias": 1
}'

GET/api/beleza/rebooks#

As próximas visitas propostas aos clientes (rebooks).

Permissão Beleza.Ler

Filtros: estado (Proposto, Aceite, Recusado ou Expirado) e dias (por omissão 60).

Parâmetros

Nome	Onde	Tipo	Obrigatório
`estado`	na pesquisa	texto
`dias`	na pesquisa	número inteiro

Pedido

curl

curl 'https://<endereço-da-API>/api/beleza/rebooks' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/beleza/marcacoes/{marcacaoId}/rebook#

Propõe a próxima visita de um serviço feito: na data do ciclo do serviço (ou na que se disser), com o profissional que o fez.

Permissão Beleza.Atender
Idempotência aceita Idempotency-Key

servicoId e, se quiser, a data.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`marcacaoId`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · RebookPedido)

Campo	Tipo	Obrigatório	Significado
`servicoId`	identificador (UUID)	sim
`data`	data (AAAA-MM-DD) ou nulo		A data e hora (UTC).

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/beleza/marcacoes/<marcacaoId>/rebook' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "servicoId": "00000000-0000-0000-0000-000000000000"
}'

POST/api/beleza/rebooks/{id}/aceitar#

O cliente aceita a próxima visita: cria a marcação na hora indicada.

Permissão Beleza.Atender
Idempotência aceita Idempotency-Key

inicio e, se quiser, o profissionalId. Devolve 200 com o marcacaoId.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · AceitarPedido)

Campo	Tipo	Obrigatório
`inicio`	data e hora (ISO 8601)	sim
`profissionalId`	identificador (UUID) ou nulo

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/beleza/rebooks/<id>/aceitar' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "inicio": "2026-10-12T09:00:00Z"
}'

POST/api/beleza/rebooks/{id}/recusar#

O cliente recusa a próxima visita proposta.

Permissão Beleza.Atender

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/beleza/rebooks/<id>/recusar' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/beleza/kits#

Os kits de material (esterilizado, em uso, sujo, em esterilização).

Permissão Beleza.Ler

apenasActivos (por omissão, verdadeiro). lojaId é opcional quando a chave só tem um estabelecimento.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`lojaId`	na pesquisa	identificador (UUID)
`apenasActivos`	na pesquisa	verdadeiro/falso

Pedido

curl

curl 'https://<endereço-da-API>/api/beleza/kits' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/beleza/kits#

Cria um kit de material.

Permissão Beleza.Higiene
Idempotência aceita Idempotency-Key

codigo e nome.

Corpo do pedido (JSON · KitPedido)

Campo	Tipo	Significado
`lojaId`	identificador (UUID) ou nulo	O estabelecimento.
`codigo`	texto ou nulo	O código curto.
`nome`	texto ou nulo	O nome.
`activo`	verdadeiro/falso ou nulo	Se está activo.

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/beleza/kits' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{}'

PUT/api/beleza/kits/{id}#

Altera um kit de material.

Permissão Beleza.Higiene

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · KitPedido)

Campo	Tipo	Significado
`lojaId`	identificador (UUID) ou nulo	O estabelecimento.
`codigo`	texto ou nulo	O código curto.
`nome`	texto ou nulo	O nome.
`activo`	verdadeiro/falso ou nulo	Se está activo.

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/beleza/kits/<id>' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST/api/beleza/kits/ler#

Lê o código de um kit para começar um serviço: se está esterilizado e dentro da validade passa a «em uso»; senão a leitura fica recusada e registada.

Permissão Beleza.Atender
Idempotência aceita Idempotency-Key

codigo e, se quiser, marcacaoId e profissionalId.

Corpo do pedido (JSON · LeituraPedido)

Campo	Tipo	Significado
`codigo`	texto ou nulo	O código curto.
`marcacaoId`	identificador (UUID) ou nulo
`profissionalId`	identificador (UUID) ou nulo

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/beleza/kits/ler' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST/api/beleza/kits/{id}/sujo#

Marca um kit como sujo.

Permissão Beleza.Atender

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/beleza/kits/<id>/sujo' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/beleza/kits/{id}/esterilizacao/iniciar#

Inicia a esterilização de um kit.

Permissão Beleza.Higiene

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/beleza/kits/<id>/esterilizacao/iniciar' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/beleza/kits/{id}/esterilizacao/concluir#

Conclui a esterilização de um kit, com o lote, o aparelho e a validade.

Permissão Beleza.Higiene
Idempotência aceita Idempotency-Key

lote e aparelho são obrigatórios; validadeDias é opcional.

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · EsterilizacaoPedido)

Campo	Tipo	Obrigatório
`lote`	texto ou nulo
`aparelho`	texto ou nulo
`validadeDias`	número inteiro ou nulo

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/beleza/kits/<id>/esterilizacao/concluir' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{}'

GET/api/beleza/higiene/relatorio#

O relatório de higiene de um período.

Permissão Beleza.Higiene

de e ate são obrigatórios.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`de`	na pesquisa	data e hora (ISO 8601)	sim
`ate`	na pesquisa	data e hora (ISO 8601)	sim

Pedido

curl

curl 'https://<endereço-da-API>/api/beleza/higiene/relatorio' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/beleza/indicadores#

Os indicadores da beleza de um período.

Permissão Beleza.IndicadoresVer

de e ate são obrigatórios.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`de`	na pesquisa	data e hora (ISO 8601)	sim
`ate`	na pesquisa	data e hora (ISO 8601)	sim

Pedido

curl

curl 'https://<endereço-da-API>/api/beleza/indicadores' \
  -H 'X-Api-Key: <a-sua-chave>'