Nfe
Controlador de Notas Fiscais Eletrônicas (NFe) da Stone Tax API.
Centraliza os recursos destinados à emissão, cancelamento e gestão de notas fiscais eletrônicas (NFe).
Fornece abstrações para simplificar a complexidade de comunicação com as Secretarias da Fazenda (SEFAZ).
Através desta controller, é possível gerenciar todo o ciclo de vida de um documento fiscal: desde a emissão até a obtenção de artefatos finais como o XML e o DANFE.
Operações de escrita (emissão/cancelamento) exigem assinatura digital e observância ao contexto do
Emissor configurado, garantindo a validade jurídica perante o Fisco.
Status SEFAZ.
Realiza a verificação em tempo real da disponibilidade dos serviços da SEFAZ (Secretaria da Fazenda) para a autorização de documentos fiscais.
Este recurso é essencial para diagnosticar instabilidades no webservice de destino, permitindo que o sistema emissor decida pela ativação de regimes de contingência ou aguarde a normalização do serviço.
⚠️ ATENÇÃO: O tempo de resposta deste endpoint depende diretamente da latência do servidor governamental consultado. Recomenda-se implementar um timeout adequado no lado do cliente para evitar retenção de threads.
🧪 TESTE: Em ambiente de sandbox, o retorno pode simular um status de “Operação Normal” de forma estática ou refletir o ambiente de homologação da SEFAZ, dependendo da configuração da aplicação.
post
Headers
DocumentoEmissorstringrequired
Documento do emissor.
Response
Response
OK
ConsultarStatusSefazViewModel
Retorno da consulta de status da SEFAZ.
* Additional properties are NOT allowed.
sucessoboolean
Indica se a consulta foi bem sucedida.
tipoAmbientestring
Tipo de ambiente da SEFAZ.
Allowed values:ProducaoHomologacao
ufstring
Lista de Unidades Federativas para Nota Fiscal.
Allowed values:ROACAMRRPAAPTOMAPICERNPBPEALSEBAMGESRJSPPRSCRSMSMTGODF
cStatinteger(int32)
Código de status da SEFAZ.
xMotivostring | null
Motivo do status da SEFAZ.
post/api/v1/Nfe/Sefaz/Status
Authentication
Headers
Pré-Nota - Modo Automático.
Realiza o processamento inteligente e retorna a estrutura de dados (payload) para a emissão da Nota Fiscal Eletrônica (modelo 55), otimizando o preenchimento de campos tributários complexos por meio de automações internas no modo automático, ocultando qualquer informação tributária.
⚠️ ATENÇÃO: Esta operação possui caráter estritamente consultivo e preparatório. O retorno consiste no objeto JSON necessário para a emissão, não realizando o registro fiscal ou o envio da nota à SEFAZ neste momento.
⚙️ PROCESSAMENTO: O resultado obtido deve ser validado pelo sistema consumidor e, estando em conformidade, utilizado como entrada (input) no endpoint de emissão definitiva: ../Espelho/ModoSimplificado.
🛡️ AUTOMAÇÃO: Este modo reduz a carga de integração ao calcular automaticamente alíquotas e enquadramentos com base no perfil do emissor e destinatário informados.
post
Headers
inscricaoEstadualEmissorstring
Inscrição estadual do emissor (Opcional - Utilizado para múltiplos estabelecimentos).
DocumentoEmissorstringrequired
Documento do emissor.
Body
Body
Dados de entrada para a geração automática da estrutura da NFe.
NfeAutomaticaInputModel
Dados da nota fiscal eletrônica Automática.
* Additional properties are NOT allowed.
codigoErpstringrequired
Identificador da pré-venda no ERP.
>= 1 characters
seriestring | null
Série do documento fiscal (Informar somente se estiver configurado para geração numérica manual).
numeroDocumentointeger | null(int64)
Numero do documento fiscal (Informar somente se estiver configurado para geração numérica manual).
naturezaOperacaostring | null
Descrição da natureza da operação.
fluxoFiscalAutomaticostring
Fluxo fiscal para cálculo automático do tributo.
Allowed values:VendaConsumidorFinalRevendaBonificacaoTransferencia
indicadorPresencastring
Indicador de presença na operação.
Allowed values:NaoSeAplicaOperacaoPresencialOperacaoNaoPresencialInternetOperacaoNaoPresencialTeleatendimentoNaoPresencialOutros
tipoEmissaostring
Tipo de emissão de NFe.
Allowed values:AutomaticaNormalContingenciaFsdaContingenciaSvcanContingenciaSvcrs
dataHoraEntradaContingenciastring | null(date-time)
Data e hora de entrada em contingência (Opcional).
justificativaContingenciastring | null
Justificativa de entrada em contingência (Opcional).
dataSaidaEntradastring | null(date-time)
Data de saída/entrada.
destinatarioobjectrequired
Dados do destinatário da NFe Automática.
* Additional properties are NOT allowed.
Show Child Parameters
enderecoEntregaobject
Dados de Endereço de Entrega para Nota Fiscal Eletrônica Automática.
* Additional properties are NOT allowed.
Show Child Parameters
enderecoRetiradaobject
Dados do endereço de retirada da NFe Automática.
* Additional properties are NOT allowed.
Show Child Parameters
autXmlarray | null[object]
Documentos autorizados a capturar e visualizar a NFe.
* Additional properties are NOT allowed.
Show Child Parameters
itensarray[object]required
Dados do item da NFe Automática.
* Additional properties are NOT allowed.
Show Child Parameters
transporteobject
Dados de transporte para NFe.
* Additional properties are NOT allowed.
Show Child Parameters
cnpjIntermediadorstring | null
CNPJ do intermediador.
identificadorIntermediadorstring | null
Identificador do intermediador.
informacaoAdicionalFiscostring | null
Informação adicional de interesse do fisco.
<= 2000 characters
informacaoComplementarstring | null
Informação complementar.
<= 5000 characters
Response
Response
OK
NfeInputModel
Dados da nota fiscal eletrônica.
* Additional properties are NOT allowed.
codigoErpstringrequired
Identificador da operação fiscal no ERP.
>= 1 characters
seriestring | null
Série do documento fiscal (Informar somente se estiver configurado para geração numérica manual).
numeroDocumentointeger | null(int64)
Numero do documento fiscal (Informar somente se estiver configurado para geração numérica manual).
naturezaOperacaostring | null
Descrição da natureza da operação.
tipoOperacaostring
Tipo de operação.
Allowed values:EntradaSaida
indicadorPresencastring
Indicador de presença na operação.
Allowed values:NaoSeAplicaOperacaoPresencialOperacaoNaoPresencialInternetOperacaoNaoPresencialTeleatendimentoNaoPresencialOutros
consumidorFinalboolean | null
Indica se é operação com consumidor final.
tipoEmissaostring
Tipo de emissão de NFe.
Allowed values:AutomaticaNormalContingenciaFsdaContingenciaSvcanContingenciaSvcrs
dataHoraEntradaContingenciastring | null(date-time)
Data e hora de entrada em contingência (Opcional).
justificativaContingenciastring | null
Justificativa de entrada em contingência (Opcional).
finalidadestring
Finalidade da NFe.
Allowed values:NormalComplementarAjusteDevolucao
dataSaidaEntradastring | null(date-time)
Data de saída/entrada.
destinatarioobjectrequired
Dados do destinatário da NFe.
* Additional properties are NOT allowed.
Show Child Parameters
enderecoEntregaobject
Dados de Endereço de Entrega para Nota Fiscal Eletrônica.
* Additional properties are NOT allowed.
Show Child Parameters
enderecoRetiradaobject
Dados do endereço de retirada da NFe.
* Additional properties are NOT allowed.
Show Child Parameters
autXmlarray | null[object]
Documentos autorizados a capturar e visualizar a NFe.
* Additional properties are NOT allowed.
Show Child Parameters
itensarray[object]required
Dados do item da NFe.
* Additional properties are NOT allowed.
Show Child Parameters
notasReferenciadasarray | null[object]
Dados para notas referenciadas na NFe.
* Additional properties are NOT allowed.
Show Child Parameters
transporteobject
Dados de transporte para NFe.
* Additional properties are NOT allowed.
Show Child Parameters
cobrancaobject
Dados da cobrança da NFe.
* Additional properties are NOT allowed.
Show Child Parameters
pagamentosobjectrequired
Dados dos pagamentos da NFe.
* Additional properties are NOT allowed.
Show Child Parameters
cnpjIntermediadorstring | null
CNPJ do intermediador.
identificadorIntermediadorstring | null
Identificador do intermediador.
exportacaoobject
Dados de exportação da NFe.
* Additional properties are NOT allowed.
Show Child Parameters
informacaoAdicionalFiscostring | null
Informação adicional de interesse do fisco.
<= 2000 characters
informacaoComplementarstring | null
Informação complementar.
<= 5000 characters
valorTotalnumber(double)required
Valor total do documento fiscal (Não incluir os impostos da reforma tributária: IBS, CBS e IS).
post/api/v1/Nfe/PreNota/ModoAutomatico
Authentication
Headers
Body
{
"codigoErp": "codigoErp",
"destinatario": {
"documento": "documento",
"nome": "nome",
"endereco": {
"logradouro": "logradouro",
"numero": "numero",
"bairro": "bairro",
"codigoMunicipio": "codigoMunicipio",
"nomeMunicipio": "nomeMunicipio",
"cep": "cep"
}
},
"itens": [
{
"codigoInterno": "codigoInterno",
"descricao": "descricao",
"origemMercadoria": "Nacional",
"unidade": "unidade"
}
]
}
Pré-Nota - Modo Simplificado.
Realiza o processamento inteligente e retorna a estrutura de dados (payload) para a emissão da Nota Fiscal Eletrônica (modelo 55), otimizando o preenchimento de campos tributários complexos por meio de automações internas no modo simplificado, exigindo apenas o preenchimento das alíquotas.
⚠️ ATENÇÃO: Esta operação possui caráter estritamente consultivo e preparatório. O retorno consiste no objeto JSON necessário para a emissão, não realizando o registro fiscal ou o envio da nota à SEFAZ neste momento.
⚙️ PROCESSAMENTO: O resultado obtido deve ser validado pelo sistema consumidor e, estando em conformidade, utilizado como entrada (input) no endpoint de emissão definitiva: ../Espelho/ModoSimplificado.
🛡️ AUTOMAÇÃO: Este modo reduz a carga de integração ao calcular automaticamente alíquotas e enquadramentos com base no perfil do emissor e destinatário informados.
post
Headers
inscricaoEstadualEmissorstring
Inscrição estadual do emissor (Opcional - Utilizado para múltiplos estabelecimentos).
DocumentoEmissorstringrequired
Documento do emissor.
Body
Body
Dados de entrada para a geração automática da estrutura da NFe.
NfeSimplificadaInputModel
Dados da nota fiscal eletrônica.
* Additional properties are NOT allowed.
codigoErpstringrequired
Identificador da operação fiscal no ERP.
>= 1 characters
seriestring | null
Série do documento fiscal (Informar somente se estiver configurado para geração numérica manual).
numeroDocumentointeger | null(int64)
Numero do documento fiscal (Informar somente se estiver configurado para geração numérica manual).
naturezaOperacaostring | null
Descrição da natureza da operação.
tipoOperacaostring
Tipo de operação.
Allowed values:EntradaSaida
indicadorPresencastring
Indicador de presença na operação.
Allowed values:NaoSeAplicaOperacaoPresencialOperacaoNaoPresencialInternetOperacaoNaoPresencialTeleatendimentoNaoPresencialOutros
consumidorFinalboolean | null
Indica se é operação com consumidor final.
tipoEmissaostring
Tipo de emissão de NFe.
Allowed values:AutomaticaNormalContingenciaFsdaContingenciaSvcanContingenciaSvcrs
dataHoraEntradaContingenciastring | null(date-time)
Data e hora de entrada em contingência (Opcional).
justificativaContingenciastring | null
Justificativa de entrada em contingência (Opcional).
dataSaidaEntradastring | null(date-time)
Data de saída/entrada.
destinatarioobjectrequired
Dados do destinatário da NFe.
* Additional properties are NOT allowed.
Show Child Parameters
enderecoEntregaobject
Dados de Endereço de Entrega para Nota Fiscal Eletrônica.
* Additional properties are NOT allowed.
Show Child Parameters
enderecoRetiradaobject
Dados do endereço de retirada da NFe.
* Additional properties are NOT allowed.
Show Child Parameters
autXmlarray | null[object]
Documentos autorizados a capturar e visualizar a NFe.
* Additional properties are NOT allowed.
Show Child Parameters
itensarray[object]required
Dados do item da NFe.
* Additional properties are NOT allowed.
Show Child Parameters
transporteobject
Dados de transporte para NFe.
* Additional properties are NOT allowed.
Show Child Parameters
cnpjIntermediadorstring | null
CNPJ do intermediador.
identificadorIntermediadorstring | null
Identificador do intermediador.
exportacaoobject
Dados de exportação da NFe.
* Additional properties are NOT allowed.
Show Child Parameters
informacaoAdicionalFiscostring | null
Informação adicional de interesse do fisco.
<= 2000 characters
informacaoComplementarstring | null
Informação complementar.
<= 5000 characters
Response
Response
OK
NfeInputModel
Dados da nota fiscal eletrônica.
* Additional properties are NOT allowed.
codigoErpstringrequired
Identificador da operação fiscal no ERP.
>= 1 characters
seriestring | null
Série do documento fiscal (Informar somente se estiver configurado para geração numérica manual).
numeroDocumentointeger | null(int64)
Numero do documento fiscal (Informar somente se estiver configurado para geração numérica manual).
naturezaOperacaostring | null
Descrição da natureza da operação.
tipoOperacaostring
Tipo de operação.
Allowed values:EntradaSaida
indicadorPresencastring
Indicador de presença na operação.
Allowed values:NaoSeAplicaOperacaoPresencialOperacaoNaoPresencialInternetOperacaoNaoPresencialTeleatendimentoNaoPresencialOutros
consumidorFinalboolean | null
Indica se é operação com consumidor final.
tipoEmissaostring
Tipo de emissão de NFe.
Allowed values:AutomaticaNormalContingenciaFsdaContingenciaSvcanContingenciaSvcrs
dataHoraEntradaContingenciastring | null(date-time)
Data e hora de entrada em contingência (Opcional).
justificativaContingenciastring | null
Justificativa de entrada em contingência (Opcional).
finalidadestring
Finalidade da NFe.
Allowed values:NormalComplementarAjusteDevolucao
dataSaidaEntradastring | null(date-time)
Data de saída/entrada.
destinatarioobjectrequired
Dados do destinatário da NFe.
* Additional properties are NOT allowed.
Show Child Parameters
enderecoEntregaobject
Dados de Endereço de Entrega para Nota Fiscal Eletrônica.
* Additional properties are NOT allowed.
Show Child Parameters
enderecoRetiradaobject
Dados do endereço de retirada da NFe.
* Additional properties are NOT allowed.
Show Child Parameters
autXmlarray | null[object]
Documentos autorizados a capturar e visualizar a NFe.
* Additional properties are NOT allowed.
Show Child Parameters
itensarray[object]required
Dados do item da NFe.
* Additional properties are NOT allowed.
Show Child Parameters
notasReferenciadasarray | null[object]
Dados para notas referenciadas na NFe.
* Additional properties are NOT allowed.
Show Child Parameters
transporteobject
Dados de transporte para NFe.
* Additional properties are NOT allowed.
Show Child Parameters
cobrancaobject
Dados da cobrança da NFe.
* Additional properties are NOT allowed.
Show Child Parameters
pagamentosobjectrequired
Dados dos pagamentos da NFe.
* Additional properties are NOT allowed.
Show Child Parameters
cnpjIntermediadorstring | null
CNPJ do intermediador.
identificadorIntermediadorstring | null
Identificador do intermediador.
exportacaoobject
Dados de exportação da NFe.
* Additional properties are NOT allowed.
Show Child Parameters
informacaoAdicionalFiscostring | null
Informação adicional de interesse do fisco.
<= 2000 characters
informacaoComplementarstring | null
Informação complementar.
<= 5000 characters
valorTotalnumber(double)required
Valor total do documento fiscal (Não incluir os impostos da reforma tributária: IBS, CBS e IS).
post/api/v1/Nfe/PreNota/ModoSimplificado
Authentication
Headers
Body
{
"codigoErp": "codigoErp",
"destinatario": {
"documento": "documento",
"nome": "nome",
"endereco": {
"logradouro": "logradouro",
"numero": "numero",
"bairro": "bairro",
"codigoMunicipio": "codigoMunicipio",
"nomeMunicipio": "nomeMunicipio",
"cep": "cep"
}
},
"itens": [
{
"codigoInterno": "codigoInterno",
"descricao": "descricao",
"ncm": "ncm",
"cfop": "cfop",
"unidade": "unidade",
"impostos": {
"pis": {
"cst": "01"
},
"cofins": {
"cst": "01"
}
}
}
]
}
Emitir NFe.
Realiza o processamento e a transmissão de uma Nota Fiscal Eletrônica (Modelo 55) para a SEFAZ no modo completo, necessitando o preenchimento de todos os campos tributários.
O endpoint abrange desde a validação do schema XML até a assinatura digital e autorização em tempo real.
⚠️ ATENÇÃO: Certifique-se de que os dados de impostos (ICMS, PIS, COFINS, IPI) e as informações do destinatário estejam em conformidade com as regras fiscais vigentes para evitar rejeições de validação da SEFAZ.
🧪 TESTE: Em ambiente de homologação, as notas emitidas possuem sem valor fiscal. Utilize o CNPJ de teste apropriado e verifique se o prefixo da série está configurado para o ambiente de testes para evitar conflitos de numeração.
⚙️ PROCESSAMENTO: O retorno bem-sucedido confirma o recebimento pela mensageria.
Erro 422: A nota foi salva no sistema, mas não autorizada pela SEFAZ.
Ação necessária: Analisar o motivo da rejeição para reenviar o documento ou realizar o cancelamento para inutilizar a numeração junto ao fisco.
post
Headers
inscricaoEstadualEmissorstring
Inscrição estadual do emissor (Opcional).
danfestring
Tipo de arquivo DANFE gerado na emissão.
Allowed values:HtmlPdfNenhum
tipoDanfeNfestring
Tipo de danfe para NFe.
Allowed values:RetratoSimplificado
DocumentoEmissorstringrequired
Documento do emissor.
Body
Body
Dados para a emissão da nota fiscal.
NfeInputModel
Dados da nota fiscal eletrônica.
* Additional properties are NOT allowed.
codigoErpstringrequired
Identificador da operação fiscal no ERP.
>= 1 characters
seriestring | null
Série do documento fiscal (Informar somente se estiver configurado para geração numérica manual).
numeroDocumentointeger | null(int64)
Numero do documento fiscal (Informar somente se estiver configurado para geração numérica manual).
naturezaOperacaostring | null
Descrição da natureza da operação.
tipoOperacaostring
Tipo de operação.
Allowed values:EntradaSaida
indicadorPresencastring
Indicador de presença na operação.
Allowed values:NaoSeAplicaOperacaoPresencialOperacaoNaoPresencialInternetOperacaoNaoPresencialTeleatendimentoNaoPresencialOutros
consumidorFinalboolean | null
Indica se é operação com consumidor final.
tipoEmissaostring
Tipo de emissão de NFe.
Allowed values:AutomaticaNormalContingenciaFsdaContingenciaSvcanContingenciaSvcrs
dataHoraEntradaContingenciastring | null(date-time)
Data e hora de entrada em contingência (Opcional).
justificativaContingenciastring | null
Justificativa de entrada em contingência (Opcional).
finalidadestring
Finalidade da NFe.
Allowed values:NormalComplementarAjusteDevolucao
dataSaidaEntradastring | null(date-time)
Data de saída/entrada.
destinatarioobjectrequired
Dados do destinatário da NFe.
* Additional properties are NOT allowed.
Show Child Parameters
enderecoEntregaobject
Dados de Endereço de Entrega para Nota Fiscal Eletrônica.
* Additional properties are NOT allowed.
Show Child Parameters
enderecoRetiradaobject
Dados do endereço de retirada da NFe.
* Additional properties are NOT allowed.
Show Child Parameters
autXmlarray | null[object]
Documentos autorizados a capturar e visualizar a NFe.
* Additional properties are NOT allowed.
Show Child Parameters
itensarray[object]required
Dados do item da NFe.
* Additional properties are NOT allowed.
Show Child Parameters
notasReferenciadasarray | null[object]
Dados para notas referenciadas na NFe.
* Additional properties are NOT allowed.
Show Child Parameters
transporteobject
Dados de transporte para NFe.
* Additional properties are NOT allowed.
Show Child Parameters
cobrancaobject
Dados da cobrança da NFe.
* Additional properties are NOT allowed.
Show Child Parameters
pagamentosobjectrequired
Dados dos pagamentos da NFe.
* Additional properties are NOT allowed.
Show Child Parameters
cnpjIntermediadorstring | null
CNPJ do intermediador.
identificadorIntermediadorstring | null
Identificador do intermediador.
exportacaoobject
Dados de exportação da NFe.
* Additional properties are NOT allowed.
Show Child Parameters
informacaoAdicionalFiscostring | null
Informação adicional de interesse do fisco.
<= 2000 characters
informacaoComplementarstring | null
Informação complementar.
<= 5000 characters
valorTotalnumber(double)required
Valor total do documento fiscal (Não incluir os impostos da reforma tributária: IBS, CBS e IS).
Response
Response
OK
EmissaoNotaFiscalViewModel
Dados de retorno da emissão de nota fiscal.
* Additional properties are NOT allowed.
sucessoboolean
Indica se a nota foi autorizada pela sefaz ou não.
codigoStatusinteger(int32)
Código de status de envio para a sefaz.
mensagemSefazstring | null
Mensagem de retorno da sefaz.
seriestring | null
Série da nota fiscal.
numeroDocumentointeger(int64)
Número do documento.
chaveAcessostring | null
Chave de acesso da nota fiscal.
numeroProtocolostring | null
Número do protocolo de autorização da nota fiscal.
linkQrcodestring | null
Link de acesso a nota fiscal (Apenas para NFC-e).
danfestring | null
Arquivo DANFE solicitado (HTML ou PDF Base64).
emitidaEmContingenciaboolean
Indica se a nota foi emitida em modo contingência.
post/api/v1/Nfe/Emitir
Authentication
Headers
Body
{
"codigoErp": "codigoErp",
"destinatario": {
"documento": "documento",
"nome": "nome",
"endereco": {
"logradouro": "logradouro",
"numero": "numero",
"bairro": "bairro",
"codigoMunicipio": "codigoMunicipio",
"nomeMunicipio": "nomeMunicipio",
"cep": "cep"
}
},
"itens": [
{
"codigoInterno": "codigoInterno",
"descricao": "descricao",
"ncm": "ncm",
"cfop": "cfop",
"unidade": "unidade",
"impostos": {
"pis": {
"cst": "01"
},
"cofins": {
"cst": "01"
}
}
}
],
"pagamentos": {
"formasDePagamento": [
{}
]
},
"valorTotal": 0
}