---
title: "Empresas (companies) no SDK Python da NFE.io"
description: "Cadastre, consulte, liste, altere e desative empresas emissoras com client.companies (API v2 em api.nfse.io), com paginação por cursor."
source_url: https://nfe.io/docs/desenvolvedores/bibliotecas/python/recursos/empresas/
product: bibliotecas
last_updated: 2026-10-14
tags: ["python", "referencia", "empresa"]
integration: ["sdk"]
---

# Empresas (`companies`)

`client.companies` cobre o cadastro de empresas emissoras na
[API de Contribuintes v2](/desenvolvedores/rest-api/contribuintes-v2), servida por
`https://api.nfse.io` com a `api_key`. O `id` de uma empresa é o `company_id` usado na emissão de
NFS-e, nos certificados e nas demais operações.

## Métodos

```python
companies.list(*, limit=10, starting_after=None, ending_before=None, options=None) -> CursorPage[Company]
companies.retrieve(company_id, *, options=None) -> Company
companies.create(params, *, options=None) -> Company
companies.update(company_id, params, *, options=None) -> Company
companies.delete(company_id, *, options=None) -> None
```

## Criar

```python
from nfeio import NfeClient
from nfeio.types import CompanyParams

client = NfeClient()

params: CompanyParams = {
    "name": "Minha Empresa LTDA",
    "tradeName": "Minha Empresa",
    "federalTaxNumber": "11222333000181",
    "taxRegime": "SimplesNacional",
    "address": {
        "country": "BRA",
        "postalCode": "80010000",
        "street": "Rua Exemplo",
        "number": "1",
        "district": "Centro",
        "state": "PR",
        "city": {"code": "4106902", "name": "Curitiba"},
    },
}

empresa = client.companies.create(params)
print(empresa.id, empresa.federal_tax_number, empresa.status)
```

O SDK envia o corpo dentro de `{"company": ...}`, como a API espera. Você passa só os campos da
empresa. `taxRegime` aceita `SimplesNacional`, `SimplesNacionalExcessoSublimite`,
`MicroempreendedorIndividual`, `LucroPresumido`, `LucroReal`, `Isento` e `None`.

## Consultar e listar

```python
from nfeio import NfeClient

client = NfeClient()

empresa = client.companies.retrieve("ID_DA_EMPRESA")
print(empresa["name"], empresa.tax_regime, empresa.created_on)

for item in client.companies.list(limit=50).auto_paging_iter():
    print(item.id, item["name"], item.status)
```

Propriedades tipadas de `Company`: `id`, `account_id`, `federal_tax_number` (CNPJ como `str` de 14
posições), `tax_regime`, `status`, `municipal_tax_ids`, `state_tax_ids`, `created_on` e
`modified_on`. A paginação é por cursor; veja [Paginação](../pagination.md).

:::note `municipalTaxNumber` na v2
Na API v2, o campo `municipalTaxNumber` guarda o **id** da inscrição municipal, não o número da
inscrição. Por isso ele não tem propriedade tipada. Os ids das inscrições estão em
`municipal_tax_ids` e `state_tax_ids`. A gestão das inscrições ainda não está no SDK.
:::

## Alterar

`update` **substitui a empresa inteira**: envie todos os campos que quer manter. O jeito seguro é
buscar, alterar e enviar o objeto completo:

```python
from typing import Any

from nfeio import NfeClient

client = NfeClient()

atual: dict[str, Any] = client.companies.retrieve("ID_DA_EMPRESA").to_dict()
atual["tradeName"] = "Minha Empresa (novo nome)"
empresa = client.companies.update("ID_DA_EMPRESA", atual)
print(empresa["tradeName"])
```

## Desativar

```python
from nfeio import NfeClient

client = NfeClient()

client.companies.delete("ID_DA_EMPRESA")
print(client.companies.retrieve("ID_DA_EMPRESA").status)  # "Inactive"
```

:::warning `delete` desativa, não apaga
A API faz exclusão lógica: responde `204` e a empresa continua consultável e listada com
`status == "Inactive"`. Não existe remoção definitiva pela API.
:::

## Veja também

- [Certificados](./certificates.md): envie o certificado A1 da empresa.
- [Consulta de CNPJ](./legal-entity-lookup.md): preencha o cadastro a partir do CNPJ.