Multitenancy na API fiscal

O que é multitenancy na API fiscal?

Multitenancy, ou multilocação, é a capacidade de um mesmo sistema servir vários clientes de forma isolada. Cada cliente é chamado de tenant, algo como um inquilino que divide o mesmo prédio com outros, mas tem seu próprio apartamento trancado.

Em uma API fiscal, o tenant costuma ser a empresa emissora ou a conta que agrupa várias empresas. A infraestrutura de emissão é compartilhada, mas cada empresa tem seu próprio certificado digital, inscrições estadual e municipal, séries, numeração, regime tributário e histórico de documentos.

Para que serve o multitenancy na emissão fiscal?

Ele serve principalmente para empresas de software que emitem notas em nome de muitos clientes, como ERPs, plataformas de venda, sistemas de gestão e marketplaces. Em vez de criar uma integração separada para cada cliente, o software faz uma única integração e apenas indica, em cada requisição, para qual empresa o documento deve ser emitido.

Isso reduz o trabalho de desenvolvimento, simplifica a manutenção e permite incluir novos clientes rapidamente, bastando cadastrar a nova empresa e seu certificado.

Como funciona o multitenancy na prática?

Cada empresa é cadastrada na plataforma com seus dados fiscais e seu certificado digital A1. Ao enviar uma NF-e, NFC-e, NFS-e, CT-e ou MDF-e, o sistema integrador informa o identificador da empresa emissora, normalmente o CNPJ ou um ID interno.

A API então usa o certificado, as configurações e a numeração daquela empresa específica para assinar e transmitir o documento. O XML, o PDF e o status retornados ficam vinculados apenas a esse emitente, e as consultas também são filtradas por ele.

Como os dados de cada empresa ficam protegidos?

A base do multitenancy é a segregação de dados: uma empresa nunca deve conseguir ver, alterar ou emitir documentos de outra. Isso é garantido por regras de autenticação, permissões de acesso e filtros aplicados em todas as operações.

Certificados digitais costumam ser guardados em cofres de segredos, com acesso restrito. Registros de auditoria mostram quem fez cada ação e em nome de qual empresa, o que ajuda a investigar problemas e comprovar a correção das operações.

Qual a diferença entre multitenancy e ter uma conta por empresa?

Com uma conta por empresa, o integrador precisaria gerenciar credenciais, configurações e painéis separados para cada cliente, o que se torna inviável quando há dezenas ou centenas de CNPJs.

No modelo multitenant, há uma conta principal que administra várias empresas emissoras em um só lugar, com uma única credencial de integração e visão centralizada de certificados, rejeições e documentos, mas mantendo o isolamento entre os emitentes.

Exemplos de Multitenancy na API fiscal

• Um ERP para pequenas indústrias atende 300 clientes e usa uma única integração com a API fiscal para emitir NF-e de todos eles, enviando o CNPJ do emitente em cada requisição.
• Um marketplace emite NFS-e de intermediação em nome de diferentes lojistas, cada um com seu certificado digital e inscrição municipal cadastrados separadamente na plataforma.
• Uma transportadora com várias filiais centraliza a emissão de CT-e e MDF-e em um só console, onde cada filial aparece como uma empresa emissora com sua própria série e numeração.
• Um agente de inteligência artificial com acesso via MCP consulta apenas as notas rejeitadas de uma empresa específica, porque suas permissões limitam o acesso àquele tenant.