18/06/2026

Segurança

• Assinatura digital obrigatória também no endpoint v1.01. POST /api/v1/nfse/v101 passa a exigir que a DPS chegue assinada digitalmente (XMLDSig), como já ocorre em POST /api/v1/nfse. DPS sem assinatura é rejeitada com E901; assinatura ou certificado inválidos retornam E902, E903 ou E905. Integrações que enviavam XML não assinado ao endpoint v1.01 precisam passar a assinar a DPS.

Alterado

• Conferência do certificado por CPF, além de CNPJ. O documento do certificado do assinante é conferido contra o prestador também quando o certificado é e-CPF (antes apenas e-CNPJ): CNPJ no e-CNPJ, CPF no e-CPF. A divergência continua retornando E906, cuja mensagem passa de "CNPJ do certificado diverge do prestador informado" para "Documento do certificado diverge do prestador informado".

17/06/2026

Adicionado

• Emissão para tomador no exterior. O webservice passa a aceitar tomador estrangeiro, identificado por <NIF> (Número de Identificação Fiscal) ou por <cNaoNIF> (motivo de não informação do NIF: 0 sem NIF, 1 dispensado, 2 não exigido), no lugar de <CNPJ>/<CPF>. O endereço usa o grupo <end><endExt><cPais> (código do país em ISO 3166-1 alfa-2, ex.: BN). Quando o tomador é do exterior, o grupo de comércio exterior <comExt> passa a ser obrigatório (mdPrestacao, vincPrest, tpMoeda, vServMoeda, mecAFComexP, mecAFComexT, movTempBens). O tpMoeda usa o código da moeda no padrão SISCOMEX (ex.: 220 = USD, 978 = EUR). Veja o exemplo na aba Exemplos → Tomador no Exterior.

Corrigido

• Tomador estrangeiro era recusado com erro genérico de campo obrigatório. Ao emitir para tomador identificado por NIF (sem CPF/CNPJ), o webservice retornava Campo obrigatório ausente: tomador_cpf_cnpj, mesmo o cenário sendo válido. Agora o webservice aplica as mesmas validações da emissão pela tela e os erros passam a vir com os códigos oficiais da ADN (ex.: E0188, E0191, E0235, E1235) no lugar do código genérico — ver a aba Códigos de Erro. Não é necessário reenviar notas já emitidas.

01/06/2026

Corrigido

• DANFSe de nota imune/exportação/não-incidência exibia "Valor Líquido da NFS-e" igual a R$ 0,00. Nessas tributações (sem alíquota de ISSQN) o valor líquido do DANFSe passa a ser calculado corretamente (= valor do serviço, descontadas eventuais retenções). O XML autorizado no ADN já estava correto (campo vLiq, conforme a regra E1303); a correção afeta apenas a representação gráfica (DANFSe). Não é necessário reenviar, cancelar ou alterar notas no ADN. Notas emitidas antes desta correção mantêm o valor antigo na representação até serem reprocessadas.

Depreciado

