Referência

Marcações

A agenda de profissionais, cadeiras, salas e equipamentos: serviços com depósito e tempos de preparação, horários e excepções, marcações com o seu ciclo de vida (pedida, confirmada, chegou, em atendimento, concluída, paga), fila de espera, lista de espera com ofertas de vaga, comissões e as mensagens aos clientes. A conta de uma marcação concluída fecha-se com um documento fiscal do núcleo, pelo fluxo de sempre.

Operação	O que faz
GET `/api/marcacoes/profissionais`	Os profissionais da agenda.
POST `/api/marcacoes/profissionais`	Cria um profissional da agenda.
PUT `/api/marcacoes/profissionais/{id}`	Altera a ficha de um profissional.
PUT `/api/marcacoes/profissionais/{id}/activo`	Activa ou desactiva um profissional.
GET `/api/marcacoes/recursos`	Os recursos da agenda (cadeiras, salas, equipamentos).
POST `/api/marcacoes/recursos`	Cria um recurso da agenda.
PUT `/api/marcacoes/recursos/{id}`	Altera o nome, o tipo e o estado de um recurso.
GET `/api/marcacoes/servicos`	Os serviços que se podem marcar.
POST `/api/marcacoes/servicos`	Cria um serviço marcável, ligado a um artigo do catálogo.
PUT `/api/marcacoes/servicos/{id}`	Altera um serviço marcável.
GET `/api/marcacoes/horarios`	O horário semanal de um estabelecimento, de um profissional ou de um recurso.
PUT `/api/marcacoes/horarios`	Define o horário semanal de um alvo, por janelas.
GET `/api/marcacoes/excepcoes`	As excepções aos horários (feriados, férias, folgas, pausas, dias de horário especial…).
POST `/api/marcacoes/excepcoes`	Cria uma excepção ao horário: um bloqueio num intervalo, ou um dia de horário especial.
DELETE `/api/marcacoes/excepcoes/{id}`	Elimina uma excepção ao horário.
GET `/api/marcacoes/configuracao`	A configuração da agenda: perfil de negócio, granularidade, tolerância de falta e overbooking.
PUT `/api/marcacoes/configuracao`	Define a configuração da agenda.
GET `/api/marcacoes/disponibilidade`	As horas possíveis para um serviço.
GET `/api/marcacoes/agenda`	As marcações de um período, na agenda.
GET `/api/marcacoes/ocupacao`	A ocupação das agendas, por profissional e por dia.
GET `/api/marcacoes/{id}`	Uma marcação completa.
POST `/api/marcacoes`	Cria uma marcação para um cliente, com um ou mais serviços.
POST `/api/marcacoes/{id}/aprovar`	Aprova uma marcação pedida.
POST `/api/marcacoes/{id}/deposito`	Regista o depósito recebido de uma marcação.
POST `/api/marcacoes/{id}/reconfirmar`	Reconfirma uma marcação (o cliente confirmou que vem).
PUT `/api/marcacoes/{id}/nota`	Muda (ou retira) a nota de uma marcação.
GET `/api/marcacoes/clientes/{clienteId}/historico`	O que a agenda sabe de um cliente: marcações, visitas feitas, faltas, desmarcações, total pago, última visita, próxima marcação e as marcações mais recentes.
POST `/api/marcacoes/{id}/chegou`	Regista a chegada do cliente.
POST `/api/marcacoes/{id}/iniciar`	Inicia o atendimento.
POST `/api/marcacoes/{id}/pausar`	Pausa o atendimento (uma pausa de processamento: o profissional fica livre, o recurso não).
POST `/api/marcacoes/{id}/retomar`	Retoma o atendimento pausado.
POST `/api/marcacoes/{id}/concluir`	Conclui o atendimento.
POST `/api/marcacoes/{id}/cancelar`	Cancela uma marcação, com motivo.
POST `/api/marcacoes/{id}/faltou`	Marca a falta do cliente.
POST `/api/marcacoes/{id}/servicos`	Acrescenta um serviço a meio do atendimento.
POST `/api/marcacoes/{id}/reagendar`	Muda uma marcação para outras horas: cria a nova, que herda o depósito e a nota, e deixa a antiga como «Reagendada», ligada à nova.
POST `/api/marcacoes/{id}/conta`	Fecha a conta de uma marcação concluída: os serviços feitos mais os produtos vendidos no fim, num só documento fiscal.
GET `/api/marcacoes/comissoes`	As comissões dos profissionais num período.
GET `/api/marcacoes/fila`	A fila de espera: os clientes à espera de serem chamados para uma marcação imediata.
POST `/api/marcacoes/fila`	Põe um cliente na fila, para um serviço e, se quiser, com um profissional preferido.
POST `/api/marcacoes/fila/{id}/chamar`	Chama o cliente: cria a marcação imediata (agora, com o profissional livre) em estado «Chegou».
POST `/api/marcacoes/fila/{id}/desistir`	Regista que o cliente desistiu da fila.
GET `/api/marcacoes/lista-de-espera`	Os pedidos da lista de espera (clientes que querem uma vaga num período).
POST `/api/marcacoes/lista-de-espera`	Acrescenta um pedido à lista de espera: o cliente, o serviço, o período e, se quiser, as horas.
POST `/api/marcacoes/lista-de-espera/{id}/cancelar`	Cancela um pedido da lista de espera.
POST `/api/marcacoes/ofertas/{id}/aceitar`	O cliente aceita a vaga oferecida: cria a marcação nessa hora (se ainda estiver livre) e satisfaz o pedido.
POST `/api/marcacoes/ofertas/{id}/recusar`	O cliente recusa a vaga oferecida.
GET `/api/marcacoes/notificacoes`	As mensagens da agenda aos clientes, com o canal, o texto e o resultado.
POST `/api/marcacoes/notificacoes/{id}/enviada`	Marca uma mensagem como enviada (a recepção abriu a ligação de WhatsApp e enviou-a).
POST `/api/marcacoes/series`	Cria uma marcação e as suas repetições (semanal, de 15 em 15 dias ou de 4 em 4 semanas).
POST `/api/marcacoes/series/{serieId}/cancelar`	Cancela as marcações de uma repetição que ainda estão por cumprir.

