Consultas

Este método permite realizar a busca de documentos fiscais (NF-e, NFC-e, CT-e, NFS-e, entre outros) dentro de um período específico. A consulta pode ser filtrada por tipo de documento (entradas ou saídas) e, no caso de documentos de saída, também é possível pesquisar por um identificador interno associado.

O que este método faz?

Ele consulta a base de documentos fiscais da empresa e retorna uma lista consolidada contendo as principais informações de cada documento encontrado no intervalo informado.

Filtros disponíveis

• Período, Data inicial e final para busca.
• Tipo de documento, Entradas ou saídas.
• Identificador interno (opcional, apenas para saídas).

O que é retornado?

O método retorna uma lista de documentos, cada item contendo informações essenciais, como:

• Tipo do documento (NF-e, NFC-e, NFS-e, etc.).
• Número, série e chave.
• Emitente e destinatário.
• Datas relevantes.
• Valores principais.
• Situação atual (autorizado, cancelado, denegado, etc.).

Quando usar?

Utilize este endpoint para:

• Consultar documentos emitidos ou recebidos em um intervalo.
• Gerar relatórios internos.
• Cruzamento de informações fiscais.
• Auditoria e conferência de movimentações.

Nota: A quantidade e o nível de detalhes retornados podem variar conforme o tipo de documento e o ambiente de origem.

Consulta o estado de processamento de um lote de NF-e ou NFC-e transmitido via /EnviarNotaFiscalLote, identificado pelo CodLote retornado naquele endpoint.

Por que existe

O /EnviarNotaFiscalLote é assíncrono — a resposta HTTP apenas confirma o aceite do lote, e o resultado real chega no webhook nfe.lote.finalizado. Este endpoint serve como fallback de polling quando:

• O cliente ainda não configurou um webhook ativo (o lote continua sendo processado, mas não há notificação).
• O cliente perdeu o disparo do webhook (todas as 5 tentativas falharam) e precisa recuperar o estado.
• É necessário inspecionar o status do lote em uma interface de operação, sem depender da chegada do webhook.

Para fluxos com webhook configurado e estável, prefira esperar o disparo — evita polling desnecessário.

O que retorna

• O status agregado do lote (1–5), com a descrição textual em DsStatusLote.
• As contagens de QtdTotal, QtdEmitida (autorizadas) e QtdErro (rejeitadas).
• O detalhe de cada nota em Notas[], com a chave de acesso (quando autorizada), o código/descrição do status SEFAZ e os totais — mesmo schema retornado por /EnviarNotaFiscal.
• Em caso de falha no processamento do lote, a mensagem aparece em erros[].descricao.

Escopo

• Apenas lotes de NF-e (modelo 55) ou NFC-e (modelo 65). Lotes de outros modelos não retornam por aqui.
• O lote precisa pertencer à empresa identificada pelo header Token. Lotes de outras empresas retornam Lote não encontrado mesmo que o CodLote exista.

Próximos passos

Este endpoint não retorna o XML nem o DANFE. Para baixar arquivos das notas autorizadas, use /ObterArquivoNotaFiscal passando a ChaveNF de cada item de Notas[].

Este método permite obter o arquivo de um documento fiscal, seja ele de entrada ou de saída. É possível solicitar tanto o XML original quanto a representação gráfica do documento, como DANFE (NF-e), DANFCE (NFC-e) ou DACTE (CT-e).

O que este método faz?

Ele recupera o arquivo correspondente à chave do documento informado ou, quando aplicável, consolida vários documentos em um único PDF.

Formas de consulta

• Chave única, Retorna o XML ou a representação gráfica do documento solicitado.
• Múltiplas chaves, Permite gerar um PDF unificado contendo diversos documentos, ideal para auditorias, armazenamento ou envios em lote.

Tipos de documentos suportados

• NF-e, XML original ou DANFE.
• NFC-e, XML ou DANFCE.
• CT-e, XML ou DACTE.
• Outros documentos, conforme disponibilidade na base.

Quando usar?

Este método é útil para:

• Recuperar documentos fiscais armazenados.
• Gerar PDFs consolidados para envio a clientes ou contabilidade.
• Baixar o XML oficial para validação, auditoria ou integração.
• Obter a versão gráfica para impressão ou visualização.

O que é retornado?

Dependendo da solicitação, a resposta pode incluir:

• O XML original do documento.
• O PDF individual da representação gráfica.
• Um PDF consolidado contendo vários documentos.

Nota: Para múltiplos documentos, o PDF unificado é retornado somente quando todos os documentos solicitados existirem na base.

Este método permite obter o arquivo de um evento específico associado a um documento fiscal, como uma Carta de Correção Eletrônica (CC-e).

A consulta é realizada utilizando dois identificadores principais:

• A chave do documento fiscal original (NF-e, CT-e, etc.).
• O protocolo do evento, que identifica de forma única o evento registrado na SEFAZ.

O que este método faz?

Ele recupera o arquivo correspondente ao evento informado, retornando:

• O XML do evento.
• A representação gráfica em PDF, quando disponível (ex.: CC-e, Cancelamento).

Quando usar?

Utilize este endpoint quando for necessário:

• Baixar a Carta de Correção enviada previamente.
• Recuperar qualquer evento associado ao documento para conferência.
• Gerar arquivos para contabilidade ou validações.

O que é retornado?

O método pode retornar:

• XML do evento.
• PDF da representação gráfica do evento.

Nota: É necessário fornecer tanto a chave do documento original quanto o protocolo do evento para garantir a identificação correta do registro na SEFAZ.

Este método oferece um endpoint robusto para download em lote de documentos fiscais, permitindo obter arquivos em formato XML, PDF ou Excel conforme a necessidade da aplicação.

O pacote retornado pode incluir NF-e, NFC-e, NFS-e, CT-e, CT-e OS, MDF-e e DC-e, abrangendo tanto notas de saída (emitidas pela empresa) quanto notas de entrada/tomadas (recebidas de terceiros) - basta ajustar o filtro de tipo para retornar saídas, entradas ou ambos.

A consulta pode ser filtrada por diversos critérios, garantindo alta flexibilidade na extração dos documentos.

Filtros disponíveis

• Período, Data inicial e final da busca.
• Ambiente, Produção ou homologação.
• Tipo de documento, Saída, entrada ou ambos.
• CPFs/CNPJs específicos, Ideal para buscas direcionadas a clientes ou fornecedores.

O que este método faz?

Ele processa a busca dos documentos conforme os filtros enviados e gera um pacote consolidado contendo todos os arquivos encontrados.

Quando usar?

Este endpoint é ideal para:

• Extração fiscal em larga escala.
• Geração de relatórios periódicos.
• Auditorias e conferências contábeis.
• Processos de backup e armazenamento externo.
• Integrações que exigem recuperação rápida de múltiplos documentos.

Benefícios

• Alta performance para grandes volumes.
• Flexibilidade de filtros.
• Retorno consolidado em formato compacto.
• Padronização dos arquivos para múltiplos tipos de documentos.

Nota: O tamanho final do arquivo .zip pode variar conforme o volume de documentos retornados. Certifique-se de que o ambiente consumidor consiga manipular corretamente cadeias Base64 extensas.

Este método realiza uma consulta ao Cadastro Centralizado de Contribuintes (CCC) da SEFAZ, permitindo verificar a situação cadastral de um contribuinte, pessoa física ou jurídica, em uma determinada Unidade Federativa.

A consulta pode ser realizada por CNPJ, CPF ou Inscrição Estadual (IE), oferecendo flexibilidade para validar informações fiscais de clientes, fornecedores ou parceiros comerciais.

Para que serve a consulta ao CCC?

Este endpoint é útil para:

• Verificar se o contribuinte está ativo, inapto, suspenso ou baixado.
• Confirmar dados cadastrais antes de emitir documentos fiscais.
• Evitar rejeições por irregularidades no cadastro do destinatário.
• Realizar auditorias e análises de conformidade fiscal.

O que é retornado?

A resposta pode incluir:

• Situação cadastral do contribuinte.
• UF de registro.
• Dados básicos associados ao CNPJ, CPF ou IE.
• Mensagens adicionais fornecidas pela SEFAZ.

Quando usar este método?

Utilize a consulta ao CCC sempre que for necessário garantir que:

• O destinatário esteja regular no cadastro estadual.
• A operação fiscal não será rejeitada por situação cadastral inválida.
• A empresa mantenha conformidade com as regras fiscais vigentes.

Nota: Nem todas as UFs possuem o mesmo grau de detalhamento no CCC. As informações retornadas podem variar conforme o estado consultado.

Este método verifica o status operacional dos serviços da SEFAZ (Secretaria da Fazenda) para um determinado modelo de documento fiscal e ambiente (produção ou homologação).

A consulta de status é essencial para identificar se os serviços da SEFAZ estão disponíveis, instáveis ou inoperantes antes de realizar transmissões de NF-e, NFC-e, MDF-e, CT-e e outros documentos.

Para que serve?

Este endpoint é útil para:

• Confirmar se os serviços da SEFAZ estão funcionando normalmente.
• Evitar tentativas de emissão durante períodos de indisponibilidade.
• Monitorar a estabilidade dos ambientes fiscais.
• Implementar rotinas automáticas de verificação antes de transmissões em massa.

O que é retornado?

A resposta geralmente inclui:

• Status do servidor (operante, instável ou indisponível).
• Motivo informado pela SEFAZ.
• Data e hora da última verificação.
• Informações complementares fornecidas pelo ambiente autorizador.

Quando usar este método?

Use este endpoint antes de:

• Emitir notas fiscais.
• Transmitir manifestos.
• Enviar documentos em lote.
• Inicializar rotinas automáticas de emissão.

Nota: A disponibilidade dos serviços da SEFAZ pode variar por UF e por modelo de documento, sendo recomendado consultar regularmente em sistemas que operam de forma contínua.