Pular para o conteúdo

Changelog

Esta página registra as alterações relevantes da API de emissão de notas do FazNota e desta documentação.

A API segue o SemVer — MAJOR.MINOR.PATCH:

ParteQuando mudaEfeito para você
PATCH (3.4.0 → 3.4.1)Correção compatívelNenhum. Nada a fazer
MINOR (3.4.0 → 3.5.0)Endpoint ou campo opcional novoNenhum. Quem não usa o recurso novo não é afetado
MAJOR (v3 → v4)Quebra de contratoNão acontece dentro da v3. Vira um novo path (/nfemyse-v4/), com as duas versões no ar em paralelo e comunicação prévia de no mínimo 90 dias

Como saber qual versão está te respondendo: toda resposta traz o header X-API-Version e o campo meta.api_version.

{ "status": "004", "descricao": "Nota emitida com sucesso.",
"data": { },
"meta": { "request_id": "req_...", "timestamp": "...", "api_version": "3.23.0" } }

3.23.0 — 2026-11-20 — NFS-e de locação de bem móvel

Campo opcional novo. Quem já integra não precisa mudar nada; a locação de imóvel segue igual.

Novo

  • locacao.bens-moveis no POST /nfse/emissao — a NFS-e do aluguel de bem móvel (serviço 99.04.01, grupo bensMoveis da NT 009): até 1000 bens com ncm, descricao e quantidade, mais o indicador-operacao obrigatório (010101, 010102, 010103 ou 010106, o modo de entrega do bem). Sem ISS. Não combina com os campos do imóvel. Guia: Locação de bem móvel.

2026-11-19 — NF-e: rateio do frete proporcional ao valor do item

Sem mudança de contrato nem de versão: nenhum campo novo no payload.

Adicionado

  • Rateio do frete proporcional ao valor dos itens, ativado por empresa (pelo suporte). Sem a ativação a nota continua com o rateio igual por linha. Ver Emitir NF-e.

3.22.0 — 2026-11-18 — NF-e: natureza da operação, frete sem transportadora e tributos aproximados

Adicionado

  • natureza-operacao em POST /nfe/emissao (opcional, até 60 caracteres): o texto do natOp da nota. Sem o campo, a nota continua com a descrição do CFOP — o payload de quem não envia o campo não muda.
  • Frete por conta do remetente (0) ou do destinatário (1) sem transportadora. Em transporte, a transportadora passa a ser opcional nessas duas modalidades (antes: “Campo nfe@transporte@transportadora deve ser preenchido.”). Nas modalidades 2, 3 e 4 continua obrigatória.
  • Tributos aproximados (Lei 12.741) na NF-e. Com o recurso ativado para a empresa (pelo suporte), o XML passa a levar o vTotTrib de cada item e o total em ICMSTot/vTotTrib, calculados pela tabela do IBPT. Nada muda no payload da API. Ver Emitir NF-e.

Corrigido

  • pST do CSOSN 500. O XML trazia vICMSSTRet preenchido com pST zerado; agora pST é o percentual-icms-st-ret da configuração fiscal do produto, o mesmo usado no cálculo. O guia Emitir NF-e explica de onde sai cada campo do ST retido.
  • GET /nfe/nota/{recibo} (e /completa) não fica mais em 999 quando a nota já teve desfecho na SEFAZ. Um erro interno de uma tentativa anterior ficava na frente da nota mesmo depois de ela ser reenviada pelo painel e autorizada, rejeitada ou cancelada; agora vale a situação da nota. Enquanto não há resposta da SEFAZ, o retorno é o mesmo de antes.

3.21.2 — 2026-11-17 — aliquotas opcional no cadastro de produto

Corrigido

  • aliquotas do ICMS por estado passa a ser opcional em POST /produtos e PUT /produtos/{ref}. Um estado sem o bloco (o normal para CSOSN 102 ou CST 40/41, que não destacam ICMS) derrubava o cadastro inteiro com “Falha ao converter JSON.”. Agora a ausência vale o mesmo que "aliquotas": {} — tudo em "0" —, como a especificação sempre descreveu.
  • A recusa do JSON do produto diz a causa. A mensagem passa a ser Falha ao converter JSON: <motivo> (por exemplo, o campo vazio ou ausente), em vez da frase genérica sozinha.

3.21.1 — 2026-11-17 — CEST no cadastro de produto

Corrigido

  • cest em POST /produtos e PUT /produtos/{ref} passa a ser gravado. Antes o código era aceito e descartado: o produto ficava sem CEST e, no PUT, o CEST cadastrado pela tela era apagado. Agora o CEST enviado vai para o cadastro (e daí para o XML da NF-e/NFC-e), e o PUT sem o campo mantém o CEST atual. Aceita 7 dígitos com ou sem pontuação ("0302100" ou "03.021.00"); vazio ou "0" remove o CEST.
  • codigo-anvisa deixa de recusar o cadastro. O campo era lido com outro nome e o produto inteiro voltava 999 com “Falha ao converter JSON.”.

Atenção

  • CEST fora da tabela CEST (ou que não tenha 7 dígitos) agora é recusado com 999 e o motivo em data.erro, em vez de ser ignorado sem aviso. O CEST não é preenchido a partir do NCM: envie-o no cadastro do produto.

3.21.0 — 2026-11-15 — CT-e, CT-e OS, MDF-e e BP-e completos

As rotas de transporte existiam desde a 3.6.0/3.7.0, mas não fechavam: não havia como consultar o resultado, o contrato documentado estava incompleto (no MDF-e, o campo pedido era ignorado) e o BP-e não tinha o serviço no ar. Agora os quatro documentos funcionam de ponta a ponta.

