Começar
Dados sensíveis
Como uma chave chega aos recursos humanos, às fichas de hóspedes e às fichas de beleza: acesso reforçado, consentimento registado, endereços de rede, validade curta e um registo de cada pedido.
A API de integração cobre todos os módulos do Mucanda. Quase todos funcionam como já viu: o perfil da chave decide o que cada operação permite. Há três áreas diferentes, porque falam de pessoas: os recursos humanos (identificação dos trabalhadores, remunerações, folha de salários, assiduidade, processos disciplinares, denúncias), as fichas de hóspedes (documento de identificação, nacionalidade, data de nascimento, preferências e ocupantes das reservas) e as fichas de beleza (condições de saúde e alergias, testes de sensibilidade, registos técnicos, consentimentos e fotografias dos clientes). Por isso uma chave só as alcança se o dono da empresa o decidir, de propósito, ao criá-la.
#O que muda numa chave com acesso a dados sensíveis
| Regra | Porquê |
|---|---|
| Consentimento registado. Quem cria a chave lê o texto em vigor, aceita-o em nome da empresa, e fica gravado quem, quando e qual a versão do texto. | A empresa continua a ser a responsável pelos dados dos trabalhadores. Saber que consentiu, e a quê, evita enganos. |
Permissão própria. Só quem tem ApiKeys.AutorizarDadosSensiveis pode dar este acesso: criar chaves não chega. | Consentir é um acto à parte de gerir chaves. Por omissão, só o Administrador a tem. |
| Endereços de rede obrigatórios. A chave só funciona a partir dos IP ou intervalos que indicar. | Uma chave roubada fora desses endereços não serve de nada. |
| Validade curta: até 90 dias. Depois, cria-se outra chave, com novo consentimento. | Obriga a rever, de tempos a tempos, quem tem acesso. |
| Só ao criar. Não se liga o acesso a uma chave que já existe: cria-se uma nova. | O consentimento e as regras ficam sempre associados à chave desde o princípio. |
| Cada pedido fica registado, antes de ser atendido. Quando, o método, o caminho (sem parâmetros nem conteúdo) e a origem. | Sem registo, não há acesso. O dono vê o registo em Definições › Chaves de API › Acessos. |
#Dar o acesso, passo a passo
- 1Crie um perfil só para esta integração
Com as permissões de recursos humanos estritamente necessárias (por exemplo, só ler trabalhadores e assiduidade). O acesso reforçado abre a porta; o perfil continua a decidir o que se faz lá dentro.
- 2Em Definições › Chaves de API, escolha «Nova chave»
Dê o nome, escolha o perfil, indique os endereços de rede e uma data de validade (no máximo 90 dias; o botão «Usar o máximo» preenche-a).
- 3Marque «Dados sensíveis (recursos humanos, hóspedes e fichas de beleza)»
Leia o consentimento que aparece e marque a declaração. Só quem tem a permissão própria vê esta opção.
- 4Guarde a chave
Como em qualquer chave, o segredo mostra-se uma única vez.
#O que a API responde
| Situação | Resposta |
|---|---|
| Uma chave sem acesso reforçado pede uma operação de dados sensíveis | 403 DADOS_SENSIVEIS_NAO_AUTORIZADOS |
| Uma chave com o consentimento da primeira versão pede uma ficha de hóspede ou de beleza | 403 DADOS_SENSIVEIS_NAO_AUTORIZADOS (é preciso uma chave nova, com o consentimento em vigor) |
| Uma chave com acesso reforçado pede de um endereço que não é o dela | 403 ORIGEM_NAO_PERMITIDA (e nada fica registado como acesso) |
| A chave tem acesso reforçado, mas o perfil não tem a permissão da operação | 403 SEM_PERMISSAO (a resposta diz qual) |
| Tudo em ordem | A resposta normal; o pedido ficou registado. |
| Criar a chave sem consentimento, sem endereços, sem validade, ou com mais de 90 dias | 400, com o que falta |
Criar a chave sem ter a permissão ApiKeys.AutorizarDadosSensiveis | 403 SEM_PERMISSAO |
#Boas práticas
- Mínimo necessário. Um perfil por integração, só com o que ela precisa. Uma integração que só lê a assiduidade não precisa de ver salários.
- Um endereço fixo. Faça os pedidos de um servidor com IP próprio; não use um computador pessoal nem uma rede variável.
- Tenha uma base legal e uma finalidade. Só envie dados de trabalhadores a quem trata deles para um fim legítimo (por exemplo, o processamento salarial pela contabilidade), e informe os trabalhadores quando a lei o exigir.
- Guarde o segredo num cofre, nunca em código-fonte nem em ficheiros partilhados.
- Reveja o registo de acessos. Se um pedido não faz sentido, revogue a chave: o efeito é imediato.
- Renove antes de expirar. Crie a chave nova com antecedência, passe a integração para ela e revogue a antiga.