Referência

Fichas de beleza (dados sensíveis)

A ficha técnica viva de cada cliente (perfis de cabelo, pele, unhas e pestanas, condições de saúde e alergias), os testes de sensibilidade, os registos técnicos (fórmulas, receitas, técnicas), os consentimentos para fotografias, as fotografias, e o que se verifica e regista em cada atendimento. São dados pessoais, em parte de saúde: a chave só os alcança se o dono da empresa lhe deu, ao criá-la, acesso reforçado com um consentimento que cubra as fichas de beleza (versão 2 ou posterior), com endereços de rede e validade curta, e cada pedido fica registado. Ver Dados sensíveis.

Operação	O que faz
GET `/api/beleza/clientes/{clienteId}/ficha`	A ficha técnica de um cliente: perfis, preferências, condições, testes, consentimentos, ciclos, registos técnicos e fotografias.
PUT `/api/beleza/clientes/{clienteId}/ficha`	Define a ficha técnica de um cliente: os perfis de cabelo, pele, unhas e pestanas, as preferências, a data da última química e as notas da equipa.
POST `/api/beleza/clientes/{clienteId}/condicoes`	Regista uma condição (gravidez, alergia…) na ficha do cliente.
POST `/api/beleza/condicoes/{id}/remover`	Remove uma condição da ficha, com motivo.
POST `/api/beleza/clientes/{clienteId}/testes`	Aplica um teste de sensibilidade: fica pendente até alguém registar o resultado depois do tempo de leitura.
POST `/api/beleza/testes/{id}/resultado`	Regista o resultado de um teste de sensibilidade.
POST `/api/beleza/testes/{id}/anular`	Anula um teste, com motivo.
GET `/api/beleza/clientes/{clienteId}/registos`	Os registos técnicos de um cliente (fórmulas, receitas, técnicas).
POST `/api/beleza/clientes/{clienteId}/registos`	Cria um registo técnico na ficha do cliente.
POST `/api/beleza/registos/{id}/repetir`	Cria um registo técnico novo a partir de um existente (repetir a mesma fórmula ou receita).
POST `/api/beleza/clientes/{clienteId}/consentimentos`	Regista o consentimento do cliente para fotografias, para uma finalidade e uma versão do texto.
POST `/api/beleza/consentimentos/{id}/revogar`	Revoga um consentimento do cliente.
POST `/api/beleza/clientes/{clienteId}/fotos`	Anexa uma fotografia à ficha de um cliente.
GET `/api/beleza/fotos/{id}`	Descarrega uma fotografia de um cliente.
GET `/api/beleza/clientes/{clienteId}/acessos`	Quem consultou a ficha de um cliente e quando.
GET `/api/beleza/marcacoes/{marcacaoId}/verificacao`	O que a ficha do cliente tem a dizer sobre os serviços de uma marcação, numa fase do atendimento (avisos e bloqueios).
POST `/api/beleza/verificar-pedido`	Antes de marcar: o que a ficha do cliente tem a dizer sobre os serviços que se vão marcar (só avisos).
GET `/api/beleza/marcacoes/{marcacaoId}/cartao`	O cartão do atendimento: o cliente, as condições, as preferências, os consentimentos, a verificação de segurança, os serviços, os kits usados e as próximas visitas.
POST `/api/beleza/marcacoes/{marcacaoId}/respostas`	Regista a resposta do cliente a uma pergunta do questionário de segurança (sim ou não) numa marcação.
POST `/api/beleza/marcacoes/{marcacaoId}/doses`	Regista uma dose de produto usada num atendimento.

GET/api/beleza/clientes/{clienteId}/ficha#

A ficha técnica de um cliente: perfis, preferências, condições, testes, consentimentos, ciclos, registos técnicos e fotografias.

Permissão Beleza.Ler

As fotografias só vêm se o cliente consentiu: sem consentimento, fotosOcultasPorFaltaDeConsentimento vem verdadeiro.

Parâmetros

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

Pedido

curl

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

PUT/api/beleza/clientes/{clienteId}/ficha#