Novo

  • GET /cte/{recibo}, GET /cte-os/{recibo}, GET /mdfe/{recibo} e GET /bpe/{recibo} — o desfecho de emissões e eventos: 004 autorizado (chave, protocolo) ou evento registrado, 010 cancelado, 900 recusado (c-stat, x-motivo), 999 técnico, 002/003 na fila, 500 recibo de outra empresa ou de outro modelo.
  • Contrato completo da emissão e de cada evento nas quatro famílias, conferido na entrada (400 com data.campo). Veja os guias CT-e, MDF-e e BP-e.
  • MDF-e montado pelo corpo: veículo pela placa, condutor pelo CPF, municípios pelo código IBGE e documentos pela chave. O id-mdfe de um rascunho montado na tela continua aceito.
  • Eventos por chave ou recibo: a API resolve protocolo e sequência do evento; o integrador não precisa guardar o protocolo da autorização.
  • Reenvio seguro: depois de 900, o mesmo numero-origem corrige e reenvia o mesmo documento; depois de 999, o documento já numerado é consultado na SEFAZ antes de qualquer nova emissão (adotado se autorizado), então o reenvio nunca gera documento duplicado.
  • BP-e: substituição feita como ela é na SEFAZ — emissão de um bilhete novo (tpBPe=3) no lugar do anterior.

Mudou

  • numero-origem passa a ser obrigatório na emissão de CT-e, CT-e OS, MDF-e e BP-e, e os campos de cada rota são conferidos na entrada. Pela regra do SemVer, recusar na entrada o que antes era aceito seria MAJOR. Ficou MINOR porque essas rotas tinham uso zero (nenhuma emissão pela API desde que entraram no ar) e o que era aceito antes nunca chegava a um resultado: não quebra nenhuma integração existente. Decisão registrada aqui.

Corrigido

  • MDF-e: cancelamento bem-sucedido era gravado como erro, e encerramento recusado (ou pendente de assinatura A3) como sucesso.
  • CT-e: carta de correção, cancelamento e eventos podiam usar a sessão de outra empresa no serviço de transmissão; em grupos com mais de uma empresa, o evento podia sair pela empresa padrão do usuário. Agora a empresa é sempre a do pedido.
  • CT-e e CT-e OS com o mesmo número de origem não colidem mais; duplicidade na SEFAZ (204) é conciliada.

3.20.0 — 2026-11-15 — Certificado digital A1 pela API

Endpoints novos. Quem já integra não precisa mudar nada.

Novo

  • POST /certificado/a1 — instala (ou troca) o certificado digital A1 da empresa da chave: o .pfx em base64 no campo arquivo (até 50 KB) e a senha. Responde na hora (001): o certificado já fica em uso na emissão seguinte. Antes de gravar, confere as mesmas regras da tela do FazNota: abre com a senha, chave privada, ICP-Brasil, dentro da validade, titular com a mesma raiz de CNPJ (ou o mesmo CPF) da empresa, e não troca um certificado válido por um que vence antes. Senha e arquivo nunca vão para log nem resposta.
  • GET /certificado — situação do certificado instalado (A1 ou A3): situacao (VALIDO, A_VENCER, VENCIDO, NAO_INSTALADO, INDISPONIVEL), dt-validade e dias-para-vencer.

Guia: Certificado digital A1.

3.19.0 — 2026-11-11 — Ajustes da base de cálculo da locação

Campo opcional novo. Quem já integra não precisa mudar nada.

Novo

  • locacao.unidades[].ajustes no POST /nfse/emissao — os ajustes da base de cálculo do aluguel (gAjusteBCLocImoveis), até 1000 por unidade: tipo 01 tributos (IPTU), 02 emolumentos, 03 condomínio, 04 redutor social (só imóvel residencial) e 99 outras (com descricao, até 150 caracteres, só nesse tipo), e valor (o total da parcela, maior que zero). A soma dos ajustes não pode passar do valor-total.

Mudou

  • Indicador de operação padrão da locação passa a 020101 (Anexo VIII 1.02.00, de 26/10/2026), no lugar de 020201, que deixou de valer para os serviços 99.03. Quem omite indicador-operacao não precisa fazer nada; quem envia 020201 passa a ter a nota recusada com a mensagem do código esperado.

3.18.0 — 2026-11-11 — NFS-e de locação de imóvel

Campo opcional novo. Quem já integra não precisa mudar nada.

Novo

  • locacao no POST /nfse/emissao — a NFS-e do aluguel de imóvel (serviços 99.03.01 a 99.03.05, NT 009): município do imóvel (IBGE), valor total, percentual de copropriedade, descontos, vencimento e as unidades imobiliárias (com o CIB ou o endereço). Vale para empresa marcada para NFS-e de locação no FazNota, com um item de serviço 99.03 cujo valor é o percentual × o valor total. Indicador de operação e classificação tributária têm padrão (020201 / 200027). Não combina com condominio.

3.17.0 — 2026-11-11 — Rotinas de emissão automática de NFS-e

Endpoints novos. Quem já integra não precisa mudar nada.

Novo

  • /rotinas: o módulo de Rotinas do emissor (Outras > Rotinas) pela API. Uma rotina emite a NFS-e sozinha em cada data da agenda (mensal, bimestral, trimestral, semestral ou anual), para o mesmo cliente e serviço. Modelos de hoje: nota de serviço recorrente (NFSE_RECORRENTE), aluguel de imóvel (NFSE_ALUGUEL) e taxa de condomínio (NFSE_CONDOMINIO, só para empresa marcada como condomínio edilício). O que é criado pela API aparece na tela, e vice-versa.
  • Cadastro: GET /rotinas/modelos (os campos de cada modelo), GET /rotinas/clientes?busca= e GET /rotinas/servicos para preencher os campos, POST /rotinas/validar (pendências sem gravar), POST /rotinas (ativar padrão true; false grava rascunho), GET/PUT/DELETE /rotinas/{id} (o PUT é parcial nos parâmetros; o modelo não muda).
  • Operação: POST /rotinas/{id}/pausar, /retomar e /emitir-agora ({"competencia": "AAAA-MM"}, vazio = mês atual), GET /rotinas/{id}/execucoes (histórico, com o recibo de cada NFS-e) e o detalhe com pendencias e diagnostico (por que emitiu ou não).
  • Valor extra: GET /rotinas/{id}/extras e PUT/DELETE /rotinas/{id}/extras/{AAAA-MM} ({"valor", "motivo"}) somam um valor a mais em um único mês, sem mudar o valor normal.
  • Sem nota em dobro: cada competência usa o numero-origem ROT-<id>-<AAAA-MM>; competência já emitida não se repete, nem pelo agendador nem pelo emitir-agora.

