Companies

What a company is

A company (empresa) is the legal entity on whose behalf documents are issued: the seller of a marketplace, a carrier, or an integrator issuing for itself. Every company is identified by the empresaId returned by Register company, which is the path variable of every issuance, query and cancellation endpoint.

Lifecycle

1. Registration: a successful call to Register company places the company in the platform approval queue. Registering the same CNPJ again returns 10003002; reuse the original empresaId or send an update with id.
2. Certificate: link the A1 certificate. The certificate must belong to the company CNPJ (10003010), be valid (10003011) and differ from the currently active one (10003012); a wrong password returns CER0005. A successful upload replaces the previous certificate.
3. Approval: operations approve the company. The company can issue only after operations approve it and the certificate is linked. Issuing before that returns 10004004 for NF-e (DCe00008 for DC-e, 10017004 for CT-e). Check approval progress with platform operations.
4. Environment: every company has one current environment, test Homologacao or production Producao. Newly registered companies start in test; switching to production is an operations action with no API. The environment value in every issuance request (ambienteEmissao for NF-e and CT-e, ambiente for DC-e) must match the company's current environment; a mismatch returns 10004030 (NF-e), 10017010 (CT-e) or DCe00004 (DC-e). See Environments.

Note: an update (body carrying id) never resubmits the company for review and never changes its status or environment.

One company, four document types

The same empresaId, the same certificate and the same webhook serve every document type. What differs is the number series each type needs:

• emissaoNFeProduto, emissaoDCe and emissaoNFSe are each optional, at least one is required. An NF-e-only company sends the first, a DC-e-only or NFS-e-only company may omit it (no model 55 series is created), and sending more than one enables the corresponding document types. Omitting all three returns 400 10001001.
• The series and the next number submitted at registration are the ones used for issuance; afterwards the platform manages the sequence.
• CT-e issuance additionally requires the CNPJ to be enabled for CT-e at the state tax authority; without it SEFAZ rejects with 230 - IE do emitente não cadastrada, which the platform cannot resolve.

Tax regime derivation

The company regime is derived from two booleans sent at registration and cannot be changed through an update:

The regime drives which tax code family an NF-e item may use (CSOSN for Simples / MEI, CST for the regular regime); see NF-e. It also decides whether regimeApuracaoSn is required in the NFS-e profile, see below. inscricaoEstadual is mandatory to issue NF-e, CT-e and DC-e: missing it returns 10003006; an NFS-e-only company is not required to carry a state registration.

Enabling DC-e

DC-e (model 99) is enabled by the emissaoDCe block:

"emissaoDCe": {
  "ambienteProducao": {
    "tipoEmitente": "Marketplace",
    "sequencialDCe": 1,
    "serieDCe": "1",
    "siteMarketplace": "https://loja.exemplo.com.br"
  }
}

• tipoEmitente is Marketplace (a platform issuing on behalf of non-taxpayer sellers / individuals) or OwnIssuer (a company issuing for itself). Carrier can be registered but issuance is rejected with 10019013. siteMarketplace is required for Marketplace.
• A company registered without emissaoDCe is not enabled for DC-e: registration still succeeds, the response carries dceHabilitado=false and issuance returns DCe00004. Check that field right after registering.
• To enable DC-e later, resend the registration payload with id and the emissaoDCe block. The model 99 series only moves up: sequencialDCe may raise the next number but never lower it (400 10001001), and switching serieDCe while the old series is still enabled is refused (400 10001001, go through operations).

Enabling NFS-e

NFS-e is enabled by the emissaoNFSe block. Only with it does the company start issuing NFS-e and get its numbering sequence. Only data that does not change from one invoice to the next lives here: service code, CNAE, NBS, ISS rate, withholding and IBS/CBS follow the service being sold and go in the servico block of each issuance.

"emissaoNFSe": {
  "serieDps": "1",
  "sequencialDps": 1,
  "regimeApuracaoSn": 1,
  "regimeEspecialTributacao": 0
}

• The registration response now carries nfseHabilitado: { "empresaId": "…", "dceHabilitado": false, "nfseHabilitado": true }. Without the block it is false and issuance returns 10018005.
• On update (a body with id) sending the block replaces the whole profile: omitted optionals fall back to their defaults; without the block the profile is untouched and nfseHabilitado reflects the current state. Forcing the municipal standard is an operations action and does not go through this block.
• Structural rules rejected at acceptance (400 10001001): ME/EPP without regimeApuracaoSn, non-Simples company with regimeApuracaoSn.
• An NFS-e-only company may omit emissaoNFeProduto (no model 55 series is created) and is not required to carry inscricaoEstadual.
• The São Paulo municipal registration (CCM) is taken from the top-level inscricaoMunicipal and is not repeated in this block.

Related error codes

The full list is in Error codes.