Empresas

Registrar empresa

Registra la empresa emisora (o la actualiza cuando el cuerpo lleva `id`) y devuelve el `empresaId` usado por todos los demás endpoints.

POST/openapi/v2/empresas

Requiere las cabeceras de firma token, timestamp y sign, vea Autenticación.

Envíe los datos de la empresa del vendedor; la respuesta trae el empresaId, variable de ruta de todos los endpoints siguientes. El registro entra en la cola de aprobación de la plataforma: la empresa solo emite después de que operaciones la apruebe y el certificado esté vinculado. Los bloques emissaoNFeProduto y emissaoDCe son cada uno opcional, pero al menos uno es obligatorio: una empresa solo de NF-e envía el primero, una empresa solo de DC-e puede omitirlo (no se crea ninguna serie NF-e) y enviar ambos habilita los dos tipos de documento; omitir ambos devuelve 400 10001001 con mensagem citando los dos bloques. Un cuerpo con id (el empresaId devuelto en el registro) se trata como actualización, vea la sección correspondiente más abajo.

Parámetros

Cuerpo de la petición

idstringobligatorio para actualizar
El empresaId devuelto en el registro. Omítalo para registrar; inclúyalo para actualizar la empresa (debe pertenecer a esta aplicación, de lo contrario 404 10003000).
cnpjstringobligatorio
14 dígitos. No puede cambiarse en la actualización: una discrepancia con la empresa devuelve 400 10001001.
Ejemplo: 14422279000106
inscricaoMunicipalstringopcional
Inscripción municipal, hasta 15 caracteres.
inscricaoEstadualstringobligatorio
Inscripción estatal (IE). Opcional en el documento de origen, pero la emisión en esta plataforma exige IE; si falta devuelve 10003006.
razaoSocialstringobligatorio
Razón social, hasta 60 caracteres.
nomeFantasiastringopcional
Nombre comercial, hasta 60 caracteres.
optanteSimplesNacionalbooleanobligatorio
Si la empresa está en el régimen Simples Nacional.
meibooleanobligatorio
Si la empresa es MEI. Derivación del régimen tributario: mei=true → MEI; si no optanteSimplesNacional=true → Simples; si no régimen normal.
emailstringobligatorio
Correo electrónico de contacto.
telefoneComercialstringobligatorio
Teléfono comercial, solo dígitos incluyendo el código de área.
enderecoobjectobligatorio
Dirección de la empresa.
emissaoNFeProdutoobjectal menos uno entre emissaoNFeProduto / emissaoDCe
Configuración de emisión de NF-e (modelo 55). Se ignora en la actualización: la serie NF-e no se mantiene por este endpoint.
emissaoDCeobjectal menos uno entre emissaoNFeProduto / emissaoDCe
Configuración de emisión de DC-e (modelo 99). Una empresa registrada sin este bloque no queda habilitada para DC-e: el registro se acepta, la respuesta trae dceHabilitado=false y la emisión devuelve DCe00004. En la actualización, omitir el bloque mantiene el perfil DC-e intacto.

Respuestas

200

Registro aceptado y colocado en la cola de aprobación (o actualización aplicada). Se devuelve el mismo formato en ambos casos.

empresaIdstring
Identificador de la empresa, variable de ruta de todos los endpoints siguientes; guárdelo. Cadena numérica.
dceHabilitadoboolean
Si la empresa está habilitada para DC-e (false cuando no se envió emissaoDCe). En la actualización refleja el estado actual de la empresa. Los integradores solo de NF-e pueden ignorarlo.

Errores

Código	HTTP
10003002	400	CNPJ ya registrado. La empresa existe: use el `empresaId` original (o actualice con `id`).
10003000	404	Actualización: `id` no existe o no pertenece a esta aplicación.
10003006	400	Datos de registro sin la IE. Informe `inscricaoEstadual`.
GW001	400	Ciudad / estado no se resuelven a un código IBGE. Verifique la UF y el nombre de la ciudad.
10001001	400	Falló la validación de campos (una entrada por campo) o error de contrato de registro / actualización: ambos bloques de configuración ausentes, actualización cambiando `cnpj` / municipio, reducción del cursor de la serie, cambio de serie.

Reglas de registro

El registro entra en la cola de aprobación de la plataforma; la empresa emite solo después de que operaciones la apruebe y el certificado esté vinculado (Vincular certificado). Emitir antes devuelve 10004004 (NF-e) o DCe00008 (DC-e). Consulte el avance de la aprobación con operaciones de la plataforma.
Tras el registro la empresa queda en el entorno de certificación (Homologacao): integre con ambienteEmissao=Homologacao (NF-e) / ambiente=Homologacao (DC-e). El cambio a producción es una acción de operaciones, sin API; enviar Producao antes del cambio devuelve 10004030 (NF-e) o DCe00004 (DC-e). Vea Entornos.
emissaoNFeProduto y emissaoDCe son cada uno opcional, pero al menos uno es obligatorio: un integrador solo de DC-e no necesita inventar una serie NF-e (omitir emissaoNFeProduto significa que no se crea ninguna serie del modelo 55). Omitir ambos devuelve 400 10001001.
Una empresa registrada sin emissaoDCe no queda habilitada para DC-e: el registro se acepta, pero la respuesta trae dceHabilitado=false y la emisión devuelve DCe00004. Verifique ese campo justo después de registrar.
inscricaoEstadual es obligatoria en esta plataforma (condición para el envío a revisión), tanto para NF-e como para DC-e.
Registrar el mismo CNPJ de nuevo devuelve 10003002.

Actualización (cuerpo con `id`)

El mismo endpoint, con el cuerpo llevando id (el empresaId devuelto en el registro), se trata como actualización: sirve para habilitar DC-e después, elevar el número inicial o corregir datos de contacto. Los demás campos siguen validándose con las reglas de registro, así que basta reenviar el payload de registro añadiendo id.

La empresa se localiza dentro del inquilino actual; desconocida devuelve 404 10003000.
Actualizados: emissaoDCe (el perfil tipoEmitente / siteMarketplace y la serie del modelo 99), nomeFantasia / email / telefoneComercial, y cep / logradouro / numero / complemento / bairro de endereco (los valores vacíos no borran los almacenados).
No actualizados: cnpj (una discrepancia con la empresa devuelve 400 10001001), razaoSocial / inscricaoEstadual / inscricaoMunicipal / régimen tributario, entorno; endereco.uf / endereco.cidade que resuelvan a otro municipio devuelven 400 10001001 (el cambio de municipio pasa por operaciones); emissaoNFeProduto se ignora en la actualización (la serie NF-e no se mantiene por este endpoint).
La serie del modelo 99 solo avanza: cuando la serie no existe (y ninguna otra está habilitada) se crea a partir de sequencialDCe / serieDCe; cuando existe, sequencialDCe solo puede elevar el próximo número (igual al próximo actual no produce cambios), un valor menor devuelve 400 10001001 con explicación; cambiar serieDCe mientras la serie anterior sigue habilitada devuelve 400 10001001 (el cambio pasa por operaciones, para que dos series habilitadas nunca hagan fallar la emisión con 10019007). Los números saltados al elevar el cursor nunca se emiten.
Una actualización sin emissaoDCe deja el perfil DC-e intacto; dceHabilitado refleja el estado actual de la empresa.
La actualización no vuelve a enviar a revisión ni cambia el estado de la empresa; la respuesta es de nuevo { empresaId, dceHabilitado }.
Operaciones también puede mantener estos valores; cambiar sequencialDCe solo afecta a documentos aún no numerados.