As respostas seguem o envelope da v3 (005 em leitura, 001 em gravação ou ação, 500 para rotina não encontrada, 400 com data.campo e/ou data.pendencias, 999 em falha interna). As chaves saem em kebab-case, menos o conteúdo de parametros e rotulos, que mantém os nomes do modelo (id_clifor, vl_servico). A chave precisa ter permissão fiscal. Veja o guia Rotinas de emissão automática.

Implantação: depende do ERP com /api/v1/rotinas (myse-erp), que sobe no mesmo pacote de deploy.

3.16.1 — 2026-11-10 — EPEC do CT-e descontinuado (NT 2026.004)

Mudança imposta pela SEFAZ. A NT 2026.004 do CT-e extingue o EPEC (evento 110113): a partir de 14/12/2026 a SEFAZ recusa o evento com a rejeição 629.

Mudou

  • POST /cte/epec: a rota continua no ar, mas recusa na hora, com erro de validação e sem recibo. Nada é enfileirado. Antes ela devolvia um recibo para algo que não chegaria a autorizar. Não há substituto: emita o CT-e normalmente em /cte/emissao.

Por que é PATCH e não MAJOR

Pela regra de versionamento do início desta página, passar a recusar o que era aceito é quebra de contrato. Aqui a recusa não é nossa, é da SEFAZ, e o EPEC nunca funcionou por esta API: ele exige um CT-e emitido em contingência (tpEmis=4), e a emissão daqui sempre sai normal (tpEmis=1). Nenhum EPEC foi enviado em produção.

3.16.0 — 2026-11-07 — Classificação fiscal de produtos e serviços

Endpoints novos. Quem já integra não precisa mudar nada.

Novo

  • POST /classificacao-fiscal: recebe o nome de um produto ou serviço (e, se você tiver, a descrição, o NCM, o item da LC 116 ou a NBS, e o uso: documento, operação, finalidade, destinatário, destino) e devolve na hora (status: "005") o pacote com a sugestão de identidade (NCM, CEST, origem), ICMS ou ISS, PIS/COFINS, IPI, IBS/CBS, Imposto Seletivo e Simples Nacional. Cada valor vem com fundamento legal, fonte e confiança. O regime tributário e a UF saem do cadastro da empresa da chave.
  • POST /classificacao-fiscal/lote: de 1 a 10 produtos por chamada ({"produtos": [...]}), processados em paralelo. Cada item tem status próprio: um item recusado não derruba os outros.
  • Perguntas pendentes: o que só a empresa sabe (industrial para o IPI, substituição tributária, alíquota de ISS do município…) volta em perguntas_pendentes; reenvie o produto com respostas: { "id": valor }. O motor nunca presume esses fatos.
  • Validação: a combinação sugerida é conferida contra regras oficiais de rejeição da SEFAZ e da NFS-e nacional (validacao.achados).

Só consulta: não grava produto nem configuração fiscal. É uma sugestão automática, que deve ser conferida por contador com registro no CRC antes de emitir. Veja o guia Classificação fiscal.

3.15.1 — 2026-11-05 — Carta de correção de NF-e com até 1000 caracteres

Correção compatível. O campo motivo de POST /nfe/correcao aceita de 15 a 1000 caracteres, o limite da SEFAZ. Antes a API recusava textos acima de 255.

3.14.0 — 2026-11-03 — RENAVE com consulta e contrato completo

Funcionalidade nova e correção. Ninguém usava o RENAVE pela API: os pedidos que passam a ser recusados na hora são os que já eram sempre recusados depois, na fila.

Novo

  • GET /renave/{recibo}: resultado de qualquer operação RENAVE. 004 registrado (com id-renave e id-estoque), 010 cancelado, 900 recusado pelo SERPRO (com o motivo), 999 erro técnico ou indeterminado. Antes o recibo não levava a lugar nenhum.
  • Cancelamento pelo recibo: cancelamento-entrada e cancelamento-saida aceitam o recibo do registro, além do id-renave, que agora a consulta devolve.
  • Reenvio depois de recusa: a mesma chaveNFe e operação podem ser reenviadas depois de 900 ou 999. O FazNota reaproveita o mesmo registro e conta mais uma tentativa. Antes o reenvio devolvia para sempre o recibo da tentativa recusada.

Corrigido

  • A recusa do SERPRO deixava de aparecer. O registro recusado ficava como processado com sucesso na fila, e o motivo se perdia. Agora a consulta traz a recusa e a mensagem do SERPRO.
  • Contrato publicado incompleto. O OpenAPI só listava chaveNFe. Agora traz todos os campos de cada operação. Os obrigatórios, o certificado A1 e o e-mail principal da empresa são conferidos na hora (400). Veja o guia RENAVE — estoque de veículos.

3.13.0 — 2026-10-21 — CIOT pela API

Endpoints novos. Quem já integra não precisa mudar nada.

Novo

  • CIOT (Código Identificador da Operação de Transporte, ANTT): POST /ciot/emissao, POST /ciot/cancelamento, POST /ciot/retificacao e POST /ciot/encerramento, com o resultado em GET /ciot/{recibo} (código do CIOT, verificador e protocolo). Emissão direta por ETC (empresa de transporte) com frota própria, para carga lotação ou fracionada. CNPJ e RNTRC do contratado, certificado A1 e ambiente vêm do cadastro da empresa. Os campos da emissão seguem o leiaute PEF da ANTT. Veja o guia Emitir CIOT.

