Nfse
Controlador de Notas Fiscais de Serviço Eletrônicas (NFSe) da Stone Tax API.
Centraliza os recursos destinados à emissão, cancelamento e gestão de notas fiscais de serviços (NFSe).
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.
Emitir NFS-e - Modo Prestador.
Realiza a emissão completa de uma Nota Fiscal de Serviços Eletrônica (NFS-e) junto ao ADN (Ambiente de Desenvolvimento Nacional), atuando o emissor como o prestador do serviço.
O recurso assegura que o contexto tributário do prestador seja validado e que as regras fiscais do município correspondente sejam aplicadas durante a emissão do documento.
O processo segue o fluxo:
-
Geração e assinatura digital do XML da DPS (Declaração de Prestação de Serviços).
-
Persistência com status Pendente.
-
Transmissão ao ADN e atualização do status para Autorizada ou Rejeitada.
🔁 IDEMPOTÊNCIA: O campo codigoErp identifica a nota unicamente por emissor. Em caso de reenvio (nota Pendente ou Rejeitada), os dados são atualizados e a DPS é retransmitida sem duplicar registros.
⚙️ SEQUÊNCIA: A série e o número da DPS são gerenciados automaticamente com base nos parâmetros de NFS-e configurados para o emissor. Para sequência manual, informe serie e numeroDps.
⚠️ ATENÇÃO: Certifique-se de que o documento do emissor configurado no cabeçalho corresponda ao perfil tributário do prestador do serviço antes de efetuar a chamada.
post
Headers
DocumentoEmissorstringrequired
Documento do emissor.
Body
Body
Dados para emissão da NFS-e.
EmitirNfseModoPrestadorInputModel
Dados para emissão de uma Nota Fiscal de Serviço Eletrônica (NFS-e) no modo prestador.
* Additional properties are NOT allowed.
codigoErpstringrequired
Código de identificação interno do ERP do cliente. Utilizado para idempotência e reemissão.
>= 1 characters<= 60 characters
seriestring | null
Série da DPS (até 5 dígitos numéricos). Informar somente quando a sequência for manual.
numeroDpsinteger | null(int64)
Número sequencial da DPS (nDPS). Informar somente quando a sequência for manual.
dataCompetenciastring | null
Mês de competência da prestação do serviço no formato “AAAA-MM”.
Deve ser igual ou anterior ao mês de emissão.
Quando não informado, assume o mês/ano atual.
substituicaoobject
Dados da NFS-e substituída (subst).
* Additional properties are NOT allowed.
Show Child Parameters
tomadorobjectrequired
Dados do tomador de serviços (toma).
* Additional properties are NOT allowed.
Show Child Parameters
servicoobjectrequired
Dados do serviço prestado (serv).
Informar CodigoMunicipioLocalizacao (nacional) OU CodigoPaisLocalizacao (exterior), nunca ambos.
* Additional properties are NOT allowed.
Show Child Parameters
valoresobjectrequired
Valores do serviço prestado e tributação ISSQN para NFS-e no modo prestador.
* Additional properties are NOT allowed.
Show Child Parameters
ibsCbsobject
Dados de tributação do IBS (Imposto sobre Bens e Serviços) e CBS (Contribuição sobre Bens e Serviços)
da reforma tributária para a NFS-e. Obrigatório para Lucro Real e Lucro Presumido; opcional para Simples Nacional e MEI.
* Additional properties are NOT allowed.
Show Child Parameters
Response
Response
OK
EmissaoNotaFiscalServicoViewModel
Dados de retorno da emissão de Nota Fiscal de Serviço Eletrônica (NFS-e).
* Additional properties are NOT allowed.
sucessoboolean
Indica se a NFS-e foi autorizada pelo ADN.
codigoStatusinteger(int32)
Código de status retornado pelo ADN.
mensagemSefazstring | null
Mensagem de retorno do ADN.
seriestring | null
Série da DPS emitida.
numeroDpsinteger(int64)
Número sequencial da DPS.
numeroNfseinteger | null(int64)
Número sequencial da NFS-e gerado pelo ADN. Disponível após autorização.
chaveNfsestring | null
Chave da NFS-e. Disponível após autorização.
alertasarray | null[object]
Mensagem de processamento retornada pelo ADN.
* Additional properties are NOT allowed.
Show Child Parameters
errosarray | null[object]
Mensagem de processamento retornada pelo ADN.
* Additional properties are NOT allowed.
Show Child Parameters
post/api/v1/Nfse/Prestador/Emitir
Authentication
Headers
Body
{
"codigoErp": "codigoErp",
"tomador": {
"documento": "documento",
"nome": "nome",
"endereco": {}
},
"servico": {
"codigoServicoCtn": "codigoServicoCtn",
"descricaoServico": "descricaoServico",
"codigoNbs": "codigoNbs"
},
"valores": {
"valorServico": 0
}
}
Emitir NFS-e - Modo Tomador.
Realiza a emissão completa de uma Nota Fiscal de Serviços Eletrônica (NFS-e) junto ao ADN (Ambiente de Desenvolvimento Nacional), atuando o emissor como o tomador do serviço.
Neste modo, os dados do prestador externo devem ser informados no corpo da requisição, enquanto os dados do tomador são obtidos automaticamente do cadastro do emissor.
O processo segue o fluxo:
-
Geração e assinatura digital do XML da DPS (Declaração de Prestação de Serviços).
-
Persistência com status Pendente.
-
Transmissão ao ADN e atualização do status para Autorizada ou Rejeitada.
🔁 IDEMPOTÊNCIA: O campo codigoErp identifica a nota unicamente por emissor. Em caso de reenvio (nota Pendente ou Rejeitada), os dados são atualizados e a DPS é retransmitida sem duplicar registros.
⚙️ SEQUÊNCIA: A série e o número da DPS são gerenciados automaticamente com base nos parâmetros de NFS-e configurados para o emissor. Para sequência manual, informe serie e numeroDps.
⚠️ ATENÇÃO: Certifique-se de que o documento do emissor configurado no cabeçalho corresponda ao tomador do serviço antes de efetuar a chamada.
post
Headers
DocumentoEmissorstringrequired
Documento do emissor.
Body
Body
Dados para emissão da NFS-e.
EmitirNfseModoTomadorInputModel
Dados para emissão de uma Nota Fiscal de Serviço Eletrônica (NFS-e) no modo tomador.
* Additional properties are NOT allowed.
codigoErpstringrequired
Código de identificação interno do ERP do cliente. Utilizado para idempotência e reemissão.
>= 1 characters<= 60 characters
seriestring | null
Série da DPS (até 5 dígitos numéricos). Informar somente quando a sequência for manual.
numeroDpsinteger | null(int64)
Número sequencial da DPS (nDPS). Informar somente quando a sequência for manual.
dataCompetenciastring | null
Mês de competência da prestação do serviço no formato “AAAA-MM”.
Deve ser igual ou anterior ao mês de emissão.
Quando não informado, assume o mês/ano atual.
substituicaoobject
Dados da NFS-e substituída (subst).
* Additional properties are NOT allowed.
Show Child Parameters
prestadorobjectrequired
Dados do prestador de serviços (prest) informado pelo tomador na emissão de NFS-e no modo tomador.
* Additional properties are NOT allowed.
Show Child Parameters
servicoobjectrequired
Dados do serviço prestado (serv).
Informar CodigoMunicipioLocalizacao (nacional) OU CodigoPaisLocalizacao (exterior), nunca ambos.
* Additional properties are NOT allowed.
Show Child Parameters
valoresobjectrequired
Valores do serviço prestado e tributação ISSQN para NFS-e no modo tomador.
* Additional properties are NOT allowed.
Show Child Parameters
ibsCbsobject
Dados de tributação do IBS (Imposto sobre Bens e Serviços) e CBS (Contribuição sobre Bens e Serviços)
da reforma tributária para a NFS-e. Obrigatório para Lucro Real e Lucro Presumido; opcional para Simples Nacional e MEI.
* Additional properties are NOT allowed.
Show Child Parameters
Response
Response
OK
EmissaoNotaFiscalServicoViewModel
Dados de retorno da emissão de Nota Fiscal de Serviço Eletrônica (NFS-e).
* Additional properties are NOT allowed.
sucessoboolean
Indica se a NFS-e foi autorizada pelo ADN.
codigoStatusinteger(int32)
Código de status retornado pelo ADN.
mensagemSefazstring | null
Mensagem de retorno do ADN.
seriestring | null
Série da DPS emitida.
numeroDpsinteger(int64)
Número sequencial da DPS.
numeroNfseinteger | null(int64)
Número sequencial da NFS-e gerado pelo ADN. Disponível após autorização.
chaveNfsestring | null
Chave da NFS-e. Disponível após autorização.
alertasarray | null[object]
Mensagem de processamento retornada pelo ADN.
* Additional properties are NOT allowed.
Show Child Parameters
errosarray | null[object]
Mensagem de processamento retornada pelo ADN.
* Additional properties are NOT allowed.
Show Child Parameters
post/api/v1/Nfse/Tomador/Emitir
Authentication
Headers
Body
{
"codigoErp": "codigoErp",
"prestador": {
"documento": "documento",
"endereco": {}
},
"servico": {
"codigoServicoCtn": "codigoServicoCtn",
"descricaoServico": "descricaoServico",
"codigoNbs": "codigoNbs"
},
"valores": {
"valorServico": 0
}
}
Cancelar NFS-e.
Inicia o processo de cancelamento de uma Nota Fiscal de Serviços Eletrônica (NFS-e) junto ao ADN.
⚠️ RESTRIÇÕES: Somente NFS-e com status Autorizada podem ser canceladas.
O campo filtro aceita ChaveNfse ou Código ERP.
post
Path Parameters
filtrostringrequired
ChaveNfse ou Código ERP.
Headers
DocumentoEmissorstringrequired
Documento do emissor.
Body
Body
Dados para o cancelamento da nota fiscal de serviço.
CancelarNotaFiscalInputModel
Dados para cancelamento de nota fiscal (NFe ou NFCe).
* Additional properties are NOT allowed.
justificativastringrequired
Justificativa do cancelamento. (Mínimo de 15 caracteres)
>= 15 characters<= 255 characters
Response
Response
No Content
post/api/v1/Nfse/{filtro}/Cancelar
Authentication
Path Parameters
Headers
Body
{
"justificativa": "justificativa"
}
Listar NFSe´s.
Fornece uma listagem detalhada das Notas Fiscais de Serviços Eletrônicas (NFSe Nacional) emitidas ou processadas pelo Emissor.
🔍 CAPACIDADE DE BUSCA: O recurso suporta filtros complexos que permitem a extração de relatórios e a reconciliação fiscal. O campo busca realiza uma varredura genérica em múltiplos campos (número da DPS, chave, nome e documento do tomador e prestador, descrição do serviço).
📑 PAGINAÇÃO: A API utiliza o modelo de offset e limit. Recomendamos o uso de limites baixos (ex: 50 registros) para garantir a performance da resposta e economia de banda.
⚖️ CONTEXTO FISCAL: Os resultados refletem o estado atual dos documentos na base da Stone Tax, permitindo filtrar por status específicos (Autorizada, Cancelada, Rejeitada, etc.) e intervalos de valores ou datas.
get
Query Parameters
notaFiscalServicoIdstring(uuid)
Filtrar pelo identificador único da nota fiscal de serviço no sistema.
codigoErpstring
Filtrar pelo código ERP.
buscastring
Filtrar pelo termo de busca genérica.
numeroDpsstring
Filtrar pelo número sequencial da DPS.
seriestring
Filtrar pela série da DPS.
chavesarray[string]
Filtrar pela lista de chaves (ChaveDps — 45 chars, ou ChaveNfse — 53 chars).
documentoTomadorstring
Filtrar pelo documento (CPF/CNPJ) do tomador do serviço.
nomeTomadorstring
Filtrar pelo nome ou razão social do tomador do serviço.
documentoPrestadorstring
Filtrar pelo documento (CPF/CNPJ) do prestador do serviço.
nomePrestadorstring
Filtrar pelo nome ou razão social do prestador do serviço.
dataEmissaoInicialstring(date-time)
Filtrar documentos emitidos a partir desta data.
dataEmissaoFinalstring(date-time)
Filtrar documentos emitidos até esta data.
dataCancelamentoInicialstring(date-time)
Filtrar documentos cancelados a partir desta data.
dataCancelamentoFinalstring(date-time)
Filtrar documentos cancelados até esta data.
valorServicoInicialnumber(double)
Filtrar pelo valor mínimo do serviço.
valorServicoFinalnumber(double)
Filtrar pelo valor máximo do serviço.
statusstring
Status da nota fiscal de serviço.
Allowed values:PendenteAutorizadaCanceladaRejeitadaEmCancelamentoSubstituidaInutilizada
ordenarPorstring
Campo pelo qual a listagem de notas fiscais de serviço será ordenada.
Allowed values:DataEmissaoSerieNumeracaoNomeTomador
ordemDecrescenteboolean
Define se a ordenação é decrescente. Padrão: true.
Default:true
offsetinteger(int32)
Paginação da listagem - offset.
Default:1
limitinteger(int32)
Paginação da listagem - limit.
Default:10
Headers
DocumentoEmissorstringrequired
Documento do emissor.
Response
Response
OK
ListarNotasFiscaisServicoViewModelListPaginationResponse
* Additional properties are NOT allowed.
offsetinteger(int32)
limitinteger(int32)
totalinteger(int32)
dataarray | null[object]
Dados de listagem de notas fiscais de serviço eletrônicas (NFS-e Nacional).
* Additional properties are NOT allowed.
Show Child Parameters
get/api/v1/Nfse/Listar