Autenticação

O FreeMaint aceita dois mecanismos de autenticação: JWTs (emitidos por /auth/login, usados ​​por nossos aplicativos web e móveis) e chaves de API (criadas em /company-settings/api, usadas por suas próprias integrações).

JWT (sessões de usuário)

1. POST /auth/login — Corpo: {e-mail, senha}. Retorna {access_token, atualização_token}.
2. Enviar cabeçalho de autorização — Em cada requisição: Authorization: Bearer <access_token>.
3. Atualizar quando expirar — POST /auth/refresh com o update_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 Configurações da empresa > API, a partir do plano Business. Uma pessoa cuja função tem a permissão “Criar chaves API pessoais” cria as próprias em Perfil > Segurança > Chaves API. Uma função com a permissão "Gerenciar integrações" (por exemplo, o modelo Administrador de integrações) pode criar, revogar e excluir as chaves da empresa sem ser administrador; só um administrador transfere uma chave para outra pessoa.
2. Clique em 'Nova chave' — Opcionalmente, defina uma data de expiração e um nível de acesso (Somente leitura por padrão). A chave bruta é mostrada UMA ÚNICA VEZ — copie-a imediatamente.
3. Use-o — Envie Authorization: Bearer fmk_<rawKey> em cada requisição. Formato: começa com fmk_ seguido de 32 caracteres hexadecimais.

Notas de segurança

• As chaves de API são armazenadas como hashes SHA-256 — depois que você fecha a caixa de diálogo de revelação, o valor bruto é irrecuperável
• A revogação de uma chave a desativa imediatamente; a linha é mantida para auditoria
• Cada chave pertence a uma única empresa e só alcança os dados dessa empresa — um registro de outra empresa simplesmente não é encontrado
• As chaves podem ter expiresAt opcional para integrações de curta duração
• Níveis de acesso, um teto acima das permissões do proprietário: READ (o padrão — somente consultas), READ_STOCK (consultas + adjustStock — ideal para um quiosque apenas de consumo), FULL (todas as operações que a função do proprietário permite)
• Cada chave age como o seu proprietário: toda chamada carrega as permissões dele e a visibilidade de dados dele, e o que ela grava é 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 passe para outra pessoa em Configuraçõ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 sempre acessa os dados reais da empresa à qual pertence. Duas formas de testar com segurança. (1) Use uma segunda empresa como empresa de teste — o isolamento entre empresas é o mesmo mecanismo que separa todos os clientes, então nada do que você fizer lá alcança seus dados de produção. As chaves de API exigem o plano Business, então essa empresa também precisa estar no Business: uma empresa gratuita não consegue criar uma chave. (2) Para trabalho somente de leitura, crie uma chave com nível de acesso READ: ela executa todas as consultas e nenhuma mutação, portanto não pode alterar nada. Quando quiser escrever, uma chave READ_STOCK permite adjustStock e nada mais.