3.12.1 — 2026-10-21 — Consulta por recibo só aceita o recibo da própria operação

Correção. Quem consulta cada recibo na rota da sua operação não percebe diferença.

Corrigido

  • As rotas de consulta passam a conferir de que operação é o recibo. GET /nfe/nota/{recibo} e /completa aceitam recibo de emissão ou alteração de NFe; GET /nfe/correcao/{recibo}, só de carta de correção; GET /nfe/cancelamento/{recibo}, só de cancelamento; e o mesmo vale para GET /nfce/cupom/{recibo}, /completa e GET /nfce/cancelamento/{recibo}. Um recibo de outra operação consultado na rota errada responde status: "500" (recibo não existe), a mesma resposta de um recibo inválido.
  • O erro interno de uma nota ou cupom (status: "999" em GET /nfe, GET /nfce, GET /nfe/nota/{recibo} e GET /nfce/cupom/{recibo}) passa a vir só da última emissão ou alteração daquele documento. Se uma alteração (PUT) falhar depois de uma emissão autorizada, a consulta da nota mostra o erro dessa alteração.
  • As listagens deixam de repetir documentos. Em GET /nfe, GET /nfce, GET /nfse e GET /nffornecedor, um documento com mais de um registro na fila (por exemplo, emissão e alteração, ou vários reconhecimentos) podia aparecer mais de uma vez e ocupar posições da página.

3.12.0 — 2026-10-21 — Inutilização de numeração pela API

Endpoint novo. Quem já integra não precisa mudar nada.

Novo

  • POST /nfe/inutilizacao e POST /nfce/inutilizacao: inutilizam na SEFAZ uma faixa de numeração de NFe (modelo 55) ou NFCe (modelo 65) que não foi usada. Corpo: serie, numero-inicial, numero-final, justificativa (15 a 255 caracteres) e ano opcional. São assíncronas, como o restante da v3: retornam recibo, e o resultado sai em GET /nfe/inutilizacao/{recibo} / GET /nfce/inutilizacao/{recibo}. 004 indica homologada (sefaz.codigo 102, com protocolo) e 900 indica recusada pela SEFAZ.
  • O pedido é recusado na hora (400) quando a faixa tem nota ou cupom autorizado ou em processamento, se sobrepõe a uma inutilização já homologada ou já na fila, a empresa usa certificado A3 ou o emitente não tem CNPJ. Repetir o mesmo pedido enquanto ele está na fila devolve o mesmo recibo. Veja o guia Inutilizar numeração.

3.11.0 — 2026-10-21 — NFS-e de condomínio edilício

Campo opcional novo. Quem já integra não precisa mudar nada.

Novo

  • condominio no POST /nfse/emissao — a NFS-e das taxas condominiais (serviço 99.05.01, NT 009 v1.01, obrigatória a partir de 01/12/2026): vencimento, cobrancas (ordinária, fundo de reserva, outras, com detalhamento opcional) e descontos (por exemplo, por pontualidade). Vale para empresa marcada como condomínio edilício no FazNota, com um item do serviço 99.05.01 cujo valor é a soma das cobranças. O município do imóvel e o enquadramento do condomínio no IBS/CBS vêm do cadastro da empresa.

3.10.0 — 2026-10-07 — NFC-e com PIX e forma de pagamento correta na nota

Valor novo aceito em campo existente. Quem já integra não precisa mudar nada.

Corrigido

  • A forma de pagamento enviada em tp_pagamento passa a sair na NFC-e. Desde 06/2024, toda NFC-e emitida pela API saía com tPag 01 (Dinheiro), qualquer que fosse o valor enviado. A correção vale a partir de 07/10/2026; as notas já autorizadas não mudam.
  • Código numérico vai direto como tPag. Antes, "17" (PIX), "18", "15" e outros códigos viravam Dinheiro sem aviso. Agora o código sai na nota, e um código que não existe na tabela da SEFAZ é recusado com Campo nfce@tp_pagamento inválido: 'NN' não é um código de forma de pagamento (tPag) da SEFAZ.

Novo

  • tp_pagamento: "pix" — PIX dinâmico (tPag 17), QR Code gerado para cada venda.
  • tp_pagamento: "pix_estatico" — PIX estático (tPag 20), chave PIX ou QR Code fixo.

A documentação dizia para usar outros no PIX. Isso continua sendo aceito, mas sai como Outros (tPag 99) na nota. Para sair como PIX, troque para pix ou pix_estatico. Veja Tipos de pagamento.

3.9.1 — 2026-10-01 — NFC-e “autorizada com alerta” (cStat 120)

Correção compatível. Nenhum contrato muda: mesmos campos, mesmas respostas, mesmos códigos de status.

Contexto

A partir de 05/10/2026 a SEFAZ (NT 2026.002, “Autorização de Uso com Alerta”) passa a responder 120 — “Autorizado o uso da NF-e, com alerta”, de início só para a NFC-e. A nota está autorizada e armazenada na SEFAZ; o alerta (até 5 pares código/texto no protocolo — ex. 172, CNPJ do destinatário inabilitado) é informativo e não pede correção nem reenvio.

Corrigido

  • NFC-e e NF-e autorizadas com 120 ou 150 passam a sair status: "004", com o bloco data.sefaz completo (chave, protocolo, url-danfe, url-xml) e data.sefaz.codigo com o código real (120/150). Antes a API só reconhecia o 100 como autorização: a nota com 120 (a partir de 05/10) ou 150 (fora de prazo, raro) teria saído 900, como se tivesse sido rejeitada.

O que fazer

  • Quem decide pelo status (004): nada.
  • Quem compara data.sefaz.codigo == "100": aceite também 120 e 150 — ou passe a usar o status. Veja Autorizada com alerta.

