---
title: "API de Empresas (Companies) - Gerenciamento | NFE.io | Docs"
description: "Documentação completa da API de Empresas para criar, atualizar, consultar e gerenciar empresas emissoras de documentos fiscais eletrônicos."
source_url: https://nfe.io/docs/documentacao/gerenciamento-empresas/api-empresas
last_updated: 2026-02-06
---

# API de Empresas (Companies)

## Gerencie empresas emissoras de documentos fiscais

> **Navegação**
> - [← Voltar para Visão Geral](./gerenciamento-empresas-resumo.md)
> - [Certificados →](./gerenciamento-certificado.md)
> - [Inscrições Estaduais →](./gerenciamento-inscricao-estadual.md)
> - [Inscrições Municipais →](./gerenciamento-inscricao-municipal.md)

---

## Visão Geral

A Empresa é a entidade central do sistema que representa a personalidade jurídica do negócio. Ela atua como um **"Hub de Identidade"**, concentrando todos os dados que são universais e imutáveis, independentemente do tipo de tributação ou esfera governamental.

---

## Anatomia de uma Empresa

### Conceitos Fundamentais

Ao criar uma empresa, você define **quem ela é**. Esses dados servem de base para qualquer emissão fiscal:

| Conceito | Campos na API | Descrição |
|----------|---------------|-----------|
| **Identificação Fiscal** | `FederalTaxNumber` | CNPJ - identificador único perante a Receita Federal |
| **Nomes Formais** | `Name`, `TradeName` | Razão Social (obrigatório) e Nome Fantasia |
| **Localização Base** | `Address` | Endereço fiscal de referência para todos os contextos |
| **Regime Tributário** | `TaxRegime` | Simples Nacional, Lucro Presumido, etc. |

### Campos Gerenciados pelo Sistema

Além dos dados que você informa, o sistema gera e mantém automaticamente:

| Campo | Tipo | Quando é definido |
|-------|------|-------------------|
| `Id` | string | Gerado na criação |
| `AccountId` | string | Vinculado à sua conta/tenant |
| `Status` | enum | Inicia como `Active` |
| `Type` | enum | Tipo de pessoa (PersonType) |
| `MunicipalTaxNumber` | Inscrição Municipal (legado) | Vinculado a Inscrição Municipal utilizada para emissão de notas fiscais de serviço |
| `CreatedOn` | datetime | Data/hora da criação |
| `ModifiedOn` | datetime | Atualizado a cada alteração |

### Campos de Contexto Tributário

Estes campos conectam a empresa às suas obrigações fiscais específicas:

| Campo | Descrição | Como é preenchido |
|-------|-----------|-------------------|
| `StateTaxes` | IDs das Inscrições Estaduais | Vinculado ao criar IE → [Ver StateTax API](./gerenciamento-inscricao-estadual.md) |
| `MunicipalTaxes` | IDs das Inscrições Municipais | Vinculado ao criar IM → [Ver MunicipalTax API](./gerenciamento-inscricao-municipal.md) |
| `STStateTaxNumber` | IE Substituto Tributário | Opcional na criação |
| `SuframaTaxNumber` | Inscrição SUFRAMA | Opcional na criação |
| `Certificate` | Certificado Digital A1 | Vinculado ao adicionar certificado → [Ver Certificate API](./gerenciamento-certificado.md) |

### Referência Completa de Propriedades

### 📋 Expandir tabela completa

| Propriedade | Tipo | Obrigatório | Descrição |
|-------------|------|:-----------:|-----------|
| `Id` | string | — | Identificador único (gerado) |
| `AccountId` | string | ✅ | Conta/tenant proprietária |
| `Name` | string | ✅ | Razão social (2-60 caracteres) |
| `TradeName` | string | — | Nome fantasia |
| `FederalTaxNumber` | long | ✅ | CNPJ (somente dígitos) |
| `MunicipalTaxNumber` | string | — | Inscrição Municipal |
| `STStateTaxNumber` | string | — | IE Substituto Tributário |
| `SuframaTaxNumber` | long | — | Inscrição SUFRAMA |
| `TaxRegime` | enum | ✅ | Regime tributário |
| `Status` | enum | — | Status operacional |
| `Type` | enum | — | Tipo de pessoa |
| `Address` | object | ✅ | Endereço completo |
| `StateTaxes` | array | — | IDs de IEs vinculadas |
| `MunicipalTaxes` | array | — | IDs de IMs vinculadas |
| `Certificate` | object | — | Metadados do certificado |
| `CreatedOn` | datetime | — | Data de criação |
| `ModifiedOn` | datetime | — | Última modificação |

