Empresas

Registrar empresa

Cadastra a empresa emitente (ou a atualiza quando o corpo traz `id`) e devolve o `empresaId` usado por todos os demais endpoints.

POST/openapi/v2/empresas

Requer os cabeçalhos de assinatura token, timestamp e sign, veja Autenticação.

Envia os dados da empresa do vendedor; a resposta traz o empresaId, variável de caminho de todos os endpoints seguintes. O cadastro entra na fila de aprovação da plataforma: a empresa só emite depois que a operação a aprova e o certificado está vinculado. Os blocos emissaoNFeProduto e emissaoDCe são cada um opcional, mas pelo menos um é obrigatório: uma empresa só de NF-e envia o primeiro, uma empresa só de DC-e pode omiti-lo (nenhuma série NF-e é criada) e enviar os dois habilita os dois tipos de documento; omitir ambos devolve 400 10001001 com mensagem citando os dois blocos. Um corpo com id (o empresaId devolvido no cadastro) é tratado como atualização, veja a seção correspondente abaixo.

Parâmetros

Corpo da requisição

idstringobrigatório para atualizar
O empresaId devolvido no cadastro. Omita para cadastrar; informe para atualizar a empresa (deve pertencer a esta aplicação, caso contrário 404 10003000).
cnpjstringobrigatório
14 dígitos. Na atualização não pode ser alterado: divergência com a empresa devolve 400 10001001.
Exemplo: 14422279000106
inscricaoMunicipalstringopcional
Inscrição municipal, até 15 caracteres.
inscricaoEstadualstringobrigatório
Inscrição estadual (IE). Opcional no documento de origem, mas a emissão nesta plataforma exige IE; ausente devolve 10003006.
razaoSocialstringobrigatório
Razão social, até 60 caracteres.
nomeFantasiastringopcional
Nome fantasia, até 60 caracteres.
optanteSimplesNacionalbooleanobrigatório
Se a empresa é optante do Simples Nacional.
meibooleanobrigatório
Se a empresa é MEI. Derivação do regime tributário: mei=true → MEI; senão optanteSimplesNacional=true → Simples; senão regime normal.
emailstringobrigatório
E-mail de contato.
telefoneComercialstringobrigatório
Telefone comercial, somente dígitos incluindo o DDD.
enderecoobjectobrigatório
Endereço da empresa.
emissaoNFeProdutoobjectpelo menos um entre emissaoNFeProduto / emissaoDCe
Configuração de emissão de NF-e (modelo 55). Ignorado na atualização: a série NF-e não é mantida por este endpoint.
emissaoDCeobjectpelo menos um entre emissaoNFeProduto / emissaoDCe
Configuração de emissão de DC-e (modelo 99). Uma empresa cadastrada sem este bloco não fica habilitada para DC-e: o cadastro é aceito, a resposta traz dceHabilitado=false e a emissão devolve DCe00004. Na atualização, omitir o bloco mantém o perfil DC-e intacto.

Respostas

200

Cadastro aceito e colocado na fila de aprovação (ou atualização aplicada). O mesmo formato é devolvido nos dois casos.

empresaIdstring
Identificador da empresa, variável de caminho de todos os endpoints seguintes; persista-o. String numérica.
dceHabilitadoboolean
Se a empresa está habilitada para DC-e (false quando emissaoDCe não foi enviado). Na atualização ecoa o estado atual da empresa. Integradores só de NF-e podem ignorá-lo.

Erros

Código	HTTP
10003002	400	CNPJ já cadastrado. A empresa existe: use o `empresaId` original (ou atualize com `id`).
10003000	404	Atualização: `id` não existe ou não pertence a esta aplicação.
10003006	400	Dados de cadastro sem a IE. Informe `inscricaoEstadual`.
GW001	400	Cidade / estado não resolvem para um código IBGE. Verifique a UF e o nome da cidade.
10001001	400	Falha de validação de campos (uma entrada por campo) ou erro de contrato de cadastro / atualização: ambos os blocos de configuração ausentes, atualização alterando `cnpj` / município, redução do cursor da série, troca de série.

Regras de cadastro

O cadastro entra na fila de aprovação da plataforma; a empresa emite somente após a aprovação da operação e a vinculação do certificado (Vincular certificado). Emitir antes devolve 10004004 (NF-e) ou DCe00008 (DC-e). Consulte o andamento da aprovação com a operação da plataforma.
Após o cadastro a empresa fica no ambiente de homologação (Homologacao): integre com ambienteEmissao=Homologacao (NF-e) / ambiente=Homologacao (DC-e). A troca para produção é uma ação da operação, sem API; enviar Producao antes da troca devolve 10004030 (NF-e) ou DCe00004 (DC-e). Veja Ambientes.
emissaoNFeProduto e emissaoDCe são cada um opcional, mas pelo menos um é obrigatório: um integrador só de DC-e não precisa inventar uma série NF-e (omitir emissaoNFeProduto significa que nenhuma série do modelo 55 é criada). Omitir ambos devolve 400 10001001.
Uma empresa cadastrada sem emissaoDCe não fica habilitada para DC-e: o cadastro é aceito, mas a resposta traz dceHabilitado=false e a emissão devolve DCe00004. Confira esse campo logo após cadastrar.
inscricaoEstadual é obrigatória nesta plataforma (condição para submissão à revisão), tanto para NF-e quanto para DC-e.
Cadastrar o mesmo CNPJ de novo devolve 10003002.

Atualização (corpo com `id`)

O mesmo endpoint, com o corpo trazendo id (o empresaId devolvido no cadastro), é tratado como atualização: serve para habilitar DC-e depois, elevar o número inicial ou corrigir dados de contato. Os demais campos continuam validados pelas regras de cadastro, então basta reenviar o payload de cadastro acrescentando id.

A empresa é localizada dentro do inquilino atual; desconhecida devolve 404 10003000.
Atualizados: emissaoDCe (o perfil tipoEmitente / siteMarketplace e a série do modelo 99), nomeFantasia / email / telefoneComercial, e cep / logradouro / numero / complemento / bairro de endereco (valores vazios não apagam os armazenados).
Não atualizados: cnpj (divergência com a empresa devolve 400 10001001), razaoSocial / inscricaoEstadual / inscricaoMunicipal / regime tributário, ambiente; endereco.uf / endereco.cidade que resolvam para outro município devolvem 400 10001001 (mudança de município passa pela operação); emissaoNFeProduto é ignorado na atualização (a série NF-e não é mantida por este endpoint).
A série do modelo 99 só avança: quando a série não existe (e nenhuma outra está habilitada) ela é criada a partir de sequencialDCe / serieDCe; quando existe, sequencialDCe só pode elevar o próximo número (igual ao próximo atual é no-op), um valor menor devolve 400 10001001 com explicação; trocar serieDCe enquanto a série antiga continua habilitada devolve 400 10001001 (a troca passa pela operação, para que duas séries habilitadas nunca façam a emissão falhar com 10019007). Números pulados ao elevar o cursor nunca são emitidos.
Uma atualização sem emissaoDCe deixa o perfil DC-e intacto; dceHabilitado ecoa o estado atual da empresa.
A atualização não ressubmete para revisão nem altera o status da empresa; a resposta é novamente { empresaId, dceHabilitado }.
A operação também pode manter esses valores; alterar sequencialDCe só afeta documentos ainda não numerados.