API e webhooks

O que são a API e os webhooks do Salonnare, para que servem e como criar chaves de API e webhooks.

API e webhooks

Com a API e os webhooks do Salonnare, ligas o teu salão a outro software: o teu programa de contabilidade, o teu próprio site, um serviço de newsletter ou um painel personalizado. Não precisas de ser programador para entender o que fazem, esta página explica-o com calma.

Ainda não disponível

Esta funcionalidade ainda está marcada como Brevemente na aplicação: não podes criar chaves de API nem webhooks neste momento. Se abrires Definições > API e webhooks, vês apenas um aviso de que a funcionalidade está a caminho. Esta página descreve como vai funcionar quando a funcionalidade estiver disponível.

O que é uma API?

Uma API (Application Programming Interface) é um acordo que permite que dois programas comuniquem entre si. Onde tu clicas num botão na aplicação para carregar uma marcação, outro programa pode pedir os mesmos dados através da API, automaticamente e sem passos manuais.

Exemplos práticos para um salão:

  • O teu software de contabilidade recolhe automaticamente a tua faturação todas as noites.
  • O teu próprio site mostra os teus tratamentos e preços diretamente do Salonnare.
  • Um parceiro de integração sincroniza a tua lista de clientes.

O acesso à API funciona através de uma chave de API: um código secreto que prova que o pedido vem de ti. Trata essa chave como uma palavra-passe.

Criar uma chave de API

  1. Vai a Definições -> API e webhooks.
  2. No separador Chaves API, clica em Nova chave.
  3. Dá à chave um nome reconhecível (por exemplo "Contabilidade") e escolhe as permissões: Apenas leitura, Leitura + escrita ou Acesso total. Neste momento, uma chave de API só consegue obter dados, independentemente do nível de permissão que escolheres; de qualquer forma, uma chave apenas de leitura nunca poderia fazer mais do que isso.
  4. Copia a chave de imediato e guarda-a em segurança. Por motivos de segurança, o Salonnare mostra a chave completa apenas uma vez.

Suspeitas que uma chave foi exposta? Elimina-a de imediato, todas as integrações que usam essa chave param imediatamente.

O que é um webhook?

Um webhook é o inverso da API. Em vez de obteres tu os dados, o Salonnare envia automaticamente uma mensagem para um endereço (URL) teu no momento em que algo acontece. O outro software já não precisa de estar constantemente a perguntar "há alguma novidade?", recebe um sinal por si só.

O Salonnare pode enviar estes seis eventos:

  • booking.created - um profissional cria uma marcação na aplicação
  • booking.updated - um profissional altera uma marcação na aplicação (incluindo uma alteração de estado para concluída ou falta)
  • booking.cancelled - um profissional cancela uma marcação na aplicação
  • payment.received - um profissional cobra na caixa
  • client.created - um profissional cria um cliente na aplicação
  • client.updated - um profissional altera os dados de um cliente na aplicação
Apenas o que acontece na aplicação

Cada evento resulta de uma ação de um profissional na aplicação. Uma marcação online através da tua página de marcações ou do Google, um cliente a cancelar por si próprio, a conversão de uma lista de espera, uma série recorrente, um programa e um cliente a registar-se a si próprio na página de marcações ainda não enviam (por agora) uma notificação. Menciona isto ao teu parceiro de integração: ele pode captar as marcações em falta ao obter periodicamente a lista de marcações.

Configurar um webhook

  1. Vai a Definições -> API e webhooks e abre o separador Webhooks.
  2. Clica em Novo webhook.
  3. Introduz o URL para onde o Salonnare deve enviar as notificações (o teu parceiro de integração ou programador fornece-o).
  4. Escolhe os eventos a que queres reagir.
  5. Guarda. Podes depois consultar os registos de entrega para ver se as notificações chegam corretamente.

O segredo que o Salonnare usa para assinar as mensagens é mostrado no momento em que guardas o webhook, guarda-o em segurança de imediato, tal como uma chave de API, porque o Salonnare não o voltará a mostrar. Se o perderes, clica no ícone de atualizar junto ao webhook (Pedir um novo segredo); vês então um novo segredo uma vez. O segredo antigo deixa de funcionar a partir desse momento, por isso o lado recetor também precisa de ser atualizado.

Cada notificação de webhook transporta uma assinatura que o recetor pode usar para verificar que a mensagem realmente veio do Salonnare.

Trabalhar com segurança

  • Nunca partilhes chaves de API publicamente (nem em e-mails, capturas de ecrã ou código publicado online).
  • Dá a uma integração apenas as permissões de que realmente precisa, escolhe apenas leitura sempre que possível.
  • Elimina chaves e webhooks que já não utilizas.

Como o Salonnare processa os teus dados na UE e és tu que decides quais as integrações que têm acesso, manténs o controlo total sobre os teus dados. Precisas de ajuda com uma integração? Não hesites em contactar-nos através da página de suporte.

És programador e procuras os detalhes técnicos (autenticação, endpoints, campos, códigos de erro, verificação de assinatura)? Consulta a Referência da API.

Artigos relacionados

DefiniçõesMarcações onlineNotificações