---

## Endpoints

| Método | Endpoint | Descrição |
|--------|----------|-----------|
| `POST` | `/v2/companies` | Criar empresa |
| `GET` | `/v2/companies` | Listar empresas |
| `GET` | `/v2/companies/{company_id}` | Consultar empresa |
| `HEAD` | `/v2/companies/{company_id}` | Verificar existência |
| `PUT` | `/v2/companies/{company_id}` | Alterar empresa |
| `DELETE` | `/v2/companies/{company_id}` | Excluir empresa |

:::info[Autenticação]
Todos os endpoints exigem autenticação via API Key: `Authorization: <sua_api_key>`

→ **[Saiba como obter sua API Key](https://nfe.io/docs/documentacao/nossa-plataforma/chaves-de-autenticacao/)**
:::

---

## Criar uma Empresa

Cria uma nova empresa na plataforma.

:::tip[Criar pela Plataforma]
Você também pode criar empresas diretamente pela interface da plataforma NFE.io. Veja o passo a passo em: [Criar Empresa](https://nfe.io/docs/documentacao/nossa-plataforma/criar-empresa/)
:::

```http
POST /v2/companies
```

### Headers

| Header | Valor |
|--------|-------|
| `Content-Type` | `application/json` |
| `Authorization` | `<sua_api_key>` |

### Corpo da Requisição

```json
{
  "Company": {
    "Name": "ACME Tecnologia LTDA",
    "TradeName": "ACME Tech",
    "FederalTaxNumber": "12345678000199",
    "TaxRegime": "SimplesNacional",
    "Address": {
      "State": "SP",
      "City": {
        "Code": "3550308",
        "Name": "São Paulo"
      },
      "District": "Centro",
      "Street": "Rua Exemplo",
      "Number": "100",
      "AdditionalInformation": "Sala 501",
      "PostalCode": "01001000",
      "Country": "BRA"
    }
  }
}
```

### Parâmetros do Corpo

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `Name` | string | ✅ | Razão social |
| `AccountId` | string | ✅ | ID da conta proprietária |
| `TradeName` | string | | Nome fantasia |
| `FederalTaxNumber` | long | ✅ | CNPJ como número (somente dígitos) |
| `TaxRegime` | enum | ✅ | Regime tributário |
| `Address` | object | ✅ | Endereço completo |

#### Objeto Address

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `State` | string | ✅ | UF (2 letras, ex: SP, RJ) |
| `City.Code` | string | ✅ | Código IBGE da cidade (7 dígitos) |
| `City.Name` | string | ✅ | Nome da cidade |
| `District` | string | ✅ | Bairro (mínimo 2 caracteres) |
| `StreetPrefix` | string | | Prefixo do logradouro (Rua, Av., etc.) |
| `Street` | string | ✅ | Logradouro (mínimo 5 caracteres, com prefixo válido) |
| `Number` | string | ✅ | Número |
| `AdditionalInformation` | string | | Complemento |
| `PostalCode` | string | ✅ | CEP (8 dígitos, somente números) |
| `Country` | string | ✅ | País (código ISO 3, ex: BRA) |

### Resposta de Sucesso

**Status:** `200 OK`

```json
{
  "Company": {
    "Id": "company_abc123",
    "AccountId": "acct_12345",
    "Name": "ACME Tecnologia LTDA",
    "TradeName": "ACME Tech",
    "FederalTaxNumber": 12345678000199,
    "MunicipalTaxNumber": null,
    "TaxRegime": "SimplesNacional",
    "Status": "Active",
    "StateTaxes": [],
    "MunicipalTaxes": [],
    "CreatedOn": "2024-01-15T10:30:00Z",
    "ModifiedOn": null,
    "Address": {
      "State": "SP",
      "City": {
        "Code": "3550308",
        "Name": "São Paulo"
      },
      "District": "Centro",
      "StreetPrefix": "Rua",
      "Street": "Rua Exemplo",
      "Number": "100",
      "AdditionalInformation": "Sala 501",
      "PostalCode": "01001000",
      "Country": "BRA"
    }
  }
}
```

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | Dados inválidos |

```json
{
  "Errors": [
    {
      "Code": 40045,
      "Message": "city code is null or empty"
    }
  ]
}
```

### Exemplo cURL

```bash
curl -X POST https://api.nfse.io/v2/companies \
  -H "Authorization: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "Company": {
      "Name": "ACME Tecnologia LTDA",
      "FederalTaxNumber": "12345678000199",
      "TaxRegime": "SimplesNacional",
      "Address": {
        "State": "SP",
        "City": { "Code": "3550308", "Name": "São Paulo" },
        "District": "Centro",
        "Street": "Rua Exemplo",
        "Number": "100",
        "PostalCode": "01001000",
        "Country": "BRA"
      }
    }
  }'
```

### Exemplo PowerShell

```powershell
$headers = @{ Authorization = "sk_live_xxx" }
$body = @{
  Company = @{
    Name = "ACME Tecnologia LTDA"
    FederalTaxNumber = "12345678000199"
    TaxRegime = "SimplesNacional"
    Address = @{
      State = "SP"
      City = @{ Code = "3550308"; Name = "São Paulo" }
      District = "Centro"
      Street = "Rua Exemplo"
      Number = "100"
      PostalCode = "01001000"
      Country = "BRA"
    }
  }
} | ConvertTo-Json -Depth 10

Invoke-RestMethod -Uri "https://api.nfse.io/v2/companies" `
  -Method Post -Headers $headers -Body $body -ContentType "application/json"
```

---

## Listar Empresas

Lista todas as empresas da conta com paginação.

```http
GET /v2/companies
```

### Headers

| Header | Valor |
|--------|-------|
| `Accept` | `application/json` |
| `Authorization` | `<sua_api_key>` |

### Parâmetros de Query

| Parâmetro | Tipo | Padrão | Descrição |
|-----------|------|--------|-----------|
| `limit` | int | 10 | Limite de resultados (1-50) |
| `startingAfter` | string | | ID do cursor para próxima página |
| `endingBefore` | string | | ID do cursor para página anterior |

### Ordenação

- Primária: `Name` (ascendente)
- Secundária: `Id` (ascendente)

### Resposta de Sucesso

**Status:** `200 OK`

```json
{
  "hasMore": true,
  "companies": [
    {
      "Id": "company_abc123",
      "AccountId": "acct_12345",
      "Name": "ACME Tecnologia",
      "TradeName": "ACME",
      "FederalTaxNumber": 12345678000199,
      "MunicipalTaxNumber": null,
      "TaxRegime": "SimplesNacional",
      "Status": "Active",
      "StateTaxes": ["statetax_xyz789"],
      "MunicipalTaxes": [],
      "CreatedOn": "2024-01-15T10:30:00Z",
      "ModifiedOn": "2024-02-20T14:45:00Z",
      "Address": {
        "State": "SP",
        "City": { "Code": "3550308", "Name": "São Paulo" },
        "District": "Centro",
        "StreetPrefix": "Rua",
        "Street": "Rua Exemplo",
        "Number": "100",
        "PostalCode": "01001000",
        "Country": "BRA"
      }
    },
    {
      "Id": "company_def456",
      "AccountId": "acct_12345",
      "Name": "Beta Serviços",
      "TradeName": "Beta",
      "FederalTaxNumber": 98765432000188,
      "MunicipalTaxNumber": null,
      "TaxRegime": "LucroPresumido",
      "Status": "Active",
      "StateTaxes": [],
      "MunicipalTaxes": ["municipaltax_abc123"],
      "CreatedOn": "2024-01-20T08:00:00Z",
      "ModifiedOn": null,
      "Address": {
        "State": "RJ",
        "City": { "Code": "3304557", "Name": "Rio de Janeiro" },
        "District": "Centro",
        "StreetPrefix": "Avenida",
        "Street": "Av. Rio Branco",
        "Number": "200",
        "PostalCode": "20040020",
        "Country": "BRA"
      }
    }
  ]
}
```

### Paginação

Use o `Id` do último item como `startingAfter` para obter a próxima página:

```http
GET /v2/companies?limit=20&startingAfter=company_def456
```

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | Parâmetros inválidos |
| `404 Not Found` | Cursor não encontrado |

### Exemplo cURL

```bash
curl -X GET "https://api.nfse.io/v2/companies?limit=20" \
  -H "Authorization: sk_live_xxx"
```

---

## Consultar Empresa por ID

Retorna os detalhes de uma empresa específica.

```http
GET /v2/companies/{company_id}
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |

### Headers

| Header | Valor |
|--------|-------|
| `Accept` | `application/json` |
| `Authorization` | `<sua_api_key>` |

### Resposta de Sucesso

**Status:** `200 OK`

```json
{
  "Company": {
    "Id": "company_abc123",
    "AccountId": "acct_12345",
    "Name": "ACME Tecnologia LTDA",
    "TradeName": "ACME Tech",
    "FederalTaxNumber": 12345678000199,
    "MunicipalTaxNumber": null,
    "TaxRegime": "SimplesNacional",
    "Status": "Active",
    "StateTaxes": ["statetax_xyz789"],
    "MunicipalTaxes": [],
    "CreatedOn": "2024-01-15T10:30:00Z",
    "ModifiedOn": "2024-02-20T14:45:00Z",
    "Address": {
      "State": "SP",
      "City": { "Code": "3550308", "Name": "São Paulo" },
      "District": "Centro",
      "StreetPrefix": "Rua",
      "Street": "Rua Exemplo",
      "Number": "100",
      "PostalCode": "01001000",
      "Country": "BRA"
    }
  }
}
```

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | ID inválido |
| `404 Not Found` | Empresa não encontrada |

```json
{
  "Errors": [
    {
      "Code": 40041,
      "Message": "company not found"
    }
  ]
}
```

### Exemplo cURL

```bash
curl -X GET https://api.nfse.io/v2/companies/company_abc123 \
  -H "Authorization: sk_live_xxx"
```

---

## Verificar Existência (HEAD)

Verifica se uma empresa existe sem retornar o corpo.

```http
HEAD /v2/companies/{company_id}
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |

### Respostas

| Status | Descrição |
|--------|-----------|
| `204 No Content` | Empresa existe |
| `400 Bad Request` | ID inválido |
| `404 Not Found` | Empresa não encontrada |

### Exemplo cURL

```bash
curl -I https://api.nfse.io/v2/companies/company_abc123 \
  -H "Authorization: sk_live_xxx"
```

---

## Alterar Empresa

Atualiza os dados de uma empresa existente.

```http
PUT /v2/companies/{company_id}
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |

### Headers

| Header | Valor |
|--------|-------|
| `Content-Type` | `application/json` |
| `Authorization` | `<sua_api_key>` |

### Corpo da Requisição

```json
{
  "Company": {
    "Name": "ACME Tecnologia LTDA - Atualizado",
    "TradeName": "ACME Tech",
    "TaxRegime": "LucroPresumido",
    "Address": {
      "State": "SP",
      "City": { "Code": "3550308", "Name": "São Paulo" },
      "District": "Jardins",
      "Street": "Av. Paulista",
      "Number": "1000",
      "AdditionalInformation": "Andar 10",
      "PostalCode": "01310100",
      "Country": "BRA"
    }
  }
}
```

### Campos Atualizáveis
    
| Campo | Tipo | Descrição |
|-------|------|-----------|
| `Name` | string | Razão social (2-60 caracteres) |
| `TradeName` | string | Nome fantasia |
| `TaxRegime` | enum | Regime tributário |
| `MunicipalTaxNumber` | string | Inscrição Municipal (legado) |
| `STStateTaxNumber` | string | IE Substituto Tributário |
| `SuframaTaxNumber` | long | Inscrição SUFRAMA |
| `Address` | object | Endereço completo |
| `Address.State` | string | UF (2 letras) |
| `Address.City` | object | Cidade (Code e Name) |
| `Address.District` | string | Bairro |
| `Address.Street` | string | Logradouro |
| `Address.Number` | string | Número |
| `Address.AdditionalInformation` | string | Complemento |
| `Address.PostalCode` | string | CEP (8 dígitos) |
| `Address.Country` | string | País (código ISO 3) |

:::note
O campo `FederalTaxNumber` (CNPJ) **não pode** ser alterado após a criação da empresa.
:::

### Resposta de Sucesso

**Status:** `200 OK`

```json
{
  "Company": {
    "Id": "company_abc123",
    "AccountId": "acct_12345",
    "Name": "ACME Tecnologia LTDA - Atualizado",
    "TradeName": "ACME Tech",
    "FederalTaxNumber": 12345678000199,
    "MunicipalTaxNumber": null,
    "TaxRegime": "LucroPresumido",
    "Status": "Active",
    "StateTaxes": ["statetax_xyz789"],
    "MunicipalTaxes": [],
    "CreatedOn": "2024-01-15T10:30:00Z",
    "ModifiedOn": "2024-03-10T16:20:00Z",
    "Address": {
      "State": "SP",
      "City": { "Code": "3550308", "Name": "São Paulo" },
      "District": "Jardins",
      "StreetPrefix": "Avenida",
      "Street": "Av. Paulista",
      "Number": "1000",
      "AdditionalInformation": "Andar 10",
      "PostalCode": "01310100",
      "Country": "BRA"
    }
  }
}
```

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | Dados inválidos |
| `404 Not Found` | Empresa não encontrada |

### Exemplo cURL

```bash
curl -X PUT https://api.nfse.io/v2/companies/company_abc123 \
  -H "Authorization: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "Company": {
      "Name": "ACME Tecnologia LTDA - Atualizado",
      "TaxRegime": "LucroPresumido",
      "Address": {
        "State": "SP",
        "City": { "Code": "3550308", "Name": "São Paulo" },
        "District": "Jardins",
        "Street": "Av. Paulista",
        "Number": "1000",
        "PostalCode": "01310100",
        "Country": "BRA"
      }
    }
  }'
```

---

## Excluir Empresa

Exclui uma empresa da plataforma.

:::warning[Atenção]
Este processo é **irreversível**. Todas as inscrições vinculadas também serão afetadas.
:::

```http
DELETE /v2/companies/{company_id}
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |

### Headers

| Header | Valor |
|--------|-------|
| `Authorization` | `<sua_api_key>` |

### Resposta de Sucesso

**Status:** `204 No Content`

(Sem corpo na resposta)

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | ID inválido |
| `404 Not Found` | Empresa não encontrada |

### Exemplo cURL

```bash
curl -X DELETE https://api.nfse.io/v2/companies/company_abc123 \
  -H "Authorization: sk_live_xxx"
```

---

## Regras de Validação

O sistema aplica as seguintes regras de validação ao criar ou alterar uma empresa:

### Dados da Empresa

| Campo | Regra | Código Erro |
|-------|-------|--------------|
| `Name` | Obrigatório, 2-60 caracteres | 40017, 40020 |
| `FederalTaxNumber` | CNPJ válido (dígito verificador) | 40031, 40032 |
| `Status` | Empresa deve estar ativa para alterações | 40019 |

### Endereço

| Campo | Regra | Código Erro |
|-------|-------|--------------|
| `Street` | Mínimo 5 caracteres, prefixo válido obrigatório | 40022 |
| `Number` | Obrigatório | 40023 |
| `District` | Mínimo 2 caracteres | 40024 |
| `Country` | Mínimo 3 caracteres (código ISO) | 40025 |
| `State` | Exatamente 2 caracteres, UF válida para Brasil | 40027 |
| `City.Code` | 7 dígitos, primeiros 2 devem corresponder ao código da UF | 40028 |
| `City.Name` | Obrigatório | 40029 |
| `PostalCode` | 8 dígitos, CEP válido | 40030 |

---

## Certificado Digital

A empresa pode ter um certificado digital ICP-Brasil (e-CNPJ A1 ou NF-e A1) vinculado para emissão de documentos fiscais eletrônicos.

### Metadados do Certificado

Quando um certificado está vinculado, os seguintes metadados são retornados:

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `Certificate.TaxPayerId` | string | ID da empresa vinculada |
| `Certificate.Thumbprint` | string | Impressão digital única do certificado |
| `Certificate.TaxId` | string | CNPJ do certificado |
| `Certificate.Subject` | string | Nome do certificado (Distinguished Name) |
| `Certificate.ValidUntil` | datetime | Data de expiração |
| `Certificate.Status` | enum | Status do certificado |
| `Certificate.ModifiedOn` | datetime | Data da última modificação |

### Status do Certificado (CertificateStatus)

| Nome | Valor | Descrição |
|------|-------|-----------|
| `Inactive` | -3 | Certificado inativo/excluído |
| `Overdue` | -2 | Certificado vencido |
| `Pending` | -1 | Certificado pendente de validação |
| `None` | 0 | Status não definido |
| `Active` | 1 | Certificado ativo e válido |

### Endpoints de Certificado

| Método | Endpoint | Descrição |
|--------|----------|-----------|
| `POST` | `/v2/companies/{company_id}/certificates` | Upload de certificado |
| `GET` | `/v2/companies/{company_id}/certificates` | Listar certificados |
| `GET` | `/v2/companies/{company_id}/certificates/{thumbprint}` | Consultar por thumbprint |
| `DELETE` | `/v2/companies/{company_id}/certificates/{thumbprint}` | Excluir certificado |

### Requisitos do Certificado

| Requisito | Descrição |
|-----------|-----------|
| **Tipo** | e-CNPJ A1 ou NF-e A1 (certificados A3 não são suportados) |
| **Formato** | Arquivo `.pfx` ou `.p12` |
| **CNPJ** | Deve corresponder ao `FederalTaxNumber` da empresa |
| **Validade** | Não pode estar expirado |
| **Senha** | Obrigatória para upload |

### Exemplo de Upload

```bash
curl -X POST https://api.nfse.io/v2/companies/company_abc123/certificates \
  -H "Authorization: sk_live_xxx" \
  -F "File=@certificado.pfx" \
  -F "Password=senha123"
```

### Resposta de Upload

```json
{
  "Certificate": {
    "TaxPayerId": "company_abc123",
    "Thumbprint": "A1B2C3D4E5F6789012345678901234567890ABCD",
    "TaxId": "12345678000199",
    "Subject": "CN=ACME TECNOLOGIA LTDA:12345678000199, OU=RFB, O=ICP-Brasil, C=BR",
    "ValidUntil": "2025-06-15T23:59:59Z",
    "ModifiedOn": "2024-01-15T10:30:00Z",
    "Status": "Active"
  }
}
```

:::info[Documentação Completa]
Para informações detalhadas sobre gerenciamento de certificados, consulte a [API de Certificados](./gerenciamento-certificado.md).
:::

---

## Códigos de Erro

### Validação de Dados da Empresa

| Código | Mensagem | Descrição |
|--------|----------|-----------|
| 40016 | id is null or empty | ID não informado |
| 40017 | name is null or empty | Razão social não informada |
| 40018 | account id is null or empty | AccountId não informado na criação |
| 40019 | company is not active | Empresa inativa não permite alterações |
| 40020 | name must be between 2 to 60 characters | Nome fora do limite permitido |

### Validação de Endereço

| Código | Mensagem | Descrição |
|--------|----------|-----------|
| 40022 | street is null or empty | Logradouro inválido ou sem prefixo válido |
| 40023 | number is null or empty | Número não informado |
| 40024 | district is null or empty | Bairro inválido (mínimo 2 caracteres) |
| 40025 | country is not valid | País inválido (mínimo 3 caracteres) |
| 40026 | city is null or empty | Cidade não informada |
| 40027 | state is not valid | UF inválida (deve ser 2 caracteres e válida para Brasil) |
| 40028 | city code is not valid | Código IBGE inválido (7 dígitos, primeiros 2 devem corresponder à UF) |
| 40029 | city name is null or empty | Nome da cidade não informado |
| 40030 | postal code is not valid | CEP inválido (deve ter 8 dígitos e ser válido) |

### Validação de CNPJ

| Código | Mensagem | Descrição |
|--------|----------|-----------|
| 40031 | federal tax number is null | CNPJ não informado |
| 40032 | federal tax number is not valid | CNPJ com dígito verificador inválido |

### Operações de Empresa

| Código | Mensagem | Descrição |
|--------|----------|-----------|
| 40035 | account id is null or empty | AccountId não informado na operação |
| 40036 | company is null | Payload da empresa nulo |
| 40037 | company id is null or empty | CompanyId não informado |
| 40038 | company id not found | Empresa não encontrada |
| 40039 | account id is not valid to this company | AccountId não corresponde à empresa |

---

## Enums

### TaxRegime (Regime Tributário)

| Nome | Valor | Descrição |
|------|-------|-----------|
| `None` | 0 | Não definido |
| `LucroReal` | 2 | Lucro Real |
| `LucroPresumido` | 4 | Lucro Presumido |
| `SimplesNacional` | 8 | Simples Nacional |
| `SimplesNacionalExcessoSublimite` | 12 | Simples Nacional - Excesso Sublimite |
| `MicroempreendedorIndividual` | 16 | MEI |
| `Isento` | 32 | Isento |

### Status

| Nome | Valor | Descrição |
|------|-------|-----------|
| `Inactive` | -1 | Inativa (empresa excluída/desativada) |
| `None` | 0 | Não definido |
| `Active` | 1 | Ativa (permite operações) |

### PersonType (Tipo de Pessoa)

| Nome | Valor | Descrição |
|------|-------|-----------|
| `None` | 0 | Não definido |
| `LegalEntity` | 1 | Pessoa Jurídica (CNPJ) |
| `Individual` | 2 | Pessoa Física (CPF) |

---

## Boas Práticas

### Validação de CNPJ

- Envie **somente dígitos** (sem pontos, barras ou traços)
- Valide o dígito verificador antes de enviar
- O tipo deve ser `long` (numérico)
- Exemplo válido: `12345678000199`
- Exemplo inválido: `12.345.678/0001-99`

### Código IBGE

- Use códigos IBGE válidos de 7 dígitos
- Os primeiros 2 dígitos devem corresponder ao código da UF
- Consulte a tabela oficial do IBGE
- Exemplos:
  - São Paulo/SP: `3550308` (35 = SP)
  - Rio de Janeiro/RJ: `3304557` (33 = RJ)
  - Belo Horizonte/MG: `3106200` (31 = MG)

### Endereço

- Preencha todos os campos obrigatórios
- Use CEP válido e formatado (somente dígitos, 8 caracteres)
- O sistema normaliza/valida automaticamente (ver abaixo)

### Normalização Automática

O sistema realiza as seguintes normalizações automaticamente:

| Comportamento | Descrição |
|---------------|------------|
| **País padrão** | Se não informado, assume `BRA` (Brasil) |
| **Números no início** | Remove números do início do logradouro |
| **Prefixo "R "** | Converte "R " para "Rua " |
| **Sem prefixo** | Adiciona "Rua" se não houver prefixo válido |

### Prefixos de Logradouro Válidos

O sistema valida se o logradouro possui um prefixo reconhecido. Exemplos aceitos:

| Prefixo | Variações |
|---------|----------|
| Rua | R., Rua |
| Avenida | Av., Av, Avenida |
| Alameda | Al., Alameda |
| Travessa | Tv., Travessa |
| Praça | Pç., Praça |
| Rodovia | Rod., Rodovia |
| Estrada | Est., Estrada |

:::note
Caso o logradouro não tenha prefixo válido, o sistema adicionará "Rua" automaticamente.
:::

---

## Próximos Passos

Após criar a empresa:

1. **Configure o certificado digital** correspondente ao CNPJ → [Ver documentação](./gerenciamento-certificado.md)
2. **Crie uma Inscrição Estadual** para emitir NF-e/NFC-e → [Ver documentação](./gerenciamento-inscricao-estadual.md)
3. **Crie uma Inscrição Municipal** para emitir NFS-e → [Ver documentação](./gerenciamento-inscricao-municipal.md)

---

## Veja também:

- [API de Certificados](./gerenciamento-certificado.md) - Gerenciamento de certificados digitais
- [Inscrições Estaduais](./gerenciamento-inscricao-estadual.md) - Configuração para NF-e/NFC-e
- [Inscrições Municipais](./gerenciamento-inscricao-municipal.md) - Configuração para NFS-e