Bem-vindo à API NFS-e Nacional

Cronograma de obrigatoriedade do IBS/CBS

O Ato Conjunto RFB/CGIBS nº 4, de 30/07/2026, definiu quando o preenchimento das informações de IBS e CBS passa a ser obrigatório na emissão de NFS-e. Para prestadores não optantes do Simples Nacional: 01/10/2026 para os serviços em geral da lista da LC 116, e 01/12/2026 para os subitens 1.03, 1.05, 1.09 e 16.01, locações, condomínio, bens imateriais e serviços de plataformas digitais.

Optantes do Simples Nacional (inclusive MEI) só a partir de 01/01/2027.

A partir da data aplicável ao serviço, notas sem essas informações serão rejeitadas pelo Ambiente de Dados Nacional (ADN) da Receita Federal.

O que muda na API: a partir da data aplicável, requisições de emissão sem o grupoibscbs passam a ser rejeitadas comHTTP 422. O segmento é determinado pelocodigo_tributacao_nacionalda nota, e o enquadramento no Simples é apurado no cadastro municipal, na competência — não pelo campo enviado no payload. O leiaute 1.00 não comporta o grupo: migre para a versão 1.01 antes da data.

Consulte a fonte oficial (comunicado do CGIBS) ↗

Em produção

Esta é a API oficial para emissão de Notas Fiscais de Serviço Eletrônicas (NFS-e) conforme o padrão nacional NFS-e (Adendo Técnico v1.01 do CGNFS-e).

Base URL:https://tributario.speedgov.com.br

Importante: Todas as URLs devem incluir o prefixo do município (tenant).
Exemplo:/{municipio}/api/v1/nfse →/ibicuitinga/api/v1/nfse

Baixar Coleção Postman

Emissão

Emita NFS-e através de DPS (Declaração de Prestação de Serviços) em formato XML

Consulta

Consulte notas fiscais emitidas através da chave de acesso

Eventos

Registre eventos como cancelamento ou substituição de notas

DANFSEDepreciado

Depreciado — consulte o DANFSe pela chave no portal nacional (nfse.gov.br/ConsultaPublica)

Fluxo de Integração

Preparar DPS

XML Schema v1.0

Emitir NFS-e

POST /nfse

Consultar

GET /nfse/:chave

Download PDF

GET /danfse/:chave

Ciclo de Vida da NFS-e

Pendente

Autorizada

Cancelada

Substituída

Especificações Técnicas

Formato

XML Schema v1.0

Protocolo

HTTP/HTTPS REST

Encoding

UTF-8

Response

JSON

O que é DPS?

DPS (Declaração de Prestação de Serviços) é o documento XML que contém todas as informações da prestação de serviço e que será transformado em NFS-e após o processamento.

A DPS deve conter: dados do prestador, tomador, serviço prestado, valores, tributos e local da prestação. Após validação, o sistema gera automaticamente a NFS-e com chave de acesso única.

Guia Rápido - Primeiros Passos

Comunicação Cliente ↔ API

Seu Sistema

API NFS-e

POST /nfse + XML DPS

JSON { chave_acesso, numero_protocolo }

GET /nfse/:chave_acesso

JSON { nota: { dados completos } }

GET /danfse/:chave_acesso

application/pdf (DANFSE)

1Prepare seu XML DPS

Primeiro, você precisa criar o arquivo XML com os dados da prestação de serviço. Veja um exemplo mínimo funcional:

dps_exemplo.xml

<?xml version="1.0" encoding="UTF-8"?>
<DPS versao="1.01" xmlns="http://www.sped.fazenda.gov.br/nfse">
      <infDPS Id="DPS230533221122233300018180000177920370165622">
        <tpAmb>2</tpAmb>
        
        <verAplic>1.01</verAplic>
        <serie>80000</serie>
        <nDPS>177920370165622</nDPS>
        <dCompet>2026-05-19</dCompet>
        <tpEmit>1</tpEmit>
        <cLocEmi>2301000</cLocEmi>
        <prest>
          <CNPJ>11222333000181</CNPJ>
          <IM>123456</IM>
          <xNome>Prestador Teste LTDA</xNome>
          <fone>11999999999</fone>
          <email>prestador@teste.com</email>
          <regTrib>
            <opSimpNac>1</opSimpNac>
            <regEspTrib>0</regEspTrib>
          </regTrib>
        </prest>
        <toma>
          <CNPJ>12345678000195</CNPJ>
          <xNome>Tomador Teste</xNome>
          <end>
            <endNac>
              <cMun>2301000</cMun>
              <CEP>12345678</CEP>
            </endNac>
            <xLgr>Rua Teste</xLgr>
            <nro>100</nro>
            <xBairro>Centro</xBairro>
          </end>
          <fone>11888888888</fone>
          <email>tomador@teste.com</email>
        </toma>
        <serv>
          <locPrest>
            <cLocPrestacao>2301000</cLocPrestacao>
          </locPrest>
          <cServ>
            <cTribNac>010101</cTribNac>
            <cTribMun>16100100</cTribMun>
            <xDescServ>Serviço de teste para homologação do sistema de NFS-e</xDescServ>
            <cNBS>101011100</cNBS>
          </cServ>
        </serv>
        <valores>
          <vServPrest>
            <vServ>1000.00</vServ>
          </vServPrest>
          <trib>
            <tribMun>
              <tribISSQN>1</tribISSQN>
              <tpRetISSQN>1</tpRetISSQN>
              <pAliq>5.00</pAliq>
            </tribMun>
            <totTrib>
              <indTotTrib>0</indTotTrib>
            </totTrib>
          </trib>
        </valores>
      </infDPS>
    </DPS>

Campos importantes:

tpAmb - Tipo de ambiente: 1=Produção, 2=Homologação
dCompet - Data de competência do serviço (obrigatória)
prest/CNPJ - CNPJ do prestador (deve estar cadastrado no município)
serv/locPrest/cLocPrestacao - Código IBGE do município onde o serviço foi prestado
serv/cServ/cTribNac - Código de tributação nacional (item da LC 116/03)
serv/cServ/cNBS - Código NBS (Nomenclatura Brasileira de Serviços) — obrigatório na v1.01
ibscbs - Grupo IBS/CBS (Reforma Tributária, LC 214/2025). OBRIGATÓRIO conforme o cronograma do Ato Conjunto RFB/CGIBS nº 4/2026: 01/10/2026 para os serviços em geral, 01/12/2026 para os subitens 1.03, 1.05, 1.09 e 16.01 e demais segmentos prorrogados, e 01/01/2027 para optantes do Simples Nacional — requisições sem o grupo passam a ser rejeitadas com HTTP 422. O segmento vem do codigo_tributacao_nacional; o enquadramento no Simples é apurado no cadastro municipal, na competência da nota, e não pelo campo enviado no payload
ibscbs/valores/trib/gIBSCBS/CST - Código de Situação Tributária do IBS/CBS (3 dígitos)
ibscbs/valores/trib/gIBSCBS/cClassTrib - Código de Classificação Tributária (6 dígitos). Precisa existir e estar ativo | na tabela de classificações vigente; caso contrário a nota é recusada com HTTP 422 | e mensagem indicando o código não encontrado. A tabela é a publicada pela RFB e | pode ser renumerada por ela — confira o código em uso antes de integrar
ibscbs - Em operação sem IBS/CBS a apurar (imunidade/não-incidência e isenção), o DPS | informa apenas CST e cClassTrib: o leiaute não transporta alíquota. As alíquotas | e os totais de IBS/CBS são apurados pelo município e retornam zerados na NFS-e
valores/vServPrest/vServ - Valor total do serviço
valores/trib/tribMun/tribISSQN - Tributação do ISSQN: 1=tributável, 2=imune, 3=isento
valores/trib/tribMun/pAliq - Alíquota do ISS (%) — o ISS é calculado pela ADN, não envie vISSQN
valores/trib/tribFed - (Opcional) Tributos federais: PIS/COFINS de apuração própria e os valores | retidos na fonte. Ver a seção abaixo
valores/vDedRed - (Opcional) Dedução/redução da base:vDR (valor) oupDR (percentual)
valores/vDescCondIncond - (Opcional) Descontos:vDescIncond (incondicionado) evDescCond (condicionado)
valores/trib/tribMun/bM - (Opcional) Benefício municipal de redução de base:pRedBCBM (percentual) ouvRedBCBM (valor)
valores/trib/tribMun/exigSusp - (Opcional) Suspensão da exigibilidade do ISSQN. Quando informado, exigetpSusp (1=decisão judicial, 2=processo administrativo) enProcesso (exatamente 30 dígitos). Com a suspensão informada, o leiaute admite apenasvLiq no grupo de valores (E1311): não enviepAliq,vBC,vISSQN nemvISSQNRet. A nota é escriturada como suspensa e não gera crédito de ISSQN. Só é aceita emtribISSQN=1 (E0585)

Quando informados, esses redutores são considerados na apuração da base de cálculo do ISSQN.

Suspensão da exigibilidade do ISSQN (exigSusp)

Use quando houver decisão judicial ou processo administrativo que suspenda a exigibilidade do ISSQN sobre o serviço. A ordem dos elementos dentro detribMun segue a sequência do XSD e é validada pelo Ambiente Nacional:tribISSQN,cPaisResult,tpImunidade,exigSusp,BM,tpRetISSQN,pAliq. Enviar fora dessa ordem resulta em rejeição.

<valores>
  <vServPrest>
    <vServ>1000.00</vServ>
  </vServPrest>
  <trib>
    <tribMun>
      <tribISSQN>1</tribISSQN>
      <exigSusp>
        <tpSusp>1</tpSusp>
        <nProcesso>000000000000012345620248060001</nProcesso>
      </exigSusp>
      <tpRetISSQN>1</tpRetISSQN>
    </tribMun>
  </trib>
</valores>

OnProcesso tem exatamente 30 dígitos, sem pontuação. Um número CNJ tem 20 dígitos — complete com zeros à esquerda, preservando os 20 finais. A retenção do ISSQN não é permitida com a exigibilidade suspensa, portanto envietpRetISSQN=1.

Tributos federais (tribFed)

Grupo opcional. Use para declarar o PIS e a COFINS de apuração própria do prestador e os valores retidos na fonte. O grupo é aceito nas duas versões do leiaute — na1.01 ele convive com o grupoIBSCBS, que fica em outro nível do documento e não o substitui.

valores/trib/tribFed/piscofins/CST - Código de Situação Tributária do PIS/COFINS, com dois dígitos (ex.:01). Obrigatório quando o subgrupopiscofins for informado
valores/trib/tribFed/piscofins/vBCPisCofins - Base de cálculo. Deve ser menor ou igual ao valor do serviço (E0677)
valores/trib/tribFed/piscofins/pAliqPis epAliqCofins - Alíquotas (%), entre 0 e 100 (E0686 e E0692)
valores/trib/tribFed/piscofins/vPis evCofins - Quando a alíquota correspondente for informada, o valor precisa ser igual a base × alíquota, com tolerância de 0,01 (E0694 e E0696)
valores/trib/tribFed/piscofins/tpRetPisCofins - Indica quais contribuições retidas na fonte compõem ovRetCSLL: 0=nenhuma, 1=PIS/COFINS, 2=PIS/COFINS não retidos, 3=PIS/COFINS/CSLL, 4=PIS/COFINS retidos e CSLL não, 5=só PIS, 6=só COFINS, 7=COFINS/CSLL, 8=só CSLL, 9=PIS/CSLL
valores/trib/tribFed/vRetCP,vRetIRRF evRetCSLL - Valores retidos de contribuição previdenciária, imposto de renda e contribuições sociais. Quando informados, devem ser maiores que zero e menores que o valor do serviço (E0699, E0700 e E0701)

A ordem dos elementos segue a sequência do XSD e é validada pelo Ambiente Nacional: dentro detribFed vêmpiscofins,vRetCP,vRetIRRF evRetCSLL; dentro depiscofins,CST,vBCPisCofins,pAliqPis,pAliqCofins,vPis,vCofins etpRetPisCofins. Enviar fora dessa ordem resulta em rejeição.

<trib>
  <tribMun>
    <tribISSQN>1</tribISSQN>
    <tpRetISSQN>1</tpRetISSQN>
    <pAliq>3.00</pAliq>
  </tribMun>
  <tribFed>
    <piscofins>
      <CST>01</CST>
      <vBCPisCofins>1000.00</vBCPisCofins>
      <pAliqPis>0.65</pAliqPis>
      <pAliqCofins>3.00</pAliqCofins>
      <vPis>6.50</vPis>
      <vCofins>30.00</vCofins>
      <tpRetPisCofins>0</tpRetPisCofins>
    </piscofins>
  </tribFed>
