Bem-vindo ao Micali.online

Funções de utilizador

Cada pessoa que interage com o Micali.online enquadra-se numa destas funções. As funções controlam o que cada um pode ver, editar e aprovar.

O que cada função pode fazer

Conta

Uma conta representa uma empresa ou organização proprietária da configuração de reservas — o salão, o estúdio, a clínica. Cada conta tem o seu próprio subdomínio público (por exemplo, yourname.micali.online) onde os visitantes acedem para efetuar uma reserva.

Uma conta contém todos os elementos com que um visitante interage: as subscrições que pode comprar, os serviços e procedimentos que pode reservar, os eventos a que se pode inscrever e os formulários que preenche pelo caminho.

Eventos

Um evento é um intervalo de tempo — ou uma série de intervalos — para o qual os visitantes se podem inscrever. Utilize os eventos para aulas, sessões em grupo, oficinas, atuações e qualquer outra reserva ligada a uma hora de início fixa.

Eventos modelo vs. eventos clássicos

Os eventos existem em duas variantes:

• Evento modelo — um modelo reutilizável. Os modelos nunca são mostrados aos visitantes; existem para que possa gerar muitos eventos reais com as mesmas definições (capacidade, formulário, mensagens, etc.) sem voltar a introduzir tudo.
• Evento clássico — um evento real e reservável. Um evento clássico pode ser criado de raiz ou ligado a um modelo, caso em que herda a configuração do modelo.

Definições importantes a conhecer

• Capacidade — quantos visitantes podem entrar num lugar e se cada visitante pode levar “amigos” (entidades adicionais). Defina um mínimo e um máximo de participantes.
• Prazo de inscrição — o último momento em que um visitante pode reservar. Se ficar vazio, as reservas permanecem abertas até ao início do evento.
• Confirmação automática — se as reservas são aceites instantaneamente ou aguardam a aprovação do administrador.
• Subscrições permitidas — restrinja quem pode reservar limitando o evento a subscrições específicas. Se deixar este campo vazio, qualquer pessoa pode reservar.
• Lista de espera — quando o evento está esgotado, os novos visitantes podem ser colocados numa lista de espera e notificados automaticamente quando um lugar ficar livre.
• Mensagens — escolha que modelos de mensagens são enviados para a confirmação da reserva, lembretes de pagamento, cancelamentos, lembretes de presença e atualizações da lista de espera. Cada evento tem o seu próprio espaço para cada finalidade, pelo que pode combinar modelos diferentes por evento.

Serviços e procedimentos

Os serviços destinam-se a reservas individuais nas quais o visitante escolhe uma hora que lhe seja conveniente. Pense num cabeleireiro, numa aula particular, numa consulta ou num tratamento.

Como se relacionam os serviços e os procedimentos

• Um serviço é o contentor — a oferta no seu todo (por exemplo, “Cabeleireiro do centro”). Tem um nome, uma descrição, uma localização, um endereço e um fuso horário.
• Um procedimento é algo específico que pode ser reservado dentro desse serviço (por exemplo, “Corte — 30 minutos”, “Coloração — 90 minutos”). Um serviço pode ter muitos procedimentos.
• A disponibilidade é o calendário das janelas de tempo em que os visitantes podem optar por reservar. Define-se por serviço.

Na página pública, um visitante escolhe primeiro um serviço, depois um procedimento, depois um horário livre — e, por fim, preenche qualquer formulário exigido.

Mensagens automáticas

Cada procedimento pode ser ligado a quatro modelos de mensagens — um para o momento em que a reserva é criada, um para a confirmação, um para a recusa e um lembrete antes da marcação. Escolha os modelos por procedimento para que diferentes serviços possam comunicar com tons diferentes.

Subscrições

Uma subscrição é um plano pré-pago que um visitante adquire — um cartão de carimbos, uma assinatura mensal, um passe de época. Utilize as subscrições para faturar antecipadamente e para controlar quem está autorizado a reservar determinados eventos.

O que define uma subscrição

• Preço e moeda — o que o visitante paga.
• Limites de utilização — número máximo de utilizações e/ou duração máxima em dias.
• Janela de disponibilidade — quando a subscrição pode ser comprada (available_from e, opcionalmente, available_to).

Como as subscrições filtram o acesso aos eventos

Por si só, uma subscrição é apenas um produto que os visitantes podem comprar. Para a usar como filtro, ligue-a a um ou mais eventos como subscrição permitida. A partir daí, apenas os visitantes que possuam essa subscrição poderão reservar o evento.

Se um visitante com uma subscrição válida não comparecer, o evento pode ser configurado para, ainda assim, consumir um crédito da sua subscrição.