GET/api/marcacoes/profissionais#

Os profissionais da agenda.

Permissão Marcacoes.AgendaLer

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/marcacoes/profissionais' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/marcacoes/profissionais#

Cria um profissional da agenda.

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

Um profissional é quem fica de serviço: não é o utilizador do sistema (muitos não entram nele), mas pode estar ligado a um (userId). cor, aceitaOnline, comissaoServicoPct, comissaoProdutoPct e descricao completam a ficha. lojaId é opcional quando a chave só tem um estabelecimento.

Corpo do pedido (JSON · CriarProfissionalCommand)

Campo	Tipo	Obrigatório	Significado
`lojaId`	identificador (UUID) ou nulo		O estabelecimento.
`nome`	texto	sim	O nome.
`userId`	identificador (UUID) ou nulo
`cor`	texto	sim
`aceitaOnline`	verdadeiro/falso	sim
`comissaoServicoPct`	número	sim
`comissaoProdutoPct`	número	sim
`descricao`	texto ou nulo		A descrição.

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/marcacoes/profissionais' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "nome": "texto",
  "cor": "texto",
  "aceitaOnline": false,
  "comissaoServicoPct": 0,
  "comissaoProdutoPct": 0
}'

PUT/api/marcacoes/profissionais/{id}#

Altera a ficha de um profissional.

Permissão Marcacoes.CatalogoEditar

Devolve 204, sem corpo.

Parâmetros

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

Corpo do pedido (JSON · ProfissionalPedido)

Campo	Tipo	Obrigatório	Significado
`nome`	texto	sim	O nome.
`userId`	identificador (UUID) ou nulo
`cor`	texto	sim
`aceitaOnline`	verdadeiro/falso	sim
`comissaoServicoPct`	número	sim
`comissaoProdutoPct`	número	sim
`descricao`	texto ou nulo		A descrição.

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/marcacoes/profissionais/<id>' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "nome": "texto",
  "cor": "texto",
  "aceitaOnline": false,
  "comissaoServicoPct": 0,
  "comissaoProdutoPct": 0
}'

PUT/api/marcacoes/profissionais/{id}/activo#

Activa ou desactiva um profissional.

Permissão Marcacoes.CatalogoEditar

Devolve 204, sem corpo.

Parâmetros

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

Corpo do pedido (JSON · ActivoPedido)

Campo	Tipo	Obrigatório	Significado
`activo`	verdadeiro/falso	sim	Se está activo.

Pedido

curl

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

GET/api/marcacoes/recursos#

Os recursos da agenda (cadeiras, salas, equipamentos).

Permissão Marcacoes.AgendaLer

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/marcacoes/recursos' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/marcacoes/recursos#

Cria um recurso da agenda.

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

tipo: Cadeira, Sala, Equipamento ou Outro. lojaId é opcional quando a chave só tem um estabelecimento.

Corpo do pedido (JSON · GuardarRecursoCommand)

Campo	Tipo	Obrigatório	Significado
`id`	identificador (UUID) ou nulo		Identificador único (UUID).
`lojaId`	identificador (UUID) ou nulo		O estabelecimento.
`nome`	texto	sim	O nome.
`tipo`	uma de: «Cadeira», «Sala», «Equipamento», «Outro»	sim
`activo`	verdadeiro/falso	sim	Se está activo.

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/marcacoes/recursos' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "nome": "texto",
  "tipo": "Cadeira",
  "activo": false
}'

PUT/api/marcacoes/recursos/{id}#

Altera o nome, o tipo e o estado de um recurso.

