Guia: Multitenancy
Arquitetura B2B2B da engineAPI. Como Partners gerenciam múltiplos CNPJs com isolamento completo de dados.
Multitenancy
A engineAPI foi projetada como uma plataforma B2B2B (Business-to-Business-to-Business). Isso significa que você, como Software House, integra a engineAPI na sua plataforma e oferece emissão fiscal para seus clientes finais. Sem que eles saibam que a engineAPI existe.
Hierarquia de dados
Isolamento de dados
Cada Issuer opera em isolamento completo:
| Aspecto | Isolamento |
|---|---|
| Certificado digital | Cada Issuer tem seu próprio A1, encriptado em repouso |
| Documentos fiscais | NFe, NFCe, NFSe, etc. são vinculados ao Issuer. Impossível acessar de outro |
| Configurações | Regime tributário, série, ambiente (produção/homologação) são independentes |
Um Partner com 500 Issuers tem garantia de que o Issuer A nunca acessa dados do Issuer B, mesmo usando a mesma API Key. O isolamento é enforced no backend por filtros automáticos.
Fluxo típico de onboarding
Os exemplos abaixo usam HTTP cru (curl). O client companies do SDK TypeScript desta
versão chama rotas erradas (/issuers/* em vez de /companies). Ver aviso em
SDK TypeScript.
Criar conta de Partner
Registre-se no dashboard ou via API. Você recebe credenciais de acesso.
POST /v1/auth/register-partner
Gerar API Key
Crie uma API Key de produção para integração server-to-server (requer subscription
ACTIVE; sem assinatura, use a de teste em POST /auth/api-keys/test/regenerate):
POST /v1/auth/api-keys/regenerate
Cadastrar Issuers
Para cada CNPJ do seu cliente, crie um Issuer:
curl -X POST https://api.engineapi.com.br/v1/companies \
-H "Authorization: Bearer SEU_JWT" \
-H "Content-Type: application/json" \
-d '{
"cnpj": "11222333000181",
"name": "Cliente Final Ltda",
"crt": 1
}'
Upload de certificado
Envie o certificado A1 (.pfx) do cliente (multipart, campo file):
curl -X POST https://api.engineapi.com.br/v1/companies/ISSUER_ID/certificate \
-H "Authorization: Bearer SEU_JWT" \
-F "file=@certificado.pfx" \
-F "password=senha-do-pfx"
Emitir documentos
Pronto. Use o issuerId na RAIZ do payload quando tiver 2+ emissores (opcional em
NFe/NFCe, obrigatório em NFSe; ver Autenticação):
curl -X POST https://api.engineapi.com.br/v1/nfe \
-H "x-api-key: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "issuerId": "ISSUER_UUID", "...": "..." }'
Gerenciando múltiplos CNPJs
Listar todos os Issuers
curl https://api.engineapi.com.br/v1/companies \
-H "Authorization: Bearer SEU_JWT"
Emitir para um Issuer específico
O issuerId (na raiz do payload) é o campo que determina qual CNPJ emite o documento:
# NFe para o Issuer A
curl -X POST https://api.engineapi.com.br/v1/nfe \
-H "x-api-key: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "issuerId": "ISSUER_A_UUID", "...": "..." }'
Certificados independentes
Cada Issuer precisa do seu próprio certificado A1:
# Upload para Issuer A
curl -X POST https://api.engineapi.com.br/v1/companies/ISSUER_A_UUID/certificate \
-H "Authorization: Bearer SEU_JWT" \
-F "file=@certificado-a.pfx" -F "password=senha-a"
# Upload para Issuer B (certificado diferente)
curl -X POST https://api.engineapi.com.br/v1/companies/ISSUER_B_UUID/certificate \
-H "Authorization: Bearer SEU_JWT" \
-F "file=@certificado-b.pfx" -F "password=senha-b"
Limites por plano
| Plano | CNPJs (Issuers) | Rate limit |
|---|---|---|
| Dev | Ilimitados | 5 req/s |
| Starter | Ilimitados | 20 req/s |
| Growth | Ilimitados | 60 req/s |
| Scale | Ilimitados | 200 req/s |
| Enterprise | Ilimitados | Dedicado |
Todos os planos têm CNPJs (Issuers) ilimitados. O que muda por plano é o rate limit (ver Rate Limits). Para planos Enterprise com necessidades específicas, entre em contato pelo email suporte@engineapi.com.br.