Mensagens automáticas de subscrição

As subscrições podem acionar quatro modelos de mensagens:

• Após cada utilização — confirma que foi gasto um crédito e quantos restam.
• Antes da data de fim — um aviso prévio um número configurável de dias antes de a subscrição expirar.
• Ao expirar — enviada quando a subscrição termina.
• Poucas utilizações restantes — enviada quando os créditos restantes do visitante caem abaixo de um limite que o senhor defina.

Modelos de mensagens

Um modelo de mensagem é um texto reutilizável que a plataforma envia aos visitantes no momento certo — confirmação de reserva, lembrete de pagamento, lembrete de presença, aviso de expiração, etc. Defina um modelo uma única vez ao nível da conta e referencie-o em cada evento, procedimento de serviço ou subscrição que o deva utilizar.

Um modelo, dois canais

Cada modelo tem espaços para uma versão em email (assunto + corpo) e uma versão em SMS (assunto + corpo). Pode preencher uma ou outra, ou ambas — ao gravar, tem de existir pelo menos um corpo.

O que deixar em branco simplesmente não é utilizado:

• Se o corpo do email estiver vazio, não é enviado nenhum email quando este modelo é acionado.
• Se o corpo do SMS estiver vazio, não é enviado nenhum SMS quando este modelo é acionado.

Num evento, dois interruptores ao nível da conta — enviar email e enviar SMS — decidem que canais são usados para os modelos desse evento. As subscrições disponibilizam o mesmo par de interruptores para a mensagem após a utilização. Os restantes espaços de modelo enviam simplesmente pelos canais que o próprio modelo tem preenchidos.

Marcadores que pode utilizar

Os modelos suportam variáveis simples que são substituídas por dados reais no momento do envio. Pode colocar qualquer um destes no assunto ou no corpo, em qualquer dos canais:

Os marcadores que não se aplicam a uma determinada mensagem (por exemplo, %event_name% num lembrete de serviço) são simplesmente deixados vazios.

Onde os modelos são utilizados

Os modelos não são enviados por si só — são utilizados pela entidade que aciona a mensagem. Aqui está a lista completa de espaços.

Num evento

• Reserva criada — enviada no momento em que um visitante submete uma reserva.
• Confirmação — enviada quando a reserva é confirmada (manual ou automaticamente).
• Pagamento em falta — lembrete de pagamento, com uma ou duas antecedências configuráveis (primeiro e segundo lembrete, em horas antes do evento).
• Lembrete de presença — enviado um número configurável de horas antes do evento.
• Cancelamento — enviado quando o visitante cancela.
• Cancelamento pela conta — enviado quando um administrador cancela a reserva do visitante.
• Lista de espera — adicionado — enviada quando o visitante é colocado na lista de espera.
• Lista de espera — promovido — enviada quando um lugar fica livre e o visitante fica autorizado a reservar.

Num procedimento de serviço

• Reserva criada — enviada quando o visitante submete o pedido.
• Confirmação — enviada quando a marcação é aprovada.
• Recusa — enviada quando o pedido é rejeitado.
• Lembrete — enviado antes da marcação.

Numa subscrição

• Após cada utilização — enviada sempre que é gasto um crédito.
• Antes da data de fim — enviada um número configurável de dias antes de a subscrição expirar.
• Ao expirar — enviada quando a subscrição atinge a sua data de fim.
• Poucas utilizações restantes — enviada quando o número de créditos restantes cai abaixo do limite que o senhor definir.

Público vs. Ativo — o que significa cada indicador

Os eventos, serviços e subscrições partilham dois interruptores ligar/desligar. Parecem semelhantes, mas respondem a duas perguntas diferentes.

Combinações e o que significam

Webhooks

Os webhooks permitem que o Micali.online notifique os seus próprios sistemas no momento em que algo acontece dentro de uma conta — um novo visitante, uma reserva, um pagamento de subscrição. Configure um ou mais URLs de escuta por conta, escolha os eventos que lhe interessam e o Micali.online envia um payload JSON para cada URL sempre que estes são despoletados. Perfeito para sincronizar reservas num CRM, despoletar automações a jusante ou criar dashboards sobre os dados das suas reservas.

Quem os pode configurar

Apenas os root admins podem criar, editar e eliminar os listeners de webhook. Os admins e os membros da equipa não os conseguem ver nem alterar. Os webhooks estão junto às outras integrações — abra Conectores → Webhooks para os gerir.

Eventos a que pode subscrever

Cada listener está associado a um único tipo de evento. Adicione vários listeners — mesmo apontando para o mesmo URL — para receber mais do que um tipo de evento. O catálogo de eventos atualmente emitidos é:

• visitor.created — um novo visitante registou-se na conta.
• visitor.updated — um perfil de visitante existente foi atualizado.
• event_booking.created — um visitante reservou um lugar num evento.
• event_booking.confirmed — uma reserva de evento foi confirmada (manual ou automaticamente).
• event_booking.cancelled — uma reserva de evento foi cancelada.
• service_booking.created — um visitante reservou um lugar num serviço.
• service_booking.confirmed — uma reserva de serviço foi confirmada.
• service_booking.cancelled — uma reserva de serviço foi cancelada.
• membership.assigned — foi atribuída uma subscrição a um visitante.
• membership.paid — uma subscrição de visitante foi marcada como paga.
• membership.ended — uma subscrição de visitante atingiu a sua data de fim.

O que é enviado

Cada entrega é um único POST HTTP para o seu URL com um corpo JSON. Os seguintes cabeçalhos acompanham sempre o pedido:

• Content-Type: application/json — o corpo está sempre codificado em JSON.
• User-Agent: micali-webhooks/1.0 — identifica o remetente.
• X-Micali-Event: <event_type> — repete o tipo de evento para que possa encaminhar sem ler o corpo.
• Authorization — presente apenas quando configura autenticação no listener (ver abaixo).

Forma do payload

Todos os payloads partilham o mesmo envelope:

• event — o tipo de evento (mesmo valor do cabeçalho X-Micali-Event).
• occurred_at — carimbo de data/hora ISO-8601 de quando o gatilho foi executado.
• resource — o tipo de objeto dentro de data: event_booking, service_booking ou visitor_membership.
• data — um instantâneo do recurso, incluindo o seu ID público, os indicadores de estado atuais e os contactos do visitante (e-mail, primeiro e último nome, telefone). As reservas de eventos e de serviços incluem também o bloco de evento ou serviço/procedimento associado; os payloads de subscrição incluem o nome da subscrição e o ID público.

Identifique os objetos entre entregas pelo seu public_id — é o identificador estável e partilhável que usamos em todo o resto da plataforma.

Autenticação

Escolha um esquema de autenticação para que o seu recetor possa verificar que o pedido vem do Micali.online:

• Nenhuma — nenhum cabeçalho Authorization é enviado. Use apenas quando o seu endpoint estiver protegido de outra forma (URL assinado, lista de IPs permitidos, rede privada).
• Basic — o nome de utilizador e a palavra-passe são enviados como o cabeçalho padrão Authorization: Basic ....
• Token Bearer — o token que fornece é enviado como Authorization: Bearer <token>. Armazenado encriptado em repouso e nunca devolvido pela API depois de guardado.

Entrega e novas tentativas

A entrega é assíncrona e passa pela fila de tarefas em segundo plano da plataforma. Se o recetor devolver um estado não-2xx (ou o pedido falhar por completo), a tarefa tenta novamente com backoff exponencial — começando em 60 segundos, duplicando de cada vez e com um limite de uma hora entre tentativas. Após dez tentativas falhadas, a entrega é marcada como falhada e descartada. Listeners que sejam desativados ou eliminados entre o gatilho e a entrega real são ignorados silenciosamente.

Como criar um evento e publicá-lo

Para administradores raiz e administradores. O objetivo: um visitante pode chegar à sua página pública e reservar um lugar.

1. Abra a página Eventos.

   Inicie sessão na aplicação, escolha a conta correta na barra superior e abra Eventos no menu principal.

2. (Opcional) Crie primeiro um modelo.

   Se vai realizar o mesmo tipo de evento repetidamente, crie-o uma vez como modelo — capacidade, formulário, mensagens, etc. Os novos eventos clássicos poderão depois herdar dele.

3. Crie um novo evento clássico.

   Clique em Novo evento, atribua-lhe um nome e uma descrição, defina a capacidade (máximo de participantes, se podem trazer amigos) e escolha o formulário de reserva.

4. Adicione uma ou mais datas do evento.

   Para cada ocorrência defina a hora de início e, se necessário, o prazo de inscrição. Sem pelo menos uma data futura, o evento não pode ser reservado.

5. Restrinja a subscrições (opcional).

   Se só os subscritores podem participar, adicione as subscrições necessárias em Subscrições permitidas. Deixe vazio para permitir que qualquer visitante reserve.

6. Escolha as mensagens.

   Escolha os modelos para os lembretes de pagamento, os cancelamentos e o lembrete de presença. Garanta que o conetor correspondente (SMTP, SendGrid ou Twilio) está configurado ao nível da conta.

7. Ligue Ativo.

   Isto torna o evento operacional dentro da conta. Ainda não chegará aos visitantes até ao passo seguinte.

