Brasil NFe - API 2.0

Operações de emissão e pré-visualização de NF-e e NFC-e. A NF-e (Nota Fiscal Eletrônica, modelo 55) é o documento fiscal digital utilizado em operações entre empresas ou com consumidor final quando há circulação de mercadorias, substituindo a nota fiscal em papel. A NFC-e (Nota Fiscal de Consumidor Eletrônica, modelo 65) é voltada ao comércio varejista e às operações com consumidor final não contribuinte, substituindo o cupom fiscal e a NF modelo 2.

O que esta seção cobre

• Transmissão da NF-e/NFC-e para a SEFAZ - o XML é validado, assinado digitalmente e enviado ao ambiente autorizador, que retorna autorizado, rejeitado ou denegado.
• Pré-visualização do documento antes do envio oficial, útil para conferência visual e homologação.

Resultados possíveis da transmissão

• Autorizado – a nota foi validada e aceita pela SEFAZ.
• Rejeitado – alguma regra de validação foi violada (XML inválido, CFOP incorreto, dados inconsistentes, etc.).
• Denegado – a operação não pode ser realizada devido a irregularidades cadastrais do emitente ou destinatário.

Nota: Os eventos da NF-e/NFC-e (carta de correção, cancelamento, manifestação do destinatário e inutilização de numeração) ficam agrupados na seção Eventos NF-e / NFC-e.

Eventos vinculados a uma NF-e ou NFC-e já autorizada. Cada evento é um registro legal que altera, complementa ou anula o documento fiscal original, sem substituí-lo.

Eventos disponíveis

• Carta de Correção (CC-e) – corrige erros formais da NF-e já emitida (ex.: descrição de mercadoria, códigos sem impacto fiscal). Não pode ser usada para alterar valores fiscais, partes envolvidas, datas ou número/série.
• Cancelamento – anula uma NF-e/NFC-e já autorizada, dentro do prazo legal e antes da circulação da mercadoria. Prazo de 24 horas para NF-e e 30 minutos para NFC-e após a autorização.
• Manifestação do Destinatário – permite ao destinatário confirmar, negar ou controlar a participação em uma NF-e emitida contra seu CNPJ, auxiliando no controle de fornecedores e evitando uso indevido.
• Inutilização de Numeração – comunica à SEFAZ números de NF-e que não serão utilizados, corrigindo quebras na sequência. Só pode ser usada para números nunca emitidos (não autorizados, cancelados ou denegados).

Atenção

Cada evento possui regras próprias - prazos, restrições de uso e requisitos específicos. Consulte a descrição de cada endpoint antes de utilizá-lo. Eventos expirados podem exigir alternativas como NF-e de devolução ou cancelamento extemporâneo, conforme a UF.

A NFS-e (Nota Fiscal de Serviços Eletrônica) é o documento fiscal digital utilizado para registrar a prestação de serviços e é de responsabilidade das prefeituras municipais. Diferentemente de outros documentos fiscais brasileiros - centralizados na SEFAZ - cada município adota seu próprio provedor (sistema, layout e regras), o que torna a emissão heterogênea entre cidades.

Particularidades

• Provedores múltiplos – cada prefeitura define o layout e o padrão de integração (ex.: Abrasf, Ginfes, ISS.net, Tinus, entre outros).
• Processamento síncrono ou assíncrono – algumas prefeituras autorizam no ato da transmissão; outras retornam apenas um número de lote, que precisa ser consultado posteriormente.
• Regras próprias de cancelamento – prazos, justificativas obrigatórias e até a exigência de NFS-e substituta variam por município.

O que esta seção cobre

• Transmissão da NFS-e para o provedor municipal.
• Consulta de status do lote (essencial em prefeituras assíncronas).
• Cancelamento da NFS-e já emitida, seguindo as regras do município.

Status de retorno mais comuns

• Status 2 – Em processamento: a prefeitura ainda não concluiu a análise.
• Processado com sucesso: NFS-e gerada e disponível para consulta ou download.
• Erro ou rejeição: a resposta indicará o motivo para correção.

Nota: Consulte sempre a documentação do provedor municipal do seu destino - comportamento, campos obrigatórios e prazos podem divergir entre cidades.

O MDF-e (Manifesto Eletrônico de Documentos Fiscais, modelo 58) é o documento fiscal digital utilizado para unificar, registrar e acompanhar o transporte de cargas no Brasil. Ele consolida diversos documentos fiscais - como NF-e e CT-e - em um único manifesto, facilitando o controle do transporte pelos órgãos fiscais e reduzindo a necessidade de documentos impressos.

Quem emite

O MDF-e é obrigatório para a maioria das operações de transporte de cargas interestaduais e para empresas que atuam como:

• Transportadoras – no transporte de cargas de terceiros.
• Embarcadores ou proprietárias de frotas – no transporte de cargas próprias.

Ciclo de vida do MDF-e