</trib>

PIS e COFINS próprios não são retenção. Os valores devPis evCofins são débito de apuração própria e não entram no total de retenções da nota — esse total soma apenasvRetCP,vRetIRRF,vRetCSLL e o ISSQN retido. O PIS/COFINS retido na fonte é declarado dentro dovRetCSLL, conforme otpRetPisCofins
ComtpRetPisCofins=0 não informevRetCSLL (E0720). Com qualquer valor diferente de 0 e de 2, ovRetCSLL passa a ser obrigatório (E0724)
Emitente identificado como MEI não pode informar tributos federais (E0676)
Em competências de 2026, o PIS e a COFINS informados são deduzidos da base de cálculo do IBS/CBS, junto do ISSQN, dos descontos incondicionados e do reembolso. A partir de 2027 essa dedução deixa de se aplicar

Importante - Data de Emissão:

A data/hora de emissão (dhEmi) é geradaautomaticamente pelo sistema no momento da criação da nota.NÃO envie este campo no XML. Envie apenas a data de competência (dCompet).

2Envie a requisição

Use o comando curl para enviar o XML ao endpoint de emissão:

Terminal

curl -X POST https://tributario.speedgov.com.br/{municipio}/api/v1/nfse/v101 \
  -H "Content-Type: application/xml" \
  -H "Accept: application/json" \
  --data @dps_exemplo.xml

# Exemplo com município específico:
curl -X POST https://tributario.speedgov.com.br/ibicuitinga/api/v1/nfse/v101 \
  -H "Content-Type: application/xml" \
  -H "Accept: application/json" \
  --data @dps_exemplo.xml

Resposta de Sucesso (200 OK)

{
  "status": "OK",
  "numero_protocolo": "20251111120000000001",
  "chave_acesso": "35503081234567800019500010...",
  "xml_nfse": "..."
}

Resposta de Erro (422)

{
  "codigo_erro": "E101",
  "mensagem": "Estabelecimento não encontrado",
  "detalhes": "O CNPJ não está cadastrado",
  "timestamp": "2025-11-11T12:00:00-03:00"
}

3Consulte a NFS-e emitida

Após a emissão, você pode consultar a nota pela chave de acesso:

Terminal

curl -X GET https://tributario.speedgov.com.br/{municipio}/api/v1/nfse/23044002300600973590300001000000000000011264046313 \
  -H "Accept: application/json"

# Exemplo:
curl -X GET https://tributario.speedgov.com.br/ibicuitinga/api/v1/nfse/23044002300600973590300001000000000000011264046313 \
  -H "Accept: application/json"

4Baixe o PDF (DANFSE)

Endpoint depreciado

Este endpoint está depreciado e será removido futuramente. Após a autorização no ADN, consulte o DANFSe oficial pela chave de acesso no portal nacional (https://www.nfse.gov.br/ConsultaPublica). O XML da NFS-e fica disponível no endpoint de consulta da nota (GET /{municipio}/api/v1/nfse/:chave_acesso ou por protocolo), permitindo montar a própria representação gráfica.

Para obter o PDF da nota fiscal:

Terminal

curl -X GET https://tributario.speedgov.com.br/{municipio}/api/v1/danfse/23044002300600973590300001000000000000011264046313 \
  -H "Accept: application/pdf" \
  -o nota_fiscal.pdf

# Exemplo:
curl -X GET https://tributario.speedgov.com.br/ibicuitinga/api/v1/danfse/23044002300600973590300001000000000000011264046313 \
  -H "Accept: application/pdf" \
  -o nota_fiscal.pdf

Próximos Passos

Agora que você conhece o fluxo básico, explore:

Endpoints - Documentação completa de todos os endpoints
Exemplos - Casos de uso mais complexos

Códigos de Erro - Tratamento de erros e validações
Status - Monitoramento da disponibilidade da API

Referência Completa da API

Prefixo de Município: Todas as URLs devem ser prefixadas com o slug do município.Exemplo:/{municipio}/api/v1/nfse onde{municipio} é o slug do município (ex: ibicuitinga, davinopolis).

A `chave_acesso` e o status de autorização

A chave_acesso (50 dígitos) retornada no POST de emissão é estável : ela é gerada na emissão e não muda de valor . O envio ao Ambiente Nacional (ADN) é assíncrono, mas a chave gerada localmente é exatamente a mesma que o ADN confirma ao autorizar a nota. Use-a como identificador da NFS-e.

Toda resposta inclui o campo chave_acesso_provisoria (booleano), que indica apenas o status de autorização da nota — não que a chave mude de valor:

Valor	Significado	Ação recomendada
`true`	A nota ainda não foi autorizada pelo ADN (status rascunho). A `chave_acesso` já é definitiva e não mudará.	Use a `chave_acesso` normalmente; acompanhe a autorização via `GET /api/v1/nfse/:chave_acesso` .
`false`	A nota já foi autorizada pelo ADN. A `chave_acesso` é a mesma desde a emissão.	Use a chave no endpoint de consulta da nota (GET /api/v1/nfse/:chave_acesso).

Resumo prático: a chave_acesso não muda — guarde-a na emissão e use-a como identificador da nota. O campo chave_acesso_provisoria apenas informa se a nota já foi autorizada pelo ADN. O endpoint GET /api/v1/nfse/protocolo/:numero_protocolo permanece disponível ( depreciado ) para integrações existentes.

POST/{municipio}/api/v1/nfse

Descontinuado

Emissão descontinuada. Este endpoint não emite mais NFS-e e responde HTTP 410 (Gone) . Utilize POST /api/v1/nfse/v101 para emitir no layout nacional vigente. As consultas GET /api/v1/nfse/:chave_acesso e GET /api/v1/nfse/protocolo/:numero_protocolo permanecem disponíveis.

Emitir NFS-e (descontinuado)

Qualquer requisição a POST /api/v1/nfse passa a retornar o erro E111 com HTTP 410 , indicando o endpoint correto.

Resposta (HTTP 410 Gone)

{
  "codigo_erro": "E111",
  "mensagem": "A emissão de NFS-e pelo endpoint v1.00 foi descontinuada. Utilize POST /api/v1/nfse/v101.",
  "detalhes": { "endpoint_correto": "/api/v1/nfse/v101" }
}

GET/{municipio}/api/v1/nfse/protocolo/:numero_protocolo

Depreciado

Endpoint depreciado. Como a chave_acesso é estável desde a emissão, prefira GET /api/v1/nfse/:chave_acesso . Este endpoint permanece disponível (sem data de remoção) para integrações existentes.

Consultar NFS-e por número de protocolo

Retorna a nota fiscal identificada pelo numero_protocolo — um identificador estável, 1:1 com a nota, alternativo à chave_acesso (que também é estável). Útil para integrações que já persistiram o numero_protocolo retornado na emissão.

Este endpoint funciona tanto para notas emitidas via POST /api/v1/nfse (v1.00 — emissão descontinuada) quanto via POST /api/v1/nfse/v101 (v1.01 estrita). O caminho /api/v1/nfse/v101/protocolo/:numero_protocolo também é válido.

Parâmetros

Parâmetro	Tipo	Descrição
`numero_protocolo`	string	Número de protocolo retornado na criação da nota (campo `numero_protocolo` da resposta de `POST /api/v1/nfse/v101` ).

Response

200 OK	Nota encontrada
404	Protocolo não encontrado

Observações de tipos:

valor_servico , valor_issqn , valor_base_calculo , aliquota_issqn são strings decimais (ex.: "1000.00" ), não numbers — faça parsing decimal no seu lado.
data_competencia vem em formato BR "DD/MM/YYYY" .
data_emissao e data_protocolo vêm em formato "YYYY-MM-DD HH:MM:SS ±HHMM" .
codigo_situacao_nfse é integer ( 100 ) ou null .
numero_dps é o número sequencial da NFS-e (integer); numero é string ou null (até a autorização).
numero_dps_nacional é o nDPS transmitido ao Ambiente Nacional — o número que aparece no portal nacional e o usado na consulta por DPS ( GET /api/v1/dps/:id ). Reflete o numero_dps informado; quando omitido, é o número sequencial da NFS-e. serie_dps_nacional é a série correspondente — a informada, ou 70000 quando omitida. Ambos ficam null enquanto a DPS não foi transmitida ao ADN.
xml_nota devolve a NFS-e autorizada pelo ADN quando disponível; antes da autorização, devolve a DPS assinada que foi enviada. Pode ser null enquanto a nota está em rascunho (sem XML gerado ainda).

Exemplo de Resposta — Nota em rascunho (ainda não autorizada)

A chave_acesso (50 dígitos) é a mesma em rascunho e após a autorização — não muda de valor. A flag chave_acesso_provisoria apenas indica se a nota já foi autorizada pelo ADN ( true = ainda em rascunho).

{
  "status": "OK",
  "nota": {
    "id": 28579,
    "numero": null,
    "serie_dps": "001",
    "numero_dps": 1,
    "serie_dps_nacional": null,
    "numero_dps_nacional": null,
    "chave_acesso": "23044002300600973590300001000000000000011264046313",
    "identificador": "IDNFS23044002300600973590300001000000000000011264046313",
    "status": "rascunho",
    "versao": "1.01",
    "data_emissao": null,
    "data_competencia": "06/01/2026",
    "codigo_situacao_nfse": null,
    "prestador_cpf_cnpj": "12345678000195",
    "prestador_razao_social": "Empresa Prestadora LTDA",
    "prestador_inscricao_municipal": "12345",
    "tomador_cpf_cnpj": "12345678901",
    "tomador_razao_social": "João da Silva",
    "valor_servico": "1000.00",
    "valor_issqn": "50.00",
    "valor_base_calculo": "1000.00",
    "aliquota_issqn": "5.00",
    "xml_nota": null
  },
  "protocolo": {
    "numero_protocolo": "20251111120000000001",
    "status": "processando",
    "mensagem_retorno": null,
    "data_protocolo": "2025-11-11 12:00:00 -0300",
    "chave_acesso": "23044002300600973590300001000000000000011264046313"
  },
  "chave_acesso_provisoria": true
}

Exemplo de Resposta — Nota autorizada pelo ADN (mesma chave_acesso)

{
  "status": "OK",
  "nota": {
    "id": 28579,
    "numero": "1",
    "serie_dps": "001",
    "numero_dps": 1,
    "serie_dps_nacional": "1",
    "numero_dps_nacional": "1",
    "chave_acesso": "23044002300600973590300001000000000000011264046313",
    "identificador": "IDNFS23044002300600973590300001000000000000011264046313",
    "status": "autorizada",
    "versao": "1.01",
    "data_emissao": "2025-11-11 12:05:32 -0300",
    "data_competencia": "06/01/2026",
    "codigo_situacao_nfse": 100,
    "prestador_cpf_cnpj": "12345678000195",
    "prestador_razao_social": "Empresa Prestadora LTDA",
    "prestador_inscricao_municipal": "12345",
    "tomador_cpf_cnpj": "12345678901",
    "tomador_razao_social": "João da Silva",
    "valor_servico": "1000.00",
    "valor_issqn": "50.00",
    "valor_base_calculo": "1000.00",
    "aliquota_issqn": "5.00",
    "xml_nota": "..."
  },
  "protocolo": {
    "numero_protocolo": "20251111120000000001",
    "status": "autorizado",
    "mensagem_retorno": "Autorizado pelo ADN",
    "data_protocolo": "2025-11-11 12:00:00 -0300",
    "chave_acesso": "23044002300600973590300001000000000000011264046313"
  },
  "chave_acesso_provisoria": false
}

Exemplo de Resposta — Protocolo não encontrado (404)

Para tratamento programático use o status HTTP 404 e o campo campo da resposta. A descrição da mensagem pode evoluir; prefira tratar pelo campo estruturado.

{
  "codigo_erro": "E601",
  "mensagem": "Nota fiscal a ser substituída não encontrada",
  "detalhes": "Numero de protocolo 20251111120000000001 nao encontrado",
  "campo": "numero_protocolo",
  "timestamp": "2025-11-11T12:00:00-03:00"
}

Acompanhar a autorização: a chave_acesso já é definitiva desde a emissão; para saber quando a nota foi autorizada pelo ADN, re-consulte periodicamente até chave_acesso_provisoria virar false (backoff exponencial recomendado). Não há SLA contratual — o tempo depende do tráfego do ADN e do agendamento do job de envio de lote.

GET/{municipio}/api/v1/nfse/:chave_acesso

Consulta

Consultar NFS-e

Consulta uma nota fiscal emitida pela chave de acesso.

A resposta inclui o objeto protocolo (pode ser null se a nota não tiver protocolo associado). Diferente do GET /api/v1/nfse/protocolo/:numero_protocolo , este endpoint não retorna a flag chave_acesso_provisoria .

Parâmetros

Parâmetro	Tipo	Descrição
`chave_acesso`	string	Chave de 50 caracteres

Response

200 OK	Nota encontrada
404	Nota não encontrada

Exemplo de Resposta

{
  "status": "OK",
  "nota": {
    "id": 28579,
    "numero": "1",
    "serie_dps": "001",
    "numero_dps": 1,
    "serie_dps_nacional": "1",
    "numero_dps_nacional": "1",
    "chave_acesso": "23044002300600973590300001000000000000011264046313",
    "identificador": "IDNFS23044002300600973590300001000000000000011264046313",
    "status": "autorizada",
    "versao": "1.01",
    "data_emissao": "2025-11-11 12:00:00 -0300",
    "data_competencia": "06/01/2026",
    "codigo_situacao_nfse": 100,
    "prestador_cpf_cnpj": "12345678000195",
    "prestador_razao_social": "Empresa Prestadora LTDA",
    "prestador_inscricao_municipal": "12345",
    "tomador_cpf_cnpj": "12345678901",
    "tomador_razao_social": "João da Silva",
    "valor_servico": "1000.00",
    "valor_issqn": "50.00",
    "valor_base_calculo": "1000.00",
    "aliquota_issqn": "5.00",
    "xml_nota": "..."
  },
  "protocolo": {
    "numero_protocolo": "20251111120000000001",
    "status": "autorizado",
    "mensagem_retorno": "Autorizado pelo ADN",
    "data_protocolo": "2025-11-11 12:00:00 -0300",
    "chave_acesso": "23044002300600973590300001000000000000011264046313"
  }
}

GET/{municipio}/api/v1/danfse/:chave_acessoDepreciado

PDF

Endpoint depreciado

Será removido futuramente. Após a autorização no ADN, consulte o DANFSe oficial pela chave de acesso no portal nacional (https://www.nfse.gov.br/ConsultaPublica). O XML da NFS-e fica disponível no endpoint de consulta da nota (GET /{municipio}/api/v1/nfse/:chave_acesso ou por protocolo), permitindo montar a própria representação gráfica. As respostas deste endpoint incluem os cabeçalhos Deprecation, Link e Warning.

Download DANFSE

Retorna o PDF da nota fiscal (Documento Auxiliar da NFS-e), apenas para notas autorizadas.

Parâmetros

Parâmetro	Tipo	Descrição
`chave_acesso`	string	Chave de 50 caracteres

Response

Content-Type	`application/pdf`
200 OK	Arquivo PDF
404	Nota não encontrada
422	Nota não está autorizada

Dica: Use o parâmetro-o nome_arquivo.pdf no curl para salvar o PDF localmente.

POST/{municipio}/api/v1/nfse/:chave_acesso/eventos

Eventos

Registrar Evento

Registra um evento na NFS-e (cancelamento, confirmação, rejeição, etc).

Tipos de Evento e Códigos CGOA

Códigos do padrão nacional NFS-e (CGOA) aceitos no tipo_evento.

Código CGOA	tipo_evento (slug)
`101101`	`cancelamento`
`105102`	`cancelamento_por_substituicao`
`101103`	`solicitacao_analise_fiscal_para_cancelamento`
`105104`	`cancelamento_deferido_por_analise_fiscal`
`105105`	`cancelamento_indeferido_por_analise_fiscal`
`202201`	`confirmacao_prestador`
`203202`	`confirmacao_tomador`
`204203`	`confirmacao_intermediario`
`205204`	`confirmacao_tacita`
`202205`	`rejeicao_prestador`
`203206`	`rejeicao_tomador`
`204207`	`rejeicao_intermediario`
`205208`	`anulacao_rejeicao`
`305101`	`cancelamento_por_oficio`
`305102`	`bloqueio_por_oficio`
`305103`	`desbloqueio_por_oficio`

Campos obrigatórios por tipo (motivos enumerados, descrições, etc) podem ser consultados em GET /:tenant/api/v1/catalogo/motivos_evento

Autor do evento (cnpj_autor / cpf_autor)

Campos opcionais. Quando omitidos, o autor é inferido a partir do tipo_eventoe dos dados da nota:

cancelamento,cancelamento_por_substituicao,solicitacao_analise_fiscal_para_cancelamento,confirmacao_prestador,rejeicao_prestador→ CPF/CNPJ do prestador da nota.
confirmacao_tomador,rejeicao_tomador→ CPF/CNPJ do tomador.
confirmacao_intermediario,rejeicao_intermediario→ CPF/CNPJ do intermediário.

Para sobrescrever a inferência, envie cnpj_autor(14 dígitos) oucpf_autor(11 dígitos). Os dois campos são mutuamente exclusivos.

Exemplo de requisição (cancelamento)

curl -X POST "https://tributario.speedgov.com.br/{tenant}/api/v1/nfse/:chave_acesso/eventos" \
     -H "Content-Type: application/json" \
     -H "X-Evento-Assinatura: " \
     -d '{
       "tipo_evento": "cancelamento",
       "codigo_motivo_cancelamento": "erro_na_emissao",
       "descricao_motivo_cancelamento": "Erro no valor do serviço"
     }'

Resposta de sucesso (HTTP 201)

O mesmo conjunto de campos é retornado pelos endpoints GETde evento (consistência POST↔GET).

{
  "id_evento": 638,
  "codigo_tipo_evento": "101101",
  "tipo_evento": "cancelamento",
  "numero_sequencial": 1,
  "numero_protocolo": "20260508122141000001",
  "chave_acesso": "...",
  "data_hora_evento": "2026-05-13T10:30:50-03:00",
  "data_hora_processamento": null,
  "aguardando_desde": null,
  "status_evento": "pendente",
  "protocolo": null,
  "codigo_retorno": null,
  "mensagem_retorno": null,
  "erros_adn": null,
  "reprocessamentos_count": 0,
  "ultimo_reprocessamento_em": null,
  "acao_sugerida": "aguardar",
  "descricao_evento": "Cancelamento de NFS-e",
  "mensagem": "Evento de cancelamento registrado com sucesso. Acompanhe em GET /api/v1/nfse/:chave/eventos/:tipo/:num_seq.",
  "status": "OK"
}

Significado de`acao_sugerida`

Recomendação de próximo passo para o integrador.

aguardar— evento em processamento normal (pendente recente, enviado, aguardando ADN dentro de 24h).
consultar_suporte— evento em estado problemático (erro sem retry disponível, pendente travado > 5 min, aguardando ADN > 24h ou erro_reprocessamento).
retentar— evento em errocom código reprocessável.
cancelado_ok— evento finalizado com sucesso ( processado,canceladoou dispensado).

Códigos de retorno HTTP

201 Created— evento registrado.
404 Not Found— nota fiscal não encontrada para a chave_acesso informada.
409 Conflict— colisão concorrente no número sequencial do evento após retry (raro, requer nova tentativa do cliente).
422 Unprocessable Entity— validação falhou (tipo_evento inválido, campos obrigatórios ausentes) ou já existe outro cancelamento desta nota em processamento (estados não-terminais).

Endpoint equivalente:o evento também pode ser registrado pelo numero_protocolo(identificador alternativo; a chave_acesso já é estável desde a emissão): POST /{municipio}/api/v1/nfse/protocolo/:numero_protocolo/eventos— payload e response idênticos ao endpoint por chave_acesso.

GET/{municipio}/api/v1/nfse/:chave_acesso/eventos

Eventos

Listar Eventos da NFS-e

Retorna todos os eventos vinculados à chave de acesso, ordenados por code.mx-1 created_at DESC | .

Resposta de sucesso (HTTP 200)

{
  "total": 2,
  "eventos": [
    { ...mesmo conjunto de campos do POST... },
    { ... }
  ],
  "status": "OK"
}

Cada item da lista contém o mesmo conjunto de campos descrito em Registrar Evento.

GET/{municipio}/api/v1/nfse/:chave_acesso/eventos/:tipo_evento

Eventos

Consultar Eventos por Tipo

Retorna apenas eventos do especificado (ex: cancelamento), ordenados pornumero_sequencial ASC.

Resposta de sucesso (HTTP 200)

{
  "total": 1,
  "tipo_evento": "cancelamento",
  "eventos": [
    { ...mesmo conjunto de campos do POST... }
  ],
  "status": "OK"
}

GET/{municipio}/api/v1/nfse/:chave_acesso/eventos/:tipo_evento/:num_seq_evento

Eventos

Consultar Evento Específico

Retorna um único evento identificado pela combinação .

Resposta de sucesso (HTTP 200)

{
  "evento": { ...mesmo conjunto de campos do POST... },
  "status": "OK"
}

404 Not Found— nota ou evento não encontrado para os parâmetros informados.

Perguntas frequentes — Fluxo de cancelamento

Respostas para dúvidas recorrentes de integradores sobre o ciclo de cancelamento de NFS-e.

Pergunta	Como obter
Como sei a data em que a nota foi cancelada?	Campo `data_cancelamento`no `GET /api/v1/nfse/:chave_acesso`. Retornado quando;`null`para notas autorizadas.
Como consulto o protocolo de um cancelamento que eu fiz?	O `POST /eventos`retorna `numero_sequencial`. Com ele, use`GET /api/v1/nfse/:chave_acesso/eventos/:tipo_evento/:num_seq_evento`para acompanhar o evento específico. Para ver todos os eventos da nota, use `GET /api/v1/nfse/:chave_acesso/eventos`.
A consulta da nota nunca muda para`cancelada`: como saber se o cancelamento falhou?	Consulte o evento(não a nota). O response traz `status_evento`,`codigo_retorno`,`mensagem_retorno`e `erros_adn`. O campo`acao_sugerida`já indica em uma palavra o que fazer: aguardar, retentar ou `consultar_suporte`(quando há erro persistente).
Como saber se o cancelamento ainda está em processamento?	Leia `acao_sugerida`no payload do evento. Valores possíveis: `aguardar`(em processamento normal), `retentar`(erro transitório, pode tentar de novo), `consultar_suporte`(estado persistente, acionar suporte), `cancelado_ok`(finalizado com sucesso).
Preciso enviar`cnpj_autor`/`cpf_autor`?	Não é obrigatório. Quando omitido, o autor é inferido a partir do `tipo_evento`: cancelamentos usam o documento do prestador da nota; manifestações de tomador (`confirmacao_tomador`,`rejeicao_tomador`) usam o documento do tomador; manifestações de intermediário usam o documento do intermediário. Envie explicitamente apenas para sobrescrever o padrão.

Fluxo recomendado:(1) registre o cancelamento via POSTe guarde numero_sequencialdo response; (2) consulte o evento por GETaté (sucesso) ou "consultar_suporte"(acionar suporte); (3) a data_cancelamentofica disponível no GET da nota quando o cancelamento for efetivado.

Histórico de Eventos da NFS-e

Use o GET /api/v1/nfse/:chave_acesso/eventospara reconstruir a linha do tempo completa de eventos da nota — a lista vem ordenada do mais recente para o mais antigo. Cada evento traz seu próprio numero_sequencialpor tipo_evento, permitindo ordenar cronologicamente também dentro de um mesmo tipo.

Campos temporais

data_hora_evento— quando o evento foi criado (momento do POST).
data_hora_processamento— quando o ADN deu palavra final ( nullenquanto pendente/aguardando).
aguardando_desde— início da espera quando .
ultimo_reprocessamento_em— timestamp do último retry automático.
reprocessamentos_count— contador cumulativo de retries (0 a 3; após 3 sem sucesso o evento vai para erro).

Estados possíveis em`status_evento`

status_evento	Semântica
`pendente`	Evento criado, ainda não enviado ao ADN.
`enviado`	Pacote enviado ao ADN, aguardando retorno.
`aguardando_autorizacao_nota`	ADN respondeu mas a nota referenciada ainda não foi reconhecida. O sistema retenta automaticamente quando a nota é autorizada.
`processado`	ADN concluiu o processamento com sucesso.
`rejeitado`	ADN rejeitou o evento (motivo em code.mx-1 erros_adn \| ).
`erro`	Erro local ou do ADN, ainda elegível a retry conforme code.mx-1 reprocessamentos_count \| .
`erro_reprocessamento`	Evento marcado em ciclo anterior como exigindo análise manual via suporte. Não é retentado automaticamente.
`cancelado`	Evento cancelado localmente.
`dispensado`	Evento dispensado de envio ao ADN.

Interpretando o estado atual

Para decidir o próximo passo sem precisar interpretar cada campo manualmente, leia acao_sugerida— vem em todo payload de evento (POST e GETs). Mapa de decisão:

aguardar— fluxo normal (recente ou dentro de janelas saudáveis); volte a consultar em alguns minutos.
retentar— erro com código reprocessável; tente o mesmo evento novamente.
consultar_suporte— estado persistente que exige acompanhamento humano (erro sem retry, travado, ou erro_reprocessamento).
cancelado_ok— evento já finalizado em estado terminal de sucesso ( processado,canceladoou dispensado).

Exemplos de Integração

Coleção Postman - Todos os Exemplos

A coleção Postman contém exemplos prontos para todos os endpoints da API, incluindo XMLs de exemplo, respostas de sucesso e erro.

Emissão

XML DPS completo com todos os campos

Consulta

Busca por chave de acesso

DANFSEDepreciado

Download do PDF (depreciado)

Eventos

Cancelamento, Substituição, etc.

Baixar Coleção Postman

Como Usar a Coleção

Passo a Passo

Baixe a coleção clicando no botão acima
Abra o Postman e vá em File → Import
Selecione o arquivo JSON baixado
A variável base_url já vem configurada
Explore os exemplos em cada pasta e execute as requisições

Estrutura das Pastas

API NFS-e Nacional/
├── Emissão/
│   └── Emitir NFS-e (POST /nfse)
├── Consulta/
│   └── Consultar NFS-e (GET /nfse/:chave)
├── DANFSE/ (depreciado)
│   └── Download DANFSE (GET /danfse/:chave)
└── Eventos/
    ├── Cancelamento (101101)
    ├── Cancelamento por Substituição (105102)
    ├── Solicitação Análise Fiscal (101103)
    ├── Confirmação do Tomador (203202)
    └── Rejeição do Tomador (203206)

Tipos de Eventos Suportados

Tipo	Código	Descrição
`cancelamento`	101101	Cancelamento simples de NFS-e
`cancelamento_por_substituicao`	105102	Cancelamento com chave da nota substituta
`solicitacao_analise_fiscal_para_cancelamento`	101103	Solicita análise fiscal para cancelar
`confirmacao_tomador`	203202	Confirmação pelo tomador
`rejeicao_tomador`	203206	Rejeição pelo tomador

Dica

Cada requisição na coleção Postman inclui exemplos de resposta (sucesso e erro). Clique em "Examples" no Postman para visualizá-los.

Operações com Exterior

Tomador no Exterior (NIF / Comércio Exterior)

O tomador estrangeiro é identificado por NIF ou cNaoNIF (motivo de não informação do NIF) no lugar de CPF/CNPJ. O endereço usa o grupo endExt, cujos quatro campos são obrigatórios quando o endereço no exterior é informado: cPais (código do país em ISO 3166-1 alfa-2), cEndPost (código postal alfanumérico, até 11 caracteres), xCidade e xEstProvReg. Quando o tomador é identificado pelo NIF e o emitente por CNPJ, o grupo de endereço no exterior é obrigatório (E0242). Quando o tomador é do exterior, o grupo comExt é obrigatório.

Exemplo completo de DPS (v1.01) com tomador no exterior

<?xml version="1.0" encoding="UTF-8"?>
<DPS xmlns="http://www.sped.fazenda.gov.br/nfse" versao="1.01">
  <infDPS Id="DPS1">
    <verAplic>1.01</verAplic>
    <serie>001</serie>
    <nDPS>000000000000001</nDPS>
    <dCompet>2026-07-01</dCompet>
    <tpEmit>1</tpEmit>
    <cLocEmi>2101707</cLocEmi>
    <prest>
      <CNPJ>35369787000148</CNPJ>
      <IM>241</IM>
      <regTrib>
        <opSimpNac>1</opSimpNac>
        <regEspTrib>0</regEspTrib>
      </regTrib>
    </prest>
    <toma>
      <NIF>987654321</NIF>
      <xNome>SILBECK SOFTWARE LTDA</xNome>
      <end>
        <endExt>
          <cPais>BN</cPais>
          <cEndPost>99999999</cEndPost>
          <xCidade>EXTERIOR</xCidade>
          <xEstProvReg>EX</xEstProvReg>
        </endExt>
        <xLgr>RUA BERNARDO LOCKS</xLgr>
        <nro>148</nro>
        <xBairro>CENTRO</xBairro>
      </end>
    </toma>
    <serv>
      <locPrest>
        <cLocPrestacao>2101707</cLocPrestacao>
      </locPrest>
      <cServ>
        <cTribNac>090101</cTribNac>
        <xDescServ>Hospedagem - tomador residente no exterior</xDescServ>
        <cNBS>103031100</cNBS>
      </cServ>
      <comExt>
        <mdPrestacao>2</mdPrestacao>
        <vincPrest>1</vincPrest>
        <tpMoeda>220</tpMoeda>
        <vServMoeda>200.00</vServMoeda>
        <mecAFComexP>01</mecAFComexP>
        <mecAFComexT>01</mecAFComexT>
        <movTempBens>1</movTempBens>
      </comExt>
    </serv>
    <valores>
      <vServPrest>
        <vServ>1000.00</vServ>
      </vServPrest>
      <trib>
        <tribMun>
          <tribISSQN>1</tribISSQN>
          <tpRetISSQN>1</tpRetISSQN>
        </tribMun>
      </trib>
    </valores>
  </infDPS>
</DPS>

O tpMoeda usa o código SISCOMEX da moeda (ex.: 220 = USD, 978 = EUR), não o código ISO numérico — consulte a lista completa em GET /api/v1/catalogo/moedas (aba Consulta de Catálogos). Para tomador sem NIF, troque a tag <NIF> por <cNaoNIF>1</cNaoNIF> (1 dispensado, 2 não exigido). O grupo comExt é obrigatório para tomador no exterior; o exemplo mostra o mínimo aceito. O envio pelo webservice exige a assinatura digital (bloco <Signature> irmão de <infDPS> — ver aba Assinatura Digital), omitida acima por legibilidade.

Domínios dos campos do grupo comExt

O valor 0 (Desconhecido / não informado na nota de origem) é reservado ao compartilhamento de notas do município com o Ambiente Nacional — não o utilize na emissão.

mdPrestacao — Modo de Prestação
1	Transfronteiriço
2	Consumo no Brasil
3	Movimento Temporário de Pessoas Físicas
4	Consumo no Exterior

vincPrest — Vínculo entre as partes
1	Controlada
2	Controladora
3	Coligada
4	Matriz
5	Filial ou Sucursal
6	Outro vínculo

O valor 0 (Sem vínculo) não é aceito pelo webservice — informe um dos valores de 1 a 6.

movTempBens — Movimentação Temporária de Bens
1	Não
2	Vinculada — Declaração de Importação (exige nDI)
3	Vinculada — Declaração de Exportação (exige nRE)

mecAFComexP — Mecanismo de apoio (prestador)
1	Nenhum
2	ACC — Adiantamento sobre Contrato de Câmbio — Redução a Zero do IR e do IOF
3	ACE — Adiantamento sobre Cambiais Entregues — Redução a Zero do IR e do IOF
4	BNDES-Exim Pós-Embarque — Serviços
5	BNDES-Exim Pré-Embarque — Serviços
6	FGE — Fundo de Garantia à Exportação
7	PROEX — Equalização
8	PROEX — Financiamento

mecAFComexT — Mecanismo de apoio (tomador)
1	Nenhum
2	Adm. Pública e Repr. Internacional
3	Alugueis e Arrend. Mercantil de máquinas, equip., embarc. e aeronaves
4	Arrendamento Mercantil de aeronave para empresa de transporte aéreo público
5	Comissão a agentes externos na exportação
6	Despesas de armazenagem, mov. e transporte de carga no exterior
7	Eventos FIFA (subsidiária)
8	Eventos FIFA
9	Fretes, arrendamentos de embarcações ou aeronaves e outros
10	Material Aeronáutico
11	Promoção de Bens no Exterior
12	Promoção de Dest. Turísticos Brasileiros
13	Promoção do Brasil no Exterior
14	Promoção Serviços no Exterior
15	RECINE
16	RECOPA
17	Registro e Manutenção de marcas, patentes e cultivares
18	REICOMP
19	REIDI
20	REPENEC
21	REPES
22	RETAERO
23	RETID
24	Royalties, Assistência Técnica, Científica e Assemelhados
25	Serviços de avaliação da conformidade vinculados aos Acordos da OMC
26	ZPE

Consulta de Catálogos

Endpoints REST somente-leitura para descobrir os valores aceitos pela API:seis catálogos de campos do XML DPS (códigos de tributação, NBS, municípios, países, moedas)mais o catálogo dos tipos de evento aceitos em POST /eventos . Sem autenticação. Resposta em JSON.

Padrão de resposta: os catálogos de DPS retornam{ "itens": [...], "paginacao": { "pagina_atual", "por_pagina", "total", "total_paginas" } }. Cada um aceita?page=e?per_page=(1..100, padrão 25). Cache HTTP de 1h. O catálogo motivos_evento é estático (sem paginação) — devolve a árvore completa de tipos.

Campo opcional. O XSD nacional () tornacTribMunfacultativo. DPS enviadas apenas comcTribNacsão aceitas — a NFS-e é gerada sem código municipal vinculado.Quem precisar de agrupamento por código municipal nos relatórioslocais deve enviar ocTribMuncorrespondente.

GET/:tenant/api/v1/catalogo/codigos_tributacao_municipal

Lista os códigos cadastrados localmente no município. O campocodigoretornado é o valor que vai em<serv><cServ><cTribMun>no XML DPS.

Filtros:?descricao=(ILIKE),?cnae_codigo=

curl "https://tributario.speedgov.com.br/{tenant}/api/v1/catalogo/codigos_tributacao_municipal?descricao=consultoria&per_page=10"

Campo obrigatórioem toda DPS — definido pelo XSD nacional. Código inválidoretorna erroE002sem fallback automático; consulte o catálogo abaixo antes de enviar.

GET/:tenant/api/v1/catalogo/codigos_tributacao_nacional

Catálogo nacional ADN. Campocodigo(6 dígitos) =<cTribNac>do XML.

Filtros:?codigo=,?descricao=,?item=. Cabeçalhos do catálogo (não-emitíveis) são sempre omitidos.

curl "https://tributario.speedgov.com.br/{tenant}/api/v1/catalogo/codigos_tributacao_nacional?item=1"

GET/:tenant/api/v1/catalogo/nbs

Campocodigo(9 dígitos sem formatação) =<cNBS>do XML.codigo_formatado é a versão XX.XX.XX.XX-X.

Filtros:?codigo=(aceita com ou sem pontos),?descricao=,?secao=

curl "https://tributario.speedgov.com.br/{tenant}/api/v1/catalogo/nbs?codigo=01.01.51.00-1"

GET/:tenant/api/v1/catalogo/municipios

Campocodigo_ibge(7 dígitos) é o valor que vai em qualquer<cMun*>do XML.

Filtros:?codigo_ibge=(exato),?uf=(case-insensitive),?nome=(ILIKE).

curl "https://tributario.speedgov.com.br/{tenant}/api/v1/catalogo/municipios?uf=CE&nome=fortal"

GET/:tenant/api/v1/catalogo/paises

Catálogo usado quando o endereço do tomador é exterior (<cPais>).

Filtros:?codigo=(exato),?nome=(ILIKE).

curl "https://tributario.speedgov.com.br/{tenant}/api/v1/catalogo/paises?nome=brasil"

GET/:tenant/api/v1/catalogo/moedas

Catálogo da moeda usada no comércio exterior (<tpMoeda>). Use o código BACEN/SISCOMEX (ex.: 220 = USD, 978 = EUR), não o código ISO 4217 numérico.

Filtros:?codigo=(exato),?sigla=(ILIKE).

curl "https://tributario.speedgov.com.br/{tenant}/api/v1/catalogo/moedas?sigla=usd"

GET/:tenant/api/v1/catalogo/motivos_evento

Catálogo dos eventos aceitos em POST /api/v1/nfse/:chave_acesso/eventos . Para cada tipo_evento (cancelamento, cancelamento_por_substituicao, rejeicao_prestador, rejeicao_tomador, rejeicao_intermediario, solicitacao_analise_fiscal_para_cancelamento, cancelamento_por_oficio, bloqueio_por_oficio, confirmacao_*, etc.) retorna a lista de campos obrigatórios e, quando aplicável, as opções aceitas em cada campo enumerado ( codigo usado no payload, valor inteiro persistido, descricao legível para popular selects).

Filtro opcional: ?tipo_evento=cancelamentodevolve apenas a entrada do tipo solicitado (404 se desconhecido, com lista de valores_validos ).

Sem filtro

curl "https://tributario.speedgov.com.br/{tenant}/api/v1/catalogo/motivos_evento"

Por tipo

curl "https://tributario.speedgov.com.br/{tenant}/api/v1/catalogo/motivos_evento?tipo_evento=cancelamento"

Códigos enviados fora dos valores listados aqui são rejeitados pelo POST /eventos com 400 e mensagem indicando o conjunto aceito. Use este catálogo para validar o payload antes de chamar o POST.

Códigos de Erro e Tratamento

Formato de Resposta de Erro

Todos os erros retornam um JSON padronizado com os seguintes campos:

{
  "codigo_erro": "E101",
  "mensagem": "Descrição curta do erro",
  "detalhes": "Explicação detalhada e como resolver",
  "timestamp": "2025-11-11T12:00:00-03:00"
}

Erros de Estabelecimento (E1XX)

HTTP	Código	Mensagem	Solução
422	`E101`	Estabelecimento não encontrado	Verifique se o CNPJ está cadastrado no sistema
403	`E102`	Estabelecimento não autorizado	O estabelecimento não tem permissão para emitir NFS-e
422	`E103`	Inscrição municipal inválida	A inscrição municipal não corresponde ao CNPJ

Erros de Validação de XML (E2XX)

HTTP	Código	Mensagem	Solução
422	`E201`	XML mal formado	Verifique a estrutura do XML e o encoding UTF-8
422	`E202`	Campo obrigatório ausente	Verifique se todos os campos obrigatórios estão presentes
422	`E203`	Schema inválido	O XML não está conforme o schema NFS-e v1.0

Erros de Nota Fiscal (E3XX)

HTTP	Código	Mensagem	Solução
404	`E301`	Nota fiscal não encontrada	Verifique se a chave de acesso está correta
422	`E302`	Nota já cancelada	Não é possível operar sobre uma nota cancelada
422	`E303`	DPS duplicado	Já existe uma nota com esta série e número

Erros de Valores e Tributos (E4XX)

HTTP	Código	Mensagem	Solução
422	`E401`	Valor inválido	Valores devem ser maiores que zero
422	`E402`	Código de tributação inválido	O código de serviço não está cadastrado
422	`E403`	Município inválido	Código IBGE do município não encontrado
422	`E404`	Cálculo do ISS incorreto	Valor do ISS não corresponde ao cálculo (Base × Alíquota)

Erros de Assinatura Digital (E9XX)

Importante: O XML da DPS deve ser assinado digitalmente com certificado ICP-Brasil do prestador (e-CNPJ ou e-CPF) na emissão via POST /api/v1/nfse/v101.O documento do certificado (CNPJ no e-CNPJ, CPF no e-CPF) deve corresponder ao CPF/CNPJ do prestador informado no XML.

HTTP	Código	Mensagem	Solução
422	`E901`	XML não está assinado digitalmente	Assinar o XML com certificado e-CNPJ ou e-CPF válido antes de enviar
422	`E902`	Assinatura digital inválida	Verificar se a assinatura foi gerada corretamente (RSA-SHA256)
422	`E903`	Certificado digital expirado	Renovar o certificado digital junto à autoridade certificadora
422	`E904`	Certificado digital inválido	Usar certificado ICP-Brasil válido (e-CNPJ ou e-CPF)
422	`E905`	Certificado não encontrado na assinatura	Incluir o elemento X509Certificate na assinatura
422	`E906`	Documento do certificado diverge do prestador	Usar certificado do próprio prestador (CNPJ ou CPF deve coincidir)

Caminho JSON (assinatura no cabeçalho): Na emissão e nos eventos enviados em JSON (Content-Type application/json), a assinatura vai em um cabeçalho — X-DPS-Assinatura na emissão, X-Evento-Assinatura nos eventos — como assinatura CMS/PKCS#7 destacada (Base64) sobre os bytes do corpo. Esses erros retornam HTTP 401.

HTTP	Código	Mensagem	Solução
401	`E9002`	Requisição JSON sem assinatura digital	Enviar a assinatura no cabeçalho (X-DPS-Assinatura na emissão, X-Evento-Assinatura nos eventos)
401	`E9003`	Assinatura digital inválida	A assinatura deve cobrir exatamente os bytes do corpo enviado; não reserializar o JSON após assinar
401	`E9006`	Certificado fora da validade	Usar certificado dentro do período de validade
401	`E9007`	Documento do certificado diverge da parte esperada	Assinar com o certificado do prestador da nota (CNPJ conferido pela raiz, ou CPF)
401	`E9016`	Evento de ofício/sistema indisponível por webservice	Eventos cujo autor não é parte da nota (prestador/tomador/intermediário) não são aceitos por este canal

Erros Internos do Sistema

HTTP	Código	Mensagem	Solução
500	`E999`	Erro interno no processamento	Entre em contato com o suporte técnico

Grupo obra (construção civil)

Enviado em/DPS/infDPS/serv/obra. Obrigatório quando ocTribNacpertence aos subitens 07.02.01, 07.02.02, 07.04.01, 07.05.01, 07.05.02, 07.06.01,07.06.02, 07.07.01, 07.08.01, 07.17.01, 07.19.01, 14.14.03 e 14.14.04; opcional parao código 99.01.01; não permitido nos demais.

Informe apenas UMA identificação. As três são alternativas exclusivas:

Campo	Descrição	Regras
`cObra`	Número da obra no CNO ou no CEI.	Até 30 caracteres. Exige o envio de`inscImobFisc`junto.
`cCIB`	Cadastro Imobiliário Brasileiro.	Exatamente 8 dígitos numéricos.
`end`	Endereço da obra.	Ver o quadro abaixo.

inscImobFisc— inscrição imobiliária fiscal, até 30 caracteres. Acompanha qualquer uma das três enão conta como alternativa; é obrigatório quando a obra vem porcObra.

Endereço da obra

Escolha entreCEP(8 dígitos, endereço no Brasil) eendExt(exterior, comcEndPost,xCidade exEstProvReg, até 11, 60 e 60 caracteres). Em ambos:xLgr(até 255),nro(até 60),xCpl(opcional, até 156) exBairro(até 60).

O grupo não tem município. Ele não é exigido nem devolvido nas notas recebidas por este webservice.

Erros deste grupo:E0011,E0370,E0372,E0373,E0382,E0384 eE0386.

Grupo infoCompl (informações complementares)

Opcional, enviado em/DPS/infDPS/serv/infoCompl.

Campo	Descrição	Limite
`idDocTec`	Documento de responsabilidade técnica (ART, RRT ou equivalente).	40 caracteres
`docRef`	Documento de referência.	255 caracteres
`xInfComp`	Texto livre de informações complementares.	2000 caracteres

Os camposxPed egItemPed do leiaute ainda não são recebidos por este webservice.

Erros do webservice NFS-e (xpath e exemplo)

Cada erro retornado pela API tem código (E1305), xpath do elemento problemáticoe link para esta tabela. Anchor do erro: clique para ir direto.

Código	Campo	XPath	Origem	Mensagem	Exemplo
`E0001`			Webservice (validação de tipo na entrada)	Tipo de dado inválido. Valor enviado não corresponde ao tipo esperado pelo schema (decimal, inteiro, etc).	`iss_no_municipio_prestacao`
`E0002`			Webservice (validação de tipo na entrada)	Valor fora do intervalo permitido pelo schema (ex: alíquota > 100%, tributação ISSQN fora do enum 1, 2, 3, 4).	`iss_no_municipio_prestacao`
`E0003`			Webservice (validação de tipo na entrada)	Formato inválido (ex: código IBGE deve ter 7 dígitos, cTribNac deve ter 6 dígitos).	`iss_no_municipio_prestacao`
`E0010`			Webservice (validação estrutural na entrada)	Tag XML não aceita pelo padrão nacional vigente. O XML DPS deve estar no formato canônico do Adendo Técnico v1.01 do CGNFS-e.	`iss_no_municipio_prestacao`
`E110`		`/DPS/@versao`	Webservice (roteamento de versão)	DPS no padrão v1.01 foi enviada ao endpoint v1.00. Reenvie para POST /api/v1/nfse/v101.	`iss_no_municipio_prestacao`
`E002`			Genérico	Campo obrigatório não informado.	`iss_no_municipio_prestacao`
`E502`	`tributacao_nacional_id`	`/DPS/infDPS/serv/cServ/cTribNac`	Genérico (validação de cadastro)	Código de tributação inválido ou não cadastrado.	`iss_no_municipio_prestacao`
`E802`		`/DPS/infDPS/IBSCBS`	MOC ADN — IBSCBS	Campo obrigatório do grupo IBSCBS não foi informado.	`iss_no_municipio_prestacao`
`E0310`	`tributacao_nacional_id`	`/DPS/infDPS/serv/cServ/cTribNac`	MOC ADN — E0310	Código de tributação nacional não está cadastrado ou não é administrado por este município.	`iss_no_municipio_prestacao`
`E0011`	`obra_tipo`	`/DPS/infDPS/serv/obra`	XSD v1.01 — TCInfoObra (xs:choice)	O grupo obra admite uma identificação: código da obra, CIB ou endereço. A inscrição imobiliária fiscal acompanha qualquer uma delas e não conta como alternativa.	`iss_no_municipio_prestacao`
`E0370`	`obra_tipo`	`/DPS/infDPS/serv/obra`	MOC ADN — E0370	Grupo obra é obrigatório quando cTribNac pertence aos subitens de construção civil.	`iss_no_municipio_prestacao`
`E0372`	`obra_tipo`	`/DPS/infDPS/serv/obra`	MOC ADN — E0372	Grupo obra não permitido quando cTribNac não pertence aos subitens de construção civil.	`iss_no_municipio_prestacao`
`E0373`	`obra_codigo_cib`	`/DPS/infDPS/serv/obra/cCIB`	MOC ADN — E0373	O CIB informado é inválido.	`iss_no_municipio_prestacao`
`E0382`	`obra_endereco_cep_brasil`	`/DPS/infDPS/serv/obra/end/CEP`	MOC ADN — E0382	O CEP não deve ser informado quando o endereço da obra ocorrer no exterior.	`iss_no_municipio_prestacao`
`E0384`	`obra_exterior_logradouro`	`/DPS/infDPS/serv/obra/end/endExt`	MOC ADN — E0384	O endereço da obra no exterior deve ser informado quando o país do local da prestação for informado na DPS.	`iss_no_municipio_prestacao`
`E0386`	`obra_exterior_logradouro`	`/DPS/infDPS/serv/obra/end/endExt`	MOC ADN — E0386	O endereço da obra no exterior não deve ser informado quando o município do local da prestação for informado na DPS.	`iss_no_municipio_prestacao`
`E0390`		`/DPS/infDPS/serv/atvEvento`	MOC ADN — E0390	Grupo atvEvento é obrigatório quando cTribNac pertence ao item 12 da LC 116/2003.	`iss_no_municipio_prestacao`
`E0392`		`/DPS/infDPS/serv/atvEvento`	MOC ADN — E0392	Grupo atvEvento não permitido quando cTribNac não pertence ao item 12 ou 99.01.01.	`iss_no_municipio_prestacao`
`E0928`		`/DPS/infDPS/IBSCBS`	MOC ADN — E0928	Inconsistência entre cTribNac, indicador de operação e dados de imóvel.	`iss_no_municipio_prestacao`
`E0931`		`/DPS/infDPS/IBSCBS`	MOC ADN — E0931	Grupo imóvel não pode ser informado para este cTribNac.	`iss_no_municipio_prestacao`
`E0932`		`/DPS/infDPS/IBSCBS`	MOC ADN — E0932	Grupo imóvel é obrigatório quando o cTribNac não for de construção civil.	`iss_no_municipio_prestacao`
`E1301`	`codigo_municipio_incidencia_id`	`/DPS/infDPS/serv/locPrest/cLocPrestacao`	MOC ADN — E1301	Município de incidência não pode ser informado para este tipo de tributação (Imunidade, Exportação ou Não Incidência).	`iss_no_municipio_prestacao`
`E1305`	`codigo_municipio_incidencia_id`	`/DPS/infDPS/serv/locPrest/cLocPrestacao`	MOC ADN — E1305	Município de incidência é obrigatório quando a tributação é 'Operação Tributável'.	`iss_no_municipio_prestacao`
`E1313`	`codigo_municipio_prestacao_id`	`/DPS/infDPS/serv/locPrest/cLocPrestacao`	MOC ADN — E1313	Quando local de prestação é 'Águas Marítimas' (0000000), cTribNac deve ser 200101.	`iss_no_municipio_prestacao`
`E1317`	`codigo_municipio_incidencia_id`	`/DPS/infDPS/serv/locPrest/cLocPrestacao`	MOC ADN — E1317	Códigos de tributação nacional cuja regra indica o município da prestação devem ter cMunIncid igual ao cMunPrest.	`iss_no_municipio_prestacao`
`E1321`	`codigo_municipio_incidencia_id`	`/DPS/infDPS/serv/locPrest/cLocPrestacao`	MOC ADN — E1321	Códigos de tributação nacional cuja regra indica o município do tomador devem ter cMunIncid igual ao cMun do tomador.	`iss_no_tomador`
`E1402`	`codigo_municipio_prestacao_id`	`/DPS/infDPS/serv/locPrest/cLocPrestacao`	MOC ADN — E1402	Quando cTribNac = 200101, não é permitido usar 0000000 (Águas Marítimas) como local de prestação.	`iss_no_municipio_prestacao`
`E0188`	`tomador_documento`	`/DPS/infDPS/toma`	MOC ADN — E0188	Informe exatamente um identificador do tomador: CPF, CNPJ, NIF ou cNaoNIF (motivo de não informação do NIF).	`iss_no_tomador`
`E0191`	`tomador_nif`	`/DPS/infDPS/toma/NIF`	MOC ADN — E0191	NIF é obrigatório quando o tomador estrangeiro é identificado por NIF (máximo 40 caracteres).	`iss_no_tomador`
`E0193`	`tomador_motivo_nao_informacao_nif`	`/DPS/infDPS/toma/cNaoNIF`	MOC ADN — E0193	cNaoNIF é obrigatório quando o tomador é estrangeiro sem NIF (0 sem NIF, 1 dispensado, 2 não exigido).	`iss_no_tomador`
`E0235`	`tomador_pais_id`	`/DPS/infDPS/toma/end/endExt/cPais`	MOC ADN — E0235	País é obrigatório quando o endereço do tomador é no exterior (cPais em ISO 3166-1 alfa-2).	`iss_no_tomador`
`E0246`	`tomador_pais_id`	`/DPS/infDPS/toma/end/endExt/cPais`	MOC ADN — E0246	O código do país do endereço exterior deve existir na tabela ISO e não pode ser o Brasil.	`iss_no_tomador`
`E1235`	`comercio_exterior_modo_prestacao`	`/DPS/infDPS/serv/comExt`	MOC ADN — E1235	Grupo de comércio exterior (comExt) incompleto: informe modo de prestação, vínculo, moeda (tpMoeda SISCOMEX), valor em moeda estrangeira, mecanismos de apoio e movimentação temporária de bens.	`iss_no_tomador`

Tags XML depreciadas

A DPS deve ser enviada no formato canônico do Adendo Técnico v1.01 (coluna "Tag correta").O endpointPOST /:tenant/api/v1/nfse/v101 rejeita as tags abaixo com erroE0010 e HTTP 422 indicando a forma correta.O endpoint legadoPOST /:tenant/api/v1/nfse foi descontinuado: qualquer emissão por ele respondeHTTP 410 (erroE111) apontando o endpoint v1.01.

Tag depreciada	Tag correta	Anchor
`<serv><cMunPrest>`	`<serv><locPrest><cLocPrestacao>`	#tag-cmunprest-depreciada
`<serv><cMunInc>`	`<infNFSe><cLocIncid> (gerado pela ADN, nao pelo integrador)`	#tag-cmuninc-depreciada
`<tom>`	`<toma>`	#tag-tom-depreciada
`<xEmail>`	`<email>`	#tag-xemail-depreciada
`<serv><xDescServ>`	`<serv><cServ><xDescServ>`	#tag-xdescserv-fora-cserv-depreciada

Boas Práticas no Tratamento de Erros

Sempre verifique o campo code.mx-1 codigo_erro | para tratamento automatizado
Exiba o campo code.mx-1 mensagem | para o usuário final
Registre o campo code.mx-1 detalhes | em logs para debugging
Use o code.mx-1 timestamp | para rastreamento temporal de problemas
Implemente retry com backoff exponencial para erros 500

Histórico de Alterações

Esta página registra mudanças no contrato público da API que possam afetar integrações externas.

Formato baseado emKeep a Changelog— categorias:Adicionado·Alterado·Corrigido·Depreciado·Removido·Segurança

Histórico de Alterações — API NFS-e Nacional

Este registro documenta mudanças no contrato público da API que possam afetar integrações externas. Formato baseado em Keep a Changelog — categorias: Adicionado, Alterado, Corrigido, Depreciado, Removido, Segurança.

O registro inicia em 07/05/2026, com a publicação da documentação pública em /api/docs. Mudanças anteriores existem no histórico do código, mas não foram catalogadas formalmente aqui.

13/08/2026

Corrigido

NFS-e com IBS/CBS de imunidade/não-incidência (CST 410) voltou a ser aceita. Desde 31/07/2026, notas enviadas com CST 410 eram recusadas com HTTP 422 informando alíquota de IBS/CBS incorreta — apontando um percentual que o emitente não havia declarado e que o leiaute do DPS sequer transporta. A apuração passou a reconhecer a operação como não tributada antes de aplicar as alíquotas: a nota é aceita e as alíquotas e totais de IBS e CBS retornam zerados. Quem tenha contornado o problema removendo o grupo ibscbs do envio pode voltar a informá-lo normalmente.
Isenção (CST 400) deixou de apurar IBS/CBS. Notas com classificação de isenção eram aceitas, porém com alíquotas e valores de IBS/CBS apurados como se fossem tributadas. Passam a retornar zeradas, como já ocorria na imunidade.

Alterado

Classificação tributária (cClassTrib) inexistente ou inativa passa a ser recusada. Um código fora da tabela vigente era aceito em silêncio, e a nota saía com alíquota cheia. Agora a emissão é recusada com HTTP 422 e mensagem indicando que o código não foi encontrado no cadastro de classificações ativas. A recusa vale para a criação da nota — notas já emitidas continuam podendo ser consultadas e ter seu XML regerado, mesmo que a RFB tenha desativado o código depois. Envios sem cClassTrib seguem tratados pelas regras de obrigatoriedade já publicadas, sem mudança.
Mensagens de divergência de alíquota de IBS/CBS agora citam isenção. Os textos que antes diziam apenas "(imunidade/não-incidência)" passam a dizer "(isenção ou imunidade/não-incidência)". O código do erro e o formato da resposta não mudaram.

31/07/2026

Alterado

Novo cronograma de obrigatoriedade do IBS/CBS na emissão de NFS-e. O Ato Conjunto RFB/CGIBS nº 4, de 30/07/2026, substituiu o calendário anterior. Não há mais nenhuma data em agosto de 2026. A obrigatoriedade passa a depender do serviço e do regime do prestador:

| Situação | Obrigatório a partir de | |---|---| | Serviços da lista da LC 116 em geral | 01/10/2026 | | Subitens 1.03, 1.05, 1.09 e 16.01, e serviços fora da lista da LC 116 | 01/12/2026 | | Prestador optante do Simples Nacional | 01/01/2027 |

O enquadramento é determinado pelo cTribNac informado na DPS (os quatro primeiros dígitos identificam item e subitem da LC 116). Quando o código não permite identificar o subitem, vale a data mais tardia. O regime do Simples é apurado no cadastro municipal, na competência da nota — não pelo valor enviado no payload.

A data é avaliada pela competência da nota, não pela data do envio. O Ato vincula a obrigatoriedade aos fatos geradores ocorridos a partir de cada marco. Uma nota de competência anterior ao marco do seu serviço continua podendo ser emitida sem o grupo ibscbs, mesmo que enviada depois da data.
A mensagem de recusa passa a informar a data aplicável àquele serviço. Requisições sem o grupo ibscbs a partir do marco do serviço continuam sendo recusadas com HTTP 422, agora citando a data correspondente ao segmento (por exemplo, 01/10/2026 ou 01/12/2026).

Corrigido

Emissão recusada indevidamente quando o CNPJ do prestador aparece em mais de um cadastro. Bases municipais podem ter o mesmo CNPJ vinculado a mais de um contribuinte. Nesses casos a emissão podia falhar com HTTP 404 (estabelecimento_nao_encontrado) mesmo havendo estabelecimento ativo, de forma não determinística. A busca passa a considerar todos os cadastros com aquele documento.
Emissão recusada indevidamente quando só parte dos estabelecimentos está autorizada. Prestadores com vários estabelecimentos podiam receber HTTP 403 (estabelecimento_nao_autorizado) mesmo tendo um estabelecimento habilitado a emitir NFS-e. A seleção passa a priorizar um estabelecimento autorizado.

30/07/2026

Corrigido

Alíquota de IBS/CBS zerada em NFS-e emitida por DPS de terceiro. Notas enviadas ao webservice com o grupo ibscbs (CST/cClassTrib) estavam saindo ao Ambiente de Dados Nacional (ADN) com alíquota de IBS estadual 0,00 e sendo rejeitadas com o erro E1539 ("Alíquota da UF para IBS incorreta"), ficando presas como rascunho. A DPS não transporta alíquota — ela é publicada pelo Comitê Gestor e aplicada pelo município —, e o sistema deixou de calculá-la nesse canal. A emissão volta a aplicar a alíquota oficial (em 2026: IBS-UF 0,10%, IBS-Municipal 0,00%, CBS 0,90%, com as reduções da classificação tributária). Nenhuma ação é necessária do integrador.

Alterado

Valores de IBS/CBS declarados no canal JSON passam a ser conferidos. valores_base_calculo, valores_aliquota_*, valores_aliquota_efetiva_* e total_* continuam sendo aceitos, mas agora são comparados com o cálculo oficial do município. Divergência resulta em HTTP 422 com o código ADN do campo (ex.: E1539, E1568), informando o valor declarado e o esperado — antes, os valores enviados eram aceitos como verdade nesse canal. Tolerância: 0,01 ponto percentual para alíquotas e R$ 0,02 para valores. Integrações que enviam os valores corretos não são afetadas.

09/07/2026

Alterado

IBS/CBS passa a ser obrigatório na emissão para prestador não optante do Simples Nacional a partir de 01/08/2026. Em cumprimento à Reforma Tributária (Lei Complementar nº 214/2025) e ao calendário nacional do IBS/CBS, a partir dessa data as requisições de emissão sem o grupo ibscbs passam a ser rejeitadas com HTTP 422, informando o motivo do bloqueio. Notas sem essas informações seriam rejeitadas pelo Ambiente de Dados Nacional (ADN) da Receita Federal, e a recusa na recepção evita que o integrador receba um protocolo para uma nota que não será autorizada. Empresas optantes do Simples Nacional (inclusive MEI) permanecem dispensadas do preenchimento em 2026. Até 31/07/2026 nada muda: o grupo segue facultativo para todos.
O leiaute 1.00 não comporta o grupo ibscbs. A partir de 01/08/2026, a emissão por esse leiaute é bloqueada para prestador não optante, com orientação para migrar à versão 1.01. Integrações que ainda usam a 1.00 devem migrar antes da data.

Corrigido

O enquadramento no Simples Nacional passa a ser apurado pelo cadastro municipal, na competência da nota. A verificação usava a data corrente, e não a competência informada na DPS: uma nota de competência anterior à saída do prestador do Simples podia ser recusada indevidamente. O regime é apurado no cadastro (não no campo opSimpNac enviado no payload), na competência do documento — o mesmo critério aplicado na emissão pelo sistema do município.

03/07/2026

Corrigido

Endereço no exterior do tomador informado na emissão passa a ser considerado. Os campos cEndPost, xCidade e xEstProvReg do grupo toma/end/endExt enviados na DPS eram desconsiderados na recepção, e a NFS-e gerada montava o grupo endExt fora do leiaute nacional (apenas cPais, com cidade e estado fora do grupo e o código postal emitido como CEP). O resultado era a rejeição da nota no Ambiente Nacional com E1235 (falha no esquema XML do DF-e). Agora os três campos são capturados e a NFS-e é gerada com o grupo endExt completo, na ordem do leiaute: cPais, cEndPost, xCidade, xEstProvReg.
Código postal do exterior (cEndPost) preserva o formato alfanumérico. O valor era tratado como CEP nacional (somente dígitos, truncado em 8 posições), descaracterizando códigos postais estrangeiros (ex.: SW1A 1AA). Agora o campo aceita e preserva valores alfanuméricos de até 11 caracteres, conforme o leiaute nacional.

Alterado

Novas validações na recepção da DPS para o endereço no exterior do tomador. Quando o endereço no exterior é informado, cEndPost, xCidade e xEstProvReg passam a ser obrigatórios (e cEndPost limitado a 11 caracteres); a ausência retorna HTTP 422 com a indicação do campo, em vez de a nota ser aceita e rejeitada posteriormente no Ambiente Nacional. Também passou a ser verificada na recepção a regra E0242 do leiaute nacional: quando o tomador é identificado pelo NIF e o emitente por CNPJ, o grupo de endereço no exterior deve ser informado.

02/07/2026

Removido

Emissão de NFS-e pelo endpoint v1.00 (POST /api/v1/nfse) foi descontinuada. A emissão passou a exigir o layout nacional vigente. Qualquer requisição a POST /api/v1/nfse agora responde HTTP 410 (Gone) com o erro E111, indicando o endpoint correto: POST /api/v1/nfse/v101. As consultas GET /api/v1/nfse/:chave_acesso e GET /api/v1/nfse/protocolo/:numero_protocolo permanecem disponíveis e inalteradas.

01/07/2026

Corrigido

Redutores da base de cálculo informados na emissão passam a ser considerados. Dedução/redução (vDedRed), descontos (vDescCondIncond) e benefício municipal (bM) enviados na DPS eram desconsiderados na recepção: a base do ISSQN era apurada apenas sobre o valor do serviço (vServ), resultando em ISSQN maior que o devido e sem o valor da dedução transmitido ao Ambiente Nacional. Agora esses redutores são considerados, a base é apurada corretamente e o valor da dedução é transmitido ao ADN.

28/06/2026

Corrigido

serie_dps e numero_dps informados na emissão passam a ser preservados. Antes, a série e o número da DPS enviados eram substituídos: o <nDPS> transmitido ao Ambiente Nacional (refletido em numero_dps_nacional) era um número gerado pelo sistema, e não o informado. Agora, ao informar serie_dps e/ou numero_dps, eles vão verbatim ao ADN e aparecem em serie_dps_nacional / numero_dps_nacional.

Alterado

numero_dps_nacional passa a coincidir com numero_dps — não é mais um número distinto gerado pelo sistema.
Preenchimento quando omitidos. Se numero_dps não for informado, numero_dps_nacional passa a ser o número sequencial da NFS-e; se serie_dps não for informada, serie_dps_nacional passa a ser 70000.

Adicionado

Validação de serie_dps e numero_dps na emissão. serie_dps aceita no máximo 5 dígitos e numero_dps de 1 a 15 dígitos; fora desses limites a emissão é rejeitada com HTTP 422 (E002). O reuso do conjunto Série + Número + CNPJ é rejeitado com HTTP 422 (E0014), e a mensagem inclui a chave de acesso da NFS-e já existente.

Segurança

Consulta pública por DPS (GET/HEAD /api/v1/dps/:id) escopada por CNPJ. A consulta passa a usar a inscrição federal contida no próprio identificador para resolver a NFS-e correta, evitando retornar a chave de acesso de outro emitente quando duas DPS de CNPJs diferentes no mesmo município compartilham a mesma série e número.

24/06/2026

Segurança

Assinatura digital obrigatória também no caminho JSON. Quando a requisição é enviada em JSON (Content-Type: application/json), o corpo passa a exigir assinatura digital, no mesmo nível de segurança já aplicado ao XML. A assinatura é informada em um cabeçalho HTTP: X-DPS-Assinatura na emissão (POST /api/v1/nfse e POST /api/v1/nfse/v101) e X-Evento-Assinatura nos eventos (POST /api/v1/nfse/:chave_acesso/eventos e a variante por :numero_protocolo), como o cancelamento. O valor do cabeçalho é uma assinatura CMS/PKCS#7 destacada, em Base64, calculada sobre os bytes exatos do corpo enviado, com o certificado A1 ICP-Brasil do prestador (e-CNPJ ou e-CPF). Requisições JSON não assinadas passam a ser rejeitadas com HTTP 401. Integrações que enviavam JSON sem assinatura precisam passar a assinar o corpo.

Alterado

Conferência do titular do certificado. O documento do certificado assinante é conferido contra a parte esperada: na emissão, o prestador; nos eventos, a parte autorizada para o tipo (no cancelamento, o prestador da nota). A conferência de CNPJ é feita pela raiz (8 dígitos), de modo que o certificado da matriz pode assinar por um estabelecimento (filial) do mesmo titular; para CPF, a conferência é exata.
Novos códigos de erro (HTTP 401) no caminho JSON: E9002 (sem assinatura), E9003 (assinatura inválida / não corresponde ao corpo enviado), E9006 (certificado fora da validade), E9007 (documento do certificado diverge da parte esperada) e E9016 (eventos de ofício/sistema — cujo autor não é parte da nota — não disponíveis por webservice). Ver as abas Assinatura Digital e Códigos de Erro.

22/06/2026

Adicionado

Catálogo de moedas. Novo endpoint GET /api/v1/catalogo/moedas (read-only, paginado, Cache-Control de 1h, sem autenticação), espelhando os demais catálogos. Retorna codigo (o valor que vai em <tpMoeda> no grupo <comExt>), sigla (ex.: USD, EUR) e nome. O codigo segue a tabela BACEN/SISCOMEX (ex.: 220 = USD, 978 = EUR), não o código ISO 4217 numérico. Aceita ?codigo= (exato) e ?sigla= (ILIKE).

Corrigido

vincPrest=0 não é mais rejeitado indevidamente. A emissão com tomador estrangeiro e <comExt> informando <vincPrest>0</vincPrest> ("Sem vínculo com o Tomador/Prestador", valor válido do layout) deixava de ser aceita com um E1235 falso ("é obrigatório informar o vínculo"). O 0 passa a ser reconhecido como informado para vincPrest.
Mensagem clara para tpMoeda desconhecido. Quando o <tpMoeda> enviado não consta na tabela de moedas (caso comum: envio do código ISO 4217, ex.: 986, em vez do BACEN/SISCOMEX), o erro passa de "é obrigatório informar a moeda" para "código de moeda (tpMoeda) desconhecido: NNN — use o código BACEN/SISCOMEX (consulte GET /api/v1/catalogo/moedas)".

Sandbox NFS-e Nacional

Você está navegando dentro do sandbox agora.

As notas emitidas neste tenant são geradas com tpAmb=2 (homologação) e não são transmitidas ao Ambiente Nacional (ADN). O DANFSE retornado contém a marca d'água AMBIENTE DE HOMOLOGAÇÃO — SEM VALOR FISCAL, e o header X-NFSe-Ambiente: homologacao é devolvido em todas as respostas dos endpoints NFS-e.

O que é o Sandbox NFS-e

O Sandbox NFS-e Nacional é um tenant compartilhado (slug integracao) dedicado a testes de integração com o webservice de NFS-e. Integradores podem validar o layout do XML da DPS, a montagem das chamadas REST, o tratamento de erros e o consumo do DANFSE sem afetar dados de produção de prefeituras reais e sem necessidade de certificado digital A1.

Base URL do sandbox

https://tributario.speedgov.com.br/integracao/api/v1/

Toda chamada para o sandbox usa o prefixo /integracao (slug do tenant). As demais URLs da API permanecem idênticas às de produção — apenas o município muda.

Sandbox vs Produção

	Produção	Sandbox (tenant `integracao`)
Base URL	`https://tributario.speedgov.com.br/{municipio}/api/v1/`	`https://tributario.speedgov.com.br/integracao/api/v1/`
Tag `<tpAmb>` no XML	`1` (produção)	`2` (homologação)
Header `X-NFSe-Ambiente`	`producao`	`homologacao`
Transmissão ao ADN	Sim (após assinatura A1 do município)	Não — fluxo encerrado localmente no banco do sandbox
Certificado digital A1 do município	Obrigatório (assinatura XML antes do envio)	Não utilizado (transmissão desligada)
Marca d'água diagonal no DANFSE	Ausente	`AMBIENTE DE HOMOLOGAÇÃO — SEM VALOR FISCAL`
Valor fiscal das notas	Sim	Não — uso exclusivo de teste
Cadastro prévio do prestador no município	Obrigatório	Não — criado automaticamente na primeira DPS (E101 bypassado)
Validação de autorização para emitir (E103)	Aplicada	Bypassada — estabelecimento criado já entra autorizado para teste
Validação algorítmica de CPF/CNPJ	Aplicada	Aplicada (idêntica à produção)
Validação do schema XSD da DPS	Aplicada	Aplicada (idêntica à produção)
Regras fiscais nacionais (NBS, IBS/CBS, cTribNac)	Aplicadas	Aplicadas (idênticas à produção)

Como começar

Aponte sua integração para a base URL https://tributario.speedgov.com.br/integracao/api/v1/
Monte o XML da DPS conforme o Guia Rápido — o schema é idêntico ao de produção, incluindo cTribNac (6 dígitos), cTribMun e estrutura de tributos.
Envie a DPS via POST /nfse com Content-Type: application/xml e o XML da DPS no body.
Confirme na resposta o header X-NFSe-Ambiente: homologacao e que o XML retornado contém <tpAmb>2</tpAmb>.
Consulte a NFS-e por chave de acesso via GET /nfse/{chave_acesso} ou pelo número de protocolo via GET /nfse/protocolo/{numero_protocolo}.
Baixe o DANFSE em GET /danfse/{chave_acesso} e confirme a presença da marca d'água diagonal.
(Opcional) Teste eventos da NFS-e via POST /nfse/{chave_acesso}/eventos — eles são registrados localmente com tpAmb=2 e não são enviados ao ADN.

Auto-cadastro do prestador no sandbox

Quando uma DPS chega ao sandbox com um CPF/CNPJ ainda não cadastrado no tenant integracao, o cadastro do prestador é criado automaticamente a partir dos dados presentes no XML — tags CNPJ/CPF e xNome dentro do bloco <prest>. Já é provisionado um estabelecimento ativo no município, pronto para emitir. Não é necessário pedir pré-cadastro ao suporte.

Detecção PF vs PJ pelo comprimento do documento normalizado (11 dígitos → CPF/PF; 14 → CNPJ/PJ).
Validação algorítmica de CPF (gem cpf_cnpj) e CNPJ (módulo 11) continua ativa — documentos mal formados são rejeitados antes do auto-cadastro.
O estabelecimento criado tem situacao=ativo, endereço genérico de sandbox e fica disponível para emissão imediata.
O município do estabelecimento auto-criado é definido pelo cLocEmi da DPS — se o IBGE informado não existir no catálogo, o auto-cadastro falha com cidade_padrao_indisponivel.
O auto-cadastro ocorre apenas em modo sandbox. Em produção, CPF/CNPJ não cadastrado continua disparando E101 normalmente.

Sobre o campo xNome: opcional no XSD v1.01 (minOccurs="0"). Quando ausente, o auto-cadastro do sandbox usa "PRESTADOR <CPF/CNPJ>" como nome — você pode atualizar depois pelo painel do município.

O que NÃO testar no sandbox

Assinatura digital ICP-Brasil: ainda não é obrigatória no webservice (passará a ser no futuro). O sandbox espelha o comportamento atual de produção — a DPS é aceita sem assinatura.
Transmissão ao ADN (Ambiente Nacional): desligada por design no sandbox. As notas são autorizadas localmente e permanecem apenas no banco do tenant integracao.
Eventos transmitidos ao ADN: cancelamentos, substituições e demais eventos são gravados localmente com tpAmb=2, mas não são enviados ao Ambiente Nacional.
Regras específicas do seu município: o sandbox usa as configurações do tenant integracao (alíquotas, lista de serviços, cadastros). Configurações específicas do município do cliente final não são replicadas aqui — para validar regras do seu município, continue usando o tenant dele em produção.

Diferenças de erros vs produção

Algumas validações de produção são bypassadas no sandbox para facilitar testes. A tabela completa de códigos está na aba Erros.

Erros que NÃO aparecem no sandbox

E101 — Estabelecimento não encontrado. O sandbox auto-cadastra o prestador a partir dos dados da DPS (ver "Auto-cadastro do prestador" acima). Exceção: dispara mesmo no sandbox se o documento for algoritmicamente inválido ou se o xNome vier vazio — o campo detalhes da resposta indica o motivo.
E103 — Estabelecimento não autorizado para emissão. O sandbox bypassa a validação do campo nota_fiscal do estabelecimento.

Erros que continuam ativos no sandbox

E0003 e demais erros de schema XSD (formato de cTribNac, campos numéricos, tamanhos máximos).
E002 — Campos obrigatórios ausentes (ex: tomador_cpf_cnpj, valor_servico).
Todas as validações de regras fiscais nacionais (NBS, IBS/CBS, alíquotas efetivas, cTribNac/cTribMun) permanecem idênticas à produção.

Assinatura Digital da DPS

Obrigatória — tanto em XML quanto em JSON

Os endpoints de emissão e de eventos exigem que a requisição chegue já assinada digitalmente com certificado A1 ICP-Brasil do prestador (e-CNPJ ou e-CPF). O webservice apenas valida a assinatura — ele não assina.

Em XML (Content-Type application/xml): a assinatura vai no próprio XML, no elemento <Signature> (XMLDSig). Sem <Signature> válido, a API retorna E901 ou E902.

Em JSON (Content-Type application/json): a assinatura vai em um cabeçalho HTTP (assinatura CMS/PKCS#7 destacada). Veja a seção Assinatura no caminho JSON abaixo. Sem assinatura válida, a API retorna 401.

Algoritmos exigidos

Padrão XML Signature (W3C XMLDSig 1.1) com algoritmos conforme especificação SPED Nacional NFS-e.

Elemento	Algorithm
`CanonicalizationMethod`	`http://www.w3.org/2001/10/xml-exc-c14n#`
`SignatureMethod`	`http://www.w3.org/2001/04/xmldsig-more#rsa-sha256`
`Transform`	`http://www.w3.org/2001/10/xml-exc-c14n#`
`DigestMethod`	`http://www.w3.org/2001/04/xmlenc#sha256`
`Reference URI`	#<Id do `<infDPS>`>

O webservice também aceita o padrão SPED Nacional oficial, em que o elemento <Transforms> contém dois algoritmos na ordem enveloped-signature seguido de exc-c14n.

Estrutura do bloco <Signature>

O elemento <Signature> deve ser inserido como irmão de <infDPS>, dentro de <DPS>. O atributo URI do <Reference> aponta para o atributo Id do <infDPS>.

O exemplo abaixo contém placeholders nos campos que dependem do certificado do prestador (DigestValue, SignatureValue, X509Certificate). Não envie este XML diretamente — o integrador deve gerar esses valores assinando o XML com a chave privada do certificado e-CNPJ do prestador antes de fazer o POST.

iss_no_municipio_prestacao_assinado_exemplo.xml

<?xml version="1.0" encoding="UTF-8"?>
<DPS versao="1.01" xmlns="http://www.sped.fazenda.gov.br/nfse">
      <infDPS Id="DPS230533221122233300018180000177817194766143">
        <tpAmb>2</tpAmb>

        <verAplic>1.01</verAplic>
        <serie>80000</serie>
        <nDPS>177817194766143</nDPS>
        <dCompet>2026-05-07</dCompet>
        <tpEmit>1</tpEmit>
        <cLocEmi>2301000</cLocEmi>
        <prest>
          <CNPJ>11222333000181</CNPJ>
          <IM>123456</IM>
          <xNome>Prestador Teste LTDA</xNome>
          <fone>11999999999</fone>
          <email>prestador@teste.com</email>
          <regTrib>
            <opSimpNac>1</opSimpNac>
            <regEspTrib>0</regEspTrib>
          </regTrib>
        </prest>
        <serv>
          <locPrest>
            <cLocPrestacao>2301000</cLocPrestacao>
          </locPrest>
          <cServ>
            <cTribNac>010101</cTribNac>
            <xDescServ>Serviço de teste para homologação do sistema de NFS-e</xDescServ>
            <cNBS>010151001</cNBS>
          </cServ>
        </serv>
        <valores>
          <vServPrest>
            <vServ>1000.00</vServ>
          </vServPrest>
          <trib>
            <tribMun>
              <tribISSQN>1</tribISSQN>
              <tpRetISSQN>1</tpRetISSQN>
              <pAliq>5.00</pAliq>
            </tribMun>
            <totTrib>
              <indTotTrib>0</indTotTrib>
            </totTrib>
          </trib>
        </valores>
      </infDPS>
      <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
        <SignedInfo>
          <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
          <SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
          <Reference URI="#DPS230533221122233300018180000177817194766143">
            <Transforms>
              <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
            </Transforms>
            <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
            <DigestValue>PREENCHER_DIGEST_BASE64</DigestValue>
          </Reference>
        </SignedInfo>
        <SignatureValue>PREENCHER_SIGNATURE_VALUE_BASE64</SignatureValue>
        <KeyInfo>
          <X509Data>
            <X509Certificate>PREENCHER_CERTIFICADO_A1_BASE64</X509Certificate>
          </X509Data>
        </KeyInfo>
      </Signature>
    </DPS>

Como gerar a assinatura

A assinatura é gerada pelo integrador, do lado do cliente, antes do envio. O webservice apenas valida. Os passos abaixo descrevem o procedimento padrão W3C XMLDSig 1.1 aplicado ao <infDPS>.

Montar o template: adicionar o bloco <Signature> (com a estrutura mostrada acima) como irmão do <infDPS>, dentro de <DPS>. Nesse momento, <DigestValue> e <SignatureValue> ficam vazios e <X509Certificate> é o Base64 do certificado A1 ICP-Brasil do prestador (e-CNPJ ou e-CPF; DER em Base64, sem cabeçalhos -----BEGIN/END CERTIFICATE----- e sem quebras de linha).
Calcular o DigestValue: aplique a canonicalização http://www.w3.org/2001/10/xml-exc-c14n# sobre o elemento <infDPS> (referenciado pela Reference URI), calcule o SHA-256 do resultado e preencha o campo <DigestValue> com o valor em Base64.
Calcular o SignatureValue: aplique a mesma canonicalização Exclusive XML sobre o elemento <SignedInfo> (já com o DigestValue preenchido), assine o resultado com a chave privada do certificado usando RSA-SHA256 (http://www.w3.org/2001/04/xmldsig-more#rsa-sha256) e preencha o campo <SignatureValue> com a assinatura em Base64.
Enviar: faça POST /api/v1/nfse/v101 com header Content-Type: application/xml e o XML completo (com <Signature> preenchida) no body.

A maioria das linguagens tem bibliotecas para o padrão W3C XML Signature que fazem os passos 2 e 3 automaticamente a partir do template do passo 1. Procure pelas implementações de XMLDSig ou XML Signature da sua linguagem ou framework.

Assinatura no caminho JSON

Quando a requisição é enviada em JSON (Content-Type: application/json), o corpo também precisa ser assinado, mas a assinatura não vai dentro do JSON — vai em um cabeçalho HTTP:

Operação	Cabeçalho da assinatura
Emissão (`POST /api/v1/nfse/v101`)	`X-DPS-Assinatura`
Eventos (`POST /api/v1/nfse/:chave_acesso/eventos` e a variante por `:numero_protocolo`) — ex.: cancelamento	`X-Evento-Assinatura`

O valor do cabeçalho é uma assinatura CMS/PKCS#7 destacada (detached), em Base64, calculada sobre os bytes exatos do corpo enviado. O certificado A1 ICP-Brasil do prestador (e-CNPJ ou e-CPF) deve estar embutido na própria estrutura CMS.

Quem assina: na emissão, o prestador; nos eventos, a parte autorizada para o tipo (no cancelamento, o prestador da nota). A conferência de CNPJ é pela raiz (8 dígitos) — o certificado da matriz pode assinar por uma filial do mesmo titular; para CPF, a conferência é exata.

Passos

Montar o corpo JSON exatamente como ele será enviado (mesma sequência de bytes).
Gerar a assinatura CMS/PKCS#7 destacada sobre esses bytes, com a chave privada do certificado do prestador, incluindo o certificado na estrutura CMS.
Codificar em Base64 e colocar no cabeçalho correspondente (X-DPS-Assinatura na emissão, X-Evento-Assinatura nos eventos).
Enviar com Content-Type: application/json e o JSON no body. Importante: não reserialize o JSON depois de assinar — a assinatura cobre os bytes exatos.

Exemplo (cancelamento via JSON)

curl -X POST "https://tributario.speedgov.com.br/{tenant}/api/v1/nfse/:chave_acesso/eventos" \
     -H "Content-Type: application/json" \
     -H "X-Evento-Assinatura: " \
     -d '{
       "tipo_evento": "cancelamento",
       "codigo_motivo_cancelamento": "erro_na_emissao",
       "descricao_motivo_cancelamento": "Erro no valor do serviço"
     }'

Erros do caminho JSON (HTTP 401): E9002, E9003, E9006, E9007, E9016 — ver a aba Erros.

Códigos de erro de assinatura

HTTP status: 422 Unprocessable Entity. Veja a aba Erros para a lista completa de códigos retornados pela API.

Código	Mensagem	Quando ocorre
`E901`	XML não está assinado digitalmente	Falta o elemento <Signature> no XML enviado
`E902`	Assinatura digital inválida	Digest ou SignatureValue não confere com o conteúdo
`E903`	Certificado digital expirado	Certificado fora da janela not_before / not_after
`E904`	Certificado digital inválido	X509Certificate não é parseável por OpenSSL
`E905`	Certificado não encontrado na assinatura	Falta o elemento <X509Certificate> em <KeyInfo>
`E906`	CNPJ do certificado diverge do prestador informado	CNPJ no SubjectAltName do cert ≠ CNPJ em <prest><CNPJ>

API NFS-e Nacional

Sandbox NFS-e Nacional — AMBIENTE DE HOMOLOGAÇÃO

Bem-vindo à API NFS-e Nacional

Cronograma de obrigatoriedade do IBS/CBS

Em produção

Emissão

Consulta

Eventos

DANFSEDepreciado

Fluxo de Integração

Ciclo de Vida da NFS-e

Especificações Técnicas

Formato

Protocolo

Encoding

Response

O que é DPS?

Guia Rápido - Primeiros Passos

Comunicação Cliente ↔ API

1Prepare seu XML DPS

Suspensão da exigibilidade do ISSQN (exigSusp)

Tributos federais (tribFed)

2Envie a requisição

Resposta de Sucesso (200 OK)

Resposta de Erro (422)

3Consulte a NFS-e emitida

4Baixe o PDF (DANFSE)

Próximos Passos

Referência Completa da API

A chave_acesso e o status de autorização

Emitir NFS-e (descontinuado)

Resposta (HTTP 410 Gone)

Consultar NFS-e por número de protocolo

Parâmetros

Response

Exemplo de Resposta — Nota em rascunho (ainda não autorizada)

Exemplo de Resposta — Nota autorizada pelo ADN (mesma chave_acesso)

Exemplo de Resposta — Protocolo não encontrado (404)

Consultar NFS-e

Parâmetros

Response

Exemplo de Resposta

Download DANFSE

Parâmetros

Response

Registrar Evento

Tipos de Evento e Códigos CGOA

Autor do evento (cnpj_autor / cpf_autor)

Exemplo de requisição (cancelamento)

Resposta de sucesso (HTTP 201)

Significado deacao_sugerida

Códigos de retorno HTTP

Listar Eventos da NFS-e

Resposta de sucesso (HTTP 200)

Consultar Eventos por Tipo

Resposta de sucesso (HTTP 200)

Consultar Evento Específico

Resposta de sucesso (HTTP 200)

Perguntas frequentes — Fluxo de cancelamento

Histórico de Eventos da NFS-e

Campos temporais

Estados possíveis emstatus_evento

Interpretando o estado atual

Exemplos de Integração

Coleção Postman - Todos os Exemplos

Emissão

Consulta

DANFSEDepreciado

Eventos

Como Usar a Coleção

Passo a Passo

Estrutura das Pastas

Tipos de Eventos Suportados

Dica

Operações com Exterior

Tomador no Exterior (NIF / Comércio Exterior)

Exemplo completo de DPS (v1.01) com tomador no exterior

Domínios dos campos do grupo comExt

Consulta de Catálogos

cTribMun— Códigos de tributação municipalopcional

A `chave_acesso` e o status de autorização

Significado de`acao_sugerida`

Estados possíveis em`status_evento`