3.9.0 — 2026-09-25 — NFS-e para tomador no exterior com nome em chinês, coreano ou japonês

Mudança compatível: só passa a aceitar o que antes era recusado. Nada que era aceito passou a ser recusado; a nota nacional não muda em nada.

Novo na emissão de NFS-e

  • Nome e endereço do tomador no exterior em qualquer alfabeto. A razão social pode vir como está no documento do tomador — 深圳市示例电子商务有限公司, 테헤란 상사 —, sem romanizar. O Padrão Nacional aceita, e a nota sai com o nome como você enviou.
  • Endereço no exterior pode vir incompleto. Só pais e documento-estrangeiro (NIF) são obrigatórios. O campo que faltar sai como - na nota, como o Padrão Nacional aceita.

O que muda no que você vê

  • Logradouro, número e bairro em outro alfabeto saem - na nota: nesses três campos o Padrão Nacional só aceita caracteres latinos. Cidade e província aceitam qualquer alfabeto.
  • O cadastro do cliente guarda um nome latino — o que ele já tinha, ou NIF <documento>. É o que GET /clientes/{NIF} devolve. A nota é que leva o nome em ideogramas.
  • Só o emissor nacional (Padrão Nacional). Prefeituras com leiaute próprio continuam aceitando só caracteres latinos e recusam antes de transmitir, dizendo a causa.

Continua como antes

  • Emoji, ideograma fora do plano básico e caractere de controle são recusados, com o campo e o caractere na mensagem (ex. U+1F600), e nada é transmitido.
  • observacao, informacoes-complementares, e-mail, código postal e todo o /clientes continuam só em caracteres latinos (ISO-8859-1), e o /clientes continua exigindo o endereço completo.

No PDF da nota (DANFSe)

O nome em ideogramas aparece desenhado, com a fonte embutida no PDF. De quebra, tomador com & no nome deixou de sair como &amp;. A fonte cobre chinês e japonês; nome em coreano (Hangul) ainda não é desenhado no PDF — a nota fiscal (o XML autorizado, que é o documento com validade) traz o nome exatamente como você enviou em qualquer caso.

3.8.1 — 2026-09-24 — Município com apóstrofo no nome do endereço

Correção compatível. Nenhum contrato muda: mesmos campos, mesmas respostas, mesmos códigos. Cidade que era recusada passa a ser aceita — nada que era aceito passou a ser recusado.

Corrigido

  • Cidade com apóstrofo no nome era recusada com Cidade <nome>/<UF> não localizada. São 24 municípios — Guarani d'Oeste, Dias d'Ávila, Mãe d'Água, Herval d'Oeste, São João d'Aliança, Olho d'Água das Flores… Agora o nome resolve nas duas grafias, com ou sem o apóstrofo, e com ou sem acento: Mãe d'Água, Mae dAgua e MÃE DÁGUA chegam todos no mesmo município. Vale em POST/PUT de /clientes e de /transportadoras, e no cliente enviado junto da emissão. Você não precisa mudar nada — se já manda sem apóstrofo (a grafia que funcionava até aqui), continua funcionando; se manda como o IBGE escreve, passa a funcionar também.
  • Município com nome repetido no cadastro (Mogi Mirim, Mogi Guaçu, Óbidos) podia resolver para registros diferentes em chamadas idênticas. Agora o desempate é fixo. O código IBGE é o mesmo nos dois registros, então o documento fiscal não muda — só para de variar.

Por quê

O nome do município ia montado dentro da consulta SQL. O apóstrofo fechava o texto da consulta antes da hora, e o que chegava ao banco era inválido. Corrigido com parâmetro (?), que é imune a isso. A mesma correção foi aplicada na API v2, que compartilha esse caminho.

3.8.0 — 2026-09-14 — NFS-e para tomador no exterior

Mudança aditiva: campos opcionais novos. Quem não os envia não percebe diferença — o JSON gravado para processamento de uma nota nacional é byte a byte o mesmo de antes.

Adicionado

  • Endereço no exterior em cliente.endereco (emissão de NFS-e e /clientes): pais (ISO alfa-2 do Anexo A), cidade, provincia, codigo-postal, rua, numero, bairro. pais ausente ou BR = endereço no Brasil, como sempre. O endereço no exterior não tem complemento, e na consulta do cliente a província volta em provincia.
  • NIF obrigatório para o tomador no exterior (documento-estrangeiro): não há emissão sem NIF.
  • tributacao-issqn-nacional ("1".."4"), pais-resultado e o grupo comercio-exterior na emissão de NFS-e, validados pelas tabelas do leiaute nacional (XSD 1.01-rtc) e pelas regras E0352/E0354/E0356 e E0590/E0591. Nenhum tem valor padrão.
  • Cliente por NIF: "cliente": "<NIF>" na emissão e GET/PUT/DELETE /clientes/{NIF}. Documento que não é CPF/CNPJ é procurado como NIF; não encontrado, a resposta é a mesma de antes.
  • documento-estrangeiro (existe desde a 3.4.0) passa a constar no schema Cliente.

Recusas novas — só para quem usa os campos novos

Toda recusa diz a causa, o que fazer e que nada foi transmitido:

  • endereço no exterior incompleto (lista todos os campos que faltam), cep/estado junto com pais estrangeiro, complemento junto com pais estrangeiro, cpf/cnpj em tomador no exterior, tomador no exterior sem NIF e o campo motivo-sem-documento-estrangeiro (qualquer valor: o NIF é obrigatório);
  • texto do tomador no exterior (e observacao/informacoes-complementares dessa nota) fora de ISO-8859-1 — nome em chinês ou coreano precisa vir romanizado; nada é apagado calado;
  • país fora do Anexo A, BR ou ZZ como país do exterior, país ainda sem código ISO alfa-2 ou cidade EXTERIOR no cadastro, ou ambiente cujo cadastro de países ainda não tem o código ISO alfa-2 (atualização do banco pendente).