Permissão Marcacoes.CatalogoEditar

Devolve 204, sem corpo.

Parâmetros

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

Corpo do pedido (JSON · GuardarRecursoCommand)

Campo	Tipo	Obrigatório	Significado
`id`	identificador (UUID) ou nulo		Identificador único (UUID).
`lojaId`	identificador (UUID) ou nulo		O estabelecimento.
`nome`	texto	sim	O nome.
`tipo`	uma de: «Cadeira», «Sala», «Equipamento», «Outro»	sim
`activo`	verdadeiro/falso	sim	Se está activo.

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/marcacoes/recursos/<id>' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "nome": "texto",
  "tipo": "Cadeira",
  "activo": false
}'

GET/api/marcacoes/servicos#

Os serviços que se podem marcar.

Permissão Marcacoes.AgendaLer

apenasActivos (por omissão, verdadeiro) e apenasOnline (por omissão, falso).

Parâmetros

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

Pedido

curl

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

POST/api/marcacoes/servicos#

Cria um serviço marcável, ligado a um artigo do catálogo.

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

produtoId liga o serviço ao artigo que se factura. deposito: Nunca, Sempre ou SoRisco, com depositoValor. bufferAntesMin e bufferDepoisMin são os tempos de preparação; segmentos são as fases do serviço e profissionais quem o pode fazer. Com exigeAprovacao verdadeiro, uma marcação que inclua este serviço fica pedida (aguardaAprovacao) até ser aprovada, e expira se ninguém a aprovar no prazo da configuração.

Corpo do pedido (JSON · GuardarServicoCommand)

Campo	Tipo	Obrigatório	Significado
`id`	identificador (UUID) ou nulo		Identificador único (UUID).
`produtoId`	identificador (UUID)	sim	O artigo.
`nome`	texto	sim	O nome.
`categoria`	texto ou nulo
`descricaoPublica`	texto ou nulo
`marcavelOnline`	verdadeiro/falso	sim
`antecedenciaMinOnlineMin`	número inteiro	sim
`antecedenciaMaxOnlineDias`	número inteiro ou nulo
`deposito`	uma de: «Nunca», «Sempre», «SoRisco»	sim
`depositoValor`	número ou nulo
`bufferAntesMin`	número inteiro	sim
`bufferDepoisMin`	número inteiro	sim
`preco`	número ou nulo
`activo`	verdadeiro/falso	sim	Se está activo.
`segmentos`	lista de objectos	sim
`segmentos[].tipo`	uma de: «Activo», «Pausa», «Recurso»	sim
`segmentos[].minutos`	número inteiro	sim
`profissionais`	lista de objectos	sim
`profissionais[].profissionalId`	identificador (UUID)	sim
`profissionais[].duracaoActivaMin`	número inteiro ou nulo
`profissionais[].preco`	número ou nulo
`recursos`	lista de lista de identificador (UUID)	sim
`exigeAprovacao`	verdadeiro/falso

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/marcacoes/servicos' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "produtoId": "00000000-0000-0000-0000-000000000000",
  "nome": "texto",
  "marcavelOnline": false,
  "antecedenciaMinOnlineMin": 1,
  "deposito": "Nunca",
  "bufferAntesMin": 1,
  "bufferDepoisMin": 1,
  "activo": false,
  "segmentos": [
    {
      "tipo": "Activo",
      "minutos": 1
    }
  ],
  "profissionais": [
    {
      "profissionalId": "00000000-0000-0000-0000-000000000000"
    }
  ],
  "recursos": [
    [
      "00000000-0000-0000-0000-000000000000"
    ]
  ]
}'

PUT/api/marcacoes/servicos/{id}#

Altera um serviço marcável.

Permissão Marcacoes.CatalogoEditar

Devolve 204, sem corpo.

Parâmetros

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

Corpo do pedido (JSON · GuardarServicoCommand)

Campo	Tipo	Obrigatório	Significado
`id`	identificador (UUID) ou nulo		Identificador único (UUID).
`produtoId`	identificador (UUID)	sim	O artigo.
`nome`	texto	sim	O nome.
`categoria`	texto ou nulo
`descricaoPublica`	texto ou nulo
`marcavelOnline`	verdadeiro/falso	sim
`antecedenciaMinOnlineMin`	número inteiro	sim
`antecedenciaMaxOnlineDias`	número inteiro ou nulo
`deposito`	uma de: «Nunca», «Sempre», «SoRisco»	sim
`depositoValor`	número ou nulo
`bufferAntesMin`	número inteiro	sim
`bufferDepoisMin`	número inteiro	sim
`preco`	número ou nulo
`activo`	verdadeiro/falso	sim	Se está activo.
`segmentos`	lista de objectos	sim
`segmentos[].tipo`	uma de: «Activo», «Pausa», «Recurso»	sim
`segmentos[].minutos`	número inteiro	sim
`profissionais`	lista de objectos	sim
`profissionais[].profissionalId`	identificador (UUID)	sim
`profissionais[].duracaoActivaMin`	número inteiro ou nulo
`profissionais[].preco`	número ou nulo
`recursos`	lista de lista de identificador (UUID)	sim
`exigeAprovacao`	verdadeiro/falso

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/marcacoes/servicos/<id>' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "produtoId": "00000000-0000-0000-0000-000000000000",
  "nome": "texto",
  "marcavelOnline": false,
  "antecedenciaMinOnlineMin": 1,
  "deposito": "Nunca",
  "bufferAntesMin": 1,
  "bufferDepoisMin": 1,
  "activo": false,
  "segmentos": [
    {
      "tipo": "Activo",
      "minutos": 1
    }
  ],
  "profissionais": [
    {
      "profissionalId": "00000000-0000-0000-0000-000000000000"
    }
  ],
  "recursos": [
    [
      "00000000-0000-0000-0000-000000000000"
    ]
  ]
}'

GET/api/marcacoes/horarios#

O horário semanal de um estabelecimento, de um profissional ou de um recurso.

Permissão Marcacoes.AgendaLer

alvo (Loja, Profissional ou Recurso) e alvoId são obrigatórios.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`alvo`	na pesquisa	uma de: «Loja», «Profissional», «Recurso»	sim
`alvoId`	na pesquisa	identificador (UUID)	sim

Pedido

curl

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

PUT/api/marcacoes/horarios#

Define o horário semanal de um alvo, por janelas.

Permissão Marcacoes.HorariosEditar

Um dia com duas janelas deixa o almoço de fora. As horas são as de Angola.

Devolve 204, sem corpo.

Corpo do pedido (JSON · DefinirHorarioCommand)

Campo	Tipo	Obrigatório
`alvo`	uma de: «Loja», «Profissional», «Recurso»	sim
`alvoId`	identificador (UUID)	sim
`janelas`	lista de objectos	sim
`janelas[].dia`	uma de: «Sunday», «Monday», «Tuesday», «Wednesday», «Thursday», «Friday», «Saturday»	sim
`janelas[].inicio`	texto	sim
`janelas[].fim`	texto	sim

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/marcacoes/horarios' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "alvo": "Loja",
  "alvoId": "00000000-0000-0000-0000-000000000000",
  "janelas": [
    {
      "dia": "Sunday",
      "inicio": "texto",
      "fim": "texto"
    }
  ]
}'

GET/api/marcacoes/excepcoes#

As excepções aos horários (feriados, férias, folgas, pausas, dias de horário especial…).

Permissão Marcacoes.AgendaLer

Filtros: alvo, alvoId, de e ate. lojaId é opcional quando a chave só tem um estabelecimento.

Parâmetros

Nome	Onde	Tipo
`alvo`	na pesquisa	uma de: «Loja», «Profissional», «Recurso»
`alvoId`	na pesquisa	identificador (UUID)
`de`	na pesquisa	data e hora (ISO 8601)
`ate`	na pesquisa	data e hora (ISO 8601)
`lojaId`	na pesquisa	identificador (UUID)

Pedido

curl

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

POST/api/marcacoes/excepcoes#

Cria uma excepção ao horário: um bloqueio num intervalo, ou um dia de horário especial.

Permissão Marcacoes.HorariosEditar
Idempotência aceita Idempotency-Key

tipo: Feriado, Ferias, Folga, Baixa, Formacao, Fechado, Pausa ou HorarioEspecial.

Um bloqueio que apanhe marcações já feitas obriga a confirmar: sem confirmarConflitos o pedido é recusado e diz quantas são; as marcações mantêm-se (nada se cancela sozinho) e ficam na lista de conflitos para a recepção reagendar.

Corpo do pedido (JSON · CriarExcepcaoCommand)

Campo	Tipo	Obrigatório
`alvo`	uma de: «Loja», «Profissional», «Recurso»	sim
`alvoId`	identificador (UUID)	sim
`tipo`	uma de: «Feriado», «Ferias», «Folga», «Baixa», «Formacao», «Fechado», «Pausa», «HorarioEspecial»	sim
`inicio`	data e hora (ISO 8601) ou nulo
`fim`	data e hora (ISO 8601) ou nulo
`dia`	data (AAAA-MM-DD) ou nulo
`janelaInicio`	texto ou nulo
`janelaFim`	texto ou nulo
`motivo`	texto ou nulo
`confirmarConflitos`	verdadeiro/falso	sim

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/marcacoes/excepcoes' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "alvo": "Loja",
  "alvoId": "00000000-0000-0000-0000-000000000000",
  "tipo": "Feriado",
  "confirmarConflitos": false
}'

DELETE/api/marcacoes/excepcoes/{id}#

Elimina uma excepção ao horário.

Permissão Marcacoes.HorariosEditar

Devolve 204, sem corpo.