Define a ficha técnica de um cliente: os perfis de cabelo, pele, unhas e pestanas, as preferências, a data da última química e as notas da equipa.

Permissão Beleza.Ler

Devolve 204, sem corpo.

Parâmetros

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

Corpo do pedido (JSON · FichaPedido)

Campo	Tipo	Significado
`capilar`	objecto ou nulo
`capilar.textura`	texto ou nulo
`capilar.densidade`	texto ou nulo
`capilar.porosidade`	texto ou nulo
`capilar.comprimento`	texto ou nulo
`capilar.estado`	texto ou nulo	O estado actual.
`capilar.corNatural`	texto ou nulo
`capilar.corActual`	texto ou nulo
`capilar.brancosPct`	número inteiro ou nulo
`capilar.couroCabeludo`	texto ou nulo
`capilar.queda`	texto ou nulo
`capilar.historicoDeQuimica`	texto ou nulo
`pele`	objecto ou nulo
`pele.tipo`	texto ou nulo
`pele.fototipo`	texto ou nulo
`pele.sensibilidade`	texto ou nulo
`pele.manchas`	texto ou nulo
`pele.acne`	texto ou nulo
`pele.rosacea`	texto ou nulo
`pele.cicatrizes`	texto ou nulo
`pele.exposicaoSolar`	texto ou nulo
`pele.produtosEmUso`	texto ou nulo
`pele.tratamentosRecentes`	texto ou nulo
`unhas`	objecto ou nulo
`unhas.tipo`	texto ou nulo
`unhas.formato`	texto ou nulo
`unhas.comprimento`	texto ou nulo
`unhas.historicoDeLesoes`	texto ou nulo
`unhas.coresHabituais`	texto ou nulo
`pestanas`	objecto ou nulo
`pestanas.formato`	texto ou nulo
`pestanas.curvatura`	texto ou nulo
`pestanas.espessura`	texto ou nulo
`pestanas.formaDeSobrancelha`	texto ou nulo
`preferencias`	objecto ou nulo
`preferencias.profissionalHabitualId`	identificador (UUID) ou nulo
`preferencias.bebida`	texto ou nulo
`preferencias.prefereSilencio`	verdadeiro/falso ou nulo
`preferencias.musica`	texto ou nulo
`preferencias.canalDeContacto`	texto ou nulo
`preferencias.lingua`	texto ou nulo
`ultimaQuimicaEm`	data (AAAA-MM-DD) ou nulo
`notasDaEquipa`	texto ou nulo

Pedido

curl

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

POST/api/beleza/clientes/{clienteId}/condicoes#

Regista uma condição (gravidez, alergia…) na ficha do cliente.

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

condicao é um valor de contra-indicação (por exemplo, Gravidez, Amamentacao, AlergiaPpd, AlergiaAmoniaco, AlergiaLatex ou AlergiaAcrilatos); fonte (por omissão DeclaradaPeloCliente) e nota.

Parâmetros

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

Corpo do pedido (JSON · CondicaoPedido)

Campo	Tipo	Obrigatório
`condicao`	texto	sim
`fonte`	texto ou nulo
`nota`	texto ou nulo

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

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

POST/api/beleza/condicoes/{id}/remover#

Remove uma condição da ficha, com motivo.

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

Devolve 204, sem corpo.

Parâmetros

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

Corpo do pedido (JSON · MotivoPedido)

Campo	Tipo	Obrigatório
`motivo`	texto	sim

Pedido

curl

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

POST/api/beleza/clientes/{clienteId}/testes#

Aplica um teste de sensibilidade: fica pendente até alguém registar o resultado depois do tempo de leitura.

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

classe: Tinta, Descolorante, Alisamento, ColaDePestanas, GelOuAcrilato ou Henna. realizadoEmUtc em branco é agora.

Parâmetros

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

Corpo do pedido (JSON · TestePedido)

Campo	Tipo	Obrigatório
`classe`	texto	sim
`produto`	texto ou nulo
`realizadoEmUtc`	data e hora (ISO 8601) ou nulo
`profissionalId`	identificador (UUID) ou nulo

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

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