Atenção — endereco.pais na NF-e e na NFC-e

Antes, um endereco.pais era ignorado em qualquer documento, e um cliente “no exterior” era gravado como se o endereço fosse brasileiro. Agora, na NF-e, na NFC-e e na transportadora, pais diferente de BR é recusado com mensagem, porque esses documentos ainda não tratam destinatário no exterior pela API. pais ausente ou "BR" continua aceito.

Documentação

  • indicador-operacao: os exemplos 30101/20201 estavam com 5 dígitos. O leiaute exige 6 (030101, 020201); com 5 dígitos o grupo IBS/CBS sai da DPS. A API não mudou a validação desse campo.

2026-09-14 — Documentação: CNPJ alfanumérico no cliente

Somente documentação. Nenhum comportamento da API muda e a versão continua 3.7.1 (meta.api_version).

Corrigido

  • A referência ainda dizia “apenas números” para o CNPJ do cliente, mas a API já aceita o CNPJ alfanumérico da Receita Federal desde a 3.2.0 (ver a nota da 3.4.0). Atualizados o campo cnpj do schema Cliente e o parâmetro {doc} de GET/PUT/DELETE /clientes/{doc}.
  • O formato: 14 posições, as 12 primeiras letras A–Z ou dígitos e as 2 últimas (dígitos verificadores) sempre dígitos — por exemplo 12ABC34501DE35. Quando há letra, os dígitos verificadores são conferidos.
  • O CNPJ só com números continua aceito exatamente como antes, e o CPF continua só com números. Quem não emite para clientes com CNPJ alfanumérico não precisa fazer nada.

Correção compatível. Nenhum campo muda de forma ou de lugar — apenas o endereço dentro de data.sefaz.url-danfe e data.sefaz.url-xml.

Mudado

  • url-danfe e url-xml agora apontam para https://app.mysebr.com.br/app/{danfe,xml}/<token>, em vez de https://myse.com.br/…. O documento é servido diretamente pelo app, sem o salto intermediário que existia antes. Um <token> assinado identifica o documento; o mesmo token serve o XML e o DANFE (o caminho decide qual).
  • Os links que você já recebeu continuam funcionando — os endereços antigos seguem no ar. A mudança vale apenas para as respostas novas.

Atenção para quem restringe saída por domínio

Se a sua integração busca esses arquivos por trás de uma allowlist de firewall fixada em myse.com.br, libere também app.mysebr.com.br — é de onde as URLs novas passam a servir. Quem apenas segue o link devolvido pela API não precisa fazer nada.

3.7.0 — 2026-08-31 — CT-e OS (modelo 67) na API

Mudança puramente aditiva: 6 endpoints novos sob /cte-os, nenhum contrato existente alterado. Quem emite CT-e de carga não é afetado em nada.

Adicionado

O CT-e OS — Conhecimento de Transporte Eletrônico para Outros Serviços (modelo 67) é o documento de quem transporta pessoas, valores ou excesso de bagagem — não carga. Qual dos três é o tp-serv do corpo: 6, 7 ou 8.

EndpointO que faz
POST /cte-os/emissaoEmite o CT-e OS
POST /cte-os/cancelamentoCancela (evento 110111)
POST /cte-os/carta-correcaoCarta de Correção (110110)
POST /cte-os/informacoes-gtvInformações da GTV (110170) — só existe no modelo 67
POST /cte-os/desacordoPrestação em desacordo (610110)
POST /cte-os/desacordo/cancelamentoCancela o desacordo (610111)

O modelo é escolhido pelo endereço, não por um campo. Tudo em /cte-os emite modelo 67; um tp-doc enviado no corpo é ignorado. Assim o modelo do documento não vira um valor que só falha lá no processamento, depois do recibo entregue.

Os eventos aqui são menos que os do CT-e. EPEC, comprovante de entrega, insucesso de entrega e registro multimodal não se aplicam ao modelo 67: os três primeiros pressupõem carga entregue e o EPEC é contingência exclusiva do 57. Eles não têm rota em /cte-os — pedi-los é 404 na hora, e não uma rejeição da SEFAZ meia hora depois.

O que cada tp-serv costuma exigir

Estas regras são do leiaute do documento, não da nossa chamada: a API aceita e enfileira, e a falta aparece no processamento, não na resposta. Confira antes de enviar.

tp-servO leiaute espera
6 — Transporte de pessoasFretamento (modal-rodo-os.fretamento); no fretamento eventual, a data/hora da viagem
7 — Transporte de valoresgtves[] com as GTV-e da prestação e seus componentes de valor
8 — Excesso de bagagemdocumentos-ref[] com a chave do BP-e que originou o excesso

Detalhes que costumam pegar quem integra

  • A numeração é separada. Série 1 de CT-e OS e série 1 de CT-e são sequências distintas para a SEFAZ. Omitindo n-ct, o número sai do contador próprio do modelo 67.
  • O numero-origem também é separado. Você pode reusar em /cte-os uma origem já usada em /cte: são espaços independentes, e cada rota só encontra duplicata do seu próprio modelo.
  • CST 60 não existe no leiaute do CT-e OS e é recusado na validação, com mensagem dizendo quais valem: 00, 20, 40, 41, 51 e 90.
  • taf e nr-reg-estadual no modal rodoviário — informe um dos dois. A ausência dos dois é recusada; se vierem ambos, o taf é o que vale.
  • O grupo servico é obrigatório. É ele que no modelo 67 faz o papel dos dados de carga do 57. O limite de tamanho da descricao é do leiaute e aparece no processamento.
  • Há um grupo de tributos federais (trib-fed: PIS, COFINS, IR, INSS, CSLL) que não existe no CT-e de carga.

Corrigido

  • A documentação de dois eventos do /cte estava errada desde a 3.6.0. A carta de correção exige correcoes (uma lista, não pode vir vazia) e não um campo correcao de texto; as informações de GTV exigem gtv. Quem seguiu o contrato publicado levava rejeição. O OpenAPI agora reflete o que o serviço faz.
  • O código 400 passou a constar na tabela de status. Ele já era devolvido — corpo ausente, JSON inválido ou operação inexistente para o documento — mas não estava documentado.

3.6.1 — 2026-08-27 — Correções na emissão de NFS-e

Correções compatíveis. Nenhum contrato muda.

Corrigido

  • numero-origem ficava queimado para sempre quando a NFS-e era recusada e depois cancelada. Reimportar a mesma planilha devolvia 050 DUPLICIDADE com o recibo da nota morta e não emitia nada — sem saída operável pelo cliente. Agora a origem é liberada quando dá para provar pelo dado que a prefeitura nunca emitiu a nota (cancelada e sem nenhum campo que só o município preenche, como o código de verificação). Escopo restrito à NFS-e de propósito: para NF-e e NFC-e não há como provar que o documento não existe no fisco, então a origem continua bloqueada.
  • A emissão de NFS-e apagava dados do cadastro do produto — NBS, CNAE e o código de serviço municipal eram limpos ao emitir.

3.6.0 — 2026-08-25 — CT-e, MDF-e, BP-e e RENAVE na API

Mudança puramente aditiva: 28 endpoints novos, nenhum campo existente alterado. Quem emite NF-e, NFC-e ou NFS-e não é afetado em nada.

A API passa a cobrir todos os documentos fiscais que o sistema emite:

DocumentoOperações
CT-e /cte/…emissão, cancelamento, carta de correção, comprovante e insucesso de entrega (e seus cancelamentos), prestação em desacordo (e o cancelamento), EPEC, registro multimodal, informações de GTV
MDF-e /mdfe/…emissão, cancelamento, encerramento, inclusão de condutor, inclusão de documento fiscal
BP-e /bpe/…emissão, cancelamento, substituição, não-embarque, alteração de poltrona, excesso de bagagem
RENAVE /renave/…entrada e saída de veículo por nota fiscal, entrada de veículo próprio, cancelamento de entrada e de saída

Todos são assíncronos, como a emissão que você já conhece

A requisição é validada e enfileirada, e a resposta traz um recibo. O documento é processado depois. Recibo não é autorização — consulte o recibo para saber o desfecho.

Isso importa especialmente no MDF-e com certificado A3: o manifesto é montado e fica aguardando assinatura no aplicativo assinador. Até você assinar, ele não foi transmitido à SEFAZ.

Os eventos são endereços, não um campo no corpo

Cada evento tem a sua rota — /cte/desacordo, /bpe/nao-embarque. Poderia ser um endpoint só com o tipo do evento no corpo, e seria pior para você: um valor inválido só apareceria no processamento, depois de já ter recebido um recibo. Como rota, evento inexistente é 404 na hora.

Idempotência só na emissão

O numero-origem (ou a chaveNFe, no RENAVE) evita emitir duas vezes o mesmo documento: se você repetir o valor, recebe o recibo original em vez de um documento novo.

Nos eventos não há idempotência por origem, de propósito: eles incidem sobre um documento que já existe, e repetir um evento é uma decisão sua — devolver “duplicata” esconderia uma segunda tentativa legítima depois de a primeira ter falhado.

O que ainda não está aqui

Cinco operações do RENAVE — transferência entre estabelecimentos, transferência entre filiais, autorização de transferência, cancelamento dessa autorização e assinatura de ATPV. Elas existem no serviço, mas ainda não têm registro local no sistema, e preferimos não expor uma operação que muda estado no órgão sem deixar trilha do que foi feito. Entram quando esse registro existir.

E as consultas do RENAVE (veículo, aptidão, CRLV-e, termos, PDF do ATPV) continuam fora da fila de propósito: consulta responde na hora, sem recibo.

3.5.0 — 2026-08-21 — Indicador de operação da NFS-e (reforma tributária)

Mudança puramente aditiva: um campo opcional novo na emissão de NFS-e. Quem não o envia continua com exatamente o mesmo comportamento — o campo é omitido e nada muda.

Adicionado

  • Campo indicador-operacao na emissão de NFS-e (POST /nfse/emissao), opcional. É o indicador de operação de fornecimento do Ambiente de Dados Nacional (Anexo VII do layout da reforma tributária).

    Algumas prefeituras recusam a NFS-e sem ele: em Barueri a recusa vem como crítica 817 (“Código Indicador da operação de fornecimento não informado e/ou fora dos padrões”), e Osasco tem exigência equivalente. Se você emite para esses municípios, passe a informar o campo.

    O código válido depende do item da LC 116 do serviço, conforme o Anexo VIII (Correlação Item LC116 × NBS × IndOp). Exemplo: "indicador-operacao": "100301" — demais serviços, em operações onerosas.

3.4.0 — 2026-08-20 — Versionamento SemVer explícito e documento estrangeiro

Adicionado

  • meta.api_version e header X-API-Version em todas as respostas. Aditivo: parsers bem comportados ignoram campos desconhecidos e nenhum contrato existente muda.
  • Campo documento-estrangeiro no cliente (opcional). Permite cadastrar tomador do exterior, que não tem CPF/CNPJ — o documento é o registro fiscal do país de origem (NIF/EIN/VAT). Quando informado, cpf/cnpj deixam de ser exigidos. Reenviar o mesmo documento atualiza o cadastro, em vez de duplicar.

Corrigido

  • Cancelamento de NFe e NFSe não era efetivado. A requisição respondia 200 com recibo, mas o registro era descartado — a nota seguia autorizada na SEFAZ. Se você cancelou por API e a nota não foi cancelada, refaça a solicitação.
  • Instabilidade momentânea do banco deixou de “grudar”. Uma falha de infraestrutura podia fazer sua integração receber 401 ou 403 por até 60 segundos depois de o serviço já ter se recuperado. Agora a falha não é mais memorizada.
  • Cliente do exterior com cnpj preenchido como 00000000000000 passa a ser recusado com mensagem clara, em vez de ser associado a um cadastro existente.

