Empresa
Onboarding, certificado A1, CSC e logomarca.
O recurso de Empresa (Tenant Emissor) centraliza as configurações fiscais, o Certificado Digital A1, a logomarca do DANFE e as credenciais de emissão vinculadas a um CNPJ. Ao cadastrar uma empresa, a NFER provisiona automaticamente a chave de API (X-API-Key), as séries fiscais iniciais e os perfis tributários padrão de acordo com o CRT informado.
Cada empresa cadastrada opera de forma independente com suas próprias sequências numéricas, certificados e webhooks.
Certificados digitais .PFX são armazenados com criptografia de ponta a ponta e monitorados preventivamente para alertar antes do vencimento.
1. Endpoints de Gerenciamento
Principais operações para gerenciamento de estabelecimentos emissores e credenciais:
| Operação | Método e Rota | Referência Técnica |
|---|---|---|
| Cadastrar Empresa Emissora | POST /v1/companies | Ver Parâmetros & Presets → |
| Consultar Dados da Empresa | GET /v1/companies/:id | Ver Retorno Completo → |
| Atualizar Configurações & CRT | PUT /v1/companies/:id | Ver Campos Editáveis → |
| Upload de Certificado Digital A1 | POST /v1/companies/:id/certificate | Ver Envio Multipart → |
| Status e Validade do Certificado | GET /v1/companies/:id/certificate/status | Ver Dias Restantes → |
| Configurar Sequência Inicial | POST /v1/companies/:id/nfe-sequence | Ver Séries e Contadores → |
| Listar Séries Fiscais Ativas | GET /v1/companies/:id/nfe-sequences | Ver Listagem → |
| Upload de Logomarca (DANFE) | POST /v1/companies/:id/logo | Ver Envio da Imagem → |
| Rotacionar Chave de API | POST /v1/companies/:id/api-key/rotate | Ver Rotação de Chave → |
2. Cadastrando uma Nova Empresa
Envie o CNPJ, razão social, regime tributário (CRT) e o endereço fiscal completo com o código IBGE do município (cMun). A criação de empresas é uma operação do Core da sua organização e exige obrigatoriamente a chave mestre (X-Org-Key).
Parâmetros do Payload
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
cnpj | string | Sim | CNPJ com 14 dígitos (apenas números). |
razaoSocial | string | Sim | Razão social oficial registrada na Receita Federal. |
crt | number | Sim | Regime Tributário: 1 (Simples Nacional), 2 (Simples sublimite), 3 (Regime Normal), 4 (MEI). |
endereco | object | Sim | Objeto fiscal com logradouro, numero, bairro, cMun (IBGE 7 dígitos), xMun, UF e CEP. |
ie | string | Não | Inscrição Estadual (obrigatória para emissão de NF-e e NFC-e se contribuinte de ICMS). |
im | string | Não | Inscrição Municipal (obrigatória para prestadores de serviços que emitem NFS-e). |
tipo_unidade | string | Não | Classificação do estabelecimento: "matriz" ou "filial". |
environment | string | Não | Ambiente inicial: "homologacao" (padrão de testes) ou "producao". |
email_atendimento | string | Não | E-mail para envio de cópias fiscais e XMLs aos clientes. |
3. Upload do Certificado Digital A1
O certificado digital A1 (.pfx ou .p12) é obrigatório para assinar digitalmente os XMLs e estabelecer a conexão TLS mútua com a SEFAZ. O envio pode ser feito via formulário multipart/form-data com o arquivo binário e a senha de proteção:
4. Configurações por Tipo de Documento Fiscal
Cada modelo fiscal possui particularidades regulatórias e parâmetros operacionais próprios na SEFAZ e nas Prefeituras. Você pode pré-configurá-los no momento do cadastro ou atualizá-los a qualquer momento via PUT /v1/companies/:id conforme a necessidade do seu negócio:
Exige Inscrição Estadual (IE) ativa perante a SEFAZ de origem. Permite definir o layout de impressão do DANFE (folha A4 completa ou bobina térmica contínua de 80mm conforme a NT 2026.003), textos fixos de interesse do Fisco, mensagens complementares e autorização de download de XML por parceiros contábeis e operadores logísticos:
| Campo | Tipo | Descrição e Aplicação Prática |
|---|---|---|
nfeDanfeFormat | string | Modelo do DANFE: "a4" (folha inteira tradicional para operações B2B e transportadoras) ou "simplificado_tipo2" (bobina térmica 80mm para PDV e expedição de e-commerce conforme NT 2026.003). |
nfeMensagemPadrao | string | Mensagem promocional do contribuinte (até 500 caracteres). Inserida automaticamente no campo infCpl do XML e impressa no rodapé da bobina térmica logo após os tributos da Lei 12.741/2012. |
dados_cadastrais.aut_xml | string[] | Pessoas autorizadas a baixar o XML diretamente na SEFAZ Nacional via web service. Cadastre até 10 CPFs ou CNPJs (escritório contábil, transportadora ou fulfillment). |
dados_cadastrais.intermediador | object | Dados do intermediador da operação / marketplace (tag intermediador no XML). Obrigatório para vendas intermediadas por plataformas terceiras (CNPJ e idCadIntTran). |
Exige Inscrição Estadual (IE) e o CSC (Código de Segurança do Contribuinte) cadastrado no portal da SEFAZ estadual. O CSC e o identificador do token (cIdToken) são indispensáveis para gerar o QR Code de autenticidade impresso no cupom e consultado pelo consumidor:
| Campo | Tipo | Descrição e Aplicação Prática |
|---|---|---|
nfceIdCsc | integer | Identificador do CSC cadastrado na SEFAZ (campo cIdToken do QR Code, geralmente 1 ou 2). |
nfceTokenCsc | string | Código Hash/Token do CSC fornecido pela SEFAZ estadual para assinar criptograficamente a URL do QR Code. |
nfceExibirLogo | boolean | Define se a logomarca da empresa deve ser impressa centralizada no topo do cupom térmico (padrão: true). |
nfceMensagemPadrao | string | Mensagem promocional ou institucional no rodapé do cupom (inserida em infCpl e impressa na bobina térmica). |
Exige Inscrição Municipal (IM) ativa. A NFER realiza a emissão via Ambiente de Dados Nacional (ADN / SEFIN), obrigatório para MEI em todas as 5.571 cidades do país e unificado para ME/EPP do Simples Nacional via Resolução CGSN nº 191/2026. Para municípios com integração dedicada (ex: Web Service próprio de Barueri - SP / IBGE 3505708), a NFER direciona a transmissão de forma transparente:
| Campo | Tipo | Descrição e Aplicação Prática |
|---|---|---|
im | string | Inscrição Municipal da empresa ativa na Prefeitura da sede (indispensável para autorização de notas de serviço). |
defaultCtribNac | string | Código de Tributação Nacional padrão de 6 dígitos da LC 116/2003 (ex: "010501" para suporte técnico e informática). |
cnaePrincipal | string | CNAE fiscal principal de 7 dígitos da prestação de serviços da empresa (ex: "6201501"). |
dados_cadastrais.dps_serie / dps_numero | integer | Série e próximo número sequencial da Declaração de Prestação de Serviços (DPS) perante o Ambiente Nacional da SEFIN. |
Exige Inscrição Estadual (IE) e registro ativo na Agência Nacional de Transportes Terrestres (RNTRC) para transportadoras rodoviárias de carga. Permite definir a modalidade operacional do CT-e (incluindo o CT-e Simplificado da NT 2024.002), o formato do DACTE e a sincronização contínua de fretes via Monitor Fiscal:
| Campo | Tipo | Descrição e Aplicação Prática |
|---|---|---|
rntrc | string | Registro Nacional de Transportadores Rodoviários de Cargas na ANTT (até 8 dígitos numéricos). |
dados_cadastrais.cte_modalidade_padrao | string | Modalidade padrão: "normal" (Modelo 57 tradicional de 1 remetente para 1 destinatário), "simplificado" (NT 2024.002 para agrupar coletas/entregas com mesmo tomador do frete) ou "os" (Modelo 67 para fretamento e passageiros). |
dados_cadastrais.cte_dacte_layout | string | Layout do DACTE em PDF: "padrao" (folha A4 completa com componentes de pedágio e frete) ou "simplificado" (layout compacto para fiscalização rápida em barreiras). |
dados_cadastrais.auto_sync_cte | boolean | Ativa o Monitor Fiscal na SEFAZ Nacional para detecção e captura automática de fretes (CT-e) onde sua empresa é tomadora, remetente ou destinatária. |
Obrigatório no transporte rodoviário interestadual e intermunicipal com múltiplos documentos fiscais vinculados (CT-e ou NF-e) ou cargas lotação (conforme a NT 2025.001). Transmitido via SEFAZ Virtual RS (SVRS), vincula veículos de tração, reboques, condutores habilitados e exige evento de encerramento fiscal no destino:
| Campo | Tipo | Descrição e Aplicação Prática |
|---|---|---|
modules_status.mdfe | boolean | Habilita o módulo de emissão de Manifesto de Cargas (Modelo 58) para o CNPJ da empresa. |
dados_cadastrais.auto_sync_mdfe | boolean | Ativa o Monitor Fiscal contínuo para captura automática de MDF-e emitidos com destino às suas filiais ou vinculados ao seu CNPJ na SEFAZ SVRS. |
Criada sob o Ajuste SINIEF para substituir a declaração física de papel em encomendas enviadas pelos Correios e transportadoras parceiras. Destinada a pessoas jurídicas e MEIs não contribuintes de ICMS (sem Inscrição Estadual ativa). O Fisco autoriza a declaração e gera o DACE com chave de 44 dígitos e QR Code para impressão e afixação na embalagem:
| Campo | Tipo | Descrição e Aplicação Prática |
|---|---|---|
dcePrintFormat | string | Modelo de impressão do DACE: "completo" (folha A4 tradicional com grade detalhada de itens) ou "resumido" (etiqueta térmica 100x150mm conforme Seção 2.5 do MOC DC-e para impressoras térmicas). |
modules_status.dce | boolean | Ativa o emissor de Declaração de Conteúdo Eletrônica para despachos postais sem nota fiscal de mercadoria. |
5. Ativação Modular de Emissores (modules_status)
Permite ligar ou desligar individualmente cada tipo de documento fiscal suportado pelo NFER para a empresa. Isso impede que estabelecimentos focados apenas em serviços ou apenas em varejo façam emissões inadvertidas de outros modelos:
6. Responsável Técnico & CSRT (infRespTec — White-Label & ERPs)
Para parceiros, ERPs e Software Houses, configure os dados do seu sistema e chave CSRT para os estados que exigem a identificação da empresa desenvolvedora de software emissor (PR, AM, MS, PE, SC, TO, etc.):
7. Sequência Numérica e Migração de Emissor
Se a empresa já emitia documentos em outro sistema (ERP legado ou emissor gratuito da SEFAZ), configure o último número emitido via POST /v1/companies/:id/nfe-sequence. A NFER assumirá a próxima numeração automaticamente (lastNumero + 1), prevenindo rejeições por duplicidade (Rejeições 204/539) ou salto indevido de numeração (Rejeição 502) na SEFAZ:
| Código do Modelo | Documento Fiscal | Regra de Sequência |
|---|---|---|
| "55" | NF-e (Nota Fiscal Eletrônica) | Série independente por ambiente (homologação e produção). Padrão para novos emissores: Série 1, lastNumero: 0. |
| "65" | NFC-e (Nota de Consumidor) | Contador independente por série. Se migrando de PDV físico, informe o último cupom emitido no sistema anterior. |
| "57" | CT-e (Conhecimento de Transporte) | Série rodoviária ou simplificada com numeração sequencial contínua mantida pela SEFAZ de origem. |
| "58" | MDF-e (Manifesto de Cargas) | Sequência de manifestos gerida na SEFAZ SVRS por ambiente. |
8. Logomarca do DANFE
Personalize a impressão das suas notas fiscais enviando a imagem da logomarca da sua empresa (PNG, JPEG ou WebP). A NFER renderizará a logo automaticamente no cabeçalho do DANFE da NF-e e NFC-e.
9. Virada para Produção (Go-Live)
Após testar o fluxo de emissão em ambiente de homologação, altere o campo environment para "producao". A partir deste momento, todas as notas fiscais transmitidas passarão a ter validade jurídica oficial junto à SEFAZ.
10. Segurança e Rotação de API Key
Caso sua chave de API seja exposta ou precise ser renovada periodicamente por políticas de segurança, utilize o endpoint de rotação. A chave anterior deixa de funcionar instantaneamente: