TF Fiscal
Documentación

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.

PasoEndpointNotas
1 Registrar empresaPOST /openapi/v2/empresasDevuelve empresaId, dceHabilitado y nfseHabilitado; un cuerpo con id actualiza una empresa existente
2 Vincular certificadoPOST /openapi/v1/empresas/{empresaId}/certificadoDigitalCertificado A1 (.pfx / .p12) y su contraseña; multipart o JSON + Base64
3 Registrar webhookPOST /openapi/v1/webhooksUna URL de callback por aplicación, compartida por todos los tipos de documento
4 Seguir el análisisGET /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 vezPOST /openapi/v2/empresas/cadastro-automaticoSolo 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

  1. 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 el empresaId original o envíe una actualización con id.
  2. 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 devuelve 10003008. Un envío exitoso reemplaza el certificado anterior.
  3. 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 10004004 para NF-e (10019004 para DC-e, 10017004 para CT-e). Siga la aprobación en Listar empresas o Consultar empresa: status Ativa significa aprobada y, con Rejeitada, el motivo viene en motivoStatus.
  4. Entorno: toda empresa tiene un entorno actual, pruebas Homologacao o producción Producao. 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 (ambienteEmissao para NF-e y CT-e, ambiente para DC-e) debe coincidir con el entorno actual de la empresa; una discrepancia devuelve 10004030 (NF-e), 10017010 (CT-e) o 10019010 (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 guarda inscricaoEstadual, 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 documentoModeloSerie configurada medianteCampo de entornoCódigo de no emisión
NF-e55emissaoNFeProduto.ambienteProducao (sequencialNFe / serieNFe) en el registro o en la actualización con idambienteEmissao10004004
CT-e57Configurada 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 10017007ambienteEmissao10017004
DC-e99emissaoDCe.ambienteProducao (tipoEmitente, sequencialDCe / serieDCe, siteMarketplace) en el registro o en una actualización con idambiente10019004
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 operacionesambienteEmissao10018004
  • emissaoNFeProduto, emissaoDCe y emissaoNFSe 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 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 400 10001001.
  • 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 id y emissaoNFeProduto: la serie se crea si no existe; si existe, el próximo número pasa a ser sequencialNFe, 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.

CRTNombre oficialQuién esoptanteSimplesNacional / mei en la consulta de la empresa
1Simples NacionalMicroempresa o pequeña empresa (ME / EPP) del Simples Nacionaltrue / false
2Simples Nacional – excesso de sublimite de receita brutaAdherida al Simples Nacional con ingresos por encima del sublímite estatal y municipaltrue / false
3Regime NormalEmpresa fuera del Simples Nacionalfalse / false
4Simples Nacional - Microempreendedor individual - MEIMicroemprendedor individualtrue / 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

meioptanteSimplesNacionalCRT guardado
falsefalse3 Regime Normal
falsetrue1 Simples Nacional
truetrue4 MEI
truefalse4 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 id no 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:

  1. En el registro, envíelas como Simples Nacional: optanteSimplesNacional=true y mei=false; la plataforma guarda CRT 1.
  2. En la consola, en «Datos tributarios», cambie el régimen a Simples Nacional (sobre el límite), es decir CRT 2.
  3. A partir de ahí la consulta de la empresa devuelve true / false, y reenviar true / false en una actualización con id no 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/COFINSParaPISCOFINS
AcumulativoLucro Presumido, Lucro Arbitrado0,65 %3,00 %
No acumulativoLucro Real1,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 referenciadaEmpresa con régimen de PIS/COFINSEmpresa sin régimen de PIS/COFINS
Con aliquotaDebe ser la alícuota legal de arriba; si no, rechazo 10005008Se usa el valor enviado
Sin aliquotaLa plataforma completa la alícuota legalRechazo 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:

json
"emissaoDCe": {
"ambienteProducao": {
"tipoEmitente": "Marketplace",
"sequencialDCe": 1,
"serieDCe": "1",
"siteMarketplace": "https://loja.exemplo.com.br"
}
}
  • tipoEmitente es Marketplace (una plataforma que emite en nombre de vendedores no contribuyentes / personas físicas) u OwnIssuer (una empresa que emite para sí misma). Carrier puede registrarse, pero la emisión se rechaza con 10019013. siteMarketplace es obligatorio para Marketplace.
  • Una empresa registrada sin emissaoDCe no queda habilitada para DC-e: el registro se acepta, la respuesta trae dceHabilitado=false y la emisión devuelve 10019012. Verifique ese campo justo después de registrar.
  • Para habilitar DC-e después, reenvíe el payload de registro con id y el bloque emissaoDCe. La serie del modelo 99 solo avanza: sequencialDCe puede elevar el próximo número, pero nunca reducirlo (400 10001001), y cambiar serieDCe mientras la serie anterior sigue habilitada se rechaza (400 10001001, 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.

json
"emissaoNFSe": {
"serieDps": "1",
"sequencialDps": 1,
"regimeApuracaoSn": 1,
"regimeEspecialTributacao": 0
}
CampoTipoObligatorioDescripción
serieDpsstring(1-5 dígitos)NoSerie del DPS / RPS usada al emitir. Toda nota usa este valor; la emisión no acepta una serie propia. Sin este campo, 1
sequencialDpsintegerNoNú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
regimeApuracaoSnintegerObligatorio para ME/EPPCó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
regimeEspecialTributacaointegerNoSi 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 es false y la emisión devuelve 10018005.
  • 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 y nfseHabilitado refleja 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 sin regimeApuracaoSn, empresa fuera del Simples con regimeApuracaoSn.
  • Una empresa solo de NFS-e puede omitir emissaoNFeProduto (no se crea ninguna serie del modelo 55) y no necesita inscricaoEstadual.
  • La inscripción municipal (CCM) de São Paulo se toma del inscricaoMunicipal del nivel superior y no se repite en este bloque.

Códigos de error relacionados

codigoHTTPEscenarioAcción
10003002400CNPJ ya registradoLa empresa existe: use el empresaId original o actualice con id
10003000404empresaId no existe o no pertenece a esta aplicaciónVerifique el empresaId
10003006400Datos de registro sin la IEInforme inscricaoEstadual
10003010 / 10003011 / 10003012400CNPJ del certificado discrepante / expirado / idéntico al actualUse el certificado correcto
10003035400Base64 inválido o certificado mayor de 1MB (forma JSON)Corrija la codificación o el archivo
10003008400La contraseña del certificado no coincideVerifique la contraseña
10003004400Registro: ciudad / estado no se resuelven a un código IBGEVerifique la UF y el nombre de la ciudad
10004004400Empresa no apta para emitir (aún no aprobada o certificado no listo)Espere la aprobación / vincule el certificado
10004030400ambienteEmissao distinto del entorno actual de la empresaEnvíe en el entorno de la empresa o pida a operaciones que lo cambie
10001001400Falló 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.