• GET /api/v1/danfse/:chave_acesso — depreciado (mantido em funcionamento, sem data de remoção). A geração do DANFSe não é responsabilidade da API: após a autorização no ADN, o DANFSe oficial é consultável pela chave de acesso no portal nacional (https://www.nfse.gov.br/ConsultaPublica). Integrações que emitem via webservice podem obter o XML completo no endpoint de consulta da nota (GET /api/v1/nfse/:chave_acesso) e montar a própria representação gráfica. As respostas do endpoint passam a incluir os cabeçalhos Deprecation: true, Link (apontando para o portal nacional) e Warning.

30/05/2026

Corrigido

• chave_acesso agora é estável desde a emissão. A chave de acesso (50 dígitos) retornada no POST /api/v1/nfse é a mesma do início ao fim do ciclo de vida da nota — não muda mais entre a emissão e a autorização pelo ADN. Antes, uma chave local "provisória" podia ser substituída por outra ao autorizar o lote; agora a chave gerada na emissão é exatamente a que o ADN confirma. Use a chave_acesso como identificador da NFS-e.
• chave_acesso_provisoria foi ressignificada. O campo continua presente nas respostas de POST e do GET por protocolo, mas passa a indicar apenas o status de autorização da nota (true = ainda não autorizada pelo ADN; false = autorizada). Ele não significa mais que a chave mudará de valor.

Depreciado

• GET /api/v1/nfse/protocolo/:numero_protocolo — depreciado (mantido para integrações existentes, sem data de remoção). Como a chave_acesso é estável, o identificador recomendado passa a ser a própria chave: prefira GET /api/v1/nfse/:chave_acesso. O numero_protocolo segue válido como identificador alternativo.

26/05/2026

Corrigido

• POST /api/v1/nfse/v101 — DPS com <cTribNac>990101</cTribNac> (Serviços sem incidência de ISSQN e ICMS) combinada a <tribISSQN>4</tribISSQN> (Não Incidência) deixa de retornar o erro falso E0532 ("Tributacao issqn deve ser 'Não Incidência' (4) quando o código de tributação for 990101"). A combinação correta agora é aceita; a regra E0532 continua sendo aplicada quando o XML envia tribISSQN diferente de 4 com cTribNac=990101.
• POST /api/v1/nfse/v101 — DPS com <tribISSQN>2</tribISSQN> (Imunidade) e <tpImunidade> informado agora propaga o tipo de imunidade para a NFS-e. Antes, o valor não era persistido, causando rejeições falsas em validações posteriores (E0592).
• POST /api/v1/nfse/v101 — quando <tribISSQN> é 2 (Imunidade), 3 (Exportação de Serviço) ou 4 (Não Incidência), a NFS-e resultante não traz mais base de cálculo, alíquota nem código de município de incidência preenchidos automaticamente. Antes esses campos eram populados internamente e disparavam E1303, E1301 ou E0601 indevidamente após a correção do E0532.
• POST /api/v1/nfse/:chave_acesso/eventos com tipo_evento cancelamento, cancelamento_por_substituicao ou cancelamento_por_oficio deixa de revalidar as regras de emissão da nota (validações IBS/CBS, base de cálculo, local de incidência etc.). Cancelamento de NFS-e v1.01 do Simples Nacional em 2026 passava a falhar com E1539 ("Alíquota da UF para IBS incorreta") por causa dessa revalidação indevida — a nota já foi validada na emissão e o cancelamento não deve verificar regras de emissão novamente.

Adicionado

• Novo retorno E003 — Formato do campo inválido (HTTP 400) quando o body XML é enviado com Content-Type incompatível (ex.: application/json). A resposta inclui detalhes orientando o uso de Content-Type: application/xml e exibe o valor recebido. Antes, esse cenário retornava E703 — Erro ao processar DPS sem detalhes úteis, dificultando o diagnóstico do integrador.

Alterado

• A mensagem do retorno de sucesso de POST /api/v1/nfse/v101 foi reescrita para orientar a consulta do XML pelo endpoint correto: "NFS-e v1.01 em processamento. Aguarde autorização da ADN; consulte o XML em GET /api/v1/nfse/v101/:chave_acesso ou GET /api/v1/nfse/protocolo/:numero_protocolo." Mensagem anterior sugeria que o integrador precisaria gerar o XML, o que é incorreto — o XML é gerado e enviado à ADN pelo próprio sistema.
• E703 — Erro ao processar DPS: o campo detalhes agora preserva mensagens multilinha. Antes, exceções cuja mensagem começava com quebra de linha retornavam detalhes vazio, ocultando a causa do erro do integrador.

23/05/2026

Alterado

• POST /api/v1/nfse/v101 — <cTribMun> (código de tributação municipal) passa a ser opcional no XML da DPS, alinhando ao XSD nacional (minOccurs="0" em TCCServ). DPS contendo apenas <cTribNac> (código de tributação nacional) é aceita; a NFS-e resultante fica sem código municipal vinculado. Integradores que precisam do agrupamento por código municipal nos relatórios locais devem continuar enviando <cTribMun>.
• Mensagem do erro E002 ("Campo obrigatório não informado") aplicada a codigo_de_tributacao_id foi reescrita para citar explicitamente as tags cTribMun e cTribNac e referenciar o endpoint do catálogo (/api/v1/catalogo/codigos_tributacao_nacional).
• Catálogo cTribMun em /api/docs/nfse recebeu marcação visual opcional com nota explicativa; catálogo cTribNac recebeu marcação obrigatório indicando que código inexistente retorna E002 sem fallback automático.

Corrigido

• POST /api/v1/nfse/v101 — quando o <cTribNac> enviado não existia no catálogo nacional, o sistema usava silenciosamente o primeiro código do catálogo como substituto, gerando NFS-e com tributação incorreta. Agora retorna erro explícito E002 — Código de tributação nacional não encontrado ou não informado, alinhado ao comportamento já existente na v1.00.

Adicionado

• Novo exemplo de DPS sem_ctribmun no catálogo público de exemplos (docs/exemplos_api_nfse_v101/), demonstrando o caminho mínimo de envio: apenas <cTribNac> no bloco <cServ>, sem <cTribMun>.

Adicionado

• Sandbox NFS-e Nacional — tenant compartilhado integracao para testes de integração sem afetar dados de produção. URL base: https://tributario.speedgov.com.br/integracao/api/v1/. Documentação completa na nova aba /api/docs#sandbox.
• Header HTTP X-NFSe-Ambiente em todas as respostas dos endpoints NFS-e: valor producao em tenants de prefeituras reais; valor homologacao em tenants com sandbox ativo. Permite ao integrador confirmar em qual ambiente a chamada foi processada.
• Tag <tpAmb> no XML da NFS-e/DPS em sandbox é sempre 2 (homologação), independente do valor enviado.
• Marca d'água diagonal AMBIENTE DE HOMOLOGAÇÃO — SEM VALOR FISCAL aplicada no DANFSE retornado por GET /api/v1/danfse/:chave_acesso quando a nota foi emitida em sandbox.
• Auto-cadastro de prestador em sandbox — quando uma DPS chega ao sandbox com CPF/CNPJ ainda não cadastrado, o sistema cria automaticamente o cadastro do prestador a partir dos dados do bloco <prest> (tags CNPJ/CPF e xNome). Elimina a necessidade de pré-cadastro manual e viabiliza testes self-service.
  • Validação algorítmica de CPF e CNPJ (módulo 11) continua ativa. Documentos mal formados são rejeitados antes do cadastro.
  • O campo xNome é obrigatório. Se vier vazio, a resposta é E101 com detalhes: "Auto-cadastro do prestador no sandbox falhou: razao_social_obrigatoria".
  • Documento algoritmicamente inválido: E101 com detalhes: "Auto-cadastro do prestador no sandbox falhou: documento_invalido".
• Nova aba Assinatura Digital em /api/docs/nfse com:
  • Tabela dos algoritmos exigidos (CanonicalizationMethod, SignatureMethod, Transform, DigestMethod, Reference URI)
  • Nota sobre suporte ao padrão SPED Nacional com os dois transforms
  • Estrutura do bloco <Signature> (irmão de <infDPS>)
  • Exemplo XML completo com placeholders nos campos que dependem do certificado do prestador
  • Tabela dos códigos de erro E901 a E906
• Novo arquivo de exemplo iss_no_municipio_prestacao_assinado_exemplo.xml (na coleção de exemplos da v1.01) contendo o bloco <Signature> completo com placeholders.
• Coleção Postman (Baixar Coleção Postman) — o raw body do request Emitir NFS-e agora inclui o bloco <Signature> com placeholders, espelhando o novo exemplo.

Alterado

• Em sandbox, a validação E103 ("Estabelecimento não autorizado para emissão") é bypassada — qualquer estabelecimento ativo do tenant pode emitir, independentemente de estar configurado para emissão de NFS-e na prefeitura. Em produção, E103 continua sendo aplicado normalmente.
• Em sandbox, a validação E101 ("Estabelecimento não encontrado") passa a ser bypassada via auto-cadastro automático (ver acima). Em produção, E101 continua sendo retornado normalmente quando o prestador não está cadastrado.
• Em sandbox, eventos da NFS-e (POST /api/v1/nfse/:chave_acesso/eventos) são gravados localmente com tpAmb=2, mas não são transmitidos ao Ambiente Nacional (ADN).
• POST /api/v1/nfse — quando a validação de assinatura falha por um erro inesperado, o campo detalhes da resposta E902 agora retorna a mensagem genérica "Erro interno ao validar assinatura digital", em vez de expor detalhes técnicos internos do servidor.

Corrigido

• POST /api/v1/nfse — validador de assinatura digital deixa de retornar E902 falso-positivo quando a DPS é assinada conforme o padrão SPED Nacional oficial, em que o elemento <Transforms> contém os dois algoritmos [enveloped-signature, exc-c14n] (caso em que <Signature> é irmão de <infDPS> e o nó referenciado por <Reference URI="#..."> não contém <Signature> como descendente).

Segurança

• Auto-cadastro de prestador ocorre apenas em tenants com sandbox ativo. Em produção, o comportamento de validação de cadastro permanece inalterado e CPF/CNPJ não cadastrado continua disparando E101.

13/05/2026

Adicionado

• GET /api/v1/nfse/:chave_acesso/eventos — lista todos os eventos vinculados à chave, ordenados por created_at DESC.
• GET /api/v1/nfse/:chave_acesso/eventos/:tipo_evento — eventos filtrados por tipo, ordenados por numero_sequencial ASC.
• GET /api/v1/nfse/:chave_acesso/eventos/:tipo_evento/:num_seq_evento — consulta de um evento específico pela combinação (chave_acesso, tipo_evento, num_seq_evento).
• Resposta do POST /api/v1/nfse/:chave_acesso/eventos e dos novos GETs passa a expor o conjunto completo do evento (19 campos): id_evento, codigo_tipo_evento (padrão CGOA), tipo_evento, numero_sequencial, numero_protocolo, chave_acesso, data_hora_evento, data_hora_processamento, aguardando_desde, status_evento, protocolo, codigo_retorno, mensagem_retorno, erros_adn (sanitizado — remove chaves sensíveis, trunca strings, limita profundidade a 3 níveis), reprocessamentos_count, ultimo_reprocessamento_em, acao_sugerida, descricao_evento. O POST inclui também o campo mensagem.
• Campo data_cancelamento no GET /api/v1/nfse/:chave_acesso — retornado quando status == "cancelada", derivado do evento de cancelamento mais recente da nota (cancelamento, cancelamento_por_substituicao ou cancelamento_por_oficio). Para notas autorizadas retorna null.
• Campo acao_sugerida em todo payload de evento (POST e GETs). Valores possíveis: aguardar, retentar, consultar_suporte, cancelado_ok. Permite ao integrador decidir o próximo passo sem precisar interpretar manualmente o conjunto de campos.
• Seção Perguntas frequentes — Fluxo de cancelamento em /api/docs#faq-cancelamento, mapeando dúvidas comuns (data do cancelamento, consulta de protocolo do evento, diagnóstico de cancelamento que falhou, polling assíncrono) para os endpoints e campos correspondentes.
• Campos opcionais cnpj_autor (14 dígitos) e cpf_autor (11 dígitos) no POST /api/v1/nfse/:chave_acesso/eventos, mutuamente exclusivos. Quando omitidos, o autor é inferido do tipo_evento e da nota: cancelamentos (cancelamento, cancelamento_por_substituicao, solicitacao_analise_fiscal_para_cancelamento, confirmacao_prestador, rejeicao_prestador) usam o documento do prestador; manifestações de tomador (confirmacao_tomador, rejeicao_tomador) usam o documento do tomador; manifestações de intermediário (confirmacao_intermediario, rejeicao_intermediario) usam o documento do intermediário.

Alterado

• O envelope { "status": "OK" } agora é preservado em toda resposta de sucesso da API v1, mesmo quando o payload do recurso usa a chave status. O status do evento foi renomeado de status para status_evento para evitar colisão com o envelope.
• Postman collection (download em /api/docs/postman):
  • Códigos CGOA corrigidos em confirmacao_tomador (203212 → 203202) e rejeicao_tomador (203216 → 203206). Os códigos anteriores não existem no catálogo oficial.
  • Adicionadas três requests GET na pasta Eventos: lista, por tipo, e específico (tipo + num_seq).

Corrigido

• POST /api/v1/nfse/:chave_acesso/eventos agora retorna HTTP 409 Conflict quando há colisão concorrente no numero_sequencial após retry interno. Antes, dois POSTs simultâneos podiam criar dois eventos com o mesmo (nota, tipo_evento, numero_sequencial).
• POST /api/v1/nfse/:chave_acesso/eventos agora retorna HTTP 422 Unprocessable Entity com mensagem explicativa quando já existe outro cancelamento desta nota em estado não-terminal (pendente, enviado, aguardando_autorizacao_nota ou erro com retry pendente). Evita corridas entre múltiplos cancelamentos da mesma nota.
• GET /api/v1/nfse/:chave_acesso/eventos[/...] retornam o envelope { "status": "OK", ... } (antes vinha sem envelope por efeito colateral da renderização).
• Eventos criados via POST /api/v1/nfse/:chave_acesso/eventos sem cnpj_autor/cpf_autor agora seguem para o ADN preenchendo o autor automaticamente (ver Adicionado). Antes, ausência do autor podia gerar rejeição no ADN com código E1235 (falha de esquema XML).
• Quando o ADN rejeita um evento, o motivo passa a aparecer no campo erros_adn da resposta do GET do evento. Antes, o status_evento virava rejeitado mas erros_adn ficava null — o motivo só estava disponível internamente.

Segurança

• O campo erros_adn exposto nas respostas é sanitizado antes da serialização: remove qualquer chave contendo senha, password, token, secret, chave_privada, backtrace, stack, cookie ou authorization; trunca strings com mais de 1000 caracteres; limita profundidade do objeto a 3 níveis.

08/05/2026

Adicionado

• GET /api/v1/catalogo/motivos_evento — catálogo público dos campos obrigatórios e opções aceitas em cada tipo_evento do POST /api/v1/nfse/:chave_acesso/eventos. Retorna, para cada tipo:
  • campos_obrigatorios — lista de campos exigidos pelo Grape;
  • enums — opções aceitas em cada campo enumerado, com codigo (string usada no payload), valor (inteiro persistido) e descricao (label legível em pt-BR);
  • endpoint — método, URL por chave_acesso e por numero_protocolo (recomendada) e content_type;
  • exemplo_payload — corpo JSON pronto para enviar (com tipo_evento + primeiro código do enum + placeholders textuais);
  • doc_url — link para a âncora correspondente em /api/docs. Use sem filtro para receber a árvore completa, ou ?tipo_evento=cancelamento para uma única entrada chata.
• POST /api/v1/nfse/protocolo/:numero_protocolo/eventos — rota paralela ao endpoint de eventos por chave_acesso. Recomendada para registrar eventos pós-emissão: o numero_protocolo é estável, enquanto a chave_acesso provisória pode ser substituída pela oficial após autorização do ADN.

Corrigido

• POST /api/v1/nfse/:chave_acesso/eventos agora aceita corretamente os campos de motivo enumerado para todos os tipos que dependem deles (cancelamento, cancelamento_por_substituicao, solicitacao_analise_fiscal_para_cancelamento, rejeicao_prestador, rejeicao_tomador, rejeicao_intermediario, cancelamento_por_oficio, bloqueio_por_oficio e similares). Antes, mesmo com payload completo, a chamada era rejeitada com 422. Quando algum campo obrigatório do tipo está ausente ou um valor de enum está fora do conjunto permitido, a resposta agora é 400 com mensagem indicando o campo e o conjunto de valores aceitos.
• Validador de tipos do XML DPS aceita tribISSQN=4 (Não Incidência), conforme o XSD oficial v1.01 do ADN. Antes a entrada era rejeitada com erro E0002 mesmo sendo válida pelo schema.
• protocolo.status agora reflete o estado final da NFS-e após o ADN confirmar o lote: processando → autorizado (ou cancelado/rejeitado quando aplicável). Antes o status ficava preso em processando mesmo após nota.status=autorizada, confundindo integradores que rastreavam o ciclo via numero_protocolo.
• Campo xml_nota na resposta dos endpoints de emissão e consulta passa a retornar o XML real da nota: prioriza a NFS-e autorizada pelo ADN (xml_nfse), com fallback para a DPS assinada (xml_assinado) enquanto o ADN ainda não devolveu a NFS-e final. Antes o campo retornava null em todas as notas emitidas via webservice, mesmo após autorização.

Alterado

• Postman collection (download em /api/docs/postman):
  • URL dos eventos corrigida de /api/v1/eventos para /api/v1/nfse/:chave_acesso/eventos.
  • Payloads dos cinco eventos atualizados com os campos corretos por tipo (incluindo codigo_motivo_cancelamento, descricao_motivo_cancelamento, motivo_rejeicao_*, etc.).
  • Adicionadas variáveis chave_acesso e numero_protocolo.
  • Nova entrada na pasta Catalogo: "Motivos por Tipo de Evento".
  • Nova entrada na pasta Eventos: "Cancelamento via numero_protocolo (recomendado)".

07/05/2026

Adicionado

• GET /api/v1/nfse/protocolo/:numero_protocolo — consulta NFS-e pelo número de protocolo. Diferente da chave_acesso (que pode ser substituída pela oficial após autorização do ADN), o numero_protocolo é estável durante todo o ciclo de vida da nota. É o jeito recomendado de o integrador rastrear a nota e descobrir a chave oficial depois do processamento assíncrono.
• Flag chave_acesso_provisoria (booleana) nas respostas dos POSTs de emissão e dos GETs de consulta. Quando true, o valor da chave_acesso ainda é local e pode ser substituído pela chave oficial quando o lote for autorizado pelo ADN. Persista também o numero_protocolo como ancoragem confiável.
• Cinco endpoints públicos de catálogo, sem autenticação, com Cache-Control: public, max-age=3600 e paginação:
  • GET /api/v1/catalogo/codigos_tributacao_municipal
  • GET /api/v1/catalogo/codigos_tributacao_nacional
  • GET /api/v1/catalogo/nbs
  • GET /api/v1/catalogo/municipios
  • GET /api/v1/catalogo/paises
• Catálogo de erros DPS com âncora HTML por código na página /api/docs#codigos-erro. Códigos catalogados nesta release: E002, E0001, E0002, E0003, E0010, E0310, E0370, E0372, E0390, E0392, E0928, E0931, E0932, E1301, E1305, E1313, E1317, E1321, E1402, E502, E802.
• Toda resposta 422 dos endpoints de emissão (v1.00 e v1.01) passa a incluir, para cada erro, os campos codigo, xpath, mensagem, origem_moc, doc_url (link para a âncora correspondente em /api/docs) e, quando aplicável, exemplo_ref indicando qual exemplo público cobre o cenário.
• Validador de tipos do XML DPS pré-parser. Rejeita 422 antes da extração silenciosa quando o XML traz tipo numérico inválido (ex.: <vServ>abc</vServ>, alíquota fora de [0,100], tribISSQN fora do enum, código IBGE com tamanho errado). Erros usam os códigos E0001, E0002, E0003.
• No POST /api/v1/nfse/v101, o XML é pré-validado contra tags legadas de padrões municipais antigos. Tags como <serv><cMunPrest>, <serv><cMunInc>, <tom>, <xEmail> e <serv><xDescServ> são rejeitadas com erro E0010 indicando a forma canônica equivalente do ADN (ex.: <serv><locPrest><cLocPrestacao>, <toma>, <email>, <serv><cServ><xDescServ>).
• Quando o POST /api/v1/nfse (v1.00) tolera uma tag legada por compatibilidade, a resposta inclui o header HTTP Warning: 299 com link para a seção /api/docs#tags-depreciadas. Sinaliza que existe forma canônica preferida — não é prazo de remoção.
• Inferência automática do município de incidência a partir do cTribNac informado no DPS. Integradores conformes ao MOC ADN não precisam enviar a tag de município de incidência: o webservice resolve pelo local_incidencia_imposto cadastrado para o cTribNac (município do prestador, do local da prestação, ou do tomador).
• Página /api/docs publicada com guia rápido, exemplos completos de DPS XML de envio (3 cenários: ISS no município da prestação, ISS no tomador, com retenção de ISS), catálogos de códigos, lista de tags aceitas e depreciadas, e Postman collection v2.1 baixável.

Corrigido

• Parser v1.00 lê cTribMun do caminho canônico <valores><trib><tribMun> do XML DPS.

Alterado

• URL pública de produção centralizada na documentação. Os campos doc_url retornados nas respostas de erro 422 sempre apontam para o domínio público, mesmo em ambientes de desenvolvimento local (evita exposição de localhost:3000 para integradores).