POST/api/beleza/testes/{id}/resultado#

Regista o resultado de um teste de sensibilidade.

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

resultado: Negativo ou Positivo; nota opcional.

Devolve 204, sem corpo.

Parâmetros

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

Corpo do pedido (JSON · ResultadoPedido)

Campo	Tipo	Obrigatório
`resultado`	texto	sim
`nota`	texto ou nulo

Pedido

curl

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

POST/api/beleza/testes/{id}/anular#

Anula um teste, com motivo.

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

Devolve 204, sem corpo.

Parâmetros

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

Corpo do pedido (JSON · MotivoPedido)

Campo	Tipo	Obrigatório
`motivo`	texto	sim

Pedido

curl

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

GET/api/beleza/clientes/{clienteId}/registos#

Os registos técnicos de um cliente (fórmulas, receitas, técnicas).

Permissão Beleza.Ler

maximo (por omissão 60).

Parâmetros

Nome	Onde	Tipo	Obrigatório
`clienteId`	no caminho	identificador (UUID)	sim
`maximo`	na pesquisa	número inteiro

Pedido

curl

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

POST/api/beleza/clientes/{clienteId}/registos#

Cria um registo técnico na ficha do cliente.

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

tipo: FormulaDeCor, ReceitaDeQuimica, ReceitaDeTrancas, TecnicaDeUnhasOuPestanas, ParametrosDeEquipamento ou NotaTecnica. Os restantes campos (componentes, oxidante, tempo de pausa, técnica, zonas, parâmetros, resultado e «fazer diferente») dependem do tipo.

Parâmetros

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

Corpo do pedido (JSON · RegistoPedido)

Campo	Tipo	Obrigatório	Significado
`servicoDaMarcacaoId`	identificador (UUID) ou nulo
`tipo`	texto	sim
`componentes`	lista de objectos ou nulo
`componentes[].produto`	texto	sim
`componentes[].produtoId`	identificador (UUID) ou nulo		O artigo.
`componentes[].quantidade`	número	sim	A quantidade.
`componentes[].unidade`	texto	sim
`oxidanteVolume`	número inteiro ou nulo
`oxidanteMl`	número ou nulo
`tempoDePausaMin`	número inteiro ou nulo
`tecnica`	texto ou nulo
`zonas`	texto ou nulo
`parametros`	texto ou nulo
`resultado`	texto ou nulo
`fazerDiferente`	texto ou nulo

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

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

POST/api/beleza/registos/{id}/repetir#

Cria um registo técnico novo a partir de um existente (repetir a mesma fórmula ou receita).

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

servicoDaMarcacaoId (opcional) liga o novo registo ao serviço onde se repete. Devolve 201 com o id do novo registo.

Parâmetros

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

Corpo do pedido (JSON · RepetirPedido)

Campo	Tipo	Obrigatório
`servicoDaMarcacaoId`	identificador (UUID) ou nulo

Pedido

curl

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

POST/api/beleza/clientes/{clienteId}/consentimentos#

Regista o consentimento do cliente para fotografias, para uma finalidade e uma versão do texto.

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

finalidade: UsoInterno, PortfolioSemRosto, PortfolioComRosto ou Publicidade. Cada finalidade é um consentimento à parte, revogável.

Parâmetros

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

Corpo do pedido (JSON · ConsentimentoPedido)

Campo	Tipo	Obrigatório
`finalidade`	texto	sim
`versaoDoTexto`	texto ou nulo

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

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

POST/api/beleza/consentimentos/{id}/revogar#

Revoga um consentimento do cliente.

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

motivo é opcional.

Devolve 204, sem corpo.

Parâmetros

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

Corpo do pedido (JSON · MotivoPedido)

Campo	Tipo	Obrigatório
`motivo`	texto	sim

Pedido

curl

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

POST/api/beleza/clientes/{clienteId}/fotos#

Anexa uma fotografia à ficha de um cliente.

Permissão Beleza.Ler

