Pular para o conteúdo principal

Gestão de API Keys de Integração (Web App)

Pilar: 02 — Funcionalidades Core / Web App
Status: 🟢 Implementado
Última Revisão Técnica: 2026-08-03
Módulos Conectados: gatein-web (src/screens/admin/ApiKey), gatein-server (app/api/web/apiKey.py, app/core/security.py), gatein-app (Destinatário das cargas criadas via API Keys)

1. Visão Geral e Integração com Sistemas Legados​

O módulo de Gestão de API Keys provê aos Administradores de Terminais e Transportadoras o gerenciamento de credenciais de acesso programático (Server-to-Server). Através dessas chaves, sistemas externos de ERP (ex: SAP, TOTVS), TMS e WMS conectam-se diretamente às APIs do Gatein para realizar a inclusão, alteração e cancelamento automatizado de agendamentos e viagens.

1.1 Diagrama de Sequência: Geração no Web App e Consumo via ERP Legado​

sequenceDiagram
    autonumber
    actor A as Admin da Empresa (Web App)
    participant W as Web App (React)
    participant S as Gatein Server (FastAPI)
    participant DB as PostgreSQL (companies)
    actor ERP as ERP / TMS Legado (Servidor Terceiro)
    actor M as Motorista (App Mobile)

    A->>W: Clica em "Gerar Nova Chave de API"
    W->>S: POST /web/api-key/generate
    S->>S: Gera full_key, extrai prefix ("gt_live_a1b2...") e gera hash bcrypt
    S->>DB: Salva prefix e api_key_hash na empresa
    S-->>W: Retorna full_key (Aviso: Exibido uma única vez!)
    W-->>A: Exibe modal com a chave completa em texto claro
    
    note over ERP, S: Integração Server-to-Server via API Key
    ERP->>S: POST /public/v1/appointments (Header X-API-Key: <full_key>)
    S->>DB: Middleware compara hash da chave enviada com api_key_hash
    S->>DB: Insere agendamento e identifica a empresa proprietária
    S->>M: Dispara Push FCM: "Novo agendamento recebido do ERP!"

2. Estrutura das Chaves no Banco de Dados (companies)​

Para garantir segurança total em caso de vazamento do banco de dados, a chave em texto claro nunca é armazenada. O PostgreSQL grava exclusivamente o prefixo visual e o hash criptográfico bcrypt:

Coluna SQL em companiesTipo SQLDescrição / Regra
api_key_prefixVARCHAR(16)Prefixo visual da chave primária (ex: gt_live_a1b2c345)
api_key_hashVARCHAR(255)Hash seguro bcrypt da chave primária em texto claro
api_key_secondary_prefixVARCHAR(16)Prefixo visual da chave secundária (ex: gt_live_x9y8z7w6)
api_key_secondary_hashVARCHAR(255)Hash seguro bcrypt da chave secundária em texto claro

3. Schemas de Requisição e Resposta​

Resposta de Geração de API Key (APIKeyGenerateResponse):​

{
  "success": true,
  "data": {
    "api_key": "gt_live_a1b2c345_9876543210fedcba9876543210fedcba",
    "prefix": "gt_live_a1b2c345",
    "created_at": "2026-08-04T01:00:00Z",
    "message": "Chave de API gerada com sucesso. Copie e guarde em local seguro."
  }
}

Resposta de Listagem de Chaves (APIKeyListResponse):​

{
  "success": true,
  "data": {
    "keys": [
      { "prefix": "gt_live_a1b2c345" },
      { "prefix": "gt_live_x9y8z7w6" }
    ],
    "total_keys": 2,
    "can_create": false
  }
}

4. Regras de Negócio Explícitas (RN-KEY-XXX)​

RN-KEY-001: Limite Estrito de No Máximo 2 Chaves Ativas por Empresa​

Cada empresa cliente pode possuir no máximo 2 (duas) chaves de API ativas simultaneamente (Chave Primária e Chave Secundária). Se o Administrador tentar chamar POST /web/api-key/generate com 2 chaves já ativas, a API rejeita com HTTP 400 (API_KEY_LIMIT_REACHED).

RN-KEY-002: Exibição Única da Chave Completa (Write-Only Key)​

O valor em texto claro da API Key (full_key) só é retornado no corpo da resposta HTTP no exato momento da chamada de geração (POST /web/api-key/generate). Não existe nenhum endpoint no sistema capaz de recuperar ou exibir a chave novamente após o fechamento do modal.

RN-KEY-003: Rotação de Chaves sem Downtime (Zero Downtime Rotation)​

Para permitir a troca de credenciais em sistemas produtivos sem paralisar a operação:

  1. O Administrador gera a Chave Secundária enquanto a Chave Primária continua em uso.
  2. Atualiza o ERP para utilizar a nova Chave Secundária.
  3. Revoga a Chave Primária antiga (DELETE /web/api-key/delete/{prefix}).

RN-KEY-004: Middleware de Autenticação via Header X-API-Key​

Endpoints públicos/admin da plataforma aceitam autenticação enviando o cabeçalho X-API-Key: <key> ou Authorization: ApiKey <key>. O middleware get_company_from_api_key:

  1. Extrai o prefixo (primeiros 16 caracteres).
  2. Localiza a empresa correspondente no PostgreSQL.
  3. Valida a chave completa contra o hash bcrypt gravado (api_key_hash ou api_key_secondary_hash).
  4. Injete o contexto da empresa na requisição.

5. Detalhamento de Endpoints​

5.1 GET /web/api-key/list​

Retorna os prefixos visuais das chaves ativas e o indicador can_create.

5.2 POST /web/api-key/generate​

Gera um novo par de chaves e retorna o segredo em texto claro.

5.3 POST /web/api-key/regenerate​

Substitui a chave do prefixo indicado por um novo segredo.

5.4 DELETE /web/api-key/delete/{prefix}​

Revoga permanentemente a chave correspondente ao prefixo fornecido.

6. Regras de Segurança e Tabela de Erros​

Código HTTPCódigo InternoCausa RaizAção no Web App
400 Bad RequestAPI_KEY_LIMIT_REACHEDLimite de 2 chaves já foi atingidoSolicitar revogação ou rotação de chave
401 UnauthorizedAPI_KEY_INVALIDChave de API inexistente, malformada ou revogadaVerificar o header enviado no sistema ERP
404 Not FoundAPI_KEY_PREFIX_NOT_FOUNDPrefixo informado não pertence à empresa do adminAtualizar a lista de chaves na interface