# Glossário de A a Z — letra J > 20 termos. Glossário compacto: https://conota.dev/glossario/llms-full.txt --- # Janela de manutenção da API > Janela de manutenção da API é o período programado, geralmente comunicado com antecedência, em que o provedor de uma API realiza atualizações, correções ou ajustes de infraestrutura. Durante esse intervalo, alguns serviços podem ficar lentos ou indisponíveis. Por isso, os sistemas integrados precisam se planejar para não interromper operações importantes, como a emissão de notas fiscais. **Também conhecido como:** Manutenção programada, Janela de manutenção programada, Parada programada da API, Manutenção agendada, Maintenance window **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** J ## O que acontece durante uma janela de manutenção da API? Durante a janela de manutenção, a equipe responsável pela API faz trabalhos que não podem ser feitos com o serviço em uso intenso. Entre eles estão atualizar servidores, aplicar correções de segurança, migrar bancos de dados e publicar novas versões. O impacto varia. Em algumas manutenções, nada muda para quem usa a API. Em outras, certos endpoints respondem mais devagar, retornam erros temporários ou ficam fora do ar por um tempo definido. Um bom aviso de manutenção informa o horário de início e fim, os serviços afetados e o comportamento esperado. ## Por que uma API fiscal precisa de janelas de manutenção? Uma API fiscal depende de muitas peças: certificados digitais, regras de validação, leiautes oficiais e conexões com SEFAZ e prefeituras. Essas peças mudam com frequência, por exemplo quando uma nota técnica altera o leiaute de um documento. Aplicar essas mudanças exige atualizar o sistema. Fazer isso em um horário planejado, normalmente de baixo movimento, reduz o risco de afetar vendas e faturamentos. A alternativa seria fazer alterações a qualquer momento, sem aviso, o que é muito mais arriscado para quem emite NF-e, NFC-e, NFS-e, CT-e ou MDF-e. ## Qual a diferença entre janela de manutenção e indisponibilidade inesperada? A janela de manutenção é planejada e anunciada. Quem integra a API sabe quando ela vai acontecer e pode se preparar. Já a indisponibilidade inesperada, chamada também de incidente ou queda, acontece sem aviso, por falha técnica, problema de rede ou sobrecarga. Nesse caso, o sistema integrado só descobre o problema quando as requisições começam a falhar. Por isso, mecanismos como retry, fila e healthcheck são úteis nas duas situações, mas a manutenção programada permite agir antes. ## A manutenção da SEFAZ ou da prefeitura é a mesma coisa? Não. A janela de manutenção da API é do provedor da API fiscal. Os órgãos autorizadores, como as SEFAZ estaduais e as prefeituras, também fazem suas próprias paradas programadas, que podem ocorrer em horários diferentes. Na prática, a emissão pode ser afetada por qualquer uma das duas. Se a API estiver funcionando, mas a SEFAZ estiver em manutenção, a nota não será autorizada naquele momento. Para NF-e e NFC-e, existem modalidades de contingência previstas na legislação, como SVC e EPEC, que podem ser usadas conforme o caso e as regras vigentes. ## Como preparar o sistema para uma janela de manutenção? O primeiro passo é acompanhar os comunicados do provedor e registrar os horários das manutenções. Depois, o sistema deve estar preparado para lidar com erros temporários: guardar as solicitações em uma fila, tentar novamente com intervalos crescentes (backoff exponencial) e usar idempotência para evitar notas duplicadas. Também ajuda programar tarefas em lote, como emissões agendadas ou sincronizações, para fora do horário da manutenção. Por fim, monitorar o status dos documentos, por webhook ou consulta periódica, garante que nenhuma nota fique esquecida quando o serviço voltar ao normal. ## Exemplos de Janela de manutenção da API - Um ERP recebe o aviso de que a API fiscal terá uma janela de manutenção de madrugada e reprograma para a manhã seguinte a emissão em lote das NFS-e de mensalidades. - Uma plataforma de e-commerce mantém os pedidos em uma fila de emissão durante a janela de manutenção e reenvia automaticamente as NF-e quando a API volta a responder. - Uma transportadora consulta o healthcheck da API antes de iniciar a emissão de CT-e e MDF-e de uma rota, evitando começar o processo no meio de uma manutenção anunciada. - Um agente de IA conectado via MCP recebe um erro temporário ao consultar notas durante a manutenção e informa ao usuário que a consulta deve ser repetida após o horário previsto. ## Perguntas frequentes ### Posso emitir notas durante uma janela de manutenção da API? Depende do aviso do provedor. Algumas manutenções não afetam a emissão; outras deixam serviços indisponíveis. O ideal é que o sistema guarde as solicitações em fila e reenvie após a manutenção, usando idempotência para evitar duplicidade. ### Quanto tempo dura uma janela de manutenção? Não há duração padrão. Cada provedor define o tempo conforme o tipo de trabalho. O importante é que o comunicado informe início, fim previsto e serviços afetados, permitindo que o sistema integrado se organize. ### Uma nota enviada durante a manutenção pode ser perdida? Se a requisição falhar e o sistema não tentar novamente, a nota pode não ser emitida. Por isso, é importante tratar erros temporários com retry, fila e acompanhamento do status de cada documento. ## Termos relacionados - [Healthcheck de API](https://conota.dev/glossario/healthcheck-de-api.md) - [Retry na integração fiscal](https://conota.dev/glossario/retry-na-integracao-fiscal.md) - [Fila de emissão fiscal](https://conota.dev/glossario/fila-de-emissao-fiscal.md) - [Fallback na integração fiscal](https://conota.dev/glossario/fallback-na-integracao-fiscal.md) - [SVC](https://conota.dev/glossario/svc.md) - [Observabilidade da API fiscal](https://conota.dev/glossario/observabilidade-da-api-fiscal.md) --- Fonte: [Janela de manutenção da API](https://conota.dev/glossario/janela-de-manutencao-da-api/) · Atualizado em 2026-10-22 --- # Java na integração fiscal > Java na integração fiscal é o uso da linguagem de programação Java para conectar sistemas empresariais, como ERPs e plataformas de venda, aos serviços de emissão de documentos fiscais eletrônicos. Com ela, o sistema monta os dados da nota, envia para uma API ou diretamente para a SEFAZ, recebe o resultado e armazena XML, PDF e status. **Também conhecido como:** Integração fiscal em Java, Emissão de nota fiscal com Java, Emissão fiscal em Java, Java tax integration **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** J ## Por que Java é tão usado em sistemas fiscais? Java é uma das linguagens mais comuns em sistemas corporativos, especialmente em ERPs, softwares de gestão e plataformas que processam grande volume de transações. Como a emissão de notas fiscais costuma ficar dentro desses sistemas, é natural que a integração fiscal também seja escrita em Java. A linguagem oferece recursos nativos para tarefas frequentes no mundo fiscal: leitura e geração de XML, comunicação segura por HTTPS, manipulação de certificados digitais e criptografia. Além disso, roda em servidores de diferentes sistemas operacionais e tem um ecossistema maduro de bibliotecas e ferramentas. ## Como funciona uma integração fiscal feita em Java? O sistema em Java reúne as informações da venda ou do serviço, como emitente, destinatário, itens, impostos e valores, e transforma esses dados no formato exigido. Em seguida, envia a requisição, aguarda a resposta e registra o resultado: documento autorizado, rejeitado ou ainda em processamento. Há dois caminhos principais. No primeiro, o próprio código Java gera o XML no leiaute oficial, assina com o certificado digital e se comunica com os web services SOAP da SEFAZ ou da prefeitura. No segundo, o código Java envia os dados em JSON para uma API fiscal, que cuida da montagem, assinatura, transmissão e acompanhamento do documento. ## Qual a diferença entre integrar direto com a SEFAZ e usar uma API fiscal em Java? Na integração direta, a equipe precisa lidar com esquemas XML, namespaces, assinatura digital, keystore de certificados, regras de cada estado, contingência e mudanças trazidas por notas técnicas. No caso da NFS-e, ainda há diferenças entre prefeituras e o Padrão Nacional. Isso exige manutenção contínua. Com uma API fiscal, o código Java faz chamadas HTTP comuns, geralmente em JSON, autenticadas por token ou chave de API. A complexidade dos leiautes e da comunicação com os órgãos fica com o provedor, e o sistema recebe de volta XML, PDF e status. Uma única integração pode atender NF-e, NFC-e, NFS-e, CT-e e MDF-e, conforme a disponibilidade de cada documento. ## O que é preciso para começar uma integração fiscal em Java? Na prática, é necessário um cliente HTTP (as versões mais recentes do Java já incluem um na biblioteca padrão), uma biblioteca para converter objetos em JSON ou XML, as credenciais de acesso à API e o certificado digital da empresa emissora, normalmente do tipo A1. Também é essencial começar pelo ambiente de homologação, onde as notas não têm validade fiscal. Ali o time testa cenários de sucesso, rejeição e cancelamento antes de passar para o ambiente de produção. ## Quais cuidados técnicos são importantes em Java? Configure timeouts adequados, porque a resposta de órgãos autorizadores pode demorar. Use retry com backoff exponencial para falhas temporárias e garanta idempotência, evitando que uma nova tentativa gere nota duplicada. Guarde certificados, senhas e chaves de API em um gerenciador de segredos, nunca dentro do código. Registre logs e identificadores de requisição para rastrear problemas, e trate datas com o fuso horário correto, já que a hora de emissão é validada pelos órgãos fiscais. ## Exemplos de Java na integração fiscal - Um ERP industrial escrito em Java envia, ao faturar um pedido, os dados da venda em JSON para uma API fiscal e recebe de volta a chave de acesso e o XML da NF-e autorizada. - Uma plataforma de serviços em Java emite NFS-e para clientes de vários municípios usando uma única API, sem implementar o padrão de cada prefeitura. - Uma transportadora integra seu sistema Java para gerar CT-e e MDF-e e consulta periodicamente o status de cada documento até a autorização. - Um software de gestão em Java recebe notificações por webhook com o resultado da emissão e valida a assinatura HMAC antes de atualizar o pedido. ## Perguntas frequentes ### Preciso de uma biblioteca específica para emitir nota fiscal em Java? Não necessariamente. Ao usar uma API fiscal REST, basta um cliente HTTP e uma biblioteca de JSON. Bibliotecas específicas de emissão são mais úteis quando a integração é feita diretamente com a SEFAZ. ### Como o Java lida com o certificado digital A1? O certificado A1, geralmente um arquivo PFX ou P12, pode ser carregado em um keystore Java para assinar o XML. Em APIs fiscais, o certificado costuma ser enviado ao provedor, muitas vezes em Base64, que faz a assinatura. ### Java é melhor que outras linguagens para integração fiscal? Não existe linguagem obrigatória. Java é popular em sistemas corporativos, mas uma API fiscal pode ser consumida por qualquer linguagem capaz de fazer requisições HTTPS, como JavaScript, Python ou C#. ## Termos relacionados - [API fiscal](https://conota.dev/glossario/api-fiscal.md) - [Biblioteca de emissão fiscal](https://conota.dev/glossario/biblioteca-de-emissao-fiscal.md) - [Keystore de certificados digitais](https://conota.dev/glossario/keystore-de-certificados-digitais.md) - [Assinatura digital do XML](https://conota.dev/glossario/assinatura-digital-do-xml.md) - [Backend de integração fiscal](https://conota.dev/glossario/backend-de-integracao-fiscal.md) - [JavaScript na integração fiscal](https://conota.dev/glossario/javascript-na-integracao-fiscal.md) --- Fonte: [Java na integração fiscal](https://conota.dev/glossario/java-na-integracao-fiscal/) · Atualizado em 2026-10-22 --- # JavaScript na integração fiscal > JavaScript na integração fiscal é o uso da linguagem JavaScript, geralmente com Node.js no servidor, para conectar sistemas de venda e gestão a uma API fiscal. Com ela, o sistema monta os dados da nota em JSON, envia a requisição de emissão, acompanha o status e recebe XML, PDF e eventos de forma automatizada. **Também conhecido como:** Integração fiscal com JavaScript, Integração fiscal com Node.js, Emissão de nota fiscal com JavaScript, Integração fiscal em Node.js, JS, JavaScript tax integration **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** J ## O que significa usar JavaScript na integração fiscal? Significa escrever, em JavaScript, o código que faz o sistema da empresa conversar com um serviço de emissão de documentos fiscais. Em vez de alguém digitar a nota em um portal, o próprio sistema envia os dados da venda para uma API, que cuida da comunicação com a SEFAZ ou com a prefeitura. Na prática, esse código costuma rodar no servidor, com Node.js, porque é ali que ficam guardadas as credenciais e onde acontece a lógica do negócio. O navegador do usuário não deve chamar a API fiscal diretamente. ## Por que JavaScript combina bem com APIs fiscais? As APIs fiscais modernas seguem o modelo REST e trocam dados no formato JSON, que nasceu da sintaxe de objetos do JavaScript. Isso torna natural montar o payload de emissão, ler respostas e tratar erros sem conversões complicadas. Além disso, o Node.js lida bem com muitas requisições simultâneas e com operações que esperam resposta, como consultar o status de uma nota. Muitas plataformas de venda, marketplaces e sistemas de gestão já são construídos nessa linguagem, o que facilita adicionar a emissão fiscal ao que já existe. ## Como funciona uma integração fiscal em JavaScript? O fluxo típico tem quatro etapas: o sistema reúne os dados da venda (emitente, destinatário, itens, impostos); monta um objeto JSON no formato exigido pela API; envia esse objeto por HTTPS com um token de autenticação no cabeçalho; e trata a resposta. Como a autorização pela SEFAZ ou pela prefeitura pode demorar, muitas APIs trabalham de forma assíncrona. O código recebe primeiro um identificador e depois descobre o resultado por consulta periódica (polling) ou por webhook, quando a própria API avisa que a nota foi autorizada ou rejeitada. Em seguida, o sistema baixa o XML e o PDF, como o DANFE ou o DANFCE. ## Quais cuidados são importantes ao integrar com JavaScript? Segurança vem primeiro: chaves de API e certificados devem ficar em variáveis de ambiente ou em um cofre de segredos, nunca no código enviado ao navegador. Webhooks recebidos devem ter a origem validada, por exemplo com assinatura HMAC. Também é preciso tratar falhas de rede com tentativas controladas (retry com backoff exponencial), usar chaves de idempotência para não emitir a mesma nota duas vezes, definir timeouts e registrar logs de cada requisição. Outro ponto de atenção são números decimais: valores monetários devem ser arredondados com cuidado para evitar diferenças de centavos que geram rejeição. ## Qual a diferença entre usar JavaScript e Java na integração fiscal? Do ponto de vista da API, não há diferença: ela recebe as mesmas requisições HTTP com JSON, venha o código de onde vier. A escolha depende da linguagem que a equipe e o sistema já usam. JavaScript, com Node.js, costuma ser preferido em aplicações web e plataformas de venda pela agilidade no desenvolvimento. Java é comum em ERPs corporativos e sistemas legados que já fazem assinatura de XML localmente. Quando a API fiscal cuida da assinatura e da comunicação com os órgãos, a integração fica simples em qualquer uma das duas. ## Exemplos de JavaScript na integração fiscal - Uma loja virtual feita em Node.js chama a API fiscal assim que o pagamento é aprovado, enviando os itens do pedido em JSON para emitir a NF-e e anexando o DANFE ao e-mail de confirmação. - Um sistema de agendamento para clínicas, escrito em JavaScript, emite automaticamente a NFS-e de cada consulta concluída e recebe por webhook o aviso de autorização da prefeitura. - Um PDV web envia os dados da venda para o backend em Node.js, que solicita a NFC-e e devolve à tela o QR Code para impressão no cupom. - Uma transportadora usa um serviço em JavaScript para emitir CT-e e MDF-e a partir das ordens de coleta e encerrar o manifesto quando a entrega é confirmada. ## Perguntas frequentes ### Posso chamar a API fiscal direto do navegador? Não é recomendado. Isso exporia a chave de API a qualquer pessoa que inspecione a página. O correto é o navegador falar com o seu backend, que guarda as credenciais e faz a chamada à API fiscal. ### Preciso de uma biblioteca específica para emitir notas em JavaScript? Não necessariamente. Como a API usa HTTP e JSON, basta o fetch nativo do Node.js ou um cliente HTTP comum. Bibliotecas ou SDKs podem facilitar, mas não são obrigatórios. ### Com JavaScript eu preciso assinar o XML da nota? Depende da solução. Ao usar uma API fiscal que cuida da assinatura com o certificado digital cadastrado, seu código envia apenas o JSON. Sem essa camada, seria preciso gerar e assinar o XML por conta própria. ### TypeScript também serve para integração fiscal? Sim. TypeScript é JavaScript com tipagem, o que ajuda a evitar erros no payload, como campos faltando ou com tipo errado. O código final roda normalmente no Node.js. ## Termos relacionados - [API fiscal](https://conota.dev/glossario/api-fiscal.md) - [Backend de integração fiscal](https://conota.dev/glossario/backend-de-integracao-fiscal.md) - [Formato JSON](https://conota.dev/glossario/formato-json.md) - [Java na integração fiscal](https://conota.dev/glossario/java-na-integracao-fiscal.md) - [Payload de emissão fiscal](https://conota.dev/glossario/payload-de-emissao-fiscal.md) - [Idempotência na emissão fiscal](https://conota.dev/glossario/idempotencia-na-emissao-fiscal.md) --- Fonte: [JavaScript na integração fiscal](https://conota.dev/glossario/javascript-na-integracao-fiscal/) · Atualizado em 2026-10-22 --- # Jitter nas retentativas de requisição > Jitter nas retentativas de requisição é uma pequena variação aleatória adicionada ao tempo de espera antes de repetir uma chamada que falhou a uma API. Em vez de todos os sistemas tentarem de novo no mesmo instante, cada um espera um intervalo ligeiramente diferente. Isso espalha as tentativas, reduz picos de tráfego e aumenta a chance de sucesso. **Também conhecido como:** Jitter, Jitter no retry, Variação aleatória no tempo de retentativa, Retry com jitter, Backoff com jitter, Retry jitter **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** J ## O que é jitter nas retentativas de requisição? Quando um sistema chama uma API e a resposta falha, por exemplo por instabilidade momentânea, tempo esgotado ou excesso de requisições, o comportamento comum é tentar de novo depois de alguns segundos. Essa nova tentativa é chamada de retentativa (ou retry). Jitter é o ingrediente de aleatoriedade colocado nesse tempo de espera. Em vez de esperar exatamente 2 segundos, o sistema espera um valor sorteado, como 1,3 ou 1,8 segundo. A palavra vem do inglês e significa algo como tremulação ou oscilação. ## Por que o jitter é necessário? Imagine centenas de sistemas emitindo notas fiscais ao mesmo tempo. Se o serviço fica fora do ar por alguns segundos, todos recebem erro quase no mesmo momento. Se todos usam a mesma regra de espera fixa, todos voltam a tentar exatamente juntos, criando uma nova onda de tráfego que pode derrubar o serviço outra vez. Esse efeito é conhecido como efeito manada (thundering herd, em inglês). O jitter quebra essa sincronia: cada cliente volta em um momento diferente, o tráfego chega de forma mais distribuída e o serviço consegue se recuperar e atender as requisições aos poucos. ## Como o jitter funciona junto com o backoff exponencial? O backoff exponencial define que o tempo de espera cresce a cada falha: por exemplo, 1, 2, 4, 8 segundos. Ele evita que o cliente insista sem parar, mas sozinho ainda mantém os clientes sincronizados, porque todos seguem a mesma sequência. O jitter entra sorteando um valor dentro desse intervalo. Uma abordagem comum é sortear qualquer valor entre zero e o tempo calculado pelo backoff (chamada de jitter completo). Outra é manter metade do tempo fixa e sortear a outra metade, garantindo uma espera mínima. Em ambos os casos, costuma-se definir também um tempo máximo de espera e um número máximo de tentativas. ## Qual a diferença entre backoff exponencial e jitter? O backoff exponencial responde à pergunta quanto tempo, em média, devo esperar antes de tentar de novo, aumentando o intervalo a cada falha. O jitter responde à pergunta como evitar que todo mundo espere exatamente o mesmo tempo, adicionando aleatoriedade. São técnicas complementares e quase sempre usadas juntas. Backoff sem jitter ainda gera picos sincronizados; jitter sem backoff espalha as tentativas, mas não reduz a pressão sobre um serviço que continua com problema. ## Quando usar jitter na emissão fiscal por API? Na integração fiscal, o jitter é útil sempre que uma falha é provavelmente passageira: respostas HTTP 429 (limite de requisições atingido), erros 5xx do servidor, tempo esgotado na conexão ou indisponibilidade temporária de serviços como SEFAZ e prefeituras. Ele não deve ser usado para erros que não vão se resolver sozinhos, como rejeições de validação fiscal, CFOP incorreto, certificado vencido ou dados de destinatário inválidos. Nesses casos, tentar de novo apenas repete o mesmo erro; o correto é corrigir o dado e reenviar. ## Que cuidados tomar ao repetir uma emissão de nota fiscal? O maior risco de repetir uma requisição de emissão é gerar documentos em duplicidade. Se a primeira tentativa chegou ao servidor, mas a resposta se perdeu no caminho, uma nova tentativa pode criar uma segunda nota. Por isso, retentativas devem ser combinadas com idempotência, usando um identificador único por operação para que o servidor reconheça repetições. Também vale respeitar o cabeçalho Retry-After quando a API informa quanto tempo esperar, registrar cada tentativa em log para auditoria e preferir fluxos assíncronos com fila, consultando o status do documento em vez de reenviar repetidamente. ## Exemplos de Jitter nas retentativas de requisição - Um ERP envia 500 NF-e no fechamento do dia e recebe HTTP 429. Em vez de reenviar todas após exatamente 5 segundos, cada requisição espera um tempo sorteado entre 0 e 5 segundos, depois entre 0 e 10, e assim por diante, até o limite de tentativas. - Uma plataforma de e-commerce tem uma falha de conexão ao emitir NFC-e. O código aplica backoff exponencial com jitter e envia sempre a mesma chave de idempotência, garantindo que, se a primeira tentativa tiver sido processada, nenhuma nota duplicada seja gerada. - Um marketplace que emite NFS-e para vários municípios detecta lentidão no serviço de uma prefeitura. As retentativas com jitter distribuem os reenvios ao longo de alguns minutos, evitando sobrecarregar ainda mais o serviço municipal durante a recuperação. - Um agente de inteligência artificial que consulta o status de documentos via MCP recebe erro temporário e aguarda um intervalo aleatório antes de consultar de novo, em vez de repetir a chamada imediatamente em sequência. ## Perguntas frequentes ### Jitter atrasa a emissão das notas? Pode adicionar alguns segundos em cenários de falha, mas normalmente acelera o resultado geral. Sem jitter, as retentativas sincronizadas tendem a provocar novas falhas, prolongando a indisponibilidade. Com jitter, o serviço se recupera mais rápido e mais requisições têm sucesso. ### Devo aplicar jitter em toda requisição que falhar? Não. Use apenas em falhas temporárias, como HTTP 429, erros 5xx e tempo esgotado. Erros de validação ou rejeições fiscais exigem correção dos dados; repetir a mesma requisição só gera o mesmo erro. ### Jitter evita notas fiscais duplicadas? Não. Jitter apenas organiza o momento das retentativas. Para evitar duplicidade, é preciso usar idempotência, enviando um identificador único por operação, e consultar o status do documento antes de reenviar quando a resposta original foi perdida. ### Quantas retentativas devo fazer? Não existe número universal. O comum é definir um limite pequeno de tentativas e um tempo máximo de espera. Depois disso, a operação deve ir para uma fila de reprocessamento ou ser sinalizada para análise, em vez de tentar indefinidamente. ## Termos relacionados - [Backoff exponencial](https://conota.dev/glossario/backoff-exponencial.md) - [HTTP 429 na integração fiscal](https://conota.dev/glossario/http-429-na-integracao-fiscal.md) - [Idempotência na emissão fiscal](https://conota.dev/glossario/idempotencia-na-emissao-fiscal.md) - [Fila de emissão fiscal](https://conota.dev/glossario/fila-de-emissao-fiscal.md) - [Fluxo assíncrono de emissão](https://conota.dev/glossario/fluxo-assincrono-de-emissao.md) - [Fallback na integração fiscal](https://conota.dev/glossario/fallback-na-integracao-fiscal.md) --- Fonte: [Jitter nas retentativas de requisição](https://conota.dev/glossario/jitter-nas-retentativas-de-requisicao/) · Atualizado em 2026-10-22 --- # JKS para armazenamento de certificados > JKS (Java KeyStore) é um formato de arquivo usado por aplicações Java para guardar, de forma protegida por senha, certificados digitais e chaves privadas. Em sistemas fiscais, serve para armazenar o certificado A1 da empresa, usado para assinar XMLs de NF-e, NFS-e e outros documentos e para se autenticar nos webservices da SEFAZ. **Também conhecido como:** Java KeyStore, Keystore Java, Arquivo .jks, JKS **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** J ## O que é um arquivo JKS? JKS é a sigla de Java KeyStore, que pode ser traduzido como "cofre de chaves do Java". Trata-se de um arquivo, geralmente com extensão .jks, que funciona como um pequeno cofre digital: dentro dele ficam guardados certificados e as chaves privadas correspondentes, e o acesso depende de senha. Cada item guardado no cofre recebe um apelido, chamado alias. Assim, um mesmo arquivo JKS pode conter vários certificados, por exemplo, de diferentes empresas ou filiais, e o sistema escolhe qual usar pelo alias. ## Para que serve o JKS na emissão de notas fiscais? Para emitir documentos fiscais eletrônicos, o sistema precisa do certificado digital da empresa emissora. Ele é usado para assinar digitalmente o XML, garantindo autoria e integridade, e para estabelecer a conexão segura com os servidores da SEFAZ ou da prefeitura. Sistemas escritos em Java, como muitos ERPs e emissores próprios, costumam carregar esse certificado a partir de um arquivo JKS, porque é um formato que a plataforma Java lê de forma nativa. Com isso, a aplicação abre o cofre, informa a senha e obtém a chave privada no momento da assinatura. ## Qual a diferença entre JKS e arquivo PFX? O certificado A1 da ICP-Brasil normalmente é entregue pela Autoridade Certificadora como um arquivo PFX (ou .p12), que segue o padrão internacional PKCS#12. Esse formato é reconhecido por praticamente qualquer linguagem e sistema operacional. O JKS, por outro lado, é um formato próprio do ecossistema Java e pouco aceito fora dele. Na prática, os dois guardam o mesmo tipo de conteúdo, certificado e chave privada, mas o PFX é mais portátil. Versões mais recentes do Java passaram inclusive a adotar o PKCS#12 como formato padrão de keystore, e o JKS segue existindo principalmente por compatibilidade. ## Como converter um certificado PFX em JKS, e vice-versa? A própria instalação do Java traz uma ferramenta de linha de comando chamada keytool, que permite importar o conteúdo de um PFX para um JKS ou fazer o caminho inverso. Na conversão, é preciso informar a senha do arquivo de origem e definir a senha do arquivo de destino. O caminho inverso é útil quando o certificado está guardado apenas em JKS e precisa ser enviado a um serviço que aceita PFX, como costuma ocorrer em APIs fiscais que recebem o certificado codificado em Base64. Sempre confira na documentação do serviço quais formatos são aceitos. ## Qual a diferença entre keystore e truststore? Os dois usam o mesmo formato de arquivo, mas têm funções diferentes. A keystore guarda o certificado e a chave privada da própria empresa, ou seja, aquilo que prova quem ela é. A truststore guarda certificados de autoridades em que o sistema confia, como os da cadeia da ICP-Brasil, para validar os servidores com que se conecta. Em integrações fiscais feitas em Java, erros de conexão com a SEFAZ muitas vezes acontecem porque a truststore não contém a cadeia de certificação necessária, e não por problema no certificado da empresa. ## Quais cuidados de segurança o JKS exige? Quem tem o arquivo JKS e a senha consegue assinar documentos em nome da empresa. Por isso, o arquivo não deve ser enviado por e-mail, versionado em repositórios de código nem guardado junto com a senha em texto aberto. Boas práticas incluem usar senhas fortes, restringir quem pode acessar o arquivo no servidor, guardar a senha em uma ferramenta de gerenciamento de segredos e manter cópia de segurança. Também é importante acompanhar a validade do certificado A1, que expira e precisa ser substituído dentro do cofre. ## Exemplos de JKS para armazenamento de certificados - Um ERP desenvolvido em Java carrega o certificado A1 de cada cliente a partir de um arquivo JKS, identificando cada empresa por um alias, antes de assinar o XML da NF-e. - Uma equipe de desenvolvimento usa o keytool para converter o PFX recebido da Autoridade Certificadora em JKS, porque a biblioteca de emissão legada do sistema só aceita esse formato. - Ao migrar a emissão para uma API fiscal que recebe o certificado em PFX codificado em Base64, uma software house exporta os certificados guardados em JKS de volta para PFX. - Um sistema Java não consegue se conectar ao webservice da SEFAZ e o problema é resolvido ao importar os certificados da cadeia da ICP-Brasil para a truststore da aplicação. ## Perguntas frequentes ### Preciso de um arquivo JKS para emitir NF-e? Não necessariamente. O JKS é apenas uma forma de armazenar o certificado, comum em sistemas Java. Outras linguagens e muitas APIs fiscais trabalham diretamente com o arquivo PFX entregue pela Autoridade Certificadora. ### Converter PFX em JKS altera o certificado? Não. A conversão apenas muda o "recipiente". O certificado, a chave privada, o titular e a data de validade continuam os mesmos. ### O que acontece se eu esquecer a senha do JKS? Sem a senha, não é possível extrair a chave privada do arquivo. Será preciso recorrer a uma cópia do PFX original com senha conhecida ou adquirir um novo certificado. ### Um arquivo JKS pode guardar certificados de várias empresas? Sim. Cada certificado fica registrado com um alias diferente, e o sistema escolhe qual usar conforme a empresa emissora do documento. ## Termos relacionados - [Arquivo PFX](https://conota.dev/glossario/arquivo-pfx.md) - [Certificado digital A1](https://conota.dev/glossario/certificado-digital-a1.md) - [Java na integração fiscal](https://conota.dev/glossario/java-na-integracao-fiscal.md) - [Assinatura digital do XML](https://conota.dev/glossario/assinatura-digital-do-xml.md) - [Gerenciamento de segredos](https://conota.dev/glossario/gerenciamento-de-segredos.md) - [Cadeia de certificação digital](https://conota.dev/glossario/cadeia-de-certificacao-digital.md) --- Fonte: [JKS para armazenamento de certificados](https://conota.dev/glossario/jks-para-armazenamento-de-certificados/) · Atualizado em 2026-10-22 --- # JSON > JSON é um formato de texto leve e legível usado para organizar e trocar dados entre sistemas. Ele representa informações em pares de nome e valor, listas e objetos aninhados. Em APIs fiscais, é comum o sistema enviar os dados de uma nota em JSON, enquanto o documento oficial transmitido ao Fisco segue em XML. **Também conhecido como:** Formato JSON, JavaScript Object Notation, Notação de Objetos JavaScript, JSON **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** J ## O que significa JSON? JSON é a sigla de JavaScript Object Notation, ou Notação de Objetos JavaScript. Apesar do nome, ele não depende da linguagem JavaScript: praticamente todas as linguagens de programação, como Java, Python, PHP, C# e Go, conseguem ler e gerar JSON com facilidade. Na prática, JSON é apenas texto organizado com algumas regras simples. Por isso, pode ser lido tanto por pessoas quanto por máquinas, o que o tornou o formato mais usado em APIs modernas. ## Como é a estrutura de um JSON? Um JSON é formado por objetos, delimitados por chaves, que contêm pares de nome e valor. Por exemplo: {"cnpj": "00000000000000", "valor_total": 150.00}. Cada nome vem entre aspas duplas, seguido de dois pontos e do valor. Os valores podem ser textos, números, verdadeiro ou falso (true e false), nulo (null), listas entre colchetes ou outros objetos. Essa possibilidade de aninhar objetos permite representar estruturas complexas, como uma nota com emitente, destinatário e vários itens, cada um com seus próprios impostos. ## Para que serve o JSON na emissão de notas fiscais? Em uma API fiscal, o JSON costuma ser o formato usado para enviar os dados da venda ou do serviço e para receber as respostas. O ERP ou a plataforma de vendas monta um JSON com os dados da operação, como produtos, valores, CFOP, NCM e dados do cliente, e envia para a API. A API valida essas informações, converte para o leiaute oficial exigido pela SEFAZ ou pela prefeitura, assina e transmite o documento. Depois, devolve em JSON o status da emissão, a chave de acesso, o protocolo ou o motivo de uma eventual rejeição, além de links ou conteúdos do XML e do PDF. Isso permite que o sistema do cliente trabalhe com uma estrutura mais simples e uniforme, sem precisar lidar diretamente com os detalhes de cada leiaute de NF-e, NFC-e, NFS-e, CT-e ou MDF-e. ## Qual a diferença entre JSON e XML? Os dois são formatos de texto para representar dados, mas o XML usa marcações de abertura e fechamento, como 150.00, enquanto o JSON usa chaves, colchetes e pares de nome e valor. Em geral, o JSON é mais curto e mais fácil de ler e manipular em aplicações web. No mundo fiscal brasileiro, o documento oficial, como o XML da NF-e, continua sendo XML, pois é o formato definido nos leiautes e exigido para assinatura digital e guarda. O JSON aparece na camada de integração: é a forma como sistemas conversam com a API que cuida da emissão. ## Quais erros são comuns ao trabalhar com JSON? Os erros mais frequentes são de sintaxe: vírgula sobrando no último item, aspas simples no lugar de aspas duplas, chaves ou colchetes não fechados e caracteres especiais sem tratamento. Nesses casos, a API nem consegue ler a requisição. Há também erros de conteúdo: o JSON está bem formado, mas um campo obrigatório ficou de fora, um número foi enviado como texto ou uma data está em formato diferente do esperado. Para evitar isso, muitas APIs publicam um JSON Schema ou uma documentação OpenAPI que descreve exatamente quais campos e tipos são aceitos. ## Exemplos de JSON - Um ERP envia para a API fiscal um JSON com os dados de uma venda, incluindo CNPJ do emitente, CPF do cliente, lista de itens com NCM e CFOP, e recebe de volta um JSON com o status da NF-e e a chave de acesso. - Uma plataforma de serviços monta um JSON com o código do serviço, o valor e os dados do tomador para solicitar a emissão de uma NFS-e, sem precisar conhecer o leiaute exigido por cada município. - Um webhook notifica o sistema do cliente com um JSON informando que uma NFC-e foi rejeitada, trazendo o código e o motivo da rejeição para correção. - Um agente de inteligência artificial conectado via MCP consulta o status de documentos fiscais e recebe as respostas estruturadas em JSON. ## Perguntas frequentes ### Posso enviar uma NF-e para a SEFAZ em JSON? Não diretamente. A SEFAZ exige o documento em XML, conforme o leiaute oficial. O JSON é usado na comunicação entre o seu sistema e a API fiscal, que faz a conversão para XML, assina e transmite. ### Preciso saber programar para entender um JSON? Não. Como é texto organizado em nomes e valores, dá para ler e entender um JSON simples sem saber programar. Para gerar e enviar JSON a uma API, porém, normalmente é necessário algum conhecimento técnico ou uma ferramenta de integração. ### Como sei se meu JSON está correto? Primeiro, verifique a sintaxe com um validador de JSON. Depois, confira se os campos e tipos seguem a documentação da API ou o JSON Schema publicado. Ambientes de homologação ajudam a testar sem efeito fiscal. ## Termos relacionados - [JSON Schema](https://conota.dev/glossario/json-schema.md) - [Payload de emissão fiscal](https://conota.dev/glossario/payload-de-emissao-fiscal.md) - [Arquivo XML fiscal](https://conota.dev/glossario/arquivo-xml-fiscal.md) - [API REST para emissão fiscal](https://conota.dev/glossario/api-rest-para-emissao-fiscal.md) - [JSON-RPC no MCP](https://conota.dev/glossario/json-rpc-no-mcp.md) - [OpenAPI](https://conota.dev/glossario/openapi.md) --- Fonte: [JSON](https://conota.dev/glossario/json/) · Atualizado em 2026-10-22 --- # JSON Schema > JSON Schema é um padrão para descrever a estrutura esperada de um documento JSON, indicando quais campos existem, quais são obrigatórios, que tipo de valor cada um aceita e quais limites devem ser respeitados. Em APIs, ele é usado para validar dados automaticamente, documentar contratos e evitar que informações malformadas sejam processadas. **Também conhecido como:** Schema JSON, Esquema JSON, JSON Schema **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** J ## O que é JSON Schema, em palavras simples? JSON é um formato de texto muito usado para trocar dados entre sistemas. Ele organiza informações em pares de nome e valor, como "cnpj": "12345678000190". O problema é que o JSON, sozinho, não diz o que é certo ou errado: qualquer campo pode aparecer, com qualquer valor. O JSON Schema resolve isso funcionando como uma espécie de molde ou checklist. Ele é, ele próprio, escrito em JSON e descreve regras como: este campo é obrigatório, aquele deve ser um número, este outro precisa ter exatamente 14 dígitos. Qualquer sistema pode comparar um JSON recebido com esse molde e dizer se ele está de acordo ou não. ## Como funciona um JSON Schema na prática? Um schema usa palavras-chave padronizadas. Algumas das mais comuns são: type (o tipo do valor, como string, number, boolean, object ou array), properties (os campos que um objeto pode ter), required (a lista de campos obrigatórios), enum (uma lista fechada de valores aceitos), minimum e maximum (limites numéricos), minLength e maxLength (tamanho de textos) e pattern (um padrão de formato, usando expressões regulares). Por exemplo, um schema para os dados de um destinatário poderia exigir que o campo cnpj seja um texto com 14 dígitos numéricos, que o campo nome seja obrigatório e tenha até 60 caracteres e que o campo uf aceite apenas siglas de estados válidas. Uma biblioteca de validação lê o schema e o JSON enviado e devolve uma lista de erros, apontando exatamente qual campo violou qual regra. ## Para que serve o JSON Schema em uma API fiscal? Documentos fiscais como NF-e, NFC-e, NFS-e, CT-e e MDF-e têm muitos campos, com regras rígidas de formato e obrigatoriedade. Em uma API de emissão que recebe dados em JSON, o JSON Schema permite checar o payload antes de qualquer processamento, barrando cedo erros como um CFOP com dígitos a menos, uma alíquota em formato de texto ou um item sem NCM. Isso traz três benefícios principais: o sistema integrador recebe respostas de erro claras e imediatas, a equipe de desenvolvimento tem um contrato objetivo do que deve ser enviado, e menos documentos chegam à SEFAZ ou à prefeitura com problemas estruturais. Vale lembrar que o schema valida a forma dos dados, não as regras tributárias: um JSON pode estar perfeitamente estruturado e ainda assim ser rejeitado pelo órgão autorizador por um motivo fiscal. ## Qual a diferença entre JSON Schema e Esquema XML (XSD)? Os dois têm o mesmo propósito: descrever e validar a estrutura de dados. A diferença está no formato que cada um valida. O Esquema XML, conhecido como XSD, valida documentos em XML, que é o formato oficial exigido pela SEFAZ e por muitos padrões de NFS-e. O JSON Schema valida documentos em JSON, formato mais comum em APIs REST modernas. Na prática, é frequente os dois conviverem: o sistema do cliente envia JSON validado por um JSON Schema para a API fiscal, e a API converte esses dados em XML, que é então validado pelo XSD oficial do leiaute antes do envio ao órgão autorizador. ## Qual a relação entre JSON Schema, OpenAPI e MCP? A especificação OpenAPI, usada para documentar APIs REST, utiliza JSON Schema (ou uma variação muito próxima dele) para descrever os corpos de requisição e de resposta de cada endpoint. É isso que permite que ferramentas como o Swagger UI mostrem os campos esperados e gerem exemplos automaticamente. No MCP (Model Context Protocol), cada ferramenta disponibilizada para agentes de inteligência artificial declara seus parâmetros de entrada por meio de um JSON Schema. Assim, o agente sabe quais informações precisa fornecer, por exemplo, para consultar o status de uma nota, e o servidor consegue recusar chamadas com parâmetros inválidos antes de executar qualquer ação. ## Exemplos de JSON Schema - Um ERP envia o payload de emissão de uma NF-e sem o campo de NCM em um dos itens; a validação por JSON Schema devolve imediatamente um erro indicando que o campo obrigatório está ausente naquele item. - A documentação OpenAPI de uma API fiscal usa JSON Schema para mostrar que o campo serie da NFC-e deve ser um número inteiro entre 0 e 999. - Um agente de IA conectado via MCP lê o JSON Schema da ferramenta de consulta de documentos e descobre que precisa informar a chave de acesso com 44 dígitos para buscar uma nota. - Uma equipe de desenvolvimento usa o JSON Schema do endpoint de emissão de NFS-e para validar os dados no próprio sistema antes de enviá-los, reduzindo chamadas com erro. ## Perguntas frequentes ### JSON Schema é uma linguagem de programação? Não. É uma especificação declarativa, escrita em JSON, que apenas descreve regras sobre dados. Para aplicá-las, usa-se uma biblioteca de validação disponível em linguagens como JavaScript, Java, Python e muitas outras. ### Se o JSON passar no schema, a nota será autorizada? Não necessariamente. O schema garante que a estrutura e os formatos estão corretos, mas a autorização depende também de regras fiscais e cadastrais verificadas pela SEFAZ ou pela prefeitura, como situação do emitente, tributação e numeração. ### JSON Schema tem versões diferentes? Sim. A especificação evoluiu em versões chamadas drafts, com algumas diferenças de palavras-chave entre elas. Por isso, um schema costuma indicar qual versão segue, e o validador usado deve ser compatível com ela. ## Termos relacionados - [JSON](https://conota.dev/glossario/json.md) - [Schema de validação](https://conota.dev/glossario/schema-de-validacao.md) - [Esquema XML](https://conota.dev/glossario/esquema-xml.md) - [OpenAPI](https://conota.dev/glossario/openapi.md) - [Payload de emissão fiscal](https://conota.dev/glossario/payload-de-emissao-fiscal.md) - [Erro de validação fiscal](https://conota.dev/glossario/erro-de-validacao-fiscal.md) --- Fonte: [JSON Schema](https://conota.dev/glossario/json-schema/) · Atualizado em 2026-10-22 --- # JSON-RPC no MCP > JSON-RPC no MCP é o formato de mensagens que o Model Context Protocol usa para a comunicação entre um agente de inteligência artificial e um servidor de ferramentas. Cada pedido, resposta ou aviso é um pequeno objeto JSON com campos padronizados, o que permite ao agente listar ferramentas, chamar ações e receber resultados de forma previsível. **Também conhecido como:** JSON-RPC 2.0 no MCP, Mensagens JSON-RPC do Model Context Protocol, Protocolo de mensagens do MCP, JSON-RPC in MCP **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** J ## O que é JSON-RPC, em termos simples? JSON-RPC é um protocolo leve de chamada de procedimento remoto. Em vez de acessar endereços diferentes para cada ação, como acontece em muitas APIs, o cliente envia uma mensagem dizendo qual função quer executar e com quais dados. O servidor executa e devolve o resultado em outra mensagem. A sigla RPC vem de Remote Procedure Call, ou chamada de procedimento remoto. A parte JSON indica que todas as mensagens são escritas no formato JSON, que é texto simples, legível por pessoas e fácil de processar por qualquer linguagem de programação. O MCP usa a versão 2.0 desse protocolo. ## Por que o MCP usa JSON-RPC? O MCP precisa que agentes de IA de fornecedores diferentes conversem com servidores de ferramentas diferentes sem combinar tudo do zero a cada integração. O JSON-RPC resolve isso porque define uma estrutura fixa para pedidos, respostas e erros, e qualquer lado que siga a especificação consegue entender o outro. Outra vantagem é que o JSON-RPC funciona nos dois sentidos. Tanto o cliente quanto o servidor podem enviar mensagens, o que permite ao servidor avisar o agente sobre mudanças, como uma nova ferramenta disponível, sem esperar ser perguntado. ## Como é uma mensagem JSON-RPC no MCP? Existem três tipos de mensagem. A requisição (request) tem os campos jsonrpc, com o valor 2.0, id, que identifica o pedido, method, com o nome da ação, e params, com os dados necessários. A resposta (response) repete o mesmo id e traz um campo result, quando deu certo, ou um campo error, quando algo falhou. O terceiro tipo é a notificação (notification), uma mensagem sem id. Ela serve apenas para avisar algo e não espera resposta, como o aviso de que a inicialização da conexão foi concluída. Os erros seguem códigos padronizados. Por exemplo, -32601 indica que o método pedido não existe e -32602 indica parâmetros inválidos. Além do código, a mensagem de erro traz um texto explicativo e, opcionalmente, dados extras. ## Como funciona na prática em uma consulta fiscal? Primeiro, o agente envia uma requisição initialize para combinar a versão do protocolo e os recursos que cada lado suporta. Depois, envia tools/list para descobrir quais ferramentas o servidor oferece, como consultar o status de uma NF-e ou baixar o XML de uma NFS-e. Quando o usuário pede algo, o agente envia tools/call informando o nome da ferramenta e os argumentos, por exemplo a chave de acesso da nota. O servidor verifica se aquela credencial tem permissão para a ação, executa e devolve o resultado na resposta com o mesmo id. Em servidores fiscais, cada chamada pode ser registrada para auditoria. ## Qual a diferença entre JSON-RPC e uma API REST? Em uma API REST, cada recurso tem um endereço próprio e a ação é indicada pelo método HTTP, como GET para consultar ou POST para criar. No JSON-RPC, a ação vem escrita dentro da própria mensagem, no campo method, e o endereço de envio costuma ser sempre o mesmo. Na prática, os dois podem conviver. Um servidor MCP fiscal pode receber chamadas JSON-RPC do agente e, por trás, acionar uma API REST de emissão. O JSON-RPC organiza a conversa com o agente, enquanto a API REST continua sendo usada por sistemas tradicionais, como ERPs. ## Por onde as mensagens JSON-RPC trafegam no MCP? O MCP separa o formato da mensagem do meio de transporte. As mesmas mensagens JSON-RPC podem trafegar pela entrada e saída padrão (stdio), quando o servidor roda na mesma máquina do agente, ou por HTTP, quando o servidor está na internet. Em servidores remotos, como os que dão acesso a documentos fiscais, o transporte por HTTP normalmente é protegido por HTTPS e exige autenticação, como um token. Assim, o conteúdo da mensagem segue o padrão JSON-RPC, enquanto a segurança fica a cargo da camada de transporte e das permissões do servidor. ## Exemplos de JSON-RPC no MCP - Um agente de IA envia uma requisição com method tools/call, o nome de uma ferramenta de consulta e a chave de acesso de uma NF-e nos parâmetros; o servidor responde com o mesmo id e o status de autorização da nota. - Ao conectar-se a um servidor MCP fiscal, o assistente envia initialize e, em seguida, tools/list, recebendo a lista de ações disponíveis, como consultar rejeições ou baixar o XML de uma NFS-e. - O agente tenta chamar uma ferramenta de cancelamento sem informar a justificativa obrigatória e recebe uma resposta com error de código -32602, indicando parâmetros inválidos. - Uma equipe de desenvolvimento analisa os logs de um servidor MCP e usa o campo id de cada mensagem JSON-RPC para relacionar cada pedido feito pelo agente à sua respectiva resposta. ## Perguntas frequentes ### Preciso conhecer JSON-RPC para usar um servidor MCP? Normalmente não. Os clientes de IA compatíveis com MCP montam e interpretam as mensagens JSON-RPC automaticamente. Conhecer o formato ajuda quando você desenvolve um servidor próprio, depura erros ou analisa logs de integração. ### O campo id é obrigatório? É obrigatório em requisições, porque é ele que liga o pedido à resposta correta. Notificações não têm id, já que não esperam resposta. No MCP, o id não pode ser nulo. ### JSON-RPC substitui a API REST de emissão fiscal? Não. O JSON-RPC é o idioma da conversa entre o agente de IA e o servidor MCP. A API REST continua sendo o caminho usual para sistemas como ERPs e plataformas de venda emitirem documentos fiscais. ### JSON-RPC é seguro para dados fiscais? O JSON-RPC define apenas o formato das mensagens. A segurança depende do transporte, como HTTPS, da autenticação por token e das permissões configuradas no servidor, que limitam quais ações cada agente pode executar. ## Termos relacionados - [Conota MCP](https://conota.dev/glossario/conota-mcp.md) - [MCP fiscal](https://conota.dev/glossario/mcp-fiscal.md) - [JSON](https://conota.dev/glossario/json.md) - [REST](https://conota.dev/glossario/rest.md) - [Permissão de acesso à API](https://conota.dev/glossario/permissao-de-acesso-a-api.md) - [Trilha de auditoria fiscal](https://conota.dev/glossario/trilha-de-auditoria-fiscal.md) --- Fonte: [JSON-RPC no MCP](https://conota.dev/glossario/json-rpc-no-mcp/) · Atualizado em 2026-10-22 --- # Julgamento administrativo tributário > Julgamento administrativo tributário é a análise feita por órgãos do próprio Fisco quando um contribuinte contesta uma cobrança, multa ou autuação. Nesse processo, julgadores examinam argumentos e provas, como notas fiscais e arquivos XML, e decidem se a exigência é mantida, reduzida ou cancelada, sem a necessidade de recorrer ao Poder Judiciário. **Também conhecido como:** Processo administrativo fiscal, Contencioso administrativo tributário, Processo administrativo tributário, Julgamento administrativo fiscal, PAF, Administrative tax judgment **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** J ## O que é julgamento administrativo tributário? É a etapa em que uma discussão entre empresa e Fisco é decidida dentro da própria administração pública. Quando a fiscalização entende que um tributo deixou de ser pago, ou foi pago a menos, ela pode lavrar um auto de infração. A empresa, se discordar, apresenta uma defesa, e essa defesa é julgada por órgãos administrativos especializados. Em vez de um juiz do Judiciário, quem decide são julgadores ligados à administração tributária, geralmente organizados em instâncias. O objetivo é revisar o lançamento do tributo e corrigir eventuais erros antes que o caso chegue à Justiça. ## Como funciona o processo, passo a passo? De forma simplificada, o caminho costuma ser: a fiscalização identifica uma suposta irregularidade e notifica a empresa; a empresa apresenta impugnação dentro do prazo previsto na legislação; um órgão de primeira instância analisa e decide; se uma das partes discordar, pode haver recurso para uma instância superior. Ao longo do processo, a empresa junta documentos que comprovem seus argumentos, como notas fiscais, livros fiscais e comprovantes de pagamento. Enquanto a discussão administrativa está em andamento, em regra a cobrança do valor contestado fica suspensa. Prazos, número de instâncias e regras variam conforme o tributo e o ente: União, estados e municípios têm órgãos e normas próprios. ## Quem julga esses processos? Depende do tributo. Para tributos federais, como IRPJ, CSLL, PIS e COFINS, há órgãos de julgamento da Receita Federal e, em instância recursal, o CARF (Conselho Administrativo de Recursos Fiscais). Para o ICMS, cada estado mantém seus próprios tribunais ou conselhos administrativos. Para o ISSQN, os municípios definem como o contencioso é organizado. Em muitos desses órgãos, especialmente nas instâncias de recurso, os colegiados reúnem representantes do Fisco e dos contribuintes, buscando uma análise mais equilibrada. ## Qual a diferença entre julgamento administrativo e processo judicial? O julgamento administrativo acontece dentro da administração tributária, costuma ter custos menores e, em geral, não exige o pagamento ou a garantia do valor discutido para que a defesa seja analisada. Já o processo judicial ocorre no Poder Judiciário e pode exigir garantias para suspender a cobrança. Se a decisão administrativa final for favorável ao contribuinte, o débito é cancelado e, em regra, o Fisco não leva o caso à Justiça. Se for desfavorável, a empresa ainda pode recorrer ao Judiciário. Por isso, muitas empresas veem a via administrativa como uma primeira chance de resolver a disputa. ## Por que documentos fiscais eletrônicos são importantes no julgamento? Grande parte das autuações envolve informações que estão nos documentos fiscais: CFOP, CST, base de cálculo, alíquotas, créditos aproveitados ou retenções. O arquivo XML autorizado de uma NF-e, NFS-e, CT-e ou NFC-e, junto com seus eventos, como cancelamentos e cartas de correção, é uma das provas mais fortes que a empresa pode apresentar. Por isso, manter a guarda organizada dos XMLs, o histórico de eventos e os protocolos de autorização faz diferença. Uma empresa que emite por API e armazena corretamente esses arquivos consegue localizar rapidamente as notas questionadas e demonstrar o que foi de fato emitido e autorizado pelo Fisco. ## Exemplos de Julgamento administrativo tributário - Uma indústria recebe um auto de infração por suposto creditamento indevido de ICMS e apresenta impugnação ao órgão de julgamento estadual, anexando os XMLs das notas de entrada que comprovam a origem dos créditos. - Uma prestadora de serviços é autuada pelo município por não recolher ISSQN e, no julgamento administrativo, demonstra com as NFS-e emitidas que o imposto foi retido pelo tomador, conseguindo cancelar a cobrança. - Uma transportadora contesta multa por divergência de dados de frete e usa o CT-e autorizado, junto com o histórico de eventos, como prova no processo. - Um ERP exporta, a pedido da equipe tributária do cliente, todos os XMLs e DANFEs de um período fiscalizado para instruir a defesa administrativa. ## Perguntas frequentes ### Preciso pagar o valor cobrado para apresentar defesa administrativa? Em regra, não. Na maior parte dos casos, a defesa administrativa pode ser apresentada sem pagamento ou garantia, e a cobrança do valor contestado fica suspensa até a decisão final. As regras exatas dependem da legislação de cada ente. ### Perder no julgamento administrativo impede ir à Justiça? Não. Se a decisão administrativa for desfavorável, o contribuinte ainda pode levar a discussão ao Poder Judiciário. Já uma decisão final favorável ao contribuinte costuma encerrar a cobrança. ### Qual o prazo para contestar uma autuação? O prazo varia conforme o tributo e o ente que fez a cobrança, e vem indicado na própria notificação. Perder esse prazo pode tornar a cobrança definitiva na esfera administrativa, por isso a contagem deve ser acompanhada com atenção. ### Que documentos ajudam na defesa? XMLs autorizados de notas fiscais, eventos fiscais, protocolos de autorização, escrituração fiscal, guias de pagamento e contratos. Quanto mais organizados e completos, mais fácil comprovar a regularidade das operações questionadas. ## Termos relacionados - [Fiscalização tributária](https://conota.dev/glossario/fiscalizacao-tributaria.md) - [Jurisprudência tributária](https://conota.dev/glossario/jurisprudencia-tributaria.md) - [Juntada de documentos em processo fiscal](https://conota.dev/glossario/juntada-de-documentos-em-processo-fiscal.md) - [Glosa de crédito tributário](https://conota.dev/glossario/glosa-de-credito-tributario.md) - [Guarda de documentos fiscais](https://conota.dev/glossario/guarda-de-documentos-fiscais.md) - [Juros de mora tributária](https://conota.dev/glossario/juros-de-mora-tributaria.md) --- Fonte: [Julgamento administrativo tributário](https://conota.dev/glossario/julgamento-administrativo-tributario/) · Atualizado em 2026-10-22 --- # Juntada de documentos em processo fiscal > Juntada de documentos em processo fiscal é o ato de anexar provas, como notas fiscais, arquivos XML, contratos, comprovantes de pagamento e relatórios, a um processo administrativo tributário. Ela permite que o contribuinte ou o fisco demonstre fatos relevantes para a discussão, por exemplo, ao contestar um auto de infração ou responder a uma intimação. **Também conhecido como:** Juntada de provas, Anexação de documentos ao processo, Juntada documental, Filing of documents in tax proceedings **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** J ## O que significa juntada de documentos em um processo fiscal? Juntar, na linguagem jurídica, significa anexar formalmente um documento a um processo. Depois de juntado, o documento passa a fazer parte dos autos e pode ser analisado por quem vai decidir o caso. No contexto fiscal, isso acontece em processos administrativos que tramitam nos órgãos de fiscalização da União, dos estados ou dos municípios. É a forma oficial de o contribuinte provar o que alega, como mostrar que uma nota foi emitida corretamente ou que um imposto já foi pago. ## Quando a juntada de documentos acontece? O momento mais comum é a defesa contra um auto de infração, conhecida como impugnação. Nela, a empresa apresenta seus argumentos e anexa as provas que os sustentam. A juntada também pode ocorrer em resposta a uma intimação durante a fiscalização, em pedidos de restituição ou compensação de tributos, em recursos contra decisões de primeira instância e em pedidos de revisão. O próprio fisco também junta documentos, como relatórios de auditoria e cruzamentos de dados. ## Quais documentos costumam ser juntados? Em discussões tributárias, as provas mais frequentes são os próprios documentos fiscais: XML de NF-e, NFC-e, NFS-e e CT-e, além de seus documentos auxiliares, como DANFE e DACTE. Eventos vinculados, como cancelamentos e cartas de correção, também são relevantes. Completam o conjunto livros e arquivos de escrituração fiscal, guias de recolhimento pagas, contratos, comprovantes de entrega de mercadoria, extratos bancários, laudos técnicos e procurações que autorizam alguém a representar a empresa. ## Existe prazo para juntar documentos? Sim. Em geral, as provas devem ser apresentadas junto com a defesa ou dentro do prazo indicado na intimação. Documentos entregues fora do prazo podem ser recusados, salvo em situações excepcionais previstas nas regras de cada órgão. Como os prazos e as exceções variam conforme a esfera (federal, estadual ou municipal) e o tipo de processo, é importante conferir a norma aplicável e o próprio documento de intimação. Por isso, ter os documentos organizados antes de precisar deles faz muita diferença. ## Como os documentos fiscais eletrônicos ajudam na juntada? O arquivo XML assinado digitalmente é a versão oficial de uma nota eletrônica. Ele carrega a assinatura do emitente e, quando autorizado, o protocolo do órgão fiscal, o que reforça a autenticidade da prova. O PDF auxiliar facilita a leitura, mas o XML é o documento com validade jurídica. Empresas que emitem notas por API, com uma infraestrutura como o Conota, conseguem recuperar rapidamente o XML, o PDF, o status e o histórico de eventos de cada documento. Isso agiliza a montagem da defesa e evita a busca manual por arquivos espalhados em diferentes sistemas. ## Qual a diferença entre juntada e simples entrega de documentos ao fisco? A entrega de documentos pode ocorrer em várias situações, como em uma fiscalização de rotina, sem que exista um processo formal aberto. A juntada, por sua vez, pressupõe um processo administrativo em andamento, no qual o documento é registrado e passa a integrar o conjunto de provas analisado no julgamento. Na prática, hoje muitos órgãos recebem a juntada por meio de sistemas eletrônicos ou do domicílio tributário eletrônico, com registro da data e do responsável pelo envio. ## Exemplos de Juntada de documentos em processo fiscal - Uma distribuidora autuada por suposta falta de emissão de notas junta à impugnação os arquivos XML autorizados das NF-e questionadas, baixados do seu emissor fiscal. - Uma prestadora de serviços cobrada de ISSQN em duplicidade anexa ao processo as NFS-e emitidas e as guias de recolhimento pagas para comprovar o pagamento. - Uma transportadora intimada a comprovar operações de frete junta os CT-e, os MDF-e encerrados e os comprovantes de entrega das cargas. - Um marketplace usa a API do seu emissor para exportar, em lote, o histórico de eventos e os XML de um período específico solicitados em uma intimação. ## Perguntas frequentes ### Posso juntar apenas o PDF da nota fiscal? Pode ajudar, mas o ideal é juntar o arquivo XML, pois ele é o documento eletrônico oficial, com assinatura digital e protocolo de autorização. O PDF, como o DANFE, é apenas uma representação auxiliar para leitura. ### Quem pode fazer a juntada de documentos? O próprio contribuinte, seu representante legal ou um procurador com poderes para isso, como advogado ou contador. O fisco também pode juntar documentos produzidos durante a fiscalização. ### Documentos juntados fora do prazo são aceitos? Em regra, podem ser recusados. Algumas normas admitem exceções, como fatos novos ou impossibilidade comprovada de apresentação anterior. As condições variam conforme o órgão e o tipo de processo. ## Termos relacionados - [Julgamento administrativo tributário](https://conota.dev/glossario/julgamento-administrativo-tributario.md) - [Fiscalização tributária](https://conota.dev/glossario/fiscalizacao-tributaria.md) - [Guarda de documentos fiscais](https://conota.dev/glossario/guarda-de-documentos-fiscais.md) - [Arquivo XML fiscal](https://conota.dev/glossario/arquivo-xml-fiscal.md) - [Histórico de eventos fiscais](https://conota.dev/glossario/historico-de-eventos-fiscais.md) - [Domicílio tributário eletrônico](https://conota.dev/glossario/domicilio-tributario-eletronico.md) --- Fonte: [Juntada de documentos em processo fiscal](https://conota.dev/glossario/juntada-de-documentos-em-processo-fiscal/) · Atualizado em 2026-10-22 --- # Jurisdição tributária > Jurisdição tributária é o alcance territorial e a autoridade de um ente público (União, estado, Distrito Federal ou município) para cobrar e fiscalizar tributos. Ela define qual governo tem poder sobre determinada operação ou contribuinte e, assim, qual legislação se aplica e a qual órgão os documentos fiscais devem ser enviados. **Também conhecido como:** Jurisdição fiscal, Competência tributária (uso informal), Tax jurisdiction **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** J ## O que significa jurisdição tributária na prática? Jurisdição tributária responde a uma pergunta simples: quem manda nesse imposto, aqui? Cada tributo pertence a um ente público, e cada ente só pode exigir esse tributo dentro de seus limites territoriais e sobre as situações previstas em lei. No Brasil, isso significa que a União cuida de tributos como IPI, IRPJ e COFINS, os estados e o Distrito Federal cuidam do ICMS, e os municípios cuidam do ISSQN. Uma mesma empresa pode, portanto, estar sob a jurisdição de três esferas ao mesmo tempo, cada uma com suas regras, cadastros e obrigações. ## Qual a diferença entre jurisdição tributária e competência tributária? Competência tributária é o poder, dado pela Constituição, para criar um tributo por meio de lei. Só o município pode instituir o ISSQN, por exemplo, e só os estados podem instituir o ICMS. Jurisdição tributária é um conceito mais amplo e mais prático: envolve onde e sobre quem esse poder é exercido, incluindo a fiscalização, a cobrança e o recebimento de documentos. Em linguagem do dia a dia, os dois termos costumam ser usados como sinônimos, mas a competência fala de criar o tributo, e a jurisdição fala de onde ele vale e quem o administra. ## Como a jurisdição tributária afeta a emissão de notas fiscais? Cada documento fiscal eletrônico é autorizado pelo órgão que tem jurisdição sobre aquela operação. A NF-e e a NFC-e, ligadas ao ICMS, são enviadas à Secretaria da Fazenda (SEFAZ) do estado do emitente. Já a NFS-e, ligada ao ISSQN, é tratada pelo município ou pelo padrão nacional, conforme a adesão de cada prefeitura. Por isso, um sistema emissor precisa saber em qual estado e município a empresa está inscrita, qual inscrição estadual ou municipal usar e quais regras locais se aplicam. Errar a jurisdição costuma resultar em rejeição do documento ou em imposto recolhido para o ente errado. ## Por que a jurisdição do ISSQN gera tantas dúvidas? Como cada município tem sua própria legislação de ISSQN, a mesma atividade pode ter alíquotas, regras de retenção e layouts de nota diferentes de cidade para cidade. Além disso, em regra o imposto é devido no município do estabelecimento do prestador, mas existem serviços em que ele é devido no local onde o serviço é executado. Saber qual município tem jurisdição sobre cada serviço é essencial para preencher corretamente o local de incidência na NFS-e. ## O que muda na jurisdição tributária com a reforma tributária? A reforma do consumo cria a CBS, de jurisdição federal, e o IBS, com gestão compartilhada entre estados e municípios. Um dos objetivos é reduzir conflitos sobre qual ente pode cobrar, adotando como regra a tributação no destino, ou seja, no local de consumo. Para quem emite documentos fiscais, isso se reflete em novos campos e grupos de tributação nos XMLs, que precisam indicar corretamente a localidade de destino e a parcela que cabe a cada ente. ## Exemplos de Jurisdição tributária - Uma loja virtual sediada em Minas Gerais emite NF-e para um cliente no Paraná: a nota é autorizada pela SEFAZ de Minas Gerais, mas a operação pode gerar DIFAL devido ao estado de destino. - Uma empresa de software com filiais em duas cidades precisa emitir NFS-e em cada município, respeitando a jurisdição e as regras de ISSQN de cada prefeitura. - Um ERP que atende vários CNPJs consulta o estado e o município de cada empresa antes de enviar o documento por API, garantindo que ele chegue ao órgão autorizador correto. - Uma prestadora de serviços de construção executa uma obra em outra cidade e precisa verificar se o ISSQN é devido no município da obra, e não no da sua sede. ## Perguntas frequentes ### Jurisdição tributária e domicílio tributário são a mesma coisa? Não. Domicílio tributário é o endereço que o contribuinte informa ao fisco para receber comunicações e cumprir obrigações. A jurisdição é a autoridade do ente público. O domicílio ajuda a definir sob qual jurisdição o contribuinte está. ### Uma empresa pode estar sob mais de uma jurisdição tributária? Sim. Toda empresa está sujeita a tributos federais, estaduais e municipais ao mesmo tempo, conforme suas atividades. Empresas com filiais em vários locais ainda ficam sob a jurisdição de diferentes estados e municípios. ### O que acontece se a nota for emitida para a jurisdição errada? O documento pode ser rejeitado pelo órgão autorizador ou, se autorizado, gerar recolhimento ao ente errado. Nesse caso, pode haver cobrança do imposto pelo ente correto, multas e necessidade de pedir restituição. ## Termos relacionados - [Fisco](https://conota.dev/glossario/fisco.md) - [ICMS](https://conota.dev/glossario/icms.md) - [ISSQN](https://conota.dev/glossario/issqn.md) - [DIFAL](https://conota.dev/glossario/difal.md) - [Inscrição municipal](https://conota.dev/glossario/inscricao-municipal.md) - [Fiscalização tributária](https://conota.dev/glossario/fiscalizacao-tributaria.md) --- Fonte: [Jurisdição tributária](https://conota.dev/glossario/jurisdicao-tributaria/) · Atualizado em 2026-10-22 --- # Jurisprudência tributária > Jurisprudência tributária é o conjunto de decisões reiteradas de tribunais judiciais e órgãos de julgamento administrativo sobre como as leis de tributos devem ser interpretadas e aplicadas. Ela orienta empresas, contadores e o próprio fisco em temas como incidência de impostos, base de cálculo, créditos e obrigações acessórias, influenciando inclusive a forma de emitir documentos fiscais. **Também conhecido como:** Jurisprudência fiscal, Entendimento dos tribunais em matéria tributária, Precedentes tributários, Tax case law **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** J ## O que é jurisprudência tributária? Jurisprudência é o entendimento que se forma quando tribunais decidem casos parecidos da mesma maneira, repetidas vezes. No campo tributário, ela mostra como os julgadores interpretam pontos da legislação que geram dúvida, como se um imposto incide sobre determinada operação ou se um valor deve entrar na base de cálculo. Ela não substitui a lei, mas ajuda a esclarecer o que a lei quer dizer na prática. Quando o texto legal é ambíguo, é a jurisprudência que costuma indicar o caminho mais seguro. ## Quem forma a jurisprudência tributária? Ela nasce em duas esferas. Na esfera judicial, participam juízes, tribunais regionais e estaduais e os tribunais superiores, cujas decisões têm maior peso e, em certos casos, efeito obrigatório para os demais juízes. Na esfera administrativa, há os órgãos de julgamento ligados ao fisco federal, estadual e municipal, que analisam recursos contra autuações. As decisões desses órgãos formam a chamada jurisprudência administrativa, assunto ligado ao julgamento administrativo tributário. ## Para que serve a jurisprudência tributária? Serve para trazer previsibilidade. Ao conhecer como os tribunais costumam decidir, a empresa consegue avaliar riscos, decidir se paga um tributo, se contesta uma cobrança ou se aproveita um crédito. Também orienta o planejamento tributário, a defesa em autuações e a atualização de regras fiscais nos sistemas de gestão, evitando cobranças indevidas ou recolhimentos a menor. ## Como a jurisprudência tributária afeta a emissão de notas fiscais? Quando um entendimento muda o que deve entrar na base de cálculo, qual alíquota se aplica ou se um tributo incide sobre um serviço, os dados informados na NF-e, NFS-e ou NFC-e podem precisar ser ajustados. Isso envolve campos como CST, base de cálculo e valores de impostos. Em empresas que emitem por API, essa mudança costuma ser feita no ERP ou na plataforma de vendas, que calcula os tributos e envia os dados ao emissor. A infraestrutura de emissão transmite o documento, mas a regra tributária adotada é definida pela empresa e por sua contabilidade. ## Qual a diferença entre jurisprudência, lei e doutrina? A lei é a norma criada pelo Poder Legislativo e é a base de toda cobrança de tributo. A jurisprudência é a interpretação dessa lei feita pelos julgadores em casos concretos. A doutrina é a opinião de estudiosos do direito, publicada em livros e artigos, que influencia, mas não decide casos. Na prática, uma empresa consulta a lei para saber a regra, a jurisprudência para saber como ela está sendo aplicada e a doutrina para entender os argumentos possíveis. ## Exemplos de Jurisprudência tributária - Uma distribuidora ajusta o cálculo de PIS e COFINS no seu ERP depois que o contador informa uma mudança de entendimento dos tribunais sobre o que compõe a base de cálculo dessas contribuições. - Um escritório de contabilidade cita decisões reiteradas de um conselho de recursos fiscais para defender um cliente autuado por aproveitamento de crédito de ICMS. - Uma empresa de software consulta a jurisprudência sobre a incidência de ISSQN em sua atividade antes de configurar o código de serviço usado na emissão de NFS-e. - Uma transportadora revisa a forma de destacar o ICMS no CT-e após orientação jurídica baseada em decisões recentes sobre operações interestaduais. ## Perguntas frequentes ### A jurisprudência tributária é obrigatória? Depende. Algumas decisões dos tribunais superiores, tomadas em ritos específicos, vinculam os demais juízes e a administração. Outras apenas orientam, servindo como indicação de como o tema tende a ser julgado. ### Uma decisão judicial muda automaticamente minha nota fiscal? Não. A empresa precisa revisar suas regras de cálculo e configurações no sistema emissor, normalmente com apoio contábil ou jurídico. Às vezes também são necessárias mudanças nas normas ou nos leiautes oficiais. ### Onde consultar a jurisprudência tributária? Nos sites oficiais dos tribunais judiciais e dos órgãos de julgamento administrativo, que oferecem ferramentas de pesquisa de decisões. Contadores e advogados tributaristas também acompanham e interpretam esses entendimentos. ## Termos relacionados - [Julgamento administrativo tributário](https://conota.dev/glossario/julgamento-administrativo-tributario.md) - [Fiscalização tributária](https://conota.dev/glossario/fiscalizacao-tributaria.md) - [Fisco](https://conota.dev/glossario/fisco.md) - [Hipótese de incidência tributária](https://conota.dev/glossario/hipotese-de-incidencia-tributaria.md) - [Base de cálculo](https://conota.dev/glossario/base-de-calculo.md) - [Jurisdição tributária](https://conota.dev/glossario/jurisdicao-tributaria.md) --- Fonte: [Jurisprudência tributária](https://conota.dev/glossario/jurisprudencia-tributaria/) · Atualizado em 2026-10-22 --- # Juros de mora tributária > Juros de mora tributária é o valor cobrado pelo Fisco quando um tributo é pago depois do vencimento. Ele compensa o governo pelo tempo em que ficou sem o dinheiro devido e é calculado sobre o imposto em atraso, desde o dia seguinte ao vencimento até a data do pagamento efetivo. **Também conhecido como:** Juros moratórios tributários, Juros de mora sobre tributos, Juros por atraso no pagamento de tributos, Tax late payment interest **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** J ## O que são juros de mora tributária? Mora significa atraso. Quando uma empresa ou pessoa deixa de pagar um tributo na data prevista, passa a estar em mora com o Fisco. Os juros de mora são o acréscimo cobrado por esse atraso, de forma parecida com os juros cobrados em um boleto vencido. Eles não têm caráter de punição. A ideia é remunerar o tempo em que o valor ficou indevidamente com o contribuinte, e não com o governo. Por isso, os juros incidem mesmo quando o atraso foi involuntário ou quando o contribuinte regulariza a situação por conta própria. ## Como os juros de mora são calculados? O cálculo depende do ente que cobra o tributo. Nos tributos federais, os juros seguem a taxa SELIC acumulada mensalmente a partir do mês seguinte ao vencimento, somada a 1% no mês do pagamento. O Código Tributário Nacional prevê juros de 1% ao mês quando a lei não fixar outra taxa. Estados e municípios podem ter regras próprias para tributos como ICMS e ISSQN, e muitos também adotam a SELIC ou índices semelhantes. Por isso, é preciso consultar a legislação de cada ente ou usar as ferramentas oficiais de cálculo de guias. ## Qual a diferença entre juros de mora e multa de mora? Os dois costumam aparecer juntos na guia de um tributo atrasado, mas têm funções diferentes. A multa de mora é uma penalidade pelo descumprimento do prazo. Os juros de mora são uma compensação financeira pelo tempo de atraso. Na esfera federal, por exemplo, a multa de mora é de 0,33% por dia de atraso, limitada a 20%, enquanto os juros continuam crescendo enquanto o débito não for pago. Ou seja, a multa tem teto, mas os juros não param de correr. ## Quando os juros de mora aparecem na rotina de quem emite notas fiscais? Os juros surgem sempre que o tributo destacado ou devido em uma operação é recolhido fora do prazo. Isso pode acontecer com o ICMS de uma NF-e, o ISSQN de uma NFS-e, o DIFAL pago por GNRE ou tributos retidos na fonte. Erros na emissão também podem gerar juros mais tarde. Uma nota com alíquota ou base de cálculo errada pode levar ao recolhimento a menor; quando o erro é identificado, na apuração ou em uma fiscalização, a diferença é cobrada com juros desde o vencimento original. Por isso, documentos emitidos com dados tributários corretos reduzem o risco de débitos acumulados. ## É possível evitar ou reduzir os juros de mora? A forma mais segura é pagar no prazo. Quando o atraso já ocorreu, quitar o débito o quanto antes limita o crescimento dos juros, já que eles aumentam com o tempo. A denúncia espontânea, que é a regularização feita pelo contribuinte antes de qualquer ação do Fisco, pode afastar a multa em determinadas situações, mas não elimina os juros. Programas de parcelamento ou de regularização criados por lei às vezes oferecem descontos sobre juros, conforme as regras de cada programa. ## Exemplos de Juros de mora tributária - Uma loja virtual apurou o ICMS do mês, mas pagou a guia com 15 dias de atraso. Além do imposto, o boleto gerado no sistema da SEFAZ incluiu multa de mora e juros de mora calculados conforme a regra estadual. - Um prestador de serviços emitiu NFS-e com alíquota de ISSQN menor que a devida. Meses depois, a prefeitura identificou a diferença e cobrou o valor faltante acrescido de juros de mora desde o vencimento original. - Uma empresa que vende para consumidores de outros estados esqueceu de recolher a GNRE do DIFAL em algumas operações e precisou pagar o imposto depois, com juros e multa. - Um ERP integrado ao emissor fiscal registra o vencimento de cada tributo apurado e alerta o financeiro antes do prazo, evitando cobrança de juros de mora. ## Perguntas frequentes ### Juros de mora tributária é a mesma coisa que multa? Não. A multa de mora é uma penalidade pelo atraso, geralmente com limite máximo. Os juros de mora compensam o tempo sem pagamento e continuam sendo cobrados enquanto o débito existir. ### Os juros de mora são cobrados mesmo em atraso de um dia? Em geral, sim, mas a forma de cálculo varia. Em tributos federais, por exemplo, no mês do pagamento incide 1%, então mesmo um atraso curto gera algum acréscimo de juros. ### Quem calcula os juros de mora? Normalmente, o próprio sistema do órgão arrecadador calcula juros e multa ao gerar a guia atualizada. O contribuinte ou seu contador também pode calcular, seguindo a legislação do ente que cobra o tributo. ### A denúncia espontânea elimina os juros de mora? Não. A regularização espontânea pode afastar a multa em certos casos, mas o tributo devido continua sendo cobrado com juros de mora. ## Termos relacionados - [Juros SELIC em débitos fiscais](https://conota.dev/glossario/juros-selic-em-debitos-fiscais.md) - [Apuração de tributos](https://conota.dev/glossario/apuracao-de-tributos.md) - [Fiscalização tributária](https://conota.dev/glossario/fiscalizacao-tributaria.md) - [Fato gerador](https://conota.dev/glossario/fato-gerador.md) - [Fisco](https://conota.dev/glossario/fisco.md) - [GNRE](https://conota.dev/glossario/gnre.md) --- Fonte: [Juros de mora tributária](https://conota.dev/glossario/juros-de-mora-tributaria/) · Atualizado em 2026-10-22 --- # Juros na cobrança de nota fiscal > Juros na cobrança de nota fiscal é o valor adicional cobrado do cliente quando o pagamento de uma venda ou serviço documentado em nota fiscal ocorre depois do vencimento combinado. Calculados sobre o valor em atraso e proporcionais ao tempo, costumam aparecer no boleto ou na fatura, e não alteram, em regra, a nota já autorizada. **Também conhecido como:** Juros de mora, Juros por atraso, Juros moratórios, Encargos por atraso de pagamento, Late payment interest **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** J ## O que são juros na cobrança de nota fiscal? Quando uma empresa vende um produto ou presta um serviço a prazo, ela emite a nota fiscal e combina com o cliente uma data de vencimento. Se o pagamento atrasa, a empresa pode cobrar um valor extra para compensar o tempo em que ficou sem receber. Esse valor extra são os juros, geralmente chamados de juros de mora. Os juros são calculados sobre o valor em aberto e crescem conforme os dias de atraso, normalmente com uma taxa diária ou mensal informada no boleto, no contrato ou nas condições comerciais da venda. ## Qual a diferença entre juros e multa por atraso? A multa é um valor cobrado uma única vez, assim que o prazo é descumprido, como uma penalidade fixa pelo atraso. Os juros, por outro lado, são proporcionais ao tempo: quanto mais dias se passam, maior o valor. Na prática, muitas cobranças combinam os dois: uma multa aplicada no primeiro dia após o vencimento e juros que se acumulam diariamente até a quitação. Os percentuais permitidos podem ter limites legais, especialmente em relações de consumo, por isso devem ser definidos com orientação jurídica ou contábil. ## Os juros por atraso entram no valor da nota fiscal? Em regra, não. A nota fiscal registra a operação de venda ou prestação de serviço no momento em que ela acontece. Os juros por atraso surgem depois, por causa do pagamento fora do prazo, e por isso costumam ser tratados como receita financeira, e não como parte do preço do produto ou serviço. Isso significa que, normalmente, não é preciso emitir uma nova nota nem corrigir a nota autorizada só porque o cliente pagou com atraso. Situação diferente é a de acréscimos financeiros já embutidos no preço de uma venda parcelada, que podem compor o valor da operação. Como o tratamento tributário depende do caso, a confirmação deve ser feita com o contador. ## Onde os juros aparecem na cobrança? Os juros costumam ser informados no instrumento de cobrança, como o boleto bancário, a fatura enviada ao cliente ou o link de pagamento. No boleto, por exemplo, é comum haver instruções como a taxa de juros ao dia e a multa após o vencimento, que o banco aplica automaticamente quando o pagamento é feito em atraso. Na NF-e, o grupo de fatura e duplicatas registra o valor original, os vencimentos e as parcelas combinadas, mas não serve para lançar juros calculados depois. Esse controle fica no sistema financeiro ou de cobrança da empresa. ## Como isso se relaciona com a emissão fiscal por API? Em empresas que usam um ERP ou plataforma própria integrada a um emissor fiscal, as responsabilidades costumam ser separadas. O emissor, como o Conota, cuida da emissão e autorização da nota, devolvendo XML, PDF e status. Já o cálculo de juros, multa e baixa de pagamento fica com o módulo financeiro, o banco ou a ferramenta de cobrança. Mesmo assim, a integração é útil para a cobrança: a chave de acesso, o número da nota e os dados de fatura ajudam a vincular cada boleto ao documento fiscal correspondente, facilitando a conciliação e a comprovação da dívida em caso de atraso. ## Exemplos de Juros na cobrança de nota fiscal - Uma distribuidora emite uma NF-e com vencimento em 30 dias. O cliente paga com 10 dias de atraso e o boleto já aplica multa e juros diários; a nota original permanece a mesma e o valor extra é lançado como receita financeira. - Uma empresa de software emite NFS-e mensal pela assinatura. Quando um cliente atrasa, o sistema de cobrança gera um novo boleto com juros, sem necessidade de emitir outra nota. - Um ERP integrado à API fiscal guarda a chave de acesso de cada NF-e junto às duplicatas, permitindo que a equipe financeira identifique quais notas estão vencidas e calcule os juros devidos. - Uma loja que vende parcelado com acréscimo já informado no momento da compra consulta o contador para saber se esse acréscimo deve compor o valor da operação na nota. ## Perguntas frequentes ### Preciso emitir nota fiscal dos juros cobrados por atraso? Em regra, não, porque juros por atraso são receita financeira e não venda de produto ou serviço. Porém, o tratamento pode variar conforme a operação e o município, então vale confirmar com o contador. ### Posso cancelar a nota e emitir outra com o valor dos juros? Não é o procedimento adequado. A nota registra a operação original. Os juros devem ser cobrados no boleto ou fatura e controlados no financeiro, sem alterar o documento fiscal autorizado. ### Quem define a taxa de juros cobrada? A própria empresa, nas condições comerciais ou no contrato, respeitando limites legais aplicáveis. A taxa costuma ser informada no boleto para que o banco calcule automaticamente o valor no pagamento. ### O emissor fiscal calcula os juros da cobrança? Normalmente não. O emissor cuida da emissão e autorização da nota. O cálculo de juros e multa fica com o sistema financeiro, o ERP ou o banco responsável pela cobrança. ## Termos relacionados - [Fatura na NF-e](https://conota.dev/glossario/fatura-na-nf-e.md) - [Quitação de cobrança vinculada à nota fiscal](https://conota.dev/glossario/quitacao-de-cobranca-vinculada-a-nota-fiscal.md) - [Base de cálculo](https://conota.dev/glossario/base-de-calculo.md) - [Totalização da NF-e](https://conota.dev/glossario/totalizacao-da-nf-e.md) - [ERP integrado ao emissor fiscal](https://conota.dev/glossario/erp-integrado-ao-emissor-fiscal.md) - [NF-e](https://conota.dev/glossario/nf-e.md) --- Fonte: [Juros na cobrança de nota fiscal](https://conota.dev/glossario/juros-na-cobranca-de-nota-fiscal/) · Atualizado em 2026-10-22 --- # Juros SELIC em débitos fiscais > Juros SELIC em débitos fiscais são os juros cobrados sobre tributos pagos depois do vencimento, calculados com base na taxa SELIC, a taxa básica de juros da economia brasileira. Eles compensam o Fisco pelo tempo de atraso, somam-se à multa de mora e são aplicados principalmente a tributos federais, além de vários tributos estaduais e municipais. **Também conhecido como:** Juros de mora pela SELIC, Atualização pela SELIC, Juros SELIC sobre tributos em atraso, Acréscimos moratórios pela SELIC, SELIC, SELIC interest on tax debts **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** J ## O que é a taxa SELIC e por que ela é usada em débitos fiscais? A SELIC é a taxa básica de juros do Brasil, definida periodicamente pelo Banco Central. Ela serve de referência para empréstimos, investimentos e também para a cobrança de impostos atrasados. Quando uma empresa deixa de pagar um tributo no prazo, o governo fica sem um dinheiro que já deveria ter recebido. Os juros SELIC funcionam como uma compensação por esse atraso, de forma parecida com os juros de um boleto pago depois do vencimento. Como a SELIC acompanha o custo do dinheiro no país, ela é usada para que o valor devido não perca expressão com o tempo. ## Como os juros SELIC são calculados em um tributo atrasado? Nos tributos federais, a regra geral é somar as taxas SELIC mensais desde o mês seguinte ao vencimento até o mês anterior ao pagamento. No mês em que o pagamento é feito, acrescenta-se 1%. A soma é simples, ou seja, não há juros sobre juros. Na prática, quanto mais meses se passam, maior fica o percentual acumulado. Um tributo pago poucos dias após o vencimento, ainda dentro do mesmo mês, costuma ter juros baixos, enquanto um débito antigo pode acumular um acréscimo significativo. Os sistemas oficiais de emissão de guias, como os da Receita Federal e das secretarias de fazenda, normalmente já fazem esse cálculo automaticamente. ## Qual a diferença entre juros SELIC e multa de mora? A multa de mora é uma penalidade pelo simples fato de ter atrasado. Nos tributos federais, ela é calculada por dia de atraso e tem um limite máximo. Já os juros SELIC remuneram o tempo em que o dinheiro ficou com o contribuinte e não têm teto: continuam crescendo enquanto o débito não for quitado. Por isso, um tributo atrasado geralmente é pago com três parcelas: o valor original, a multa de mora e os juros. Se o débito for identificado em uma fiscalização, pode haver ainda multa de ofício, que é mais pesada do que a multa de mora. ## A SELIC também vale para tributos estaduais e municipais? Depende de cada ente. A SELIC é a regra nos tributos federais, como IRPJ, CSLL, PIS e COFINS. Muitos estados adotam a SELIC para o ICMS, mas alguns usam índices ou percentuais próprios. Nos municípios, que cobram o ISSQN, as regras variam bastante conforme a legislação local. Por isso, ao calcular um débito de ICMS ou ISSQN em atraso, o correto é consultar a legislação ou o sistema de emissão de guias do estado ou do município responsável pela cobrança. ## Como a emissão de notas fiscais pode gerar débitos com juros SELIC? A nota fiscal registra o fato gerador de vários tributos. Se uma empresa emite notas corretamente, mas atrasa a apuração ou o pagamento do imposto destacado nelas, o débito passa a sofrer juros e multa. Também é comum o débito surgir de erros na emissão: alíquota errada, CST ou CFOP incorretos, DIFAL não recolhido em vendas interestaduais ou ISSQN retido que não foi repassado. Quando o erro é descoberto meses depois, o tributo que faltou precisa ser pago com juros SELIC contados desde o vencimento original. Por isso, dados fiscais corretos na hora da emissão ajudam a evitar acréscimos futuros. ## Os juros SELIC também beneficiam o contribuinte? Sim. Na esfera federal, quando a empresa paga um tributo a mais ou indevidamente, o valor a restituir ou a compensar costuma ser atualizado pela SELIC. Assim, a mesma lógica que aumenta o débito em atraso também corrige o crédito que o contribuinte tem a receber. ## Exemplos de Juros SELIC em débitos fiscais - Uma empresa do lucro presumido esqueceu de pagar a COFINS de um mês e só quitou o valor quatro meses depois. A guia gerada no sistema da Receita Federal incluiu o valor original, a multa de mora e os juros SELIC acumulados no período. - Um e-commerce vendeu para consumidores de outros estados sem recolher o DIFAL. Ao regularizar a situação, precisou emitir guias GNRE com o imposto devido acrescido de juros, calculados conforme a regra de cada estado de destino. - Um prestador de serviços descobriu que emitiu NFS-e com alíquota de ISSQN menor do que a correta. Ao recolher a diferença, o município cobrou o valor complementar com os acréscimos previstos em sua legislação. - Após revisar a apuração, uma indústria identificou que pagou PIS a mais em um período anterior e pediu a compensação do valor, que foi atualizado pela SELIC. ## Perguntas frequentes ### Juros SELIC e juros de mora são a mesma coisa? Nos tributos federais, sim na prática: os juros de mora são calculados com base na taxa SELIC. Juros de mora é o nome genérico para juros por atraso; a SELIC é o índice usado para calculá-los. ### Os juros SELIC em débitos fiscais são compostos? Não, na regra federal. As taxas mensais são somadas de forma simples, sem juros sobre juros, e acrescenta-se 1% no mês do pagamento. ### Pagar no mesmo mês do vencimento gera juros SELIC? Nos tributos federais, o pagamento atrasado feito dentro do mesmo mês do vencimento costuma ter apenas 1% de juros, além da multa de mora proporcional aos dias de atraso. ### Corrigir uma nota fiscal elimina os juros de um imposto pago a menor? Não. Corrigir o documento ajusta a informação, mas a diferença de imposto continua devida desde o vencimento original e deve ser paga com os acréscimos legais. ## Termos relacionados - [Juros de mora tributária](https://conota.dev/glossario/juros-de-mora-tributaria.md) - [Apuração de tributos](https://conota.dev/glossario/apuracao-de-tributos.md) - [Fisco](https://conota.dev/glossario/fisco.md) - [Fiscalização tributária](https://conota.dev/glossario/fiscalizacao-tributaria.md) - [GNRE](https://conota.dev/glossario/gnre.md) - [Fato gerador](https://conota.dev/glossario/fato-gerador.md) --- Fonte: [Juros SELIC em débitos fiscais](https://conota.dev/glossario/juros-selic-em-debitos-fiscais/) · Atualizado em 2026-10-22 --- # Justificativa de cancelamento fiscal > Justificativa de cancelamento fiscal é o texto obrigatório que o emitente informa ao pedir o cancelamento de um documento fiscal eletrônico, como NF-e, NFC-e, CT-e ou MDF-e, explicando por que a operação não ocorreu ou não deve valer. Ela integra o evento de cancelamento enviado ao Fisco e fica registrada permanentemente. **Também conhecido como:** Motivo de cancelamento, Justificativa do cancelamento da NF-e, Justificativa do evento de cancelamento, Fiscal document cancellation justification **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** J ## O que é a justificativa de cancelamento fiscal? Quando uma empresa emite uma nota fiscal eletrônica e depois percebe que ela não deveria existir, por exemplo porque a venda foi desfeita antes da entrega, pode pedir o cancelamento ao Fisco. Esse pedido não é um simples clique: ele é enviado como um evento fiscal, e um dos campos obrigatórios desse evento é a justificativa. A justificativa é um texto curto, escrito pelo emitente, que explica o motivo do cancelamento. Ela é assinada digitalmente junto com o restante do evento e passa a fazer parte do histórico do documento, podendo ser consultada depois pela fiscalização. ## Para que serve a justificativa? A principal função é dar transparência e rastreabilidade. O cancelamento apaga os efeitos fiscais de uma operação, então o Fisco exige que o emitente declare por que fez isso. Em uma fiscalização, cancelamentos frequentes ou com motivos vagos podem chamar atenção. Ela também ajuda a própria empresa: a equipe contábil e o setor financeiro conseguem entender, meses depois, por que determinada nota foi anulada, sem depender da memória de quem fez o pedido. ## Quais regras a justificativa precisa seguir? Nos leiautes nacionais da NF-e, NFC-e, CT-e e MDF-e, a justificativa precisa ter no mínimo 15 e no máximo 255 caracteres. Textos menores são rejeitados automaticamente pela SEFAZ, e o cancelamento não é registrado. Também é recomendável evitar quebras de linha, caracteres especiais incomuns e espaços extras no início ou no fim, pois eles podem causar erro de validação do XML. Na NFS-e, as regras variam conforme o padrão adotado: no padrão nacional há um código de motivo e uma descrição, enquanto alguns municípios usam regras próprias. Além do texto, o cancelamento depende de outras condições, como estar dentro do prazo permitido e de a mercadoria ainda não ter circulado. Uma justificativa bem escrita não supera essas restrições. ## Como a justificativa funciona em uma emissão por API? Em sistemas que emitem documentos por API, o ERP ou a plataforma de vendas envia uma requisição de cancelamento informando qual documento deve ser cancelado e o texto da justificativa. A API monta o evento, assina o XML com o certificado digital da empresa e o transmite ao Fisco. A resposta indica se o cancelamento foi homologado ou rejeitado. Por isso, é útil que o sistema valide o tamanho do texto antes de enviar e ofereça ao usuário motivos pré-definidos, evitando rejeições por justificativas curtas como apenas "erro". ## Qual a diferença entre justificativa de cancelamento e de inutilização? A justificativa de cancelamento se aplica a um documento que já foi autorizado pelo Fisco e que precisa perder a validade. A justificativa de inutilização se aplica a números da sequência que nunca chegaram a gerar um documento autorizado, como quando o sistema pulou uma numeração. As duas têm formato parecido e exigem um texto explicativo, mas tratam de situações diferentes: uma anula uma nota existente, a outra declara que certos números não serão usados. ## Exemplos de Justificativa de cancelamento fiscal - Uma loja virtual emite a NF-e de um pedido, mas o cliente desiste da compra antes do despacho. O ERP envia o cancelamento com a justificativa "Pedido cancelado pelo cliente antes do envio da mercadoria". - Um supermercado emite uma NFC-e com o CPF errado e o consumidor pede uma nova nota. O sistema do caixa cancela a primeira com o texto "Emissao com dados incorretos do consumidor, nova nota emitida". - Uma transportadora emite um CT-e para uma carga que acabou não sendo coletada e cancela o documento com a justificativa "Servico de transporte nao realizado, carga nao coletada". - Um marketplace tenta cancelar uma nota com a justificativa "erro" e recebe rejeição da SEFAZ por texto abaixo do mínimo de caracteres, precisando reenviar com uma explicação mais completa. ## Perguntas frequentes ### Quantos caracteres a justificativa de cancelamento precisa ter? Na NF-e, NFC-e, CT-e e MDF-e, a justificativa deve ter entre 15 e 255 caracteres. Na NFS-e, as regras dependem do padrão utilizado, nacional ou municipal. ### Posso alterar a justificativa depois que o cancelamento foi homologado? Não. Depois de homologado, o evento de cancelamento fica registrado de forma definitiva junto ao documento. Não existe correção posterior da justificativa. ### Qualquer motivo é aceito como justificativa? O Fisco valida automaticamente apenas o formato, como o tamanho do texto. Porém, o motivo deve ser verdadeiro e coerente, pois pode ser analisado em uma fiscalização posterior. ### A justificativa substitui a Carta de Correção? Não. A Carta de Correção Eletrônica corrige informações permitidas sem anular a nota. A justificativa de cancelamento acompanha o pedido para anular o documento por completo. ## Termos relacionados - [Cancelamento de documento fiscal](https://conota.dev/glossario/cancelamento-de-documento-fiscal.md) - [Evento fiscal](https://conota.dev/glossario/evento-fiscal.md) - [Justificativa de inutilização fiscal](https://conota.dev/glossario/justificativa-de-inutilizacao-fiscal.md) - [Carta de Correção Eletrônica](https://conota.dev/glossario/carta-de-correcao-eletronica.md) - [Erro de validação fiscal](https://conota.dev/glossario/erro-de-validacao-fiscal.md) - [Histórico de eventos fiscais](https://conota.dev/glossario/historico-de-eventos-fiscais.md) --- Fonte: [Justificativa de cancelamento fiscal](https://conota.dev/glossario/justificativa-de-cancelamento-fiscal/) · Atualizado em 2026-10-22 --- # Justificativa de inutilização fiscal > Justificativa de inutilização fiscal é o texto obrigatório que o emissor envia à SEFAZ para explicar por que uma faixa de números de documentos fiscais eletrônicos, como NF-e, NFC-e ou CT-e, não foi usada e precisa ser invalidada. Ela fica registrada no pedido de inutilização e pode ser consultada pelo fisco em fiscalizações. **Também conhecido como:** Justificativa de inutilização, Motivo da inutilização, Justificativa de inutilização de numeração, xJust da inutilização **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** J ## O que é a justificativa de inutilização fiscal? Quando uma empresa pula números na sequência das suas notas fiscais eletrônicas, ela precisa avisar a Secretaria da Fazenda (SEFAZ) que esses números nunca serão usados. Esse aviso se chama inutilização de numeração, e a justificativa é o campo de texto em que a empresa explica o motivo do salto. Sem a justificativa, o pedido de inutilização não é aceito. Ela funciona como uma declaração formal do emissor: em poucas palavras, diz o que aconteceu para que aqueles números ficassem sem uso. ## Para que serve a justificativa de inutilização? A numeração dos documentos fiscais deve ser sequencial. Um buraco na sequência pode levantar suspeita de nota emitida e escondida. A justificativa mostra ao fisco que o salto foi um erro ou falha operacional, e não uma tentativa de omitir vendas. Ela também cria um histórico. Em uma fiscalização ou auditoria, a empresa e o contador conseguem consultar por que cada faixa foi inutilizada, sem depender da memória de quem fez o pedido. ## Quais são as regras para escrever a justificativa? Nos leiautes da NF-e e da NFC-e, a justificativa deve ter no mínimo 15 e no máximo 255 caracteres. Textos menores que o mínimo são rejeitados automaticamente pela SEFAZ. Por segurança, é comum evitar caracteres especiais e quebras de linha, que podem causar erro de validação no XML. O texto deve ser claro e verdadeiro. Frases genéricas como "erro" ou repetições de letras até completar o mínimo são tecnicamente aceitas pelo sistema, mas não ajudam a explicar o ocorrido em uma eventual fiscalização. ## Em quais documentos fiscais existe inutilização? A inutilização com justificativa existe para documentos de numeração controlada pela SEFAZ, principalmente NF-e, NFC-e e CT-e. Cada pedido informa o modelo do documento, a série, o número inicial e o número final da faixa, além da justificativa. O MDF-e não possui esse serviço, e a NFS-e, em geral, segue regras próprias do município ou do padrão nacional, sem um equivalente direto à inutilização estadual. Por isso, vale verificar as regras de cada documento antes de automatizar o processo. ## Qual a diferença entre justificativa de inutilização e de cancelamento? A justificativa de cancelamento explica por que um documento que já foi autorizado pela SEFAZ deixou de valer, por exemplo, porque a venda foi desfeita. A justificativa de inutilização explica por que números que nunca chegaram a ser autorizados não serão usados. Em resumo: cancela-se o que existe; inutiliza-se o que nunca existiu. Ambas exigem um texto explicativo, mas são enviadas por serviços diferentes e se referem a situações distintas. ## Como a justificativa é enviada em uma integração por API? Em sistemas que emitem notas por API fiscal, o ERP ou a plataforma de vendas envia uma requisição de inutilização com CNPJ, modelo, série, faixa de números e o texto da justificativa. A API monta o XML, assina com o certificado digital e transmite à SEFAZ. A resposta indica se a inutilização foi homologada ou rejeitada. Uma boa prática é o sistema já sugerir textos padronizados para cada tipo de falha, garantindo o tamanho mínimo e evitando rejeições, e guardar o XML de retorno junto com o histórico da empresa. ## Exemplos de Justificativa de inutilização fiscal - Um e-commerce teve uma falha de comunicação e o ERP reservou os números 1520 a 1525 da série 1 da NF-e sem transmiti-los. O sistema envia a inutilização com a justificativa: "Falha de comunicacao no sistema gerou salto na numeracao". - Uma loja que emite NFC-e configurou por engano o número seguinte como 3000 em vez de 2001. Ela inutiliza a faixa 2001 a 2999 com a justificativa: "Erro de parametrizacao do numero inicial no sistema emissor". - Uma transportadora teve um CT-e rejeitado por erro nos dados e decidiu não reaproveitar o número. Ela envia a inutilização daquele número com a justificativa: "Documento rejeitado pela SEFAZ e numero nao sera reutilizado". - Uma plataforma integrada por API recebe a rejeição de um pedido de inutilização porque o usuário digitou apenas "erro". O sistema passa a exigir textos com pelo menos 15 caracteres antes de enviar. ## Perguntas frequentes ### Qual o tamanho mínimo da justificativa de inutilização? Na NF-e e na NFC-e, a justificativa precisa ter entre 15 e 255 caracteres. Textos menores são rejeitados automaticamente pela SEFAZ. ### Posso inutilizar um número que já foi autorizado? Não. Se o documento foi autorizado, o caminho é o cancelamento, com sua própria justificativa. A inutilização vale apenas para números que nunca foram autorizados. ### Depois de inutilizado, o número pode ser usado de novo? Não. Uma vez homologada a inutilização, aquela faixa de números fica definitivamente invalidada para o CNPJ, modelo e série informados. ### É possível desfazer uma inutilização com justificativa errada? Não existe evento para desfazer ou corrigir a inutilização. Por isso, é importante revisar a faixa de números e o texto da justificativa antes do envio. ## Termos relacionados - [Inutilização de numeração](https://conota.dev/glossario/inutilizacao-de-numeracao.md) - [Justificativa de cancelamento fiscal](https://conota.dev/glossario/justificativa-de-cancelamento-fiscal.md) - [Cancelamento de documento fiscal](https://conota.dev/glossario/cancelamento-de-documento-fiscal.md) - [Erro de validação fiscal](https://conota.dev/glossario/erro-de-validacao-fiscal.md) - [Histórico de eventos fiscais](https://conota.dev/glossario/historico-de-eventos-fiscais.md) - [Emissão fiscal por API](https://conota.dev/glossario/emissao-fiscal-por-api.md) --- Fonte: [Justificativa de inutilização fiscal](https://conota.dev/glossario/justificativa-de-inutilizacao-fiscal/) · Atualizado em 2026-10-22 --- # JWE > JWE (JSON Web Encryption) é um padrão aberto para criptografar dados em formato JSON e transportá-los com segurança entre sistemas. Ele embala uma informação de modo que apenas quem possui a chave correta consiga lê-la, garantindo confidencialidade. É muito usado para proteger tokens e dados sensíveis trafegados por APIs. **Também conhecido como:** JSON Web Encryption, Token JWE, JWT criptografado, Criptografia Web JSON, JWE **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** J ## O que é JWE, explicado de forma simples? Pense no JWE como um envelope lacrado e opaco. Quem intercepta o envelope vê que ele existe, mas não consegue ler o que está dentro. Só o destinatário, que tem a chave certa, abre o envelope e lê a mensagem. Tecnicamente, o JWE é uma especificação publicada pela IETF, a mesma organização que padroniza vários protocolos da internet. Ele faz parte de uma família de padrões chamada JOSE (JSON Object Signing and Encryption), que também inclui o JWS (assinatura) e o JWT (tokens). ## Como funciona um JWE? Na forma mais comum, chamada serialização compacta, um JWE é um texto com cinco partes separadas por pontos: o cabeçalho, a chave de conteúdo criptografada, o vetor de inicialização, o texto cifrado (os dados protegidos) e uma etiqueta de autenticação, que permite detectar se algo foi alterado no caminho. O cabeçalho informa dois algoritmos. O campo alg indica como a chave que protege o conteúdo foi tratada, por exemplo com RSA-OAEP ou com uma chave simétrica compartilhada. O campo enc indica como o conteúdo em si foi cifrado, por exemplo com AES-GCM. Esse modelo é chamado de criptografia híbrida: uma chave aleatória e rápida cifra os dados, e essa chave, por sua vez, é protegida com a chave do destinatário. Assim se combina desempenho com segurança. ## Qual a diferença entre JWE, JWS e JWT? O JWS assina os dados: garante quem os emitiu e que não foram alterados, mas o conteúdo continua legível por qualquer pessoa, bastando decodificar o Base64. O JWE criptografa os dados: o foco é esconder o conteúdo de quem não tem a chave. O JWT é um formato de token que carrega informações, como identificador do usuário e prazo de validade. Um JWT pode ser construído como JWS (assinado) ou como JWE (criptografado). Quando é preciso as duas garantias, é comum assinar primeiro e depois criptografar o resultado, o chamado JWT aninhado. ## Para que serve o JWE em integrações fiscais? Em integrações com APIs fiscais circulam dados delicados: identificação de empresas emissoras, informações de clientes, tokens de acesso e até senhas de certificados digitais. O JWE é uma opção para proteger esses dados quando eles precisam passar por sistemas intermediários, ficar armazenados temporariamente ou ser lidos apenas por um serviço específico. Um exemplo típico é um token de acesso que carrega informações internas, como o identificador do tenant ou permissões. Se o token for criptografado com JWE, o sistema cliente consegue usá-lo normalmente, mas não consegue ler nem expor o que há dentro dele. ## JWE substitui o HTTPS? Não. O HTTPS, que usa TLS, protege a conexão entre dois pontos enquanto os dados estão em trânsito. Quando a mensagem chega ao destino, ou passa por um proxy, fila ou log, ela deixa de estar protegida pelo TLS. O JWE protege a própria mensagem, independentemente do canal. Por isso os dois são complementares: o HTTPS continua obrigatório em qualquer API fiscal, e o JWE acrescenta uma camada extra quando o conteúdo precisa permanecer confidencial além da conexão. ## Quais cuidados são importantes ao usar JWE? O ponto mais crítico é a gestão de chaves. De nada adianta criptografar se a chave privada fica exposta no código-fonte ou em variáveis mal protegidas. O recomendado é guardá-la em um cofre de segredos ou serviço de gerenciamento de chaves e fazer rotação periódica. Também é importante usar bibliotecas consolidadas em vez de implementar a criptografia manualmente, aceitar apenas algoritmos previamente definidos pelo servidor e validar prazo de expiração e emissor do conteúdo após descriptografar. ## Exemplos de JWE - Um ERP recebe da API fiscal um token de acesso no formato JWE. O ERP apenas o envia no header de autenticação das próximas requisições, sem conseguir ler as permissões e dados de tenant que estão dentro dele. - Uma plataforma de vendas precisa repassar a senha de um certificado digital A1 a um serviço interno de emissão. Em vez de enviá-la em texto puro no payload, a senha é empacotada em um JWE que só o serviço de emissão consegue abrir. - Um marketplace gera links temporários para o lojista baixar XML e PDF de notas. O parâmetro do link é um JWE com o identificador do documento e a data de expiração, impedindo que alguém descubra ou altere esses dados. - Um time de desenvolvimento usa JWT aninhado: o token é assinado com JWS para garantir a origem e depois criptografado com JWE para ocultar o conteúdo. ## Perguntas frequentes ### Dá para ler o conteúdo de um JWE decodificando o Base64? Não. Ao contrário do JWS, a parte de conteúdo do JWE está cifrada. Decodificar o Base64 só revela bytes ilegíveis. Apenas o cabeçalho, que indica os algoritmos usados, pode ser lido sem a chave. ### Todo JWT é um JWE? Não. A maioria dos JWT usados em APIs é do tipo JWS, ou seja, apenas assinada. Um JWT só é JWE quando seu conteúdo é criptografado, o que se reconhece pelas cinco partes separadas por pontos, em vez de três. ### JWE garante quem enviou a mensagem? Não necessariamente. O JWE garante confidencialidade e detecta alterações, mas, dependendo do algoritmo, qualquer pessoa com a chave pública do destinatário pode criar um JWE. Para comprovar a origem, combine com assinatura JWS. ### Preciso usar JWE para integrar com uma API fiscal? Depende da API. Muitas integrações funcionam apenas com HTTPS e um token Bearer ou API Key. O JWE é usado quando a documentação exige ou quando há dados sensíveis que precisam permanecer protegidos além da conexão. ## Termos relacionados - [JWS](https://conota.dev/glossario/jws.md) - [JWT](https://conota.dev/glossario/jwt.md) - [TLS](https://conota.dev/glossario/tls.md) - [Token de autenticação](https://conota.dev/glossario/token-de-autenticacao.md) - [Gerenciamento de segredos](https://conota.dev/glossario/gerenciamento-de-segredos.md) - [Key management service](https://conota.dev/glossario/key-management-service.md) --- Fonte: [JWE](https://conota.dev/glossario/jwe/) · Atualizado em 2026-10-22 --- # JWS > JWS (JSON Web Signature) é um padrão aberto para assinar digitalmente dados em formato JSON, garantindo que eles vieram de quem diz tê-los enviado e que não foram alterados no caminho. É muito usado em APIs para proteger tokens, como o JWT, e mensagens trocadas entre sistemas, sem esconder o conteúdo. **Também conhecido como:** JSON Web Signature, Assinatura JWS, Token JWS, JWS **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** J ## O que é JWS, em palavras simples? Pense no JWS como um lacre de segurança colado em uma mensagem. Qualquer pessoa consegue ler o que está escrito, mas, se alguém mexer no conteúdo, o lacre deixa de bater e o destinatário percebe a adulteração na hora. Na prática, o JWS é uma forma padronizada de juntar três coisas: informações sobre como a assinatura foi feita, o conteúdo da mensagem e a própria assinatura. Por ser um padrão aberto, sistemas diferentes, escritos em linguagens diferentes, conseguem gerar e conferir essas assinaturas da mesma maneira. ## Como funciona um JWS? Um JWS no formato mais comum, chamado de serialização compacta, é um texto dividido em três partes separadas por pontos. A primeira é o cabeçalho, que informa o algoritmo usado. A segunda é o payload, ou seja, o conteúdo protegido. A terceira é a assinatura, calculada a partir das duas primeiras e de uma chave. As duas primeiras partes são codificadas em Base64URL, um formato que transforma os dados em texto seguro para trafegar em URLs e cabeçalhos HTTP. Isso não é criptografia: basta decodificar para ler o conteúdo. Quem recebe o JWS recalcula a assinatura com a chave adequada e compara com a que veio na mensagem. Se forem iguais, o conteúdo é íntegro e autêntico. ## Quais tipos de chave e algoritmo o JWS usa? Existem dois grandes grupos. No primeiro, chamado simétrico, quem assina e quem verifica usam o mesmo segredo compartilhado, como nos algoritmos da família HS256, baseados em HMAC. É simples, mas exige que as duas pontas guardem o segredo com cuidado. No segundo, chamado assimétrico, usa-se um par de chaves: a chave privada assina e a chave pública verifica, como nos algoritmos RS256 e ES256. Assim, qualquer um pode conferir a assinatura sem ter poder para criar assinaturas falsas, o que é útil quando muitos sistemas precisam validar mensagens de um mesmo emissor. ## Qual a diferença entre JWS, JWT e JWE? JWT (JSON Web Token) é um formato de token com informações, chamadas de claims, como quem é o usuário e até quando o token vale. Na maioria das vezes, um JWT é transportado como um JWS, ou seja, é um token assinado. Por isso os dois termos costumam aparecer juntos. JWE (JSON Web Encryption) tem outro objetivo: criptografar o conteúdo para que só o destinatário consiga lê-lo. Resumindo, o JWS protege contra alteração e comprova a origem, enquanto o JWE protege contra leitura indevida. Os dois podem ser combinados quando se precisa das duas garantias. ## Para que serve o JWS em integrações fiscais? Em APIs fiscais, o JWS aparece principalmente na camada de segurança da comunicação entre sistemas. Ele pode proteger tokens de autenticação usados para acessar a API, garantindo que as permissões contidas no token não foram alteradas, e também pode assinar notificações enviadas por webhook, permitindo que o ERP confirme que a mensagem sobre a autorização ou rejeição de um documento veio mesmo do emissor. É importante não confundir com a assinatura dos documentos fiscais em si. NF-e, NFC-e, CT-e, MDF-e e muitos modelos de NFS-e são assinados em XML, com certificado digital ICP-Brasil, seguindo regras próprias dos órgãos autorizadores. O JWS protege a conversa entre sistemas; a assinatura do XML dá validade jurídica ao documento. ## Quais cuidados tomar ao usar JWS? Nunca coloque dados sensíveis no payload achando que estão escondidos, pois qualquer pessoa pode decodificá-lo. Sempre valide a assinatura antes de confiar no conteúdo, defina quais algoritmos são aceitos e rejeite tokens com algoritmo inesperado ou sem assinatura. Guarde as chaves em local seguro, como um cofre de segredos, e faça a rotação delas periodicamente. Também vale conferir campos como data de expiração e emissor, quando existirem, para evitar que uma mensagem antiga e válida seja reaproveitada indevidamente. ## Exemplos de JWS - Um ERP recebe um token de acesso no formato JWT assinado com RS256 e, antes de liberar a consulta de notas fiscais, verifica a assinatura usando a chave pública do provedor de autenticação. - Uma plataforma de emissão envia um webhook informando que uma NF-e foi autorizada, com o corpo da mensagem assinado em JWS; o sistema do cliente valida a assinatura e só então atualiza o status do pedido. - Um marketplace usa JWS com HS256 para assinar mensagens internas entre seu backend de vendas e seu serviço de integração fiscal, impedindo que alguém altere valores ou CNPJs no meio do caminho. - Um desenvolvedor depura um problema de autenticação decodificando as duas primeiras partes de um JWS e percebe que o token já estava expirado quando foi enviado à API. ## Perguntas frequentes ### JWS criptografa os dados? Não. O JWS apenas assina. O conteúdo fica codificado em Base64URL, que qualquer pessoa pode decodificar e ler. Para esconder o conteúdo, é preciso usar criptografia, como o JWE, ou garantir que a comunicação ocorra por HTTPS. ### Todo JWT é um JWS? Não necessariamente, mas na maioria dos casos sim. Um JWT pode ser transportado como JWS (assinado) ou como JWE (criptografado). Os tokens de autenticação usados em APIs costumam ser JWTs assinados, ou seja, no formato JWS. ### Posso usar JWS para assinar uma NF-e? Não. A NF-e e os demais documentos fiscais eletrônicos exigem assinatura digital do XML com certificado ICP-Brasil, conforme o leiaute oficial. O JWS serve para proteger tokens e mensagens entre sistemas, não para dar validade fiscal ao documento. ### O que acontece se o conteúdo de um JWS for alterado? A assinatura deixa de corresponder ao conteúdo. Quando o destinatário recalcula a verificação, o resultado não confere e a mensagem deve ser rejeitada, indicando adulteração ou erro na transmissão. ## Termos relacionados - [JWT](https://conota.dev/glossario/jwt.md) - [JWE](https://conota.dev/glossario/jwe.md) - [HMAC em webhooks](https://conota.dev/glossario/hmac-em-webhooks.md) - [Key pair na assinatura digital](https://conota.dev/glossario/key-pair-na-assinatura-digital.md) - [Token de autenticação](https://conota.dev/glossario/token-de-autenticacao.md) - [Assinatura digital do XML](https://conota.dev/glossario/assinatura-digital-do-xml.md) --- Fonte: [JWS](https://conota.dev/glossario/jws/) · Atualizado em 2026-10-22 --- # JWT > JWT (JSON Web Token) é um formato padronizado de token usado para transmitir informações de forma compacta e verificável entre sistemas. Ele é composto por três partes codificadas, cabeçalho, conteúdo e assinatura, e costuma ser usado para autenticar requisições a APIs, comprovando quem está acessando e o que tem permissão para fazer. **Também conhecido como:** JSON Web Token, Token JWT, JWT **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** J ## Para que serve o JWT? O JWT serve principalmente para provar identidade e permissões em comunicações entre sistemas. Em vez de enviar usuário e senha a cada requisição, o sistema recebe um token assinado e o apresenta sempre que precisa acessar um recurso protegido. Em integrações com APIs fiscais, por exemplo, um ERP ou uma plataforma de vendas pode usar um JWT para mostrar à API que está autorizado a emitir uma NF-e, consultar o status de uma NFS-e ou baixar o XML de um documento. O servidor confere o token e decide se libera ou bloqueia a operação. ## Como funciona um JWT? Um JWT é uma sequência de texto dividida em três partes separadas por pontos. A primeira é o cabeçalho, que indica o tipo do token e o algoritmo de assinatura. A segunda é o conteúdo, chamado de payload, que traz informações conhecidas como claims, por exemplo quem emitiu o token, para quem ele foi emitido e quando expira. A terceira é a assinatura. Cabeçalho e conteúdo são escritos em formato JSON e depois codificados em Base64URL, um tipo de codificação que transforma os dados em texto seguro para trafegar na internet. A assinatura é calculada a partir dessas duas partes com uma chave secreta ou um par de chaves. Se alguém alterar qualquer letra do conteúdo, a assinatura deixa de bater e o servidor rejeita o token. Algumas claims comuns são exp (data de expiração), iat (momento de emissão), iss (quem emitiu) e sub (a quem o token se refere). O padrão é aberto e descrito na RFC 7519. ## O conteúdo de um JWT é secreto? Na forma mais comum, não. O JWT assinado, tecnicamente chamado de JWS, garante que o conteúdo não foi alterado, mas não o esconde. Qualquer pessoa que tenha o token consegue decodificar o cabeçalho e o payload e ler o que está escrito. Por isso, não se deve colocar em um JWT dados sensíveis, como senhas, conteúdo de certificados digitais ou informações fiscais confidenciais. Quando é preciso esconder o conteúdo, existe a variante criptografada, chamada JWE. ## Qual a diferença entre JWT e API Key? Uma API Key costuma ser uma sequência aleatória que funciona como uma senha fixa: o servidor precisa consultar sua base de dados para saber a quem ela pertence e quais permissões tem. Ela geralmente vale até ser revogada. Já o JWT carrega dentro de si as informações necessárias, como identificação e validade, e o servidor consegue verificar a autenticidade apenas conferindo a assinatura. Em geral, JWTs têm vida curta e são renovados com frequência. Muitas APIs combinam os dois: a API Key ou credencial é usada para obter um JWT temporário, que então autentica as chamadas. ## Como o JWT é enviado em uma requisição? O jeito mais comum é colocar o token no cabeçalho HTTP Authorization, no formato Bearer, seguido do token. Por isso o JWT é frequentemente usado como bearer token, ou seja, quem o apresenta é tratado como portador da autorização. Esse modelo aparece em fluxos de OAuth 2.0, em que um servidor de autorização gera o token de acesso, e também em cenários com agentes de inteligência artificial que acessam ferramentas via MCP, onde o token ajuda a limitar quais ações o agente pode executar. ## Quais cuidados de segurança o JWT exige? Como quem tem o token pode usá-lo, ele deve trafegar sempre por HTTPS e ser guardado em local protegido, nunca em logs, código-fonte ou repositórios públicos. Definir um tempo de expiração curto reduz o estrago caso o token vaze. O servidor deve sempre validar a assinatura, o algoritmo esperado e a data de expiração, recusando tokens sem assinatura. Também vale lembrar que um JWT emitido continua válido até expirar, então revogá-lo antes disso exige mecanismos extras, como listas de bloqueio ou rotação de chaves. ## Exemplos de JWT - Um ERP envia sua credencial a um endpoint de autenticação, recebe um JWT válido por uma hora e o inclui no cabeçalho Authorization: Bearer de cada chamada para emitir NF-e. - Uma plataforma de marketplace recebe erro 401 ao consultar o status de uma NFC-e porque o JWT expirou; o sistema então solicita um novo token e repete a consulta. - Um agente de inteligência artificial conectado via MCP recebe um token com permissão apenas de leitura, podendo consultar documentos fiscais, mas não cancelá-los. - Durante a depuração, um desenvolvedor decodifica o payload do JWT e confirma que a claim exp indica um horário já passado, explicando a rejeição das requisições. ## Perguntas frequentes ### Como se pronuncia JWT? A pronúncia sugerida pela especificação é a da palavra inglesa jot, mas no Brasil é muito comum falar as letras separadamente, jota-dáblio-tê. ### Posso guardar dados do certificado digital dentro de um JWT? Não. O conteúdo de um JWT assinado pode ser lido por qualquer pessoa que tenha o token. Certificados, senhas e dados sensíveis devem ficar em locais protegidos, como um cofre de segredos. ### O que acontece quando o JWT expira? O servidor passa a recusar as requisições, normalmente com erro 401. O sistema cliente precisa obter um novo token, seja repetindo a autenticação, seja usando um token de renovação, quando a API oferecer esse recurso. ### Todo bearer token é um JWT? Não. Bearer descreve a forma de envio do token, no cabeçalho Authorization. O token pode ser um JWT ou uma sequência aleatória sem estrutura interna, dependendo de como a API foi projetada. ## Termos relacionados - [Bearer token](https://conota.dev/glossario/bearer-token.md) - [Token de autenticação](https://conota.dev/glossario/token-de-autenticacao.md) - [JWS](https://conota.dev/glossario/jws.md) - [JWE](https://conota.dev/glossario/jwe.md) - [OAuth 2.0](https://conota.dev/glossario/oauth-2-0.md) - [Header de autenticação](https://conota.dev/glossario/header-de-autenticacao.md) --- Fonte: [JWT](https://conota.dev/glossario/jwt/) · Atualizado em 2026-10-22