Segurança

A engineAPI lida com dados fiscais sensíveis e certificados digitais. Segurança é levada a sério em todas as camadas da infraestrutura.

Encriptação

TLS 1.3 em trânsito, AES-256 em repouso

Isolamento

Dados segregados por Partner e Issuer

Compliance

Aderência à LGPD e padrões fiscais

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 dedicado.

Validade e renovação

curl https://api.engineapi.com.br/v1/companies/ISSUER_UUID \
  -H "Authorization: Bearer SEU_JWT"
# → { "data": { "certExpiry": "...", ... } }

Desde @engineapi/sdk@1.1.0, client.companies.* chama as rotas reais (/companies) e envia o certificado como multipart/form-data. Pode usar o SDK ou chamadas REST diretas como acima. Detalhe em SDK TypeScript.

Configure um webhook para ser notificado quando um certificado está próximo do vencimento: ver Certificado digital.

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 do access token	12 horas
Refresh token	30 dias, rotacionado a cada uso (o antigo morre na hora)
Logout	Revoga a sessão no servidor: o access token para de valer imediatamente, não só quando expira
Troca de senha	Derruba todas as sessões abertas da conta

Verificação em duas etapas (2FA)

Característica	Implementação
Padrão	TOTP (RFC 6238), 6 dígitos, passo de 30 s, tolerância de ±1 passo
Obrigatória para	Superadmin da plataforma e dono de parceiro (`PartnerMember.role = OWNER`)
Opcional para	Demais usuários (ligável em Configurações → Segurança)
Segredo	Cifrado em repouso (AES-256-GCM) com a chave amarrada ao usuário; exibido uma única vez, no enrolamento
Códigos de recuperação	10 por enrolamento, uso único, guardados só como hash SHA-256
Reuso de código	Recusado: o mesmo código de 30 s não vale duas vezes

O SSO Google não é atalho: quem é obrigado a ter segundo fator passa pelo mesmo portão ao entrar pelo Google.

Característica	Implementação
Escopos	Por e-mail e por IP, independentes
Escada (e-mail)	5 falhas → 1 min · 10 → 15 min · 15 → 1 h · 20 → 4 h
Durante o bloqueio	A senha correta também é recusada
Resposta	Sempre `401 Credenciais inválidas`: bloqueio, senha errada e e-mail inexistente são indistinguíveis (anti-enumeração)
Esquecimento	Balde sem falha nova por 1 hora zera sozinho

Alertas de segurança por e-mail

O titular da conta (e o dono da plataforma, quando configurado) recebe e-mail a cada login de superadmin, troca de senha, mudança de 2FA e uso de código de recuperação. O alerta traz quando, de onde e por qual navegador; nunca carrega senha, código ou token.

Infraestrutura

Práticas de segurança

A engineAPI segue estas práticas em toda a infraestrutura, independente da tecnologia por trás:

Prática	O que garante
Transporte encriptado	TLS 1.2+ em toda comunicação, com HSTS e rate limiting na borda
Certificados em repouso	Certificados A1 encriptados com chave rotacionada, nunca em texto plano
Isolamento por tenant	Dados segregados por Partner e Issuer, sem vazamento entre contas
Validação estrita em cada endpoint	Payload fora do contrato é recusado com mensagem de erro estruturada
Menor privilégio	Cada componente acessa só o que precisa para operar, nada além disso
Monitoramento 24/7	Rastreamento de erros e métricas de disponibilidade em tempo real

Headers de segurança

Todas as respostas incluem estes headers de segurança:

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.

Boas práticas

Proteja sua API Key

Nunca exponha a API Key em código frontend
Use variáveis de ambiente no servidor
Rotacione keys periodicamente
Revogue keys comprometidas imediatamente

Valide certificados antes do upload

Verifique a validade do certificado (.pfx) antes de enviar
Configure alertas para certificados próximos do vencimento
Mantenha um processo de renovação documentado

Monitore o uso da API

Acompanhe o consumo via dashboard
Configure webhooks para eventos de erro
Use os headers X-RateLimit-* para evitar throttling

Ambiente de homologação

Sempre teste em homologação antes de ir para produção
Use dados fictícios em testes
Nunca use certificados de produção em homologação

Registro de acesso e alertas

Toda chamada autenticada entra na trilha de auditoria do seu parceiro com o endereço de origem, e é esse endereço que aparece no painel e nos alertas de segurança da EngineAPI. O endereço é resolvido a partir de X-Engine-Client-IP, X-Forwarded-For e X-Real-IP, mas apenas quando esses cabeçalhos chegam pelo gateway da EngineAPI. Se a sua integração enviar um deles numa chamada direta, o valor é descartado e vale o endereço real da conexão: não é possível escolher qual IP aparece na sua auditoria. Se você chama a EngineAPI através de um proxy próprio (NAT, saída fixa, gateway corporativo), o endereço registrado é o de saída desse proxy, não o da máquina interna.

O que dispara alerta

Estas situações avisam a equipe da EngineAPI na hora, mesmo quando a chamada é sua e legítima. Nenhuma delas bloqueia a chamada.

Situação	Limiar
Respostas `401`/`403` do mesmo endereço	20 em 5 minutos
Cadastros criados do mesmo endereço	3 em 1 hora
`PATCH /v1/webhooks/config` (destino do webhook)	toda vez
`POST /v1/webhooks/secret/regenerate`	toda vez
Regeneração de chave de API	toda vez

Se a sua esteira de testes costuma bater em 401 em série, use a chave ek_test_ e trate o erro em vez de repetir a tentativa em laço.

Veja também

Rate limits: limites de uso e como evitar throttling.
Multi-tenancy: arquitetura B2B2B e isolamento de dados.

Comece aqui

Emissão

Tributação

Erros e operação

IA e automação

Conceitos

Migração

Perguntas frequentes

Encriptação

Isolamento

Compliance

Certificados digitais

Armazenamento seguro

Validade e renovação

Autenticação

API Keys

JWT (sessões de dashboard)

Verificação em duas etapas (2FA)

Alertas de segurança por e-mail

Infraestrutura

Práticas de segurança

Headers de segurança

LGPD e proteção de dados

Dados coletados

Direitos do titular

Boas práticas

Registro de acesso e alertas

O que dispara alerta

Veja também

Encriptação

Isolamento

Compliance

​Certificados digitais

​Armazenamento seguro

​Validade e renovação

​Autenticação

​API Keys

​JWT (sessões de dashboard)

​Verificação em duas etapas (2FA)

​Bloqueio por tentativas de login

​Alertas de segurança por e-mail

​Infraestrutura

​Práticas de segurança

​Headers de segurança

​LGPD e proteção de dados

​Dados coletados

​Direitos do titular

​Boas práticas

​Registro de acesso e alertas

​O que dispara alerta

​Veja também

Certificados digitais

Armazenamento seguro

Validade e renovação

Autenticação

API Keys

JWT (sessões de dashboard)

Verificação em duas etapas (2FA)

Bloqueio por tentativas de login

Alertas de segurança por e-mail

Infraestrutura

Práticas de segurança

Headers de segurança

LGPD e proteção de dados

Dados coletados

Direitos do titular

Boas práticas

Registro de acesso e alertas

O que dispara alerta

Veja também