Stone Tax API

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:

  1. Geração e assinatura digital do XML da DPS (Declaração de Prestação de Serviços).

  2. Persistência com status Pendente.

  3. 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

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

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

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

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

No Content

post/api/v1/Nfse/{filtro}/Cancelar

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

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
 

Resumo de NFSe´s.

Fornece dados totalizados e consolidados de notas fiscais de serviço com base nos filtros aplicados.
Este recurso é ideal para alimentar dashboards, painéis de conferência ou indicadores financeiros (KPIs),
permitindo uma visão macro do volume de documentos e valores sem a necessidade de processar a listagem completa.

Os totais são agrupados por status: Aprovadas, Canceladas, Rejeitadas, Pendentes e Substituídas.

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

Headers

DocumentoEmissorstringrequired

Documento do emissor.

Response

OK

ObterTotalizacaoListagemNfseViewModel

Dados totalizados da listagem de notas fiscais de serviço (NFS-e Nacional).

* Additional properties are NOT allowed.
quantidadeTotalNotasinteger(int32)

Quantidade total de notas.

quantidadeTotalNotasAprovadasinteger(int32)

Quantidade total de notas autorizadas.

quantidadeTotalNotasCanceladasinteger(int32)

Quantidade total de notas canceladas.

quantidadeTotalNotasRejeitadasinteger(int32)

Quantidade total de notas rejeitadas.

quantidadeTotalNotasPendentesinteger(int32)

Quantidade total de notas pendentes de emissão.

quantidadeTotalNotasSubstituidasinteger(int32)

Quantidade total de notas substituídas por nova emissão.

valorTotalNotasnumber(double)

Valor total em notas fiscais de serviço.

valorTotalNotasAprovadasnumber(double)

Valor total de notas autorizadas.

valorTotalNotasCanceladasnumber(double)

Valor total de notas canceladas.

valorTotalNotasRejeitadasnumber(double)

Valor total de notas rejeitadas.

valorTotalNotasPendentesnumber(double)

Valor total de notas pendentes de emissão.

valorTotalNotasSubstituidasnumber(double)

Valor total de notas substituídas por nova emissão.

get/api/v1/Nfse/Resumo
 

Status da NFS-e.

Retorna o status de uma nota fiscal de serviço identificada pelo filtro.

🔍 IDENTIFICAÇÃO: O filtro aceita a ChaveNfse ou o Código ERP informado pelo integrador no momento da emissão.

📋 RETORNO: Inclui série, número da DPS, número da NFS-e, chaves, status, protocolo de autorização e mensagem do ADN.

get

Path Parameters

filtrostringrequired

ChaveNfse ou Código ERP.

Headers

DocumentoEmissorstringrequired

Documento do emissor.

Response

OK

ObterStatusFiscalNfseViewModel

Dados fiscais de uma nota fiscal de serviço identificada pelo filtro.

* Additional properties are NOT allowed.
codigoErpstring | null

Identificador da operação fiscal no ERP.

seriestring | null

Série da DPS.

numeroDpsinteger(int64)

Número sequencial da DPS.

numeroNfseinteger | null(int64)

Número sequencial da NFS-e gerado pelo ADN após autorização.

chaveNfsestring | null

Chave de acesso da NFS-e.

dataEmissaostring(date-time)

Data de emissão da DPS.

dataCompetenciastring | null

Mês de competência da prestação do serviço (formato “AAAA-MM”).

tipoAmbientestring

Tipo de ambiente da SEFAZ.

Allowed values:ProducaoHomologacao

statusstring

Status da nota fiscal de serviço.

Allowed values:PendenteAutorizadaCanceladaRejeitadaEmCancelamentoSubstituidaInutilizada

ultimoCstatinteger | null(int32)

Último código de status retornado pela sefaz.

mensagemSefazstring | null

Última mensagem retornada pelo ADN.

protocoloAutorizacaostring | null

Protocolo de autorização emitido pelo ADN.

get/api/v1/Nfse/{filtro}/StatusFiscal