1. Transmissão – envio e autorização do manifesto pela SEFAZ.
2. Cancelamento – possível apenas se o transporte ainda não foi iniciado e dentro de 24 horas da autorização.
3. Encerramento – obrigatório ao final da viagem para registrar a conclusão do percurso, liberando emissão de novos MDF-e para o mesmo veículo/UF.

Nota: Cancelamento e encerramento são operações distintas. Use cancelamento apenas quando a viagem não ocorreu e está dentro do prazo legal; use encerramento quando o transporte foi concluído.

O CT-e (Conhecimento de Transporte Eletrônico, modelo 57) é o documento fiscal digital que registra a prestação de serviço de transporte de cargas e substitui os conhecimentos de transporte em papel - rodoviário, aéreo, aquaviário, ferroviário e dutoviário. Ele formaliza a relação entre remetente, destinatário, tomador do serviço e transportador, incluindo valores, cargas transportadas, modal e documentos fiscais vinculados (NF-e, por exemplo).

Participantes

• Remetente – quem entrega a mercadoria ao transportador.
• Destinatário – quem recebe a mercadoria no destino final.
• Tomador – quem contrata e paga o serviço de transporte.
• Transportador – quem executa o transporte e emite o CT-e.

O que esta seção cobre

• Transmissão do CT-e para a SEFAZ.
• Cancelamento do CT-e dentro do prazo legal.

Resultados possíveis da transmissão

• Autorizado – o CT-e foi validado e aceito pela SEFAZ.
• Rejeitado – alguma regra de validação foi violada (XML inválido, CFOP incorreto, dados divergentes, etc.).
• Denegado – o documento não pode ser emitido devido a irregularidades cadastrais do emitente, remetente, destinatário ou tomador.

Nota: O CT-e é obrigatório para a maioria das operações de transporte de cargas no Brasil, tanto intermunicipais quanto interestaduais.

A DC-e (Declaração de Conteúdo Eletrônica) é o documento fiscal eletrônico utilizado para declarar o conteúdo de encomendas e pacotes que não possuem nota fiscal vinculada. Ela é obrigatória para transportadoras, marketplaces e emissores próprios que movimentam mercadorias sem documentação fiscal de origem.

Casos de uso

• Transportadoras que movimentam mercadorias de terceiros sem NF-e.
• Marketplaces que intermediam vendas entre pessoas físicas.
• Envios via Correios ou serviço de entrega próprio.
• Pessoas físicas enviando mercadorias para outras pessoas físicas.

Participantes

• Remetente – pessoa física ou jurídica que envia o pacote.
• Destinatário – pessoa física ou jurídica que recebe o pacote.

Tipos de emitente

• App Fisco (0) – aplicativo disponibilizado pelo fisco.
• Marketplace (1) – plataforma de intermediação (requer informar a URL do site).
• Emissor próprio (2) – sistema próprio do contribuinte.
• Transportadora (3) – empresa de transporte (padrão).

Modalidades de transporte

• Correios (0) – envio pelos Correios.
• Conta própria (1) – entrega realizada pelo próprio remetente.
• Transportadora (2) – serviço de transporte terceirizado (padrão).

Resultados possíveis da transmissão

• Autorizado – a DC-e foi validada e aceita pela SEFAZ.
• Rejeitado – alguma regra de validação foi violada (dados incompletos, CPF/CNPJ inválido, valores inconsistentes, etc.).

Endpoints destinados à consulta de informações e documentos fiscais já processados pela API - NF-e, NFC-e, NFS-e, CT-e, MDF-e e demais documentos suportados.

O que esta seção cobre

• Listagem de documentos fiscais emitidos ou recebidos por período, com filtros por tipo (entradas/saídas) e identificador interno.
• Download do XML original e das representações gráficas (DANFE para NF-e, DANFCE para NFC-e, DACTE para CT-e).
• PDF consolidado reunindo múltiplos documentos em um único arquivo - ideal para auditorias e envios em lote.
• Download de arquivos de evento (carta de correção, cancelamento, manifestação, etc.) associados a um documento.
• Consulta por período para obter todos os arquivos XML de um intervalo.
• Consulta ao cadastro de contribuintes diretamente na SEFAZ.
• Status dos serviços da SEFAZ em cada UF, para diagnosticar indisponibilidades.

Casos de uso típicos

• Geração de relatórios fiscais internos.
• Auditoria e conciliação de movimentações.
• Download em lote para contabilidade.
• Integração de dados fiscais com o ERP.
• Monitoramento operacional da SEFAZ antes de transmitir.

Nota: O nível de detalhe retornado pode variar conforme o tipo de documento e o ambiente (homologação/produção).

Operações relacionadas ao SPED (Sistema Público de Escrituração Digital), ao SINTEGRA e ao FCI.

O que é o SPED

O SPED é um conjunto de obrigações acessórias eletrônicas utilizadas para padronizar, validar e transmitir informações fiscais das empresas aos órgãos governamentais, substituindo escriturações em papel. A API é capaz de gerar automaticamente:

• SPED ICMS/IPI (EFD ICMS/IPI) – reúne operações e prestações que influenciam na apuração do ICMS e do IPI, incluindo entradas, saídas, inventário, apurações e ajustes fiscais.
• SPED PIS/COFINS (EFD Contribuições) – consolida operações relacionadas às contribuições de PIS e COFINS, abrangendo documentos fiscais, créditos, débitos e bases de cálculo.

O que é o SINTEGRA

O SINTEGRA (Sistema Integrado de Informações sobre Operações Interestaduais com Mercadorias e Serviços) é um arquivo magnético exigido por algumas UFs para informar operações de entrada e saída de mercadorias.

O que é o FCI

A FCI (Ficha de Conteúdo de Importação) é uma declaração obrigatória para mercadorias industrializadas com insumos importados, informando o percentual de conteúdo de importação utilizado na produção.

Fluxo assíncrono

A geração de arquivos SPED é assíncrona: o endpoint de geração retorna um código de processamento, que deve ser consultado posteriormente em outro endpoint para obter o arquivo finalizado. Isso permite processar grandes volumes sem bloquear a chamada original.

O que esta seção cobre

• Geração de arquivos SPED (ICMS/IPI e PIS/COFINS).
• Unificação de múltiplos arquivos SPED PIS/COFINS em um único arquivo.
• Recriação de arquivos SPED a partir de geração anterior.
• Download do arquivo SPED gerado.
• Geração de arquivo SINTEGRA.
• Geração de arquivo FCI.

Nota: O tempo de geração varia conforme o volume de documentos do período. A consulta posterior usando o código de processamento é obrigatória para recuperar o arquivo final.

Emissão de notas fiscais dos modelos 06, 21 e 22, destinadas a prestadores de serviços cujas atividades se enquadram nos segmentos de energia elétrica, comunicação ou telecomunicação.

Modelos suportados

• Modelo 06 – Nota Fiscal/Conta de Energia Elétrica. Utilizada por distribuidoras de energia para registrar consumo, tarifas, tributos e informações relacionadas ao fornecimento.
• Modelo 21 – Nota Fiscal de Serviço de Comunicação. Utilizada por provedores de internet, rádio, TV, serviços multimídia, transmissão de anúncios, entre outros.
• Modelo 22 – Nota Fiscal de Serviço de Telecomunicação. Utilizada por empresas de telefonia fixa ou móvel, VoIP, serviços de voz, dados e outros meios de transmissão de sinal.

Fluxo de emissão

1. Transmissão individual ou em lote das notas - ficam armazenadas internamente.
2. Geração do arquivo magnético consolidado do período.
3. Validação externa do arquivo no validador oficial da SEFAZ, que realiza a transmissão final ao ambiente fiscal da UF.

Formas de envio

• Individual – uma nota por requisição, ideal para fluxo contínuo.
• Lote – múltiplas notas por requisição, ideal para integrações periódicas.

Nota: A transmissão oficial à SEFAZ não é feita pela API - ela apenas gera o arquivo magnético, que deve ser processado pelo validador oficial. O validador pode ser obtido em: https://portal.fazenda.sp.gov.br/servicos/nf-comunicacao-energia/Paginas/Downloads.aspx

Métodos responsáveis por definir e gerenciar configurações essenciais das empresas cadastradas na plataforma. Cada empresa possui configurações individuais que podem ser alteradas tanto pelo painel quanto pelo webservice, e tais informações são de total responsabilidade do usuário. Essas configurações impactam diretamente o funcionamento de diversos serviços, como:

• Emissão de documentos fiscais (NF-e, NFC-e, CT-e, MDF-e, NFS-e, DC-e).
• Geração de SPED, SINTEGRA e arquivos magnéticos.
• Armazenamento, consultas, eventos e operações diversas.
• Vinculação e validação de certificados digitais.

Cabeçalhos obrigatórios

Para utilizar os métodos desta seção, envie os seguintes HTTP headers:

Code
-H "UserToken: token_usuario"
-H "Token: token_empresa"            // Obrigatório em todos os métodos exceto Adicionar e Buscar Todas
-H "Content-Type: application/json"

O UserToken identifica o usuário autenticado; o Token identifica qual empresa será manipulada pela operação. Adicionar e Buscar Todas dispensam o Token por não atuarem sobre uma empresa específica.

O que esta seção cobre

• Adicionar uma nova empresa à plataforma.
• Editar os dados de uma empresa existente.
• Buscar dados de uma ou de todas as empresas cadastradas.
• Alterar o certificado digital vinculado à empresa.
• Verificar o certificado digital cadastrado.
• Gerar link de ativação para liberar o uso da empresa.
• Consultar numeração atual de cada combinação modelo + série + ambiente.
• Atualizar numeração para alinhar contadores em migrações de ERP ou abrir novas séries.

Nota: As informações cadastradas são utilizadas em vários serviços fiscais. Mantenha-as sempre corretas e atualizadas para evitar rejeições ou falhas nas transmissões.