Empresas
Ciclo de vida de una empresa emisora en TF Fiscal, cómo una empresa atiende NF-e, CT-e, DC-e y NFS-e, régimen tributario y régimen de PIS/COFINS, habilitación de DC-e y de NFS-e y los códigos de error relacionados.
Qué es una empresa
Una empresa (empresa) es la entidad legal en cuyo nombre se emiten los documentos: el vendedor de un marketplace, una transportadora o un integrador que emite para sí mismo. Toda empresa se identifica por el empresaId devuelto por Registrar empresa, que es la variable de ruta de todos los endpoints de emisión, consulta y cancelación.
| Paso | Endpoint | Notas |
|---|---|---|
| 1 Registrar empresa | POST /openapi/v2/empresas | Devuelve empresaId, dceHabilitado y nfseHabilitado; un cuerpo con id actualiza una empresa existente |
| 2 Vincular certificado | POST /openapi/v1/empresas/{empresaId}/certificadoDigital | Certificado A1 (.pfx / .p12) y su contraseña; multipart o JSON + Base64 |
| 3 Registrar webhook | POST /openapi/v1/webhooks | Una URL de callback por aplicación, compartida por todos los tipos de documento |
| 4 Seguir el análisis | GET /openapi/v2/empresas, GET /openapi/v2/empresas/{empresaId} | Lista sus empresas; consulta estado del análisis, motivo de rechazo, documentos habilitados y resumen del certificado por empresaId; no se cobra |
| Todo de una vez | POST /openapi/v2/empresas/cadastro-automatico | Solo CNPJ, certificado A1 y contraseña; la plataforma crea la empresa y vincula el certificado, sustituyendo los pasos 1 y 2. Pendientes: Registrar empresa con id; estado: Consultar empresa |
Ciclo de vida
- Registro: una llamada exitosa a Registrar empresa coloca la empresa en la cola de aprobación de la plataforma. Registrar el mismo CNPJ de nuevo devuelve
10003002; reutilice elempresaIdoriginal o envíe una actualización conid. - Certificado: vincule el certificado A1. El certificado debe pertenecer al CNPJ de la empresa (
10003010), estar vigente (10003011) y ser distinto del actualmente activo (10003012); una contraseña incorrecta devuelve10003008. Un envío exitoso reemplaza el certificado anterior. - Aprobación: cuando la aprobación automática está activa para el integrador, la plataforma compara los datos registrados con el registro nacional de empresas de Brasil y aprueba automáticamente si coinciden; si hay diferencias, el servicio de consulta no está disponible o no hay registro, operaciones lo revisa manualmente. Sin aprobación automática, la revisión siempre es manual. La empresa solo emite después de que operaciones la apruebe y el certificado esté vinculado. Emitir antes devuelve
10004004para NF-e (10019004para DC-e,10017004para CT-e). Siga la aprobación en Listar empresas o Consultar empresa:statusAtivasignifica aprobada y, conRejeitada, el motivo viene enmotivoStatus. - Entorno: toda empresa tiene un entorno actual, pruebas
Homologacaoo producciónProducao. Las empresas recién registradas comienzan en pruebas; el cambio a producción es una acción de operaciones, sin API. El valor de entorno en toda solicitud de emisión (ambienteEmissaopara NF-e y CT-e,ambientepara DC-e) debe coincidir con el entorno actual de la empresa; una discrepancia devuelve10004030(NF-e),10017010(CT-e) o10019010(DC-e). Vea Entornos.
Nota: una actualización (cuerpo con
id) nunca vuelve a enviar la empresa a revisión ni cambia su estado o entorno. La excepción son las empresas en borrador o rechazadas, como las dejadas por el registro automático: sin inscripción estatal, la actualización guardainscricaoEstadual, y con los datos completos el borrador entra en análisis automáticamente; la rechazada solo vuelve a análisis (manual) cuando la actualización completa un campo que estaba pendiente.
Una empresa, cuatro tipos de documento
El mismo empresaId, el mismo certificado y el mismo webhook atienden todos los tipos de documento. Lo que cambia es la serie de numeración que cada tipo exige:
| Tipo de documento | Modelo | Serie configurada mediante | Campo de entorno | Código de no emisión |
|---|---|---|---|---|
| NF-e | 55 | emissaoNFeProduto.ambienteProducao (sequencialNFe / serieNFe) en el registro o en la actualización con id | ambienteEmissao | 10004004 |
| CT-e | 57 | Configurada del lado de la plataforma; el registro no tiene bloque de CT-e. Sin serie, o con varias habilitadas y ninguna elegida, la emisión devuelve 10017007 | ambienteEmissao | 10017004 |
| DC-e | 99 | emissaoDCe.ambienteProducao (tipoEmitente, sequencialDCe / serieDCe, siteMarketplace) en el registro o en una actualización con id | ambiente | 10019004 |
| NFS-e | — | emissaoNFSe (serieDps y los demás valores por defecto del perfil) en el registro o en una actualización con id, o mantenido por operaciones | ambienteEmissao | 10018004 |
emissaoNFeProduto,emissaoDCeyemissaoNFSeson 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 o solo de NFS-e puede omitirlo (no se crea ninguna serie del modelo 55) y enviar más de uno habilita los tipos de documento correspondientes. Omitir los tres devuelve 40010001001.- La serie y el próximo número enviados en el registro son los que se usan en la emisión; después la plataforma gestiona la secuencia.
- En la actualización con
idyemissaoNFeProduto: la serie se crea si no existe; si existe, el próximo número pasa a sersequencialNFe, y las demás series de NF-e de la empresa se deshabilitan; sin el bloque las series quedan como están. Bajar el próximo número hace que la SEFAZ rechace duplicados, subirlo salta números que no se inutilizan automáticamente; ambas cosas son responsabilidad de quien llama. Vea «Definir la numeración de NF-e» en Registrar empresa. - El mismo CNPJ puede registrarse con integradores distintos; cada integrador define sus propias series y la plataforma no verifica superposiciones entre integradores. Si el mismo CNPJ emite a través de varios integradores, cada uno debe usar series que no se superpongan; de lo contrario los números chocan y la SEFAZ los rechaza.
- La emisión de CT-e exige además que el CNPJ esté habilitado para CT-e en la SEFAZ estatal; sin ello la SEFAZ rechaza con
230 - IE do emitente não cadastrada, lo que la plataforma no puede resolver.
Régimen tributario
El régimen tributario (Código de Regime Tributário, CRT) define qué códigos tributarios usa la factura y cómo se calculan los tributos. La plataforma guarda internamente el código oficial de 1 a 4; la API abierta no recibe ni devuelve ese código y expresa el régimen con dos booleanos, optanteSimplesNacional y mei.
| CRT | Nombre oficial | Quién es | optanteSimplesNacional / mei en la consulta de la empresa |
|---|---|---|---|
| 1 | Simples Nacional | Microempresa o pequeña empresa (ME / EPP) del Simples Nacional | true / false |
| 2 | Simples Nacional – excesso de sublimite de receita bruta | Adherida al Simples Nacional con ingresos por encima del sublímite estatal y municipal | true / false |
| 3 | Regime Normal | Empresa fuera del Simples Nacional | false / false |
| 4 | Simples Nacional - Microempreendedor individual - MEI | Microemprendedor individual | true / true |
La familia de código sigue al régimen: en NF-e y NFC-e, CRT 1 / 4 usa CSOSN de 3 dígitos y CRT 2 / 3 usa CST de 2 dígitos; si no, 10004046 (vea NF-e). El régimen también define si regimeApuracaoSn es obligatorio en el perfil de NFS-e, vea más abajo. inscricaoEstadual es obligatoria para emitir NF-e, CT-e y DC-e: si falta devuelve 10003006; una empresa solo de NFS-e no necesita inscripción estatal.
Cómo los dos booleanos se convierten en CRT en el registro
mei | optanteSimplesNacional | CRT guardado |
|---|---|---|
false | false | 3 Regime Normal |
false | true | 1 Simples Nacional |
true | true | 4 MEI |
true | false | 4 MEI: mei prevalece, sin rechazo y sin mirar optanteSimplesNacional |
Todo MEI está adherido al Simples Nacional, así que envíe true / true. Ninguna combinación de los dos booleanos da CRT 2; vea «Exceso de sublímite» abajo.
Cómo cambiarlo después
- La actualización de Registrar empresa con
idno cambia el régimen. La única excepción es la empresa del registro automático con el régimen pendiente de confirmación: en ese caso los dos booleanos de la solicitud se guardan una vez. - En la consola, el botón «Datos tributarios» del detalle de la empresa cambia el CRT en cualquier momento (de 1 a 4), en cualquier estado de la empresa, y también cierra la confirmación pendiente. El cambio llega a la emisión en un minuto como máximo, y las clases de impuesto referenciadas se revalidan con el régimen nuevo.
- Consultar empresa devuelve los dos booleanos según el CRT actual; con el régimen pendiente de confirmación los dos vienen
null.
Exceso de sublímite (CRT 2)
La API abierta no expresa el CRT 2, y la plataforma nunca lo deduce. Para estas empresas:
- En el registro, envíelas como Simples Nacional:
optanteSimplesNacional=trueymei=false; la plataforma guarda CRT 1. - En la consola, en «Datos tributarios», cambie el régimen a Simples Nacional (sobre el límite), es decir CRT 2.
- A partir de ahí la consulta de la empresa devuelve
true/false, y reenviartrue/falseen una actualización conidno vuelve a CRT 1.
Con CRT 2, el ICMS de los ítems usa CST de 2 dígitos.
Lucro Presumido, Lucro Real y Lucro Arbitrado
No son regímenes tributarios: son formas de cálculo del impuesto federal sobre la renta, y en la factura todas son CRT 3 Regime Normal. La API abierta no recibe ni devuelve esta información; la Consulta de CNPJ, los endpoints de empresa y el registro automático no tienen campo para ella. En la emisión solo afecta la alícuota de PIS / COFINS en el CST 01, que la plataforma llama régimen de PIS/COFINS:
| Régimen de PIS/COFINS | Para | PIS | COFINS |
|---|---|---|---|
| Acumulativo | Lucro Presumido, Lucro Arbitrado | 0,65 % | 3,00 % |
| No acumulativo | Lucro Real | 1,65 % | 7,60 % |
El régimen de PIS/COFINS se configura en la consola en «Datos tributarios»: Lucro Presumido (acumulativo) o Lucro Real (no acumulativo); para Lucro Arbitrado elija el acumulativo. Una empresa CRT 3 registrada por la API empieza sin régimen de PIS/COFINS. La NFS-e también usa el régimen de PIS/COFINS, con reglas propias (vea NFS-e); abajo, solo NF-e y NFC-e.
Al emitir NF-e y NFC-e (incluida la emisión offline) de una empresa CRT 3, la alícuota de PIS y COFINS en el CST 01 sigue esta tabla:
| En la solicitud o en la clase de impuesto referenciada | Empresa con régimen de PIS/COFINS | Empresa sin régimen de PIS/COFINS |
|---|---|---|
Con aliquota | Debe ser la alícuota legal de arriba; si no, rechazo 10005008 | Se usa el valor enviado |
Sin aliquota | La plataforma completa la alícuota legal | Rechazo 10005007 |
Al guardar una clase de impuesto rige la misma verificación: con régimen de PIS/COFINS configurado, una fila CST 01 con aliquota distinta de la legal devuelve 10005008. Fuera del CST 01 la plataforma no completa alícuotas por el régimen; en empresas CRT 1, 2 y 4 tampoco.
Habilitar DC-e
El DC-e (modelo 99) se habilita con el bloque emissaoDCe:
"emissaoDCe": {"ambienteProducao": {"tipoEmitente": "Marketplace","sequencialDCe": 1,"serieDCe": "1","siteMarketplace": "https://loja.exemplo.com.br"}}
tipoEmitenteesMarketplace(una plataforma que emite en nombre de vendedores no contribuyentes / personas físicas) uOwnIssuer(una empresa que emite para sí misma).Carrierpuede registrarse, pero la emisión se rechaza con10019013.siteMarketplacees obligatorio paraMarketplace.- Una empresa registrada sin
emissaoDCeno queda habilitada para DC-e: el registro se acepta, la respuesta traedceHabilitado=falsey la emisión devuelve10019012. Verifique ese campo justo después de registrar. - Para habilitar DC-e después, reenvíe el payload de registro con
idy el bloqueemissaoDCe. La serie del modelo 99 solo avanza:sequencialDCepuede elevar el próximo número, pero nunca reducirlo (40010001001), y cambiarserieDCemientras la serie anterior sigue habilitada se rechaza (40010001001, pase por operaciones).
Habilitar NFS-e
La NFS-e se habilita con el bloque emissaoNFSe. Solo con él la empresa pasa a emitir NFS-e y obtiene su secuencia de numeración. Aquí solo van los datos que no cambian de una nota a otra: código de servicio, CNAE, NBS, alícuota de ISS, retención e IBS/CBS acompañan al servicio vendido y van en el bloque servico de cada emisión.
"emissaoNFSe": {"serieDps": "1","sequencialDps": 1,"regimeApuracaoSn": 1,"regimeEspecialTributacao": 0}
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
serieDps | string(1-5 dígitos) | No | Serie del DPS / RPS usada al emitir. Toda nota usa este valor; la emisión no acepta una serie propia. Sin este campo, 1 |
sequencialDps | integer | No | Número de la próxima nota a emitir, a partir de 1. Al migrar de otro emisor, envíe el mayor número ya usado más uno para que la numeración continúe donde quedó. Sin este campo, 1. Una vez creada la secuencia, la actualización no la modifica |
regimeApuracaoSn | integer | Obligatorio para ME/EPP | Cómo el Simples Nacional calcula el impuesto: 1 federal y municipal por el SN / 2 federal por el SN y municipal fijo / 3 federal por el SN y municipal normal. La adhesión al Simples viene de optanteSimplesNacional / mei del nivel superior. Enviarlo en una empresa fuera del Simples se rechaza |
regimeEspecialTributacao | integer | No | Si hay un tratamiento tributario especial: 0 ninguno / 1 acto cooperativo / 2 estimación / 3 microempresa municipal / 4 notarial y registral / 5 profesional autónomo / 6 sociedad de profesionales. Sin este campo, 0 |
- La respuesta del registro pasa a traer
nfseHabilitado:{ "empresaId": "…", "dceHabilitado": false, "nfseHabilitado": true }. Sin el bloque esfalsey la emisión devuelve10018005. - En la actualización (cuerpo con
id) enviar el bloque sustituye el perfil entero: los opcionales omitidos vuelven al valor por defecto; sin el bloque el perfil no cambia ynfseHabilitadorefleja el estado actual. Forzar el estándar municipal es una acción de operaciones y no pasa por este bloque. - Reglas estructurales rechazadas en la aceptación (400
10001001): ME/EPP sinregimeApuracaoSn, empresa fuera del Simples conregimeApuracaoSn. - Una empresa solo de NFS-e puede omitir
emissaoNFeProduto(no se crea ninguna serie del modelo 55) y no necesitainscricaoEstadual. - La inscripción municipal (CCM) de São Paulo se toma del
inscricaoMunicipaldel nivel superior y no se repite en este bloque.
Códigos de error relacionados
| codigo | HTTP | Escenario | Acción |
|---|---|---|---|
10003002 | 400 | CNPJ ya registrado | La empresa existe: use el empresaId original o actualice con id |
10003000 | 404 | empresaId no existe o no pertenece a esta aplicación | Verifique el empresaId |
10003006 | 400 | Datos de registro sin la IE | Informe inscricaoEstadual |
10003010 / 10003011 / 10003012 | 400 | CNPJ del certificado discrepante / expirado / idéntico al actual | Use el certificado correcto |
10003035 | 400 | Base64 inválido o certificado mayor de 1MB (forma JSON) | Corrija la codificación o el archivo |
10003008 | 400 | La contraseña del certificado no coincide | Verifique la contraseña |
10003004 | 400 | Registro: ciudad / estado no se resuelven a un código IBGE | Verifique la UF y el nombre de la ciudad |
10004004 | 400 | Empresa no apta para emitir (aún no aprobada o certificado no listo) | Espere la aprobación / vincule el certificado |
10004030 | 400 | ambienteEmissao distinto del entorno actual de la empresa | Envíe en el entorno de la empresa o pida a operaciones que lo cambie |
10001001 | 400 | Falló la validación de campos, o error de contrato de registro / actualización (los tres bloques de configuración ausentes, actualización cambiando cnpj / municipio, reducción del cursor de la serie DC-e, cambio de serie, reglas estructurales de emissaoNFSe no cumplidas) | Corrija según mensagem |
La lista completa está en Códigos de error.
