Autenticação

O FreeMaint aceita dois mecanismos de autenticação: JWT (emitidos por /auth/login, utilizados pelas nossas aplicações web e móvel) e chaves de API (criadas em /company-settings/api, utilizadas pelas suas próprias integrações).

JWT (sessões de utilizador)

1. POST /auth/login — Corpo: {email, password}. Devolve {access_token, refresh_token}.
2. Enviar o cabeçalho Authorization — Em cada pedido: Authorization: Bearer <access_token>.
3. Atualizar quando expirar — POST /auth/refresh com o refresh_token para obter um novo access_token. Os tokens de acesso duram 2 horas.

Chave API (integrações de servidor)

1. Abra /company-settings/api ou /profile/api-keys — Os administradores criam chaves em Definições da Empresa > API, a partir do plano Business. Uma pessoa cuja função tenha a permissão «Criar chaves API pessoais» cria as suas em Perfil > Segurança > Chaves API. Uma função com a permissão «Gerir integrações» (por exemplo, o modelo Administrador de integrações) pode criar, revogar e eliminar as chaves da empresa sem ser administrador; só um administrador entrega uma chave a outra pessoa.
2. Clique em «Nova chave» — Opcionalmente, defina uma data de expiração e um nível de acesso (Apenas leitura por predefinição). A chave em bruto é mostrada UMA ÚNICA VEZ — copie-a imediatamente.
3. Utilize-a — Envie Authorization: Bearer fmk_<rawKey> em cada pedido. Formato: começa por fmk_, seguido de 32 caracteres hexadecimais.

Notas de segurança

• As chaves de API são guardadas como hashes SHA-256 — depois de fechar a janela que a revela, o valor em bruto não pode ser recuperado
• Revogar uma chave desativa-a de imediato; a linha é conservada para auditoria
• Cada chave pertence a uma única empresa e só acede aos dados dessa empresa — um registo de outra empresa simplesmente não é encontrado
• As chaves podem ter um expiresAt opcional para integrações de curta duração
• Níveis de acesso, um teto que se soma às permissões do proprietário: READ (a predefinição — apenas consultas), READ_STOCK (consultas + adjustStock — ideal para um quiosque só de consumo), FULL (todas as operações que a função do proprietário permite)
• Cada chave atua como o seu proprietário: cada chamada transporta as permissões dele e a visibilidade de dados dele, e o que escreve fica assinado com o nome dele. Se o proprietário for desativado, a chave é recusada (401, código API_KEY_OWNER_INACTIVE) até que um administrador a atribua a outra pessoa em Definições da Empresa > API — o valor da chave não muda.

Testar uma integração

Não existe um ambiente de testes separado: uma chave de API dirige-se sempre aos dados reais da empresa a que pertence. Duas formas de testar em segurança. (1) Use uma segunda empresa como empresa de teste — o isolamento entre empresas é o mesmo mecanismo que separa todos os clientes, pelo que nada do que fizer lá pode alcançar os seus dados de produção. As chaves de API exigem o plano Business, por isso essa empresa também tem de estar no Business: uma empresa gratuita não pode criar nenhuma. (2) Para trabalho apenas de leitura, crie uma chave com o nível de acesso READ: executa todas as consultas e nenhuma mutação, logo não pode alterar nada. Quando quiser escrever, uma chave READ_STOCK permite adjustStock e mais nada.