Envio de ficheiro (multipart/form-data): a fotografia vai no campo ficheiro e o momento (Antes, Depois ou Referencia) é obrigatório; servicoDaMarcacaoId e nota são opcionais.

Um ficheiro vazio, ou que exceda o limite de tamanho, é recusado.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`clienteId`	no caminho	identificador (UUID)	sim
`momento`	na pesquisa	texto	sim
`servicoDaMarcacaoId`	na pesquisa	identificador (UUID)
`nota`	na pesquisa	texto

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

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

GET/api/beleza/fotos/{id}#

Descarrega uma fotografia de um cliente.

Permissão Beleza.Ler

Parâmetros

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

Resposta

Devolve 200 com a imagem.

Pedido

curl

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

GET/api/beleza/clientes/{clienteId}/acessos#

Quem consultou a ficha de um cliente e quando.

Permissão Beleza.FichaTodos

maximo (por omissão 100).

Parâmetros

Nome	Onde	Tipo	Obrigatório
`clienteId`	no caminho	identificador (UUID)	sim
`maximo`	na pesquisa	número inteiro

Pedido

curl

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

GET/api/beleza/marcacoes/{marcacaoId}/verificacao#

O que a ficha do cliente tem a dizer sobre os serviços de uma marcação, numa fase do atendimento (avisos e bloqueios).

Permissão Beleza.Ler

fase: Marcar, Iniciar (por omissão) ou Concluir.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`marcacaoId`	no caminho	identificador (UUID)	sim
`fase`	na pesquisa	texto

Pedido

curl

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

POST/api/beleza/verificar-pedido#

Antes de marcar: o que a ficha do cliente tem a dizer sobre os serviços que se vão marcar (só avisos).

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

Ajuda a recepção a pedir o teste a tempo. clienteId e servicos. Não grava nada.

Corpo do pedido (JSON · VerificarPedidoQuery)

Campo	Tipo	Obrigatório	Significado
`clienteId`	identificador (UUID)	sim	O cliente do documento.
`servicos`	lista de objectos	sim
`servicos[].servicoId`	identificador (UUID)	sim
`servicos[].inicio`	data e hora (ISO 8601)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/beleza/verificar-pedido' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "clienteId": "00000000-0000-0000-0000-000000000000",
  "servicos": [
    {
      "servicoId": "00000000-0000-0000-0000-000000000000",
      "inicio": "2026-10-12T09:00:00Z"
    }
  ]
}'

GET/api/beleza/marcacoes/{marcacaoId}/cartao#

O cartão do atendimento: o cliente, as condições, as preferências, os consentimentos, a verificação de segurança, os serviços, os kits usados e as próximas visitas.

Permissão Beleza.Atender

Parâmetros

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

Pedido

curl

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

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

Regista a resposta do cliente a uma pergunta do questionário de segurança (sim ou não) numa marcação.

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

condicao e sim.

Devolve 204, sem corpo.

Parâmetros

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

Corpo do pedido (JSON · RespostaPedido)

Campo	Tipo	Obrigatório
`condicao`	texto	sim
`sim`	verdadeiro/falso	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/beleza/marcacoes/<marcacaoId>/respostas' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "condicao": "texto",
  "sim": false
}'

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

Regista uma dose de produto usada num atendimento.

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

quantidade, unidade (Gramas, Mililitros ou Unidades), o produto (produtoId ou produtoNome), ePadrao e descartavel; servicoDaMarcacaoId liga-a a um serviço.

Parâmetros

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

Corpo do pedido (JSON · DosePedido)

Campo	Tipo	Obrigatório	Significado
`servicoDaMarcacaoId`	identificador (UUID) ou nulo
`produtoId`	identificador (UUID) ou nulo		O artigo.
`produtoNome`	texto ou nulo
`quantidade`	número	sim	A quantidade.
`unidade`	texto	sim
`ePadrao`	verdadeiro/falso	sim
`descartavel`	verdadeiro/falso	sim

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/beleza/marcacoes/<marcacaoId>/doses' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "quantidade": 0,
  "unidade": "texto",
  "ePadrao": false,
  "descartavel": false
}'