8. Ligue Público.

   Agora o evento surge no seu subdomínio público. Abra o subdomínio numa janela privada do navegador para verificar que tudo aparece corretamente.

Como criar um serviço ou procedimento e publicá-lo

Para administradores raiz e administradores. O objetivo: um visitante pode escolher um procedimento e reservar um horário livre.

1. Abra a página Serviços.

   No menu da aplicação, escolha Serviços. A lista mostra tudo o que pertence à conta ativa.

2. Crie o serviço.

   Clique em Novo serviço, introduza o nome, a descrição, a localização, o endereço e o fuso horário. O fuso horário é importante — todas as janelas de disponibilidade são interpretadas nele.

3. Adicione procedimentos.

   Para cada coisa que um visitante pode reservar, crie um procedimento com um nome e uma duração. Opcionalmente, defina um tempo de preparação antes do procedimento e um tempo de limpeza depois, para que o calendário não faça reservas duplicadas.

4. Defina a disponibilidade.

   Defina as janelas de tempo recorrentes em que as reservas são permitidas (por exemplo, seg.–sex. 9:00–17:00). Só podem ser reservados os horários dentro de uma janela de disponibilidade ativa.

5. Escolha o formulário de reserva (opcional).

   Se precisar de informações do visitante no momento da reserva — telefone, alergias, notas —, anexe um formulário ao serviço.

6. Ligue Ativo no serviço e em cada procedimento.

   Um serviço inativo fica oculto em todo o lado; um procedimento inativo permanece na base de dados mas não aparece no fluxo de reservas.

7. Ligue Público no serviço.

   Os visitantes veem agora o serviço no seu subdomínio público, com os procedimentos disponíveis e os próximos horários livres.

Como criar uma subscrição e publicá-la

Para administradores raiz e administradores. O objetivo: um visitante pode comprar uma subscrição e usá-la para reservar eventos.

1. Abra a página Subscrições.

   No menu da aplicação, escolha Subscrições.

2. Crie a subscrição.

   Clique em Nova subscrição, atribua-lhe um nome e uma breve descrição que explique o que o visitante recebe.

3. Defina o preço, a moeda e os limites.

   Introduza o preço (na menor unidade monetária), a moeda, o número máximo de utilizações e/ou a duração em dias. Deixar um limite vazio significa que é ilimitado.

4. Defina quando pode ser comprada.

   Defina disponível a partir de (quando surge na página pública) e, opcionalmente, disponível até (quando desaparece). Útil para ofertas sazonais ou por tempo limitado.

5. (Opcional) Ligue-a a eventos.

   Se a subscrição deve desbloquear eventos específicos, abra cada evento e adicione a subscrição em Subscrições permitidas.

6. Ligue Ativo.

   A subscrição faz agora parte da sua conta. As subscrições existentes de visitantes recorrentes continuam a funcionar mesmo quando isto está desligado.

7. Ligue Público.

   Os visitantes veem a subscrição no seu subdomínio público e podem comprá-la. Confirme abrindo o subdomínio numa janela privada.

Como criar um modelo de mensagem

Para administradores raiz e administradores. Os modelos vivem ao nível da conta — escreva-os uma vez e reutilize-os em qualquer evento, serviço ou subscrição.

1. Abra a página Modelos de mensagens.

   No menu da aplicação, escolha Modelos de mensagens dentro da conta ativa.

2. (Opcional) Semeie as predefinições.

   Se esta for uma conta nova, clique em Semear predefinições para criar um modelo inicial para cada espaço suportado, no idioma da conta. Pode editar qualquer um deles depois.

3. Crie um novo modelo.

   Clique em Novo modelo e dê-lhe um nome interno claro — por exemplo, “Aula de ioga — lembrete de pagamento”. O nome só é mostrado ao seu pessoal.

4. Escreva a versão de email.

   Preencha o assunto e o corpo do email. Utilize marcadores como %visitor_first_name% e %event_start_at% onde quiser valores personalizados. Opcionalmente, defina um nome de remetente.

5. Escreva a versão de SMS (opcional).

   Se também pretender enviá-lo como SMS, preencha o corpo do SMS. Mantenha-o curto — os fornecedores de SMS cobram por segmento.

6. Grave o modelo.

   Precisa, no mínimo, do nome mais um corpo de email ou de SMS. O modelo aparece agora nos menus pendentes em cada formulário de evento, procedimento e subscrição.

7. Anexe o modelo onde precisar.

   Abra o evento, o procedimento de serviço ou a subscrição pertinente e escolha o novo modelo no espaço apropriado — por exemplo, Lembrete de presença num evento. Grave e está concluído.