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:
| Parte | Quando muda | Efeito para você |
|---|---|---|
PATCH (3.4.0 → 3.4.1) | Correção compatível | Nenhum. Nada a fazer |
MINOR (3.4.0 → 3.5.0) | Endpoint ou campo opcional novo | Nenhum. Quem não usa o recurso novo não é afetado |
MAJOR (v3 → v4) | Quebra de contrato | Nã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-moveisnoPOST /nfse/emissao— a NFS-e do aluguel de bem móvel (serviço99.04.01, grupobensMoveisda NT 009): até 1000 bens comncm,descricaoequantidade, mais oindicador-operacaoobrigatório (010101,010102,010103ou010106, 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-operacaoemPOST /nfe/emissao(opcional, até 60 caracteres): o texto donatOpda 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. Emtransporte, atransportadorapassa a ser opcional nessas duas modalidades (antes: “Campo nfe@transporte@transportadora deve ser preenchido.”). Nas modalidades2,3e4continua 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
vTotTribde cada item e o total emICMSTot/vTotTrib, calculados pela tabela do IBPT. Nada muda no payload da API. Ver Emitir NF-e.
Corrigido
pSTdo CSOSN 500. O XML traziavICMSSTRetpreenchido compSTzerado; agorapSTé opercentual-icms-st-retda 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 em999quando 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
aliquotasdo ICMS por estado passa a ser opcional emPOST /produtosePUT /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
cestemPOST /produtosePUT /produtos/{ref}passa a ser gravado. Antes o código era aceito e descartado: o produto ficava sem CEST e, noPUT, 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 oPUTsem 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-anvisadeixa de recusar o cadastro. O campo era lido com outro nome e o produto inteiro voltava999com “Falha ao converter JSON.”.
Atenção
- CEST fora da tabela CEST (ou que não tenha 7 dígitos) agora é recusado com
999e o motivo emdata.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}eGET /bpe/{recibo}— o desfecho de emissões e eventos:004autorizado (chave, protocolo) ou evento registrado,010cancelado,900recusado (c-stat,x-motivo),999técnico,002/003na fila,500recibo de outra empresa ou de outro modelo.- Contrato completo da emissão e de cada evento nas quatro famílias, conferido na entrada (
400comdata.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-mdfede 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 mesmonumero-origemcorrige e reenvia o mesmo documento; depois de999, 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-origempassa 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.pfxem base64 no campoarquivo(até 50 KB) e asenha. 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-validadeedias-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[].ajustesnoPOST /nfse/emissao— os ajustes da base de cálculo do aluguel (gAjusteBCLocImoveis), até 1000 por unidade:tipo01tributos (IPTU),02emolumentos,03condomínio,04redutor social (só imóvel residencial) e99outras (comdescricao, até 150 caracteres, só nesse tipo), evalor(o total da parcela, maior que zero). A soma dos ajustes não pode passar dovalor-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 de020201, que deixou de valer para os serviços 99.03. Quem omiteindicador-operacaonão precisa fazer nada; quem envia020201passa 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
locacaonoPOST /nfse/emissao— a NFS-e do aluguel de imóvel (serviços99.03.01a99.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 comcondominio.
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=eGET /rotinas/servicospara preencher os campos,POST /rotinas/validar(pendências sem gravar),POST /rotinas(ativarpadrãotrue;falsegrava rascunho),GET/PUT/DELETE /rotinas/{id}(oPUTé parcial nos parâmetros; o modelo não muda). - Operação:
POST /rotinas/{id}/pausar,/retomare/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 compendenciasediagnostico(por que emitiu ou não). - Valor extra:
GET /rotinas/{id}/extrasePUT/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-origemROT-<id>-<AAAA-MM>; competência já emitida não se repete, nem pelo agendador nem peloemitir-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") opacotecom 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 comrespostas: { "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.004registrado (comid-renaveeid-estoque),010cancelado,900recusado pelo SERPRO (com o motivo),999erro técnico ou indeterminado. Antes o recibo não levava a lugar nenhum.- Cancelamento pelo recibo:
cancelamento-entradaecancelamento-saidaaceitam orecibodo registro, além doid-renave, que agora a consulta devolve. - Reenvio depois de recusa: a mesma
chaveNFee operação podem ser reenviadas depois de900ou999. 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/retificacaoePOST /ciot/encerramento, com o resultado emGET /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/completaaceitam 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 paraGET /nfce/cupom/{recibo},/completaeGET /nfce/cancelamento/{recibo}. Um recibo de outra operação consultado na rota errada respondestatus: "500"(recibo não existe), a mesma resposta de um recibo inválido. - O erro interno de uma nota ou cupom (
status: "999"emGET /nfe,GET /nfce,GET /nfe/nota/{recibo}eGET /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 /nfseeGET /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/inutilizacaoePOST /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) eanoopcional. São assíncronas, como o restante da v3: retornamrecibo, e o resultado sai emGET /nfe/inutilizacao/{recibo}/GET /nfce/inutilizacao/{recibo}.004indica homologada (sefaz.codigo102, com protocolo) e900indica 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
condominionoPOST /nfse/emissao— a NFS-e das taxas condominiais (serviço99.05.01, NT 009 v1.01, obrigatória a partir de 01/12/2026):vencimento,cobrancas(ordinária, fundo de reserva, outras, comdetalhamentoopcional) edescontos(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_pagamentopassa a sair na NFC-e. Desde 06/2024, toda NFC-e emitida pela API saía com tPag01(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 comCampo 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 (tPag17), QR Code gerado para cada venda.tp_pagamento: "pix_estatico"— PIX estático (tPag20), 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
120ou150passam a sairstatus: "004", com o blocodata.sefazcompleto (chave,protocolo,url-danfe,url-xml) edata.sefaz.codigocom o código real (120/150). Antes a API só reconhecia o100como autorização: a nota com120(a partir de 05/10) ou150(fora de prazo, raro) teria saído900, como se tivesse sido rejeitada.
O que fazer
- Quem decide pelo
status(004): nada. - Quem compara
data.sefaz.codigo == "100": aceite também120e150— ou passe a usar ostatus. 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ó
paisedocumento-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 queGET /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/clientescontinuam só em caracteres latinos (ISO-8859-1), e o/clientescontinua 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 &. 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 dAguaeMÃE DÁGUAchegam todos no mesmo município. Vale emPOST/PUTde/clientese 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.paisausente ouBR= endereço no Brasil, como sempre. O endereço no exterior não temcomplemento, e na consulta do cliente a província volta emprovincia. - NIF obrigatório para o tomador no exterior (
documento-estrangeiro): não há emissão sem NIF. tributacao-issqn-nacional("1".."4"),pais-resultadoe o grupocomercio-exteriorna 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 eGET/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 schemaCliente.
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/estadojunto compaisestrangeiro,complementojunto compaisestrangeiro,cpf/cnpjem tomador no exterior, tomador no exterior sem NIF e o campomotivo-sem-documento-estrangeiro(qualquer valor: o NIF é obrigatório); - texto do tomador no exterior (e
observacao/informacoes-complementaresdessa nota) fora de ISO-8859-1 — nome em chinês ou coreano precisa vir romanizado; nada é apagado calado; - país fora do Anexo A,
BRouZZcomo 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 exemplos30101/20201estavam 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
cnpjdo schemaClientee o parâmetro{doc}deGET/PUT/DELETE /clientes/{doc}. - O formato: 14 posições, as 12 primeiras letras
A–Zou dígitos e as 2 últimas (dígitos verificadores) sempre dígitos — por exemplo12ABC34501DE35. 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.
3.7.1 — 2026-09-03 — Links de DANFE/XML servidos direto pelo app
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-danfeeurl-xmlagora apontam parahttps://app.mysebr.com.br/app/{danfe,xml}/<token>, em vez dehttps://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.
| Endpoint | O que faz |
|---|---|
POST /cte-os/emissao | Emite o CT-e OS |
POST /cte-os/cancelamento | Cancela (evento 110111) |
POST /cte-os/carta-correcao | Carta de Correção (110110) |
POST /cte-os/informacoes-gtv | Informações da GTV (110170) — só existe no modelo 67 |
POST /cte-os/desacordo | Prestação em desacordo (610110) |
POST /cte-os/desacordo/cancelamento | Cancela 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-serv | O leiaute espera |
|---|---|
6 — Transporte de pessoas | Fretamento (modal-rodo-os.fretamento); no fretamento eventual, a data/hora da viagem |
7 — Transporte de valores | gtves[] com as GTV-e da prestação e seus componentes de valor |
8 — Excesso de bagagem | documentos-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-origemtambém é separado. Você pode reusar em/cte-osuma origem já usada em/cte: são espaços independentes, e cada rota só encontra duplicata do seu próprio modelo. CST 60nã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.tafenr-reg-estadualno modal rodoviário — informe um dos dois. A ausência dos dois é recusada; se vierem ambos, otafé 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 dadescricaoé 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
/cteestava errada desde a 3.6.0. A carta de correção exigecorrecoes(uma lista, não pode vir vazia) e não um campocorrecaode texto; as informações de GTV exigemgtv. Quem seguiu o contrato publicado levava rejeição. O OpenAPI agora reflete o que o serviço faz. - O código
400passou 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-origemficava queimado para sempre quando a NFS-e era recusada e depois cancelada. Reimportar a mesma planilha devolvia050DUPLICIDADE 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,CNAEe 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:
| Documento | Operaçõ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-operacaona 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_versione headerX-API-Versionem todas as respostas. Aditivo: parsers bem comportados ignoram campos desconhecidos e nenhum contrato existente muda.- Campo
documento-estrangeirono 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/cnpjdeixam 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
200com 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
401ou403por até 60 segundos depois de o serviço já ter se recuperado. Agora a falha não é mais memorizada. - Cliente do exterior com
cnpjpreenchido como00000000000000passa 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 deemitidas— não some os dois campos. Veja Resumo diário de emissões.POST /xml/solicitacaoeGET /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) e400(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) emPOST /nfse/emissaoePUT /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) emPOST /nfse/emissaoePUT /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-Idem todas as respostas. Idêntico ao novo campometa.request_idno body. Cite ao acionar o suporte. - Headers
X-RateLimit-Limit,X-RateLimit-Remaining,X-RateLimit-Resetem respostas autenticadas. Permitem auto-regulação do consumo. - Bloco
metaem todas as respostas comrequest_idetimestamp(ISO-8601 UTC). - Endpoint
GET /healthsem autenticação. Retorna200 OKquando aplicação + banco saudáveis;503quando 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 legadonumero_origem(com underscore). Os dois formatos funcionam. - Header
Access-Control-Expose-HeadersexpõeX-Request-Ide osX-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:
- Comunicação prévia com prazo adequado (mínimo 90 dias).
- Janela de retrocompatibilidade com versão antiga funcionando em paralelo.
- 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.