Nfce
Controlador de Notas Fiscais de Consumidor Eletrônicas (NFCe) da Stone Tax API.
Centraliza os recursos destinados à emissão, cancelamento e gestão de notas fiscais de consumidor (NFCe).
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/Nfce/Sefaz/Status
Authentication
Headers
Emitir NFCe - Modo Automático.
Realiza o processamento e a transmissão de uma Nota Fiscal de Consumidor Eletrônica (modelo 65) no modo automático, otimizando o preenchimento de campos tributários complexos por meio de automações internas da API.
⚠️ ATENÇÃO: Esta operação possui validade jurídica perante a SEFAZ. Certifique-se de que os dados do destinatário e dos itens estão corretos antes de processar a emissão, pois a autorização consome recursos do ambiente de produção.
🧪 TESTE: Em ambiente de sandbox, as notas emitidas NÃO possuem valor fiscal e são enviadas para os servidores de homologação da SEFAZ. Utilize este ambiente para validar a estrutura do JSON e o fluxo de resposta antes do go-live.
⚙️ 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
tipoDanfeNfcestring
Tipo de danfe para NFCe.
Allowed values:Danfe56mmDanfe80mm
DocumentoEmissorstringrequired
Documento do emissor.
Body
Body
Dados para emissão da NFCe Automática.
NfceAutomaticaInputModel
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.
indicadorPresencastring
Indicador de presença na operação.
Allowed values:OperacaoPresencialNfceEntregaDomicilio
tipoEmissaostring
Tipo de emissão de NFCe.
Allowed values:AutomaticaNormalContingenciaNfce
dataHoraEntradaContingenciastring | null(date-time)
Data e hora de entrada em contingência (Opcional).
justificativaContingenciastring | null
Justificativa de entrada em contingência (Opcional).
destinatarioobject
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
itensarray[object]required
Dados do item da NFe Automática.
* Additional properties are NOT allowed.
Show Child Parameters
transporteobject
Dados de transporte para NFe Automática.
* Additional properties are NOT allowed.
Show Child Parameters
cobrancaobject
Dados da cobrança da NFe Automática.
* Additional properties are NOT allowed.
Show Child Parameters
pagamentosobjectrequired
Dados dos pagamentos da NFe Automática.
* 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/Nfce/Emitir/ModoAutomatico
Authentication
Headers
Body
{
"codigoErp": "codigoErp",
"itens": [
{
"codigoInterno": "codigoInterno",
"descricao": "descricao",
"unidade": "unidade"
}
],
"pagamentos": {
"formasDePagamento": [
{}
]
},
"valorTotal": 0
}
Emitir NFCe - Modo Simplificado.
Realiza o processamento e a transmissão de uma Nota Fiscal de Consumidor Eletrônica (modelo 65) no modo simplificado, ocultando campos de base e valor de tributos calculados pelo sistema.
⚠️ ATENÇÃO: Esta operação possui validade jurídica perante a SEFAZ. Certifique-se de que os dados do destinatário e dos itens estão corretos antes de processar a emissão, pois a autorização consome recursos do ambiente de produção.
🧪 TESTE: Em ambiente de sandbox, as notas emitidas NÃO possuem valor fiscal e são enviadas para os servidores de homologação da SEFAZ. Utilize este ambiente para validar a estrutura do JSON e o fluxo de resposta antes do go-live.
⚙️ 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
tipoDanfeNfcestring
Tipo de danfe para NFCe.
Allowed values:Danfe56mmDanfe80mm
DocumentoEmissorstringrequired
Documento do emissor.
Body
Body
Dados para emissão da NFCe simplificada.
NfceSimplificadaInputModel
Dados da nota fiscal eletrônica simplificada.
* 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.
indicadorPresencastring
Indicador de presença na operação.
Allowed values:OperacaoPresencialNfceEntregaDomicilio
tipoEmissaostring
Tipo de emissão de NFCe.
Allowed values:AutomaticaNormalContingenciaNfce
dataHoraEntradaContingenciastring | null(date-time)
Data e hora de entrada em contingência (Opcional).
justificativaContingenciastring | null
Justificativa de entrada em contingência (Opcional).
destinatarioobject
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 simplificada.
* 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
pagamentosobjectrequired
Dados dos pagamentos 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/Nfce/Emitir/ModoSimplificado
Authentication
Headers
Body
{
"codigoErp": "codigoErp",
"itens": [
{
"codigoInterno": "codigoInterno",
"descricao": "descricao",
"ncm": "ncm",
"cfop": "cfop",
"unidade": "unidade"
}
],
"pagamentos": {
"formasDePagamento": [
{}
]
},
"valorTotal": 0
}
Emitir NFCe.
Realiza o processamento e a transmissão de uma Nota Fiscal de Consumidor Eletrônica (Modelo 65) para a SEFAZ no modo completo, preenchendo 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) 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
tipoDanfeNfcestring
Tipo de danfe para NFCe.
Allowed values:Danfe56mmDanfe80mm
DocumentoEmissorstringrequired
Documento do emissor.
Body
Body
Dados para a emissão da nota fiscal de consumidor eletrônica.
NfceInputModel
Dados da nota fiscal eletrônica simplificada.
* 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.
indicadorPresencastring
Indicador de presença na operação.
Allowed values:OperacaoPresencialNfceEntregaDomicilio
tipoEmissaostring
Tipo de emissão de NFCe.
Allowed values:AutomaticaNormalContingenciaNfce
dataHoraEntradaContingenciastring | null(date-time)
Data e hora de entrada em contingência (Opcional).
justificativaContingenciastring | null
Justificativa de entrada em contingência (Opcional).
destinatarioobject
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 simplificada.
* 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
pagamentosobjectrequired
Dados dos pagamentos 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/Nfce/Emitir
Authentication
Headers
Body
{
"codigoErp": "codigoErp",
"itens": [
{
"codigoInterno": "codigoInterno",
"descricao": "descricao",
"ncm": "ncm",
"cfop": "cfop",
"unidade": "unidade"
}
],
"pagamentos": {
"formasDePagamento": [
{}
]
},
"valorTotal": 0
}