> ## Documentation Index
> Fetch the complete documentation index at: https://docs.engineapi.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-tenancy

> Como a arquitetura B2B2B isola dados de cada CNPJ do seu cliente, mesmo com uma única API Key.

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.

***

Como o isolamento se propaga do Partner até os documentos de cada CNPJ:

```mermaid theme={null}
flowchart TD
    P("Partner<br/><i>sua Software House</i><br/>1 conta, N CNPJs · autenticação por API Key")
    I1("Issuer<br/><i>CNPJ do cliente A</i><br/>certificado A1 próprio")
    I2("Issuer<br/><i>CNPJ do cliente B</i><br/>certificado A1 próprio")
    D1("Documentos fiscais<br/>NF-e, NFC-e, NFS-e...")
    D2("Documentos fiscais<br/>NF-e, NFC-e, NFS-e...")

    P --> I1
    P --> I2
    I1 --> D1
    I2 --> D2

    classDef profundo fill:#0F2A5E,stroke:#0F2A5E,color:#fff
    classDef nucleo fill:#1E56B1,stroke:#0F2A5E,color:#fff
    classDef destaque fill:#2D7AF6,stroke:#0F2A5E,color:#fff
    class P profundo
    class I1,I2 nucleo
    class D1,D2 destaque
```

<CardGroup cols={3}>
  <Card title="Partner" icon="handshake">
    Sua Software House. Uma conta, múltiplos CNPJs. Autenticação via API Key.
  </Card>

  <Card title="Issuer" icon="building">
    Cada CNPJ do seu cliente. Certificado A1 próprio, dados isolados.
  </Card>

  <Card title="Documents" icon="file-invoice">
    Notas e documentos fiscais. Cada um vinculado a um Issuer específico.
  </Card>
</CardGroup>

***

## 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  | NF-e, NFC-e, NFS-e 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   |

<Info>
  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.
</Info>

***

## Fluxo típico de onboarding

<Info>
  Os exemplos abaixo usam HTTP cru (curl). O [SDK TypeScript](/sdks/typescript#companies-empresas-emissoras)
  oferece os mesmos fluxos via `client.companies.*`.
</Info>

<Steps>
  <Step title="Criar conta de Partner">
    Registre-se no dashboard ou via API. Você recebe credenciais de acesso.

    ```bash theme={null}
    POST /v1/auth/register-partner
    ```
  </Step>

  <Step title="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`):

    ```bash theme={null}
    POST /v1/auth/api-keys/regenerate
    ```
  </Step>

  <Step title="Cadastrar Issuers">
    Para cada CNPJ do seu cliente, crie um Issuer:

    ```bash theme={null}
    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
      }'
    ```
  </Step>

  <Step title="Upload de certificado">
    Envie o certificado A1 (.pfx) do cliente (multipart, campo `file`):

    ```bash theme={null}
    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"
    ```
  </Step>

  <Step title="Emitir documentos">
    Pronto. Use o `issuerId` na raiz do payload quando tiver 2+ emissores (opcional em
    NF-e/NFC-e, obrigatório em NFS-e; ver [Autenticação](/authentication#multi-tenancy)):

    ```bash theme={null}
    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", "...": "..." }'
    ```
  </Step>
</Steps>

***

## Gerenciando múltiplos CNPJs

### Listar todos os Issuers

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
# 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   |

<Info>
  Todos os planos têm CNPJs (Issuers) **ilimitados**. O que muda por plano é o rate
  limit (ver [Rate limits](/guides/rate-limits)). Para planos Enterprise com necessidades
  específicas, entre em contato pelo email [suporte@engineapi.com.br](mailto:suporte@engineapi.com.br).
</Info>

***

## Veja também

* **[Segurança](/guides/security):** como a engineAPI protege os dados dos seus clientes.
* **[Webhooks](/guides/webhooks):** receba notificações em tempo real por Issuer.