Parâmetros

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

Pedido

curl

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

GET/api/marcacoes/configuracao#

A configuração da agenda: perfil de negócio, granularidade, tolerância de falta e overbooking.

Permissão Marcacoes.AgendaLer

Pedido

curl

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

PUT/api/marcacoes/configuracao#

Define a configuração da agenda.

Permissão Marcacoes.Configurar

perfil: Salao, Barbearia, Estetica ou Clinica (muda o vocabulário e as regras). Os restantes campos: granularidadeMin, toleranciaDeFaltaMin, horasParaExpirarPedida, minutosUteis e overbookingMaximoPorHora.

Devolve 204, sem corpo.

Corpo do pedido (JSON · DefinirConfiguracaoDaAgendaCommand)

Campo	Tipo	Obrigatório
`perfil`	uma de: «Salao», «Barbearia», «Estetica», «Clinica»	sim
`granularidadeMin`	número inteiro	sim
`toleranciaDeFaltaMin`	número inteiro	sim
`horasParaExpirarPedida`	número inteiro	sim
`minutosUteis`	número inteiro	sim
`overbookingMaximoPorHora`	número inteiro	sim

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/marcacoes/configuracao' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "perfil": "Salao",
  "granularidadeMin": 1,
  "toleranciaDeFaltaMin": 1,
  "horasParaExpirarPedida": 1,
  "minutosUteis": 1,
  "overbookingMaximoPorHora": 1
}'

GET/api/marcacoes/disponibilidade#

As horas possíveis para um serviço.

Permissão Marcacoes.AgendaLer

servicoId, de e ate são obrigatórios. Sem profissionalId, junta as horas de todos os habilitados («qualquer»). maximo (por omissão 100) limita a lista e soSugeridas pede só as sugeridas. lojaId é opcional quando a chave só tem um estabelecimento.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`servicoId`	na pesquisa	identificador (UUID)	sim
`de`	na pesquisa	data e hora (ISO 8601)	sim
`ate`	na pesquisa	data e hora (ISO 8601)	sim
`profissionalId`	na pesquisa	identificador (UUID)
`lojaId`	na pesquisa	identificador (UUID)
`maximo`	na pesquisa	número inteiro
`soSugeridas`	na pesquisa	verdadeiro/falso

Pedido

curl

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

GET/api/marcacoes/agenda#

As marcações de um período, na agenda.

Permissão Marcacoes.AgendaLer

de e ate são obrigatórios; profissionalId limita a um profissional. lojaId é opcional quando a chave só tem um estabelecimento.

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
`lojaId`	na pesquisa	identificador (UUID)
`profissionalId`	na pesquisa	identificador (UUID)

Pedido

curl

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

GET/api/marcacoes/ocupacao#

A ocupação das agendas, por profissional e por dia.

Permissão Marcacoes.IndicadoresVer

de e ate são datas (os dias são os de Luanda) e o período vai até 366 dias. É só de leitura e agrega no servidor. lojaId é opcional quando a chave só tem um estabelecimento.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`de`	na pesquisa	data (AAAA-MM-DD)	sim
`ate`	na pesquisa	data (AAAA-MM-DD)	sim
`lojaId`	na pesquisa	identificador (UUID)

Pedido

curl

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

GET/api/marcacoes/{id}#

Uma marcação completa.

Permissão Marcacoes.AgendaLer

Parâmetros

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

Pedido

curl

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

POST/api/marcacoes#

Cria uma marcação para um cliente, com um ou mais serviços.

Permissão Marcacoes.AgendaOperar
Idempotência aceita Idempotency-Key

clienteId, servicos, origem (Recepcao, Telefone, Online, WhatsApp, App, FilaDeEspera, ListaDeEspera, Reactivacao ou Recorrencia), nota e overbooking. lojaId é opcional quando a chave só tem um estabelecimento.

Envie Idempotency-Key: repetir o pedido não o executa duas vezes. Ver Idempotência.

Corpo do pedido (JSON · CriarMarcacaoCommand)

Campo	Tipo	Obrigatório	Significado
`lojaId`	identificador (UUID) ou nulo		O estabelecimento.
`clienteId`	identificador (UUID)	sim	O cliente do documento.
`servicos`	lista de objectos	sim
`servicos[].servicoId`	identificador (UUID)	sim
`servicos[].profissionalId`	identificador (UUID) ou nulo
`servicos[].inicio`	data e hora (ISO 8601)	sim
`origem`	uma de: «Recepcao», «Telefone», «Online», «WhatsApp», «App», «FilaDeEspera», «ListaDeEspera», «Reactivacao», «Recorrencia»	sim
`nota`	texto ou nulo
`overbooking`	verdadeiro/falso	sim

Resposta

Devolve 201 com o id do registo criado.

Erros específicos

IDEMPOTENCIA_CONFLITO — além dos gerais.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/marcacoes' \
  -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"
    }
  ],
  "origem": "Recepcao",
  "overbooking": false
}'

