---
title: "Referência: Empresas"
description: "Referência do recurso Empresas da API: objeto empresa, cadastrar, listar, consultar e atualizar empresas da carteira do escritório e erros possíveis."
url: https://docs.emissordenota.com/referencia/empresas
language: pt-BR
---
# Empresas

As empresas da carteira do escritório. O id de cada empresa identifica o emissor nas chamadas de NFS-e, clientes, serviços e guias.

**Escopos**: empresas:ler · empresas:escrever

**URL base**

```bash
# Produção
https://api.emissordenota.com/v1

# Sandbox
https://sandbox.api.emissordenota.com/v1
```

## Notificações ao usuário da integração

Inclua notificacoes no corpo da operação para avisar quem usa seu sistema. Informe os contatos desse usuário. A escolha vale só para a operação e seus resultados, inclusive quando a autorização da nota chega depois.

**Campos opcionais**

```json
{
  "notificacoes": {
    "destinatario": {
      "email": "usuario@example.com"
    },
    "eventos": {
      "empresa.cadastrada": [
        "email"
      ]
    }
  }
}
```

Omitir notificacoes executa a operação sem solicitar aviso. Cada canal precisa estar liberado no plano para o evento da API. Um pedido sem permissão retorna 403 permissao_insuficiente antes de executar a operação. Informe o WhatsApp com DDI e confirme a autorização do destinatário. Repetir uma chamada concluída com a mesma Idempotency-Key recupera a resposta original sem novo disparo. O sandbox valida a seleção e simula a operação sem efetuar entregas.

No cadastro, solicite empresa.cadastrada ou empresa.bloqueada. Na atualização, empresa.bloqueada está disponível. Para eventos futuros do CNPJ, inclua avisos_automaticos no cadastro ou na atualização. Enviar uma configuração substitui a anterior. Enviar null desativa. Omitir preserva a configuração.

**Avisos futuros por CNPJ**

```json
{
  "avisos_automaticos": {
    "destinatario": {
      "email": "usuario@example.com"
    },
    "eventos": {
      "guia.disponivel": [
        "email"
      ],
      "guia.vencendo": [
        "email"
      ],
      "ecac.nova_mensagem": [
        "email"
      ]
    }
  }
}
```

A chave precisa também de guias:ler para guias, empresas:ler para certificados e ecac:avisos para a Caixa Postal. Outros eventos automáticos disponíveis incluem guia.vencida, guia.paga, certificado.cadastrado, certificado.vencendo, certificado.vencido, empresa.bloqueada, acesso.disponivel, acesso.aceito e acesso.revogado. Para avisos de acesso, informe o e-mail do usuário convidado.

## Endpoints

- `GET /v1/empresas`: Lista as empresas da carteira
- `POST /v1/empresas`: Cadastra uma empresa
- `GET /v1/empresas/{id}`: Consulta uma empresa
- `POST /v1/empresas/{id}`: Atualiza os dados cadastrais

## O objeto empresa

- `id` (string): Identificador da empresa, com o prefixo emp_.
- `cnpj` (string): 14 dígitos, sem pontuação.
- `razao_social` (string): Como consta no cadastro da Receita Federal.
- `inscricao_municipal` (string): Inscrição na prefeitura do município do prestador.
- `regime_tributario` (string): simples_nacional, mei, lucro_presumido ou lucro_real.
- `municipio` (object): Código IBGE, nome e UF do município do prestador.
- `situacao` (string): pendente ou pronta. Só empresas prontas emitem.
- `pendencias` (array): O que falta para emitir: certificado, inscricao_municipal ou endereco.
- `criada_em` (string): Data e hora do cadastro, em ISO 8601.

**O objeto empresa**

```json
{
  "id": "emp_8Kq2mXv41c",
  "cnpj": "12345678000190",
  "razao_social": "Studio Aurora Design Ltda",
  "nome_fantasia": "Studio Aurora",
  "inscricao_municipal": "48291037",
  "regime_tributario": "simples_nacional",
  "municipio": {
    "codigo_ibge": "3550308",
    "nome": "São Paulo",
    "uf": "SP"
  },
  "email": "financeiro@studioaurora.com.br",
  "situacao": "pronta",
  "pendencias": [],
  "criada_em": "2026-10-02T14:20:31-03:00"
}
```

## Cadastrar uma empresa

`POST /v1/empresas`

Cria a empresa na carteira do escritório. Ela nasce com a situação pendente até o certificado A1 ser enviado pelo painel.

**Corpo da requisição**

- `cnpj` (string, obrigatório): 14 dígitos, sem pontuação. Não pode ser alterado depois.
- `razao_social` (string, obrigatório): Como consta no cadastro da Receita Federal.
- `regime_tributario` (string, obrigatório): simples_nacional, mei, lucro_presumido ou lucro_real.
- `endereco` (object, obrigatório): Endereço do estabelecimento.
  - `cep` (string, obrigatório): 8 dígitos. Rua, bairro e município são preenchidos a partir dele.
  - `numero` (string, obrigatório): Número do endereço. Use S/N quando não houver.
  - `complemento` (string, opcional): Sala, andar ou bloco.
- `nome_fantasia` (string, opcional): Nome usado no painel e nos e-mails.
- `inscricao_municipal` (string, opcional): Exigida pela maioria das prefeituras para emitir.
- `email` (string, opcional): Contato financeiro da empresa.

**POST /v1/empresas**

```bash
curl -X POST https://api.emissordenota.com/v1/empresas \
  -H "Authorization: Bearer $EDN_KEY" \
  -H "Idempotency-Key: empresa-12345678000190" \
  -H "Content-Type: application/json" \
  -d '{
    "cnpj": "12345678000190",
    "razao_social": "Studio Aurora Design Ltda",
    "regime_tributario": "simples_nacional",
    "endereco": {
      "cep": "01310100",
      "numero": "1578"
    }
  }'
```

## Listar empresas

`GET /v1/empresas`

Devolve as empresas liberadas para a chave, da mais recente para a mais antiga.

**Parâmetros de consulta**

- `situacao` (string, opcional): pendente ou pronta.
- `cnpj` (string, opcional): Busca exata pelo CNPJ.
- `limite` (integer, opcional): Itens por página. O padrão e o máximo são 50.
- `cursor` (string, opcional): O proximo_cursor da página anterior.

**GET /v1/empresas · 200 OK**

```json
{
  "dados": [
    {
      "id": "emp_8Kq2mXv41c",
      "cnpj": "12345678000190",
      "razao_social": "Studio Aurora Design Ltda",
      "situacao": "pronta"
    }
  ],
  "proximo_cursor": null
}
```

## Atualizar uma empresa

`POST /v1/empresas/{id}`

Envie só os campos que mudaram. A resposta traz o objeto empresa atualizado.

## Erros

| Status | Código | Quando |
| --- | --- | --- |
| 403 | limite_de_empresas | A carteira chegou ao limite do plano. |
| 409 | empresa_ja_cadastrada | O CNPJ já está na carteira. |
| 422 | dados_invalidos | CNPJ, CEP ou regime inválidos. |
