API de Empresas (Companies)

Gerencie empresas emissoras de documentos fiscais

Navegação

• ← Voltar para Visão Geral
• Certificados →
• Inscrições Estaduais →
• Inscrições Municipais →

---

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
MunicipalTaxes	IDs das Inscrições Municipais	Vinculado ao criar IM → Ver MunicipalTax API
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

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

Autenticação

Todos os endpoints exigem autenticação via API Key: Authorization: <sua_api_key>

→ Saiba como obter sua API Key

---

Criar uma Empresa

Cria uma nova empresa na plataforma.

Criar pela Plataforma

Você também pode criar empresas diretamente pela interface da plataforma NFE.io. Veja o passo a passo em: Criar Empresa

POST /v2/companies

Headers

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

Corpo da Requisição

{
  "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

{
  "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

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

Exemplo cURL

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

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

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

{
  "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:

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

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.

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

{
  "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

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

Exemplo cURL

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.

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

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

---

Alterar Empresa

Atualiza os dados de uma empresa existente.

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

{
  "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)

nota

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

Resposta de Sucesso

Status: 200 OK

{
  "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

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.

Atenção

Este processo é irreversível. Todas as inscrições vinculadas também serão afetadas.

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

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

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

{
  "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"
  }
}

Documentação Completa

Para informações detalhadas sobre gerenciamento de certificados, consulte a API de Certificados.

---

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

nota

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
2. Crie uma Inscrição Estadual para emitir NF-e/NFC-e → Ver documentação
3. Crie uma Inscrição Municipal para emitir NFS-e → Ver documentação

---

Veja também:

• API de Certificados - Gerenciamento de certificados digitais
• Inscrições Estaduais - Configuração para NF-e/NFC-e
• Inscrições Municipais - Configuração para NFS-e