POST/api/marcacoes/{id}/aprovar#

Aprova uma marcação pedida.

Permissão Marcacoes.AgendaOperar

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/marcacoes/<id>/aprovar' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/marcacoes/{id}/deposito#

Regista o depósito recebido de uma marcação.

Permissão Marcacoes.Cobrar
Idempotência aceita Idempotency-Key

valor e, se houver, a referencia.

Devolve 204, sem corpo.

Parâmetros

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

Corpo do pedido (JSON · DepositoPedido)

Campo	Tipo	Obrigatório	Significado
`valor`	número	sim	O valor.
`referencia`	texto ou nulo

Pedido

curl

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

POST/api/marcacoes/{id}/reconfirmar#

Reconfirma uma marcação (o cliente confirmou que vem).

Permissão Marcacoes.AgendaOperar

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/marcacoes/<id>/reconfirmar' \
  -H 'X-Api-Key: <a-sua-chave>'

PUT/api/marcacoes/{id}/nota#

Muda (ou retira) a nota de uma marcação.

Permissão Marcacoes.AgendaOperar

nota com até 500 caracteres; vazia ou nula retira a nota. Fica no histórico da marcação. Já não se muda depois de a marcação ficar paga, cancelada, faltada ou remarcada.

Devolve 204, sem corpo.

Parâmetros

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

Corpo do pedido (JSON · NotaPedido)

Campo	Tipo	Obrigatório
`nota`	texto ou nulo

Pedido

curl

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

GET/api/marcacoes/clientes/{clienteId}/historico#

O que a agenda sabe de um cliente: marcações, visitas feitas, faltas, desmarcações, total pago, última visita, próxima marcação e as marcações mais recentes.

Permissão Marcacoes.AgendaLer

maximo limita as marcações recentes devolvidas (30 por omissão, 100 no máximo). As marcações mudadas de hora não contam duas vezes: vale a nova. Só entram as dos estabelecimentos a que a chave tem acesso.

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/marcacoes/clientes/<clienteId>/historico' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/marcacoes/{id}/chegou#

Regista a chegada do cliente.

Permissão Marcacoes.AgendaOperar Marcacoes.MinhaAgenda

Quem tem a permissão da recepção («Marcacoes.AgendaOperar») trata de qualquer marcação; quem só tem a da própria agenda («Marcacoes.MinhaAgenda») só das marcações em que é o profissional.

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/marcacoes/<id>/chegou' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/marcacoes/{id}/iniciar#

Inicia o atendimento.

Permissão Marcacoes.AgendaOperar Marcacoes.MinhaAgenda

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/marcacoes/<id>/iniciar' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/marcacoes/{id}/pausar#

Pausa o atendimento (uma pausa de processamento: o profissional fica livre, o recurso não).

Permissão Marcacoes.AgendaOperar Marcacoes.MinhaAgenda

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/marcacoes/<id>/pausar' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/marcacoes/{id}/retomar#

Retoma o atendimento pausado.

Permissão Marcacoes.AgendaOperar Marcacoes.MinhaAgenda

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/marcacoes/<id>/retomar' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/marcacoes/{id}/concluir#

Conclui o atendimento.

Permissão Marcacoes.AgendaOperar Marcacoes.MinhaAgenda

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/marcacoes/<id>/concluir' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/marcacoes/{id}/cancelar#

Cancela uma marcação, com motivo.

Permissão Marcacoes.AgendaOperar
Idempotência aceita Idempotency-Key

motivo e peloCliente (se foi o cliente que cancelou).

Devolve 204, sem corpo.

Parâmetros

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

Corpo do pedido (JSON · CancelamentoPedido)

Campo	Tipo	Obrigatório
`motivo`	texto	sim
`peloCliente`	verdadeiro/falso	sim

Pedido

curl

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

POST/api/marcacoes/{id}/faltou#

Marca a falta do cliente.

Permissão Marcacoes.AgendaOperar

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/marcacoes/<id>/faltou' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/marcacoes/{id}/servicos#

Acrescenta um serviço a meio do atendimento.

Permissão Marcacoes.AgendaOperar
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 · ServicoPedido)

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

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/marcacoes/<id>/servicos' \
  -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",
  "inicio": "2026-10-12T09:00:00Z"
}'

POST/api/marcacoes/{id}/reagendar#

Muda uma marcação para outras horas: cria a nova, que herda o depósito e a nota, e deixa a antiga como «Reagendada», ligada à nova.

Permissão Marcacoes.AgendaOperar
Idempotência aceita Idempotency-Key

servicos indica os serviços e as horas da marcação nova. Devolve 201 com o id da nova marcação.

Parâmetros

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

Corpo do pedido (JSON · ReagendamentoPedido)