Nota sobre a validação de CNPJ (introduzida na 3.2.0)

A adequação ao CNPJ alfanumérico (NT 2026.004) passou a rejeitar valores com texto solto junto do documento — por exemplo "CNPJ 11.222.333/0001-81" ou "cnpj: 11222333000181", que antes eram limpos silenciosamente. Envie apenas o documento, com ou sem máscara. Pelo critério do SemVer isso é uma quebra e deveria ter exigido MAJOR; registramos aqui por transparência. Nenhuma integração ativa enviava esse formato.

3.3.0 — 2026-08-06 — Resumo diário e download de XMLs por período

Mudança puramente aditiva: dois recursos novos, nenhum endpoint existente foi alterado.

Adicionado

  • GET /resumo?data-inicial=&data-final= — totais por dia de NFe e NFCe emitidas, canceladas e denegadas, mais as falhas de emissão. Reflete tudo que a empresa emitiu, inclusive pela tela do ERP. Período máximo de 92 dias. Atenção: canceladas é subconjunto de emitidas — não some os dois campos. Veja Resumo diário de emissões.
  • POST /xml/solicitacao e GET /xml/solicitacao/{protocolo} — download em lote dos XMLs de um período, em fluxo assíncrono (solicita → consulta protocolo → baixa do link temporário, válido por 7 dias). Período máximo de 92 dias, até 3 solicitações simultâneas por empresa. O arquivo também é enviado por e-mail. Veja Baixar XMLs por período.
  • Status novos no envelope: 006 (processado sem resultado), 007 (falha no processamento assíncrono) e 400 (parâmetro inválido — erro do chamador, repetir a requisição não resolve).

3.2.0 — 2026-08-04 — NFSe: informações complementares e ISS retido

Mudança puramente aditiva. Requisições que não enviem os novos campos continuam se comportando exatamente como antes.

Adicionado

  • Campo informacoes-complementares (NFSe, opcional, até 2.000 caracteres) em POST /nfse/emissao e PUT /nfse/{id}. Texto livre que sai na seção “Informações Complementares” do DANFSe/XML. É uma seção diferente da discriminação do serviço (observacao) — os dois convivem na mesma nota. Omitido: nota emitida sem informações complementares (comportamento anterior).
  • Campo iss-retido (NFSe, opcional) em POST /nfse/emissao e PUT /nfse/{id}. "1" = ISS retido pelo tomador (substituição tributária), "2" = não retido. Padrão "2" quando omitido (comportamento anterior). É informação da nota, não do item; mesmo com ISS retido a alíquota e o valor do ISS continuam no XML. Valor diferente de "1"/"2" é rejeitado com mensagem de validação.

Veja Emitir uma NFSe.

2026-05-13 — Modernização de DX (v3 mantida)

Esta release mantém compatibilidade total com o contrato existente. Nada quebra. Novas capacidades são puramente aditivas.

Adicionado

  • Header X-Request-Id em todas as respostas. Idêntico ao novo campo meta.request_id no body. Cite ao acionar o suporte.
  • Headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset em respostas autenticadas. Permitem auto-regulação do consumo.
  • Bloco meta em todas as respostas com request_id e timestamp (ISO-8601 UTC).
  • Endpoint GET /health sem autenticação. Retorna 200 OK quando aplicação + banco saudáveis; 503 quando degradado.
  • Paginação por query string (?page=&page_size=) em todas as listagens, como alternativa ao path-based legado. Veja Paginação.
  • Campo numero-origem (com hífen) aceito em emissões, equivalente ao legado numero_origem (com underscore). Os dois formatos funcionam.
  • Header Access-Control-Expose-Headers expõe X-Request-Id e os X-RateLimit-* para clientes browser conseguirem lê-los.

Melhorado

  • Mensagens de erro internas mais seguras: stack traces e detalhes de infraestrutura não vazam mais ao cliente. Mensagens de validação (em português, começando com "Campo <recurso>@<campo>...") permanecem idênticas.
  • Logs estruturados (interno) via SLF4J + Logback. Cada log contém requestId= para correlação. Sem impacto no cliente.
  • Health check de DB real em GET /health (não apenas ping de aplicação).
  • OPTIONS preflight respondido imediatamente sem exigir autenticação, melhorando integrações browser.

Corrigido (interno)

  • Bug histórico que impedia gravação no log de uso da API (tb_uso_api). Logs passam a ser gravados corretamente.
  • Vulnerabilidade SQL injection no provider de log (uso de PreparedStatement).
  • Duplicação de headers CORS nos resources (centralizado no filter).

Documentação

  • Nova documentação completa com a estrutura de 12 seções (esta versão).
  • Spec OpenAPI 3.0.3 publicada em openapi/nota-fiscal.yaml.
  • 7 recipes práticos cobrindo os principais fluxos.
  • Coleção Postman/Insomnia oficial.

Versões anteriores

A documentação consolidada começou nesta versão. Mudanças anteriores estão registradas no Painel FazNota e em comunicados por e-mail aos integradores.

Política de breaking changes

A v3 está congelada em contrato — nenhuma mudança quebrante entra nesta versão. Uma quebra exige MAJOR novo (/nfemyse-v4/), e sempre com:

  1. Comunicação prévia com prazo adequado (mínimo 90 dias).
  2. Janela de retrocompatibilidade com versão antiga funcionando em paralelo.
  3. Documentação clara do que mudou e como migrar.

Veja Políticas operacionais para o regramento completo.

Como acompanhar

  • 📧 E-mail: os contatos cadastrados no Painel FazNota recebem comunicados.
  • 🌐 Painel: avisos importantes aparecem ao logar.
  • 📄 Esta página: consulte periodicamente.