Guia: Segurança
Práticas de segurança da engineAPI: encriptação, certificados, LGPD, infraestrutura e compliance.
Segurança
A engineAPI lida com dados fiscais sensíveis e certificados digitais. Levamos segurança a sério em todas as camadas da infraestrutura.
Certificados digitais
Armazenamento seguro
Os certificados A1 (.pfx) dos seus clientes são tratados com o mais alto nível de proteção:
| Aspecto | Implementação |
|---|---|
| Upload | Via HTTPS (TLS 1.3). Certificado nunca trafega em texto plano |
| Armazenamento | Encriptado com AES-256 usando chave rotacionada |
| Acesso | Somente o serviço de emissão fiscal acessa o certificado, em memória |
| Exposição | A API nunca retorna o conteúdo do certificado. Apenas metadados |
| Substituição | Não existe endpoint para remover só o certificado. Um novo upload via POST /v1/companies/:id/certificate substitui o anterior |
| Remoção total | DELETE /v1/companies/:id remove a empresa inteira, incluindo o certificado |
Certificados A1 são arquivos sensíveis. Nunca armazene a senha do certificado em código-fonte, logs ou variáveis de ambiente expostas. Use um vault de secrets (AWS Secrets Manager, HashiCorp Vault, etc.).
Validade e renovação
# Verificar status do certificado
curl https://api.engineapi.com.br/v1/companies/ISSUER_UUID \
-H "Authorization: Bearer SEU_JWT"
# → { "data": { "certificateExpiresAt": "...", ... } }
O client companies do SDK TypeScript desta versão chama rotas erradas (/issuers/*
em vez de /companies). Use chamadas REST diretas como acima. Detalhe em
SDK TypeScript.
Recomendamos configurar um webhook para ser notificado quando um certificado está próximo do vencimento.
Autenticação
API Keys
| Característica | Implementação |
|---|---|
| Formato | ek_live_UUID (prefixo identificável) |
| Hash | Armazenada como hash bcrypt. Impossível recuperar |
| Rotação | Crie quantas keys quiser, revogue as antigas |
| Exposição | O valor completo é mostrado apenas na criação |
# Regenerar API Key (revoga a anterior)
curl -X POST https://api.engineapi.com.br/v1/auth/api-keys/regenerate \
-H "Authorization: Bearer SEU_JWT"
# → { "apiKey": "ek_live_..." } (único momento em que a chave completa aparece)
JWT (sessões de dashboard)
| Característica | Implementação |
|---|---|
| Algoritmo | HS256 com secret rotacionado |
| Expiração | 24 horas |
| Refresh | Via re-login |
Infraestrutura
Stack de segurança
| Camada | Tecnologia |
|---|---|
| Proxy reverso | Nginx com TLS 1.3, HSTS, rate limiting |
| Application | NestJS com Helmet.js (headers de segurança) |
| Autenticação | Passport.js (JWT + API Key strategies) |
| Validação | Validação de schema em cada endpoint, com mensagens de erro estruturadas |
| Database | PostgreSQL 16 com conexões encriptadas |
| Container | Docker com user não-root, read-only filesystem |
| Monitoramento | Sentry para error tracking, Prometheus para métricas |
Headers de segurança
Todas as respostas incluem headers de segurança via Helmet.js:
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 0
Content-Security-Policy: default-src 'self'
Referrer-Policy: strict-origin-when-cross-origin
LGPD e proteção de dados
Dados coletados
| Dado | Propósito | Retenção |
|---|---|---|
| CNPJ/CPF | Emissão fiscal (obrigatório por lei) | Enquanto a conta estiver ativa |
| Certificado A1 | Assinatura digital junto à SEFAZ | Até remoção pelo partner |
| Endereços | Composição do XML fiscal | Enquanto a conta estiver ativa |
| Logs de acesso | Auditoria e troubleshooting | 90 dias |
Direitos do titular
| Direito | Como exercer |
|---|---|
| Acesso | GET /v1/companies/:id retorna todos os dados |
| Correção | PATCH /v1/companies/:id atualiza dados |
| Exclusão | DELETE /v1/companies/:id remove empresa e dados |
| Portabilidade | Download de XMLs via endpoints de download |
A engineAPI atua como operadora de dados. O Partner (Software House) é o controlador perante a LGPD. O Partner é responsável por obter consentimento do titular antes de enviar dados para a API.