API parceira: gerir chaves e webhooks
Com a API parceira ligas as tuas páginas de reserva, apps e integrações ao STRYK. Crias chaves com exatamente as permissões necessárias e configuras webhooks.
Contents
Antes de começares
- Precisas da permissão Gerir canais. Só assim vês a linha API na página Canais.
- Define quais as áreas que a integração tem de ler ou escrever. Uma chave recebe apenas estas permissões.
- Uma integração chama a API parceira a partir do seu servidor. Nunca coloques a chave em código de navegador ou numa app. Endpoints, parâmetros e exemplos encontras na Documentação para programadores. Lá, a secção Autenticação e âmbitos explica o que cada permissão permite.
- Os webhooks precisam de um destinatário com um endereço que comece por https://.
Abre a API
In STRYKCanais
- Em Ligações próprias, escolhe a linha API com a indicação "Chaves API e webhooks". Abre-se o diálogo API.
- Escolhe o separador Chaves API ou Webhooks. Com Documentação para programadores no cabeçalho do diálogo abres o portal de programadores.
- Separadores Chaves API e Webhooks
- Chave com permissões
- Ações da chave
Criar chave API
In STRYKCanaisAPIChaves API
- Escolhe Criar chave API. Abre-se o diálogo Criar chave API.
- Introduz o Nome, por exemplo "Página de reservas".
- Em Permissões, escolhe um padrão: Só leitura (ler todas as áreas), Leitura e escrita (escrever onde for possível) ou Personalizado. Com Personalizado escolhes, para cada área, Sem acesso, Leitura ou Escrita. As áreas são Hotel e quartos, Disponibilidade, Preços e tarifas, Reservas, Hóspedes, Pagamentos e Faturas. Escrita inclui Leitura. As faturas são documentos fiscais do hotel e só podem ser lidas através da API.
- Opcional: abre Avançado. Escolhe a Validade: Sem validade, 30 dias, 90 dias, 1 ano ou Data (a partir de amanhã, no máximo três anos). Em Restrição de IP introduz, por linha, um endereço ou uma rede CIDR, no máximo 20. Vazio permite todos os endereços. Em Nota registas uma indicação interna.
- Escolhe Criar. A STRYK mostra Chave API criada com a chave e a indicação Visível apenas agora.
- Copia a chave e guarda-a, por exemplo, num gestor de palavras-passe. Escolhe Concluído.
Gerir chaves
In STRYKCanaisAPIChaves API
A lista mostra, para cada chave, o Nome, o início da chave, as Permissões, Criado, Usado pela última vez, a Validade e o estado: Ativo, Expira em breve, Revogado ou Expirado. Seleciona uma chave para ver as Permissões, a Validade, os Endereços IP permitidos, o Limite de pedidos (pedidos por minuto), a Utilização, os Pedidos recentes e o Histórico.
- Abre o menu Opções na linha.
- Escolhe Regenerar se a integração deve receber uma nova chave com as mesmas permissões. Em Chave atual escolhe Chave antiga válida mais 24 h, para poderes adaptar a integração, ou Revogar imediatamente. Confirma com Regenerar. A STRYK mostra a nova chave uma vez.
- Escolhe Revogar e confirma Revogar a chave API? para bloquear uma chave de imediato. Os pedidos com esta chave passam a ser recusados pela STRYK.
Configurar webhooks
In STRYKCanaisAPIWebhooks
Um webhook envia os eventos escolhidos, assinados, por HTTPS para os teus sistemas.
- Escolhe Criar webhook. Abre-se o diálogo Novo webhook.
- Introduz o URL de destino, por exemplo https://crm.nordlicht.invalid/hooks/stryk. O endereço tem de começar por https://.
- Opcional: introduz uma Descrição, por exemplo "Reservas para o nosso CRM".
- Escolhe em Eventos pelo menos um: Reserva criada, Reserva alterada, Reserva cancelada, Hóspede alterado, Disponibilidade alterada, Preço alterado, Pagamento alterado ou Estado do quarto alterado. Com Selecionar tudo e Limpar seleção escolhes todos ou nenhum.
- Escolhe Criar webhook. A STRYK mostra O teu segredo de assinatura uma vez.
- Guarda o segredo no teu destinatário. Como o destinatário verifica a assinatura, descreve-o a documentação para programadores em Webhooks e verificação de assinatura.
- Escolhe o webhook e depois Enviar evento de teste. A STRYK indica "Evento de teste enviado."
Gerir webhooks
Ort: Canais > API > Webhooks, escolher o webhook
- Com o interruptor Entrega ativa pausas ou ativas o webhook. Webhooks pausados não recebem eventos. Depois de ativares, a entrega começa com os novos eventos.
- Últimos 7 dias, Último sucesso e Última falha mostram o estado. Em Entregas vês cada entrega com o Estado HTTP e as Tentativas. Com Reenviar repetes uma entrega.
- Renovar segredo gera um novo segredo. O anterior continua válido durante 24 horas, para poderes adaptar o destinatário.
- Com Editar alteras o endereço e os eventos; com Excluir e a confirmação Eliminar o webhook? removes o webhook. O registo de entregas mantém-se durante 30 dias.
Como verificas o resultado
- Na chave aparece Usado pela última vez com a data, assim que a integração a utiliza. Pedidos 24 h conta os pedidos.
- No webhook, Últimos 7 dias mostra "{Zahl} entregues, {Zahl} falhadas", e o evento de teste aparece em Entregas.
Se algo não correr bem
| O que vês | Causa | Como resolver |
|---|---|---|
| "Escolhe pelo menos uma permissão." | Nenhuma área tem uma permissão. | Escolhe um padrão ou atribui a pelo menos uma área Leitura ou Escrita. |
| "Introduz um nome, por favor." | Falta o Nome. | Introduz um nome. |
| "Verifica:" com um endereço | Um endereço na Restrição de IP é inválido. | Corrige o endereço ou a rede CIDR. São permitidas no máximo 20 entradas. |
| "Escolhe uma data a partir de amanhã, no máximo daqui a três anos." | A data de validade está fora do período. | Escolhe uma data a partir de amanhã que fique no máximo três anos à frente. |
| "O endereço tem de começar por https://." | O URL de destino não é um endereço HTTPS. | Introduz um endereço com https://. |
| "Escolhe pelo menos um evento." | O webhook não tem nenhum evento. | Escolhe pelo menos um evento em Eventos. |
| Pausado por erros repetidos | O destinatário não responde com um estado 2xx. | Verifica se o destinatário está acessível e escolhe Reativar. |
| "Ativa o webhook para enviar um evento de teste." | O webhook está pausado. | Ativa Entrega ativa e envia o evento de teste. |
| "Não foi possível carregar a seleção. Fecha e volta a abrir." | A lista de permissões e eventos não foi carregada. | Fecha o diálogo e volta a abri-lo. |