Empresas (companies)

client.companies cobre o cadastro de empresas emissoras na API de 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

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

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

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.

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:

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

from nfeio import NfeClient

client = NfeClient()

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

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: envie o certificado A1 da empresa.
• Consulta de CNPJ: preencha o cadastro a partir do CNPJ.