Campo	Tipo	Obrigatório
`servicos`	lista de objectos	sim
`servicos[].servicoId`	identificador (UUID)	sim
`servicos[].profissionalId`	identificador (UUID) ou nulo
`servicos[].inicio`	data e hora (ISO 8601)	sim

Pedido

curl

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

POST/api/marcacoes/{id}/conta#

Fecha a conta de uma marcação concluída: os serviços feitos mais os produtos vendidos no fim, num só documento fiscal.

Permissão Marcacoes.Cobrar
Idempotência aceita Idempotency-Key

O documento é emitido pelo mesmo comando do «Novo documento»: Factura/Recibo se se paga no acto, Factura (conta corrente) se não há pagamentos e o cliente a tem. O depósito já recebido não é abatido aqui. produtos e pagamentos são opcionais.

Parâmetros

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

Corpo do pedido (JSON · ContaPedido)

Campo	Tipo	Obrigatório	Significado
`produtos`	lista de objectos ou nulo
`produtos[].produtoId`	identificador (UUID)	sim	O artigo.
`produtos[].quantidade`	número	sim	A quantidade.
`produtos[].precoUnitario`	número ou nulo		O preço de uma unidade, sem imposto.
`produtos[].profissionalId`	identificador (UUID) ou nulo
`pagamentos`	lista de objectos ou nulo
`pagamentos[].metodoPagamentoId`	identificador (UUID)	sim	O método de pagamento.
`pagamentos[].valor`	número	sim	O valor.

Pedido

curl

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

GET/api/marcacoes/comissoes#

As comissões dos profissionais num período.

Permissão Marcacoes.IndicadoresVer

de e ate são obrigatórios; profissionalId limita a um profissional.

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
`profissionalId`	na pesquisa	identificador (UUID)

Pedido

curl

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

GET/api/marcacoes/fila#

A fila de espera: os clientes à espera de serem chamados para uma marcação imediata.

Permissão Marcacoes.AgendaLer

lojaId é opcional quando a chave só tem um estabelecimento.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`lojaId`	na pesquisa	identificador (UUID)

Pedido

curl

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

POST/api/marcacoes/fila#

Põe um cliente na fila, para um serviço e, se quiser, com um profissional preferido.

Permissão Marcacoes.AgendaOperar
Idempotência aceita Idempotency-Key

lojaId é opcional quando a chave só tem um estabelecimento.

Corpo do pedido (JSON · EntrarNaFilaCommand)

Campo	Tipo	Obrigatório	Significado
`lojaId`	identificador (UUID) ou nulo		O estabelecimento.
`clienteId`	identificador (UUID)	sim	O cliente do documento.
`servicoId`	identificador (UUID)	sim
`profissionalPreferidoId`	identificador (UUID) ou nulo

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/marcacoes/fila' \
  -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",
  "servicoId": "00000000-0000-0000-0000-000000000000"
}'

POST/api/marcacoes/fila/{id}/chamar#

Chama o cliente: cria a marcação imediata (agora, com o profissional livre) em estado «Chegou».

Permissão Marcacoes.AgendaOperar
Idempotência aceita Idempotency-Key

profissionalId (opcional). Devolve 200 com o marcacaoId.

Parâmetros

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

Corpo do pedido (JSON · ChamadaPedido)

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

Pedido

curl

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

POST/api/marcacoes/fila/{id}/desistir#

Regista que o cliente desistiu da fila.

Permissão Marcacoes.AgendaOperar

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/marcacoes/fila/<id>/desistir' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/marcacoes/lista-de-espera#

Os pedidos da lista de espera (clientes que querem uma vaga num período).

Permissão Marcacoes.AgendaLer

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/marcacoes/lista-de-espera' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/marcacoes/lista-de-espera#

Acrescenta um pedido à lista de espera: o cliente, o serviço, o período e, se quiser, as horas.

Permissão Marcacoes.AgendaOperar
Idempotência aceita Idempotency-Key

de e ate são datas; depoisDas e antesDas limitam a hora do dia; vip marca o pedido como VIP. lojaId é opcional quando a chave só tem um estabelecimento.

Corpo do pedido (JSON · AdicionarPedidoDeEsperaCommand)

Campo	Tipo	Obrigatório	Significado
`lojaId`	identificador (UUID) ou nulo		O estabelecimento.
`clienteId`	identificador (UUID)	sim	O cliente do documento.
`servicoId`	identificador (UUID)	sim
`profissionalId`	identificador (UUID) ou nulo
`de`	data (AAAA-MM-DD)	sim
`ate`	data (AAAA-MM-DD)	sim
`depoisDas`	texto ou nulo
`antesDas`	texto ou nulo
`vip`	verdadeiro/falso	sim

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/marcacoes/lista-de-espera' \
  -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",
  "servicoId": "00000000-0000-0000-0000-000000000000",
  "de": "2026-10-12",
  "ate": "2026-10-12",
  "vip": false
}'

POST/api/marcacoes/lista-de-espera/{id}/cancelar#

Cancela um pedido da lista de espera.

Permissão Marcacoes.AgendaOperar

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/marcacoes/lista-de-espera/<id>/cancelar' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/marcacoes/ofertas/{id}/aceitar#

O cliente aceita a vaga oferecida: cria a marcação nessa hora (se ainda estiver livre) e satisfaz o pedido.

Permissão Marcacoes.AgendaOperar

A hora oferecida não fica reservada: quem a marcar primeiro fica com ela. Devolve 200 com o marcacaoId.

Parâmetros

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

Pedido

curl

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

POST/api/marcacoes/ofertas/{id}/recusar#

O cliente recusa a vaga oferecida.

Permissão Marcacoes.AgendaOperar

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/marcacoes/ofertas/<id>/recusar' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/marcacoes/notificacoes#

As mensagens da agenda aos clientes, com o canal, o texto e o resultado.

Permissão Marcacoes.AgendaLer

Filtros: estado (Pendente, Enviada ou Falhou), canal (Email ou WhatsAppLigacao) e marcacaoId. maximo (por omissão 100).

Parâmetros

Nome	Onde	Tipo
`estado`	na pesquisa	uma de: «Pendente», «Enviada», «Falhou», «null»
`canal`	na pesquisa	uma de: «Email», «WhatsAppLigacao», «null»
`marcacaoId`	na pesquisa	identificador (UUID)
`maximo`	na pesquisa	número inteiro

Pedido

curl

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

POST/api/marcacoes/notificacoes/{id}/enviada#

Marca uma mensagem como enviada (a recepção abriu a ligação de WhatsApp e enviou-a).

Permissão Marcacoes.AgendaOperar

A plataforma não envia mensagens de WhatsApp em nome de ninguém: deixa a mensagem pronta e a ligação.

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/marcacoes/notificacoes/<id>/enviada' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/marcacoes/series#

Cria uma marcação e as suas repetições (semanal, de 15 em 15 dias ou de 4 em 4 semanas).

Permissão Marcacoes.AgendaOperar
Idempotência aceita Idempotency-Key

clienteId, servicos (a primeira marcação), frequencia (Semanal, Quinzenal ou QuatroSemanas), ocorrencias (de 2 a 26, contando com a primeira), origem e nota. Cada repetição é uma marcação como as outras, à mesma hora, com o mesmo serviço e profissional. lojaId é opcional quando a chave só tem um estabelecimento.

A primeira tem de ficar marcada, ou nada se cria (400). As seguintes que não caibam (hora ocupada, dia fechado) ficam de fora e vêm em falhadas, com o motivo. O cliente recebe um só aviso, o da primeira.

Envie Idempotency-Key: repetir o pedido não o executa duas vezes. Ver Idempotência.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`lojaId`	na pesquisa	identificador (UUID)

Corpo do pedido (JSON · SeriePedido)

Campo	Tipo	Obrigatório	Significado
`clienteId`	identificador (UUID)	sim	O cliente do documento.
`servicos`	lista de objectos	sim
`servicos[].servicoId`	identificador (UUID)	sim
`servicos[].profissionalId`	identificador (UUID) ou nulo
`servicos[].inicio`	data e hora (ISO 8601)	sim
`frequencia`	uma de: «Semanal», «Quinzenal», «QuatroSemanas»	sim
`ocorrencias`	número inteiro	sim
`origem`	uma de: «Recepcao», «Telefone», «Online», «WhatsApp», «App», «FilaDeEspera», «ListaDeEspera», «Reactivacao», «Recorrencia»
`nota`	texto ou nulo

Resposta

Devolve 201 com o serieId, as marcações criadas (ordem, marcacaoId, inicio) e as falhadas (ordem, inicio, motivo). Cada marcação da série traz serieId e ordemNaSerie.

Erros específicos

IDEMPOTENCIA_CONFLITO — além dos gerais.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/marcacoes/series' \
  -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"
    }
  ],
  "frequencia": "Semanal",
  "ocorrencias": 1
}'

POST/api/marcacoes/series/{serieId}/cancelar#

Cancela as marcações de uma repetição que ainda estão por cumprir.

Permissão Marcacoes.AgendaOperar
Idempotência aceita Idempotency-Key

motivo é obrigatório; peloCliente (por omissão, verdadeiro) diz quem desmarcou. Só as marcações pedidas, confirmadas ou reconfirmadas, a partir de agora; as que já aconteceram não mudam. Devolve 400 se não houver nenhuma por cumprir.

Parâmetros

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

Corpo do pedido (JSON · CancelamentoPedido)

Campo	Tipo	Obrigatório
`motivo`	texto	sim
`peloCliente`	verdadeiro/falso	sim

Resposta

Devolve 200 com o número de marcações canceladas.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/marcacoes/series/<serieId>/cancelar' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "motivo": "texto",
  "peloCliente": false
}'