DocumentoFiscal
Controlador de Serviços de Documentos Fiscais da Stone Tax API.
Atua como uma camada de apoio e auditoria, fornecendo recursos para a gestão de artefatos
e rastreabilidade operacional de documentos fiscais eletrônicos (NF-e, NFC-e, NFS-e, etc).
Esta controller centraliza funcionalidades genéricas que permitem a extração de XMLs em massa
e a consulta ao histórico completo de eventos (como autorizações, cancelamentos e correções)
processados pela plataforma, garantindo conformidade técnica e fiscal.
Todos os recursos operam sob o contexto do Emissor informado no cabeçalho,
permitindo que o sistema consumidor monitore o ciclo de vida dos documentos e recupere dados históricos para fins contábeis.
Download de XMLs - Solicitar.
Inicia o processo de geração e recuperação de arquivos XML das notas fiscais de forma assíncrona.
Devido ao volume de dados, a requisição não retorna os arquivos imediatamente, mas sim um identificador de solicitação.
⚠️ ATENÇÃO: O ticket (ID) retornado deve ser utilizado posteriormente no endpoint de consulta de status para verificar se o pacote de arquivos já está disponível para download.
⚙️ PROCESSAMENTO: O tempo de geração pode variar conforme o intervalo de datas e a quantidade de documentos filtrados. Recomenda-se evitar solicitações com intervalos superiores a 30 dias para otimizar a performance.
📅 RESTRIÇÃO DE PERÍODO: O sistema processa solicitações com um intervalo máximo de 90 dias entre a data inicial e final. Solicitações que excedam este limite retornarão erro de validação.
📂 CONTEÚDO: O arquivo final será disponibilizado em formato compactado (.zip) contendo os XMLs autorizados que atendam aos critérios informados.
post
Headers
DocumentoEmissorstringrequired
Documento do emissor.
Body
Body
Filtros e critérios para a extração dos arquivos XML.
SolicitarDownloadXmlInputModel
Filtros solicitados para download de arquivos xmls.
* Additional properties are NOT allowed.
dataIniciostring(date)required
Filtrar pela data de emissão da nota “a partir de”.
>= 1 characters
Example:2025-03-31
dataFimstring(date)required
Filtrar pela data de emissão da nota “até”.
>= 1 characters
Example:2025-03-31
inscricaoEstadualstring | null
Filtrar pela inscrição estadual do emissor da nota fiscal.
buscastring | null
Filtro de busca genérica (dados do destinatário, transportador, chave de acesso, intermediador ou número do documento).
modelosDocumentoarray | null[string]
Modelo de documentos solicitados para download.
Allowed values:NfeNfce
urlCallbackstring | null
URL de callback para disparar notificação após conclusão do processamento da solicitação.
Response
Response
OK
string(uuid)
post/api/v1/DocumentoFiscal/DownloadXml/Solicitar
Authentication
Headers
Body
{
"dataInicio": "2025-03-31",
"dataFim": "2025-03-31"
}
Download de XMLs - Consultar.
Permite o acompanhamento do processamento de uma solicitação de download de arquivos XML previamente realizada.
Através deste endpoint, o sistema consumidor pode verificar se os arquivos já foram compactados e estão prontos para baixar.
🔄 ESTADOS: A solicitação pode transitar entre os estados de Pendente, EmProcessamento, Concluido, Expirado ou Falha. O link de download só será preenchido quando o status for Concluido.
🔗 DISPONIBILIDADE: Uma vez gerado, o link para o arquivo .zip possui uma validade temporária. Certifique-se de realizar o download assim que o processamento for finalizado.
⚠️ DICA: Caso o status retorne como Falha, verifique os detalhes da mensagem para identificar se o intervalo de busca foi muito extenso ou se não foram encontrados documentos para os filtros informados.
get
Path Parameters
downloadXmlIdstring(uuid)required
Identificador único (Ticket) da solicitação de download.
Headers
DocumentoEmissorstringrequired
Documento do emissor.
Response
Response
OK
DownloadXmlViewModel
Dados da solicitação de download do XML.
* Additional properties are NOT allowed.
idstring(uuid)
Identificador da solicitação do download.
statusstring
Status do processamento da solicitação de download de XML.
Allowed values:PendenteEmProcessamentoConcluidoFalhaExpirado
dataSolicitacaostring(date-time)
Data de solicitação do download.
inscricaoEstadualstring | null
Filtrar pela inscrição estadual do emissor da nota fiscal.
buscastring | null
Filtro de busca genérica (dados do destinatário, transportador, chave de acesso, intermediador ou número do documento).
dataIniciostring | null(date)
Filtrar pela data de emissão da nota “a partir de”.
dataFimstring | null(date)
Filtrar pela data de emissão da nota “até”.
modelosDocumentoarray | null[string]
Modelo de documentos solicitados para download.
Allowed values:NfeNfce
mensagemFalhastring | null
Mensagem em caso de falha.
dataHoraProcessamentostring | null(date-time)
Data e hora do processamento.
statusCallbackstring
Status do envio de callback.
Allowed values:NaoRealizadoSucessoFalha
urlCallbackstring | null
URL de callback do solicitante.
urlDownloadstring | null
Url com link de download dos arquivos XMLs.
get/api/v1/DocumentoFiscal/DownloadXml/{downloadXmlId}
Authentication
Path Parameters
Headers
Histórico de eventos - Listar.
Permite a listagem e rastreabilidade de eventos processados pela API de Notas Fiscais.
Fornece uma visão detalhada do ciclo de vida das requisições, permitindo auditoria técnica e funcional.
🔍 BUSCA ABRANGENTE: O campo de busca genérica atua sobre a rota acessada e o conteúdo (body) das requisições, facilitando a localização de transações específicas.
⏱️ PERFORMANCE: É possível filtrar eventos por tempo de execução (milissegundos), ideal para identificar gargalos operacionais ou latências atípicas no processamento.
🛡️ AUDITORIA: O filtro por sucesso ou erro permite isolar rapidamente falhas de integração ou validações de negócio impeditivas.
get
Query Parameters
tipoEventostring
Tipo de evento do contexto de notas fiscais.
Allowed values:PreNotaAutomaticaPreNotaSimplificadaEmissaoNfeEmissaoNfceAutomaticaEmissaoNfceSimplificadaEmissaoNfceCancelarNotaFiscalInutilizarFaixaNumeracaoTransmitirNotaFiscalEmitidaEmContingenciaEmitirNfeEstornoEmitirNfeDevolucaoEmitirNfeDevolucaoXmlObterDanfeNfeObterDanfeNfceObterArquivoXmlEmitirCartaDeCorrecaoObterXmlCartaCorrecaoObterArquivoXmlNfseObterDanfeNfseCancelarNotaFiscalServicoEmissaoNfse
sucessoboolean
Filtrar por eventos com sucesso ou erro.
buscastring
Termo de busca genérico (rota ou conteúdo).
dataInicialstring(date-time)
Filtrar pela data de início do evento “a partir de”.
dataFinalstring(date-time)
Filtrar pela data de início do evento “até”.
duracaoInicialMilissegundosnumber(double)
Filtrar pela duração mínima em milissegundos.
duracaoFinalMilissegundosnumber(double)
Filtrar pela duração máxima em milissegundos.
offsetinteger(int32)
Registro inicial para paginação.
Default:1
limitinteger(int32)
Quantidade de registros por página.
Default:10
Headers
DocumentoEmissorstringrequired
Documento do emissor.
Response
Response
OK
ListarHistoricoEventosNotaFiscalViewModelListPaginationResponse
* Additional properties are NOT allowed.
offsetinteger(int32)
limitinteger(int32)
totalinteger(int32)
dataarray | null[object]
Dados da listagem do histórico de comandos de notas fiscais.
* Additional properties are NOT allowed.
Show Child Parameters
get/api/v1/DocumentoFiscal/HistoricoEventos/Listar
Authentication
Query Parameters
Headers
Histórico de eventos - Detalhe.
Permite obter o detalhamento completo de um evento específico vinculado a uma Nota Fiscal, utilizando o identificador único do histórico.
Esta operação é fundamental para a rastreabilidade de ocorrências e conferência de logs de processamento ou eventos fiscais (como cancelamentos, cartas de correção, etc.) registrados na plataforma.
get
Path Parameters
historicoEventoIdstring(uuid)required
Identificador único do histórico do evento.
Headers
DocumentoEmissorstringrequired
Documento do emissor.
Response
Response
OK
ObterDetalheHistoricoEventosNotaFiscalViewModel
Dados detalhados do histórico de evento de nota fiscal.
* Additional properties are NOT allowed.
idstring(uuid)
Identificador interno do histórico do evento.
tipoEventostring
Tipo de evento do contexto de notas fiscais.
Allowed values:PreNotaAutomaticaPreNotaSimplificadaEmissaoNfeEmissaoNfceAutomaticaEmissaoNfceSimplificadaEmissaoNfceCancelarNotaFiscalInutilizarFaixaNumeracaoTransmitirNotaFiscalEmitidaEmContingenciaEmitirNfeEstornoEmitirNfeDevolucaoEmitirNfeDevolucaoXmlObterDanfeNfeObterDanfeNfceObterArquivoXmlEmitirCartaDeCorrecaoObterXmlCartaCorrecaoObterArquivoXmlNfseObterDanfeNfseCancelarNotaFiscalServicoEmissaoNfse
documentoEmissorstring | null
Documento (CPF/CNPJ) do emissor.
nomeEmissorstring | null
Nome ou Razão Social do emissor.
sucessoboolean
Indica se o processamento do evento foi realizado com sucesso.
rotastring | null
Rota ou endpoint do evento.
jsonEnviadostring | null
Conteúdo do body enviado na requisição.
jsonRetornadostring | null
Conteúdo retornado na requisição.
inicioExecucaostring(date-time)
Data de início da execução do evento.
finalExecucaostring(date-time)
Data do fim da execução do evento.
duracaoMilissegundosnumber(double)
Tempo de duração do evento em milissegundos.
duracaostring | null
Tempo de duração do evento.
get/api/v1/DocumentoFiscal/HistoricoEventos/{historicoEventoId}/ObterDetalhe