# Glossário de A a Z — letra H > 20 termos. Glossário compacto: https://conota.dev/glossario/llms-full.txt --- # Habilitação no Siscomex > Habilitação no Siscomex é a autorização concedida pela Receita Federal para que uma empresa ou pessoa física opere no comércio exterior, importando ou exportando em nome próprio. Conhecida como Radar, ela libera o acesso aos sistemas aduaneiros e define até que volume de operações o habilitado pode realizar, conforme a modalidade concedida. **Também conhecido como:** Radar, Radar Siscomex, Habilitação Radar, Habilitação para operar no comércio exterior, RADAR, Siscomex registration **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** H ## O que é a habilitação no Siscomex? O Siscomex é o sistema do governo federal que registra e controla as operações de importação e exportação do Brasil. Para usar esse sistema e atuar diretamente no comércio exterior, a empresa precisa antes ser habilitada pela Receita Federal. Essa habilitação é popularmente chamada de Radar. Funciona como uma credencial: sem ela, a empresa não consegue registrar declarações de importação ou de exportação em seu próprio nome. ## Quem precisa da habilitação no Siscomex? Precisa da habilitação quem vai importar ou exportar diretamente, ou seja, figurar como importador ou exportador nos registros aduaneiros. Isso vale para indústrias, distribuidoras, e-commerces que trazem mercadorias de fora e empresas que vendem para clientes no exterior. Quem vende para o exterior por meio de uma trading company ou empresa comercial exportadora, na chamada exportação indireta, normalmente não precisa da própria habilitação, porque é a intermediária que realiza o despacho aduaneiro. ## Quais são as modalidades de habilitação? A Receita Federal concede a habilitação em modalidades diferentes, que variam conforme o porte e a capacidade financeira demonstrada pela empresa. Para pessoas jurídicas, as modalidades costumam ser chamadas de expressa, limitada e ilimitada, cada uma com um teto distinto para o valor das operações. Também existe habilitação para pessoa física, voltada a operações próprias, sem fins comerciais em grande escala. Os limites e requisitos de cada modalidade são definidos em normas da Receita Federal e podem mudar, por isso vale consultar as regras vigentes antes de pedir. ## Como é feito o pedido de habilitação? O pedido é feito de forma eletrônica junto à Receita Federal, geralmente com o uso do certificado digital da empresa, como o e-CNPJ. Dependendo da modalidade, a empresa precisa apresentar documentos que comprovem sua situação cadastral e capacidade financeira. Depois de habilitada, a empresa deve manter os dados atualizados. Em alguns casos, um longo período sem operações pode levar à suspensão da habilitação, exigindo novo pedido. ## Qual a relação entre a habilitação no Siscomex e a emissão de notas fiscais? A habilitação e a emissão fiscal andam juntas. Na importação, depois do desembaraço, a empresa emite uma NF-e de entrada com dados da declaração de importação. Na exportação, emite uma NF-e com CFOP de saída para o exterior e preenche o grupo de informações de exportação, que depois é vinculado à declaração de exportação. Por isso, sistemas como ERPs e plataformas de venda que emitem notas por API precisam tratar esses campos específicos. A habilitação permite registrar a operação aduaneira, e a nota fiscal documenta a circulação da mercadoria perante o fisco. ## Exemplos de Habilitação no Siscomex - Uma loja virtual que passou a importar acessórios da Ásia solicitou a habilitação no Siscomex para registrar as importações em nome próprio e, após o desembaraço, emitir pelo seu ERP a NF-e de entrada com os dados da importação. - Uma indústria de alimentos que vendia ao exterior por meio de uma trading decidiu exportar diretamente e, para isso, pediu a habilitação no Siscomex antes de fechar o primeiro contrato. - Uma distribuidora habilitada na modalidade limitada percebeu que o volume de importações cresceria e pediu a revisão para a modalidade ilimitada. - Um software de gestão integrado a uma API fiscal passou a enviar o grupo de exportação na NF-e somente para clientes que informaram ter habilitação no Siscomex. ## Perguntas frequentes ### Habilitação no Siscomex e Radar são a mesma coisa? Sim. Radar é o nome popular da habilitação concedida pela Receita Federal para operar no Siscomex. Os dois termos são usados como equivalentes no dia a dia do comércio exterior. ### Posso emitir NF-e de exportação sem habilitação no Siscomex? A nota pode ser emitida, mas sem habilitação a empresa não registra a declaração de exportação em nome próprio. Na exportação indireta, quem registra é a trading, e a empresa emite a nota com destino a ela. ### A habilitação no Siscomex tem validade? Ela não precisa ser renovada periodicamente, mas pode ser suspensa em situações previstas pela Receita Federal, como longo período sem operações ou irregularidades cadastrais. ### Preciso de certificado digital para pedir a habilitação? Em geral, sim. O pedido é eletrônico e costuma exigir o certificado digital da empresa, como o e-CNPJ, ou do seu representante legal. ## Termos relacionados - [Exportação indireta](https://conota.dev/glossario/exportacao-indireta.md) - [Grupo de informações de exportação da NF-e](https://conota.dev/glossario/grupo-de-informacoes-de-exportacao-da-nf-e.md) - [Ficha de Conteúdo de Importação](https://conota.dev/glossario/ficha-de-conteudo-de-importacao.md) - [CFOP](https://conota.dev/glossario/cfop.md) - [e-CNPJ](https://conota.dev/glossario/e-cnpj.md) - [Habilitação para emissão fiscal](https://conota.dev/glossario/habilitacao-para-emissao-fiscal.md) --- Fonte: [Habilitação no Siscomex](https://conota.dev/glossario/habilitacao-no-siscomex/) · Atualizado em 2026-10-22 --- # Habilitação para emissão fiscal > Habilitação para emissão fiscal é o conjunto de cadastros, autorizações e requisitos que uma empresa precisa cumprir junto à SEFAZ ou à prefeitura antes de emitir documentos fiscais eletrônicos, como NF-e, NFC-e, NFS-e, CT-e e MDF-e. Envolve inscrição ativa, credenciamento no órgão autorizador, certificado digital válido e, em alguns casos, códigos específicos. **Também conhecido como:** Credenciamento para emissão fiscal, Credenciamento de emissor de NF-e, Autorização para emissão de nota fiscal, Habilitação de emissor **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** H ## O que significa estar habilitado para emitir documentos fiscais? Estar habilitado significa que o órgão responsável reconhece a empresa como apta a emitir determinado tipo de documento fiscal eletrônico. Para notas de mercadorias e transporte, esse órgão costuma ser a SEFAZ do estado. Para notas de serviço, é a prefeitura do município ou o ambiente do Padrão Nacional da NFS-e, conforme o caso. A habilitação não é um único documento ou cadastro. Ela é a soma de condições: a empresa precisa existir regularmente, ter as inscrições corretas, estar autorizada no sistema do órgão e conseguir se identificar digitalmente. Se uma dessas peças faltar, a nota é rejeitada, mesmo que todos os dados da venda estejam corretos. ## Quais são os requisitos mais comuns para a habilitação? Os requisitos variam conforme o documento e o estado ou município, mas alguns aparecem quase sempre: CNPJ ativo, inscrição estadual (para NF-e, NFC-e, CT-e e MDF-e) ou inscrição municipal (para NFS-e), credenciamento como emissor eletrônico no órgão autorizador e um certificado digital válido, geralmente do tipo A1, usado para assinar os arquivos XML. Alguns documentos exigem itens adicionais. A NFC-e depende do CSC, um código gerado no portal da SEFAZ que entra no cálculo do QR Code. Empresas de transporte de cargas, em geral, precisam de registro no RNTRC para emitir CT-e e MDF-e. Em muitos municípios, a emissão de NFS-e só é liberada depois que a prefeitura aprova uma solicitação de acesso. ## Como a habilitação funciona para cada tipo de documento? Para NF-e e NFC-e, a empresa verifica no portal da SEFAZ do seu estado se o credenciamento é automático ou se precisa ser solicitado, e se há etapas específicas para cada modelo. No caso da NFC-e, também gera o CSC. Para CT-e e MDF-e, o processo é parecido, também junto à SEFAZ, com atenção às regras do setor de transporte. Para a NFS-e, o caminho depende de onde o serviço é tributado. Alguns municípios usam sistema próprio e exigem cadastro e liberação na prefeitura. Outros aderiram ao Padrão Nacional da NFS-e, que tem regras de acesso próprias. Por isso, uma empresa com filiais em cidades diferentes pode precisar cuidar de várias habilitações separadas. ## O que acontece se a empresa tentar emitir sem estar habilitada? O órgão autorizador recusa o documento e devolve uma rejeição fiscal com um código e uma mensagem explicando o problema, como emitente não credenciado, inscrição estadual inválida ou certificado não aceito. A nota não ganha validade jurídica e a operação fica sem documento fiscal. Na prática, isso pode travar faturamento, expedição de mercadorias ou circulação de cargas. Por isso, é recomendável confirmar a habilitação e testar a emissão no ambiente de homologação antes de começar a emitir em produção. ## Qual o papel de uma API fiscal na habilitação? Uma API fiscal não habilita a empresa: esse passo é sempre feito pelo próprio contribuinte, ou por seu contador, junto à SEFAZ ou à prefeitura. O papel da API é usar os dados dessa habilitação para emitir os documentos de forma automática, a partir do sistema da empresa. Em uma infraestrutura como o Conota, o sistema cadastra cada empresa emissora, envia o certificado digital, informa dados como inscrição estadual, inscrição municipal e CSC, e a partir daí passa a emitir por API. Se algo na habilitação estiver irregular, a rejeição retornada pelo órgão aparece no status do documento, ajudando a identificar o que precisa ser corrigido no cadastro. ## Exemplos de Habilitação para emissão fiscal - Um e-commerce que vai começar a vender produtos físicos confirma no portal da SEFAZ do seu estado o credenciamento como emissor de NF-e antes de ativar a emissão automática pelo seu ERP. - Uma rede de lojas gera o CSC da NFC-e para cada estabelecimento no portal da SEFAZ e cadastra esses códigos na plataforma de emissão para que os cupons saiam com QR Code válido. - Uma empresa de software com clientes em três cidades descobre que precisa solicitar liberação de NFS-e em uma das prefeituras, enquanto as outras duas seguem o Padrão Nacional. - Uma transportadora regulariza seu registro no RNTRC antes de integrar o sistema de gestão de frota à API para emitir CT-e e MDF-e. ## Perguntas frequentes ### Ter certificado digital já basta para emitir nota fiscal? Não. O certificado digital serve para assinar os documentos, mas a empresa também precisa de inscrições ativas e de credenciamento ou autorização no órgão responsável, como SEFAZ ou prefeitura. ### A habilitação vale para todos os tipos de documento? Não necessariamente. Cada documento pode ter requisitos próprios. Estar apto a emitir NF-e não garante a emissão de NFC-e, NFS-e, CT-e ou MDF-e, que podem exigir cadastros e códigos adicionais. ### Cada filial precisa de habilitação própria? Em geral, sim. Cada estabelecimento tem CNPJ e inscrições próprias, e o credenciamento costuma ser verificado por estabelecimento, especialmente quando as filiais ficam em estados ou municípios diferentes. ### Como saber se a empresa está habilitada? Consultando o portal da SEFAZ ou da prefeitura, com apoio do contador, e fazendo testes de emissão no ambiente de homologação antes de emitir em produção. ## Termos relacionados - [SEFAZ](https://conota.dev/glossario/sefaz.md) - [Inscrição estadual](https://conota.dev/glossario/inscricao-estadual.md) - [Inscrição municipal](https://conota.dev/glossario/inscricao-municipal.md) - [Certificado digital A1](https://conota.dev/glossario/certificado-digital-a1.md) - [CSC da NFC-e](https://conota.dev/glossario/csc-da-nfc-e.md) - [Prefeitura autorizadora de NFS-e](https://conota.dev/glossario/prefeitura-autorizadora-de-nfs-e.md) --- Fonte: [Habilitação para emissão fiscal](https://conota.dev/glossario/habilitacao-para-emissao-fiscal/) · Atualizado em 2026-10-22 --- # Hash de documento fiscal > Hash de documento fiscal é um código de tamanho fixo, gerado por um algoritmo matemático a partir do conteúdo de um documento como NF-e, NFC-e ou CT-e. Ele funciona como uma impressão digital do arquivo: qualquer alteração, por menor que seja, gera um hash diferente, o que permite verificar se o documento continua íntegro. **Também conhecido como:** Resumo criptográfico, Digest, Valor de hash, Hash do XML, Fiscal document hash **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** H ## O que é um hash de documento fiscal? Um hash é o resultado de uma função matemática que transforma um conteúdo de qualquer tamanho, como o XML inteiro de uma nota fiscal, em uma sequência curta de letras e números. Esse resultado sempre tem o mesmo tamanho, seja o documento pequeno ou enorme. A característica mais importante é que o mesmo conteúdo sempre gera o mesmo hash, mas basta trocar uma vírgula, um espaço ou um valor para que o hash mude completamente. Além disso, não é possível reconstruir o documento original a partir do hash. Por isso ele é usado como uma espécie de lacre digital. ## Para que serve o hash em documentos fiscais? O principal uso é garantir a integridade: confirmar que o documento recebido pela SEFAZ, pela prefeitura, pelo destinatário ou guardado pela empresa é exatamente o mesmo que foi gerado pelo emitente, sem adulterações. Ele também ajuda a vincular informações entre si. Em alguns pontos dos leiautes fiscais, o hash combina dados do documento com um código secreto conhecido apenas pelo emitente ou pelo responsável técnico, o que permite que o fisco confira a origem da informação sem que esse segredo circule abertamente. ## Onde o hash aparece na NF-e, NFC-e e outros documentos? Na assinatura digital do XML, o sistema calcula um hash do conteúdo do documento, chamado de valor de resumo ou digest, e é esse resumo que é assinado com o certificado digital. Quem recebe o XML recalcula o hash e compara: se for diferente, a assinatura é considerada inválida. Na NFC-e, o QR Code impresso no DANFCE inclui um hash calculado a partir de dados da nota combinados com o CSC, o código de segurança do contribuinte. Nos leiautes da NF-e e de outros modelos também existe a possibilidade de informar um hash ligado ao código de segurança do responsável técnico pelo software emissor, quando exigido pela unidade federativa. Fora dos leiautes oficiais, empresas e plataformas também usam hashes para controle interno, por exemplo para conferir se um XML armazenado não foi alterado ou para detectar arquivos duplicados em uma importação. ## Qual a diferença entre hash e assinatura digital? O hash, sozinho, só diz se o conteúdo mudou. Qualquer pessoa pode calcular o hash de um arquivo, então ele não prova quem gerou o documento. A assinatura digital usa o hash como ponto de partida e o criptografa com a chave privada do certificado digital do emitente. Assim, ela garante ao mesmo tempo a integridade (o conteúdo não mudou) e a autoria (foi aquele CNPJ que assinou). ## Qual a diferença entre hash e chave de acesso? A chave de acesso da NF-e é um número de 44 dígitos montado a partir de dados conhecidos, como UF, data, CNPJ, modelo, série e número, com um dígito verificador no final. Ela serve para identificar e consultar o documento. O hash, por outro lado, é derivado de todo o conteúdo ou de um conjunto de dados e serve para verificar integridade. A chave identifica qual é a nota; o hash ajuda a confirmar que ela não foi alterada. ## Quem integra por API precisa calcular hashes? Depende de como a emissão é feita. Quem monta e assina o XML por conta própria precisa calcular corretamente os hashes exigidos pela assinatura e pelos leiautes, e qualquer diferença de formatação, como espaços extras ou quebras de linha, pode gerar rejeição por assinatura inválida. Ao usar uma API fiscal, normalmente o sistema envia os dados da venda em JSON e a plataforma de emissão cuida da geração do XML, da assinatura, do QR Code e dos hashes envolvidos. Ainda assim, entender o conceito ajuda a interpretar rejeições e a validar XMLs recebidos ou armazenados. ## Exemplos de Hash de documento fiscal - Um ERP envia os dados de uma venda para a API fiscal, que gera o XML da NF-e, calcula o hash do conteúdo e o assina com o certificado A1 do emitente antes de transmitir à SEFAZ. - Uma loja emite uma NFC-e e o DANFCE sai com um QR Code que contém um hash calculado com o CSC, permitindo ao consumidor e ao fisco conferir a autenticidade da nota. - Uma empresa guarda os XMLs autorizados e registra o hash de cada arquivo; meses depois, recalcula os hashes para confirmar que nenhum documento foi alterado no armazenamento. - Um desenvolvedor recebe uma rejeição por assinatura inválida e descobre que o XML foi reformatado depois de assinado, o que mudou o hash e quebrou a verificação. ## Perguntas frequentes ### É possível descobrir o conteúdo da nota a partir do hash? Não. A função de hash é de mão única: a partir do resultado não é possível reconstruir o documento original. O hash só serve para comparar se dois conteúdos são idênticos. ### Se eu alterar um XML autorizado, o que acontece com o hash? O hash muda e a assinatura digital deixa de ser válida. Por isso um XML autorizado não deve ser editado; correções devem ser feitas por eventos fiscais, como carta de correção ou cancelamento, conforme o caso. ### Hash é a mesma coisa que criptografia? Não exatamente. A criptografia permite recuperar o conteúdo original com a chave correta. O hash gera um resumo irreversível, usado para verificar integridade, e não para esconder ou recuperar informações. ## Termos relacionados - [Assinatura digital do XML](https://conota.dev/glossario/assinatura-digital-do-xml.md) - [Arquivo XML fiscal](https://conota.dev/glossario/arquivo-xml-fiscal.md) - [QR Code da NFC-e](https://conota.dev/glossario/qr-code-da-nfc-e.md) - [CSC da NFC-e](https://conota.dev/glossario/csc-da-nfc-e.md) - [Chave de acesso da NF-e](https://conota.dev/glossario/chave-de-acesso-da-nf-e.md) - [Guarda de documentos fiscais](https://conota.dev/glossario/guarda-de-documentos-fiscais.md) --- Fonte: [Hash de documento fiscal](https://conota.dev/glossario/hash-de-documento-fiscal/) · Atualizado em 2026-10-22 --- # Header Content-Type > Header Content-Type é o cabeçalho de uma requisição ou resposta HTTP que informa qual é o formato dos dados enviados no corpo da mensagem, como application/json ou application/xml. Ele permite que o servidor e o cliente interpretem corretamente o conteúdo, sendo essencial em integrações de emissão fiscal por API. **Também conhecido como:** Cabeçalho Content-Type, Content-Type, Cabeçalho de tipo de conteúdo, Tipo de mídia, MIME type, Content-Type header **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** H ## O que é o header Content-Type? Toda comunicação pela web usando o protocolo HTTP é formada por cabeçalhos (headers) e, muitas vezes, por um corpo (body). Os cabeçalhos são informações extras que acompanham a mensagem, como etiquetas em um pacote. O Content-Type é uma dessas etiquetas. Ele diz a quem recebe a mensagem que tipo de conteúdo está no corpo: um texto em JSON, um documento XML, um PDF, uma imagem ou um formulário. O valor segue um padrão chamado tipo de mídia (ou MIME type), como application/json. ## Para que serve o Content-Type em uma API fiscal? Quando um ERP ou plataforma de vendas envia os dados de uma nota fiscal para uma API, o servidor precisa saber como ler aquelas informações. Se o corpo está em JSON, o Content-Type deve ser application/json; se está em XML, application/xml ou text/xml. Na resposta, o mesmo cabeçalho indica o que está voltando: um JSON com o status do documento, o XML autorizado da NF-e ou o PDF do DANFE. Assim, o sistema do cliente sabe se deve processar dados, salvar um arquivo ou exibir um documento. ## Como o Content-Type aparece na prática? Ele é escrito como uma linha no cabeçalho da requisição, por exemplo: Content-Type: application/json. Pode incluir parâmetros adicionais, como a codificação de caracteres: Content-Type: application/json; charset=utf-8. Bibliotecas e linguagens de programação costumam permitir definir esse cabeçalho com uma linha de código. Em muitas delas, ao enviar um objeto JSON, o valor é preenchido automaticamente, mas é sempre bom conferir. ## O que acontece se o Content-Type estiver errado ou ausente? Se o cabeçalho não corresponder ao conteúdo real, o servidor pode não conseguir interpretar os dados. Em geral, a API devolve um erro, como o código HTTP 415 (tipo de mídia não suportado) ou 400 (requisição inválida). Em integrações fiscais, isso pode parecer um problema nos dados da nota, quando na verdade é apenas um cabeçalho mal configurado. Verificar o Content-Type é um dos primeiros passos ao investigar falhas de envio. ## Qual a diferença entre Content-Type e Accept? O Content-Type descreve o formato do que está sendo enviado. Já o cabeçalho Accept informa qual formato o cliente prefere receber na resposta. Por exemplo, um sistema pode enviar os dados da nota em JSON (Content-Type: application/json) e pedir o PDF do documento auxiliar como resposta (Accept: application/pdf). Os dois cabeçalhos trabalham juntos, mas têm papéis diferentes. ## Quais caracteres especiais exigem atenção com o charset? Documentos fiscais brasileiros têm acentos e cedilha em nomes, endereços e descrições de produtos. Se a codificação não for informada ou estiver incorreta, palavras como 'Ação' ou 'São Paulo' podem chegar corrompidas. Indicar charset=utf-8 no Content-Type, e garantir que o texto realmente esteja nessa codificação, evita esse tipo de problema e reduz rejeições por caracteres inválidos. ## Exemplos de Header Content-Type - Um ERP envia os dados de uma NF-e para a API de emissão com o cabeçalho Content-Type: application/json; charset=utf-8, e o servidor interpreta corretamente os itens e tributos da nota. - Uma plataforma de marketplace recebe a resposta de uma consulta de documento com Content-Type: application/pdf e salva o arquivo como o DANFE para enviar ao comprador. - Um desenvolvedor recebe erro 415 ao emitir uma NFS-e porque esqueceu de definir o Content-Type; ao incluir application/json, a requisição passa a ser aceita. - Ao baixar o XML autorizado de um CT-e, o sistema identifica pelo Content-Type: application/xml que deve armazenar o conteúdo como arquivo fiscal, e não exibi-lo como texto. ## Perguntas frequentes ### O Content-Type é obrigatório em toda requisição? Não. Ele é necessário quando a requisição tem corpo, como em envios com POST ou PUT. Em consultas simples com GET, normalmente não há corpo, então o cabeçalho costuma ser dispensável. ### Qual Content-Type usar para enviar uma nota fiscal por API? Depende do formato aceito pela API. Em APIs REST modernas, o mais comum é application/json. Consulte a documentação do provedor para confirmar o valor esperado em cada endpoint. ### O nome do header diferencia maiúsculas e minúsculas? Não. Pelo padrão HTTP, nomes de cabeçalhos não diferenciam maiúsculas e minúsculas, então Content-Type e content-type são equivalentes. Já o valor, como application/json, deve seguir a grafia padrão. ### O que significa o erro HTTP 415? Significa que o servidor não suporta o tipo de mídia informado no Content-Type. Geralmente indica cabeçalho ausente, incorreto ou incompatível com o formato que a API espera receber. ## Termos relacionados - [HTTP](https://conota.dev/glossario/http.md) - [Formato JSON](https://conota.dev/glossario/formato-json.md) - [Arquivo XML fiscal](https://conota.dev/glossario/arquivo-xml-fiscal.md) - [Header de autenticação](https://conota.dev/glossario/header-de-autenticacao.md) - [Endpoint de API](https://conota.dev/glossario/endpoint-de-api.md) - [API REST para emissão fiscal](https://conota.dev/glossario/api-rest-para-emissao-fiscal.md) --- Fonte: [Header Content-Type](https://conota.dev/glossario/header-content-type/) · Atualizado em 2026-10-22 --- # Header de autenticação > Header de autenticação é um campo enviado no cabeçalho de cada requisição HTTP que identifica quem está chamando uma API e comprova que essa chamada tem permissão. Em uma API fiscal, ele carrega uma credencial, como API Key ou Bearer token, para que apenas sistemas autorizados emitam, consultem ou cancelem documentos fiscais. **Também conhecido como:** Cabeçalho de autenticação, Header Authorization, Cabeçalho Authorization, Authorization header, Authentication header **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** H ## O que é um header de autenticação, na prática? Toda requisição HTTP é formada por algumas partes: o endereço (endpoint), o método (como GET ou POST), o corpo com os dados e os headers, que são linhas de informação extra enviadas junto com o pedido. Os headers funcionam como a etiqueta de um envelope: não são o conteúdo da carta, mas dizem ao destinatário como tratá-la. O header de autenticação é uma dessas etiquetas. Ele leva uma credencial secreta que permite à API reconhecer quem está fazendo o pedido. Sem ele, a API não sabe se a requisição veio de um cliente legítimo ou de alguém desconhecido, e por isso costuma recusá-la. ## Como funciona o header de autenticação em uma API fiscal? Quando um ERP, uma plataforma de vendas ou um marketplace quer emitir uma NF-e, uma NFS-e ou uma NFC-e por API, ele monta a requisição com os dados do documento e inclui o header de autenticação com a credencial fornecida pelo provedor. A API lê esse header antes de qualquer outra coisa. Se a credencial for válida, a API verifica quais permissões ela tem e a qual conta ou empresa está vinculada, e só então processa a emissão. Se for inválida, ausente ou expirada, a requisição é interrompida ali mesmo, sem que nenhum documento seja criado. Esse controle é especialmente importante em ambientes com várias empresas emissoras, pois garante que um sistema só acesse os documentos e CNPJs da conta à qual pertence. ## Quais são os formatos mais comuns de header de autenticação? O formato mais difundido usa o header padrão Authorization, seguido de um esquema e da credencial. No esquema Bearer, por exemplo, a linha fica parecida com Authorization: Bearer seguido do token. Esse modelo é muito usado com tokens gerados por OAuth 2.0 ou com JWT. Outro formato frequente é um header personalizado dedicado à chave de API, algo como X-API-Key seguido do valor da chave. Há ainda o esquema Basic, que envia usuário e senha codificados em Base64, hoje menos recomendado para integrações entre sistemas. O nome exato do header e o formato aceito sempre devem ser conferidos na documentação de cada API. ## Qual a diferença entre header de autenticação e certificado digital? São coisas diferentes, que muitas vezes aparecem juntas na emissão fiscal. O header de autenticação prova à API do provedor que o seu sistema pode usar o serviço. O certificado digital, como o A1, identifica a empresa emissora perante a SEFAZ ou a prefeitura e é usado para assinar o XML do documento. Em uma integração por API fiscal, o sistema do cliente normalmente só envia o header de autenticação em cada chamada. O certificado fica cadastrado no provedor, que o utiliza para assinar e transmitir os documentos aos órgãos autorizadores. ## Quais cuidados de segurança o header de autenticação exige? A credencial do header equivale a uma senha: quem a possui pode agir em nome da sua empresa. Por isso, ela deve trafegar apenas por HTTPS, que criptografa a comunicação, e nunca ser colocada em query string, pois endereços costumam ficar gravados em históricos e logs. Também é recomendável guardar a credencial em um cofre de segredos ou variável de ambiente, e não diretamente no código-fonte; evitar que ela apareça em logs de integração; usar credenciais separadas para homologação e produção; e trocá-la periodicamente ou sempre que houver suspeita de vazamento. ## Que erros costumam aparecer quando o header está errado? O mais comum é o código HTTP 401 (Unauthorized), que indica credencial ausente, inválida ou expirada. Ele aparece quando o header não foi enviado, foi escrito com nome errado, falta o prefixo esperado (como Bearer) ou a chave tem espaços e caracteres a mais. Já o código 403 (Forbidden) indica que a credencial foi reconhecida, mas não tem permissão para aquela ação, como cancelar um documento ou acessar dados de outra empresa. Diferenciar os dois ajuda a resolver o problema mais rápido. ## Exemplos de Header de autenticação - Um ERP envia uma requisição POST para emitir uma NF-e e inclui o header Authorization: Bearer seguido do token da conta; a API valida o token e devolve o status da emissão. - Uma plataforma de agendamento emite NFS-e para vários prestadores e usa uma chave de API diferente em cada ambiente, enviando no header a chave de homologação durante os testes e a de produção após a publicação. - Um desenvolvedor recebe erro 401 ao consultar o status de uma NFC-e e descobre que havia copiado a chave com um espaço no final, o que invalidava o header. - Um agente de inteligência artificial conectado via MCP consulta documentos fiscais usando uma credencial com permissão apenas de leitura, de modo que tentativas de cancelamento são recusadas. ## Perguntas frequentes ### Preciso enviar o header de autenticação em todas as requisições? Sim, na maioria das APIs REST. Elas não guardam sessão entre chamadas, então cada requisição precisa trazer sua própria credencial para ser aceita, inclusive consultas, downloads de XML e cancelamentos. ### Posso colocar a chave de API na URL em vez do header? Não é recomendado. URLs costumam ficar registradas em logs, históricos de navegador e ferramentas de monitoramento, aumentando o risco de vazamento. O header, enviado por HTTPS, é o local adequado para credenciais. ### O que fazer se a credencial do header vazar? Revogue ou substitua a credencial imediatamente no painel do provedor, atualize-a nos sistemas que a utilizam e revise os registros de acesso para identificar chamadas suspeitas feitas no período. ## Termos relacionados - [API Key](https://conota.dev/glossario/api-key.md) - [Bearer token](https://conota.dev/glossario/bearer-token.md) - [Token de autenticação](https://conota.dev/glossario/token-de-autenticacao.md) - [HTTPS](https://conota.dev/glossario/https.md) - [Gerenciamento de segredos](https://conota.dev/glossario/gerenciamento-de-segredos.md) - [Permissão de acesso à API](https://conota.dev/glossario/permissao-de-acesso-a-api.md) --- Fonte: [Header de autenticação](https://conota.dev/glossario/header-de-autenticacao/) · Atualizado em 2026-10-22 --- # Healthcheck de API > Healthcheck de API é uma verificação automática, geralmente feita por um endpoint específico, que informa se uma API está funcionando e pronta para receber requisições. Em integrações fiscais, ajuda o sistema do cliente a saber, antes de emitir uma nota, se o serviço e suas dependências estão disponíveis, evitando falhas e filas paradas. **Também conhecido como:** Health check, Verificação de saúde da API, Checagem de disponibilidade, Endpoint de status, Health endpoint, API health check **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** H ## O que é um healthcheck de API? Healthcheck, ou verificação de saúde, é uma checagem simples que responde à pergunta: esta API está no ar e funcionando? Normalmente existe um endereço próprio para isso, como /health ou /status, que devolve uma resposta curta indicando se o serviço está saudável. A resposta costuma usar um código HTTP, como 200 quando tudo está bem ou 503 quando o serviço está indisponível. Às vezes também traz detalhes, como o estado do banco de dados ou de serviços externos dos quais a API depende. ## Para que serve o healthcheck em uma API fiscal? Na emissão fiscal, uma nota que não é emitida pode travar uma venda, um faturamento ou a saída de uma carga. O healthcheck permite que o ERP, a plataforma de vendas ou o marketplace descubram rapidamente se a API está disponível antes de enviar documentos ou durante a operação. Com essa informação, o sistema pode decidir o que fazer: seguir normalmente, segurar os envios em uma fila, acionar um plano alternativo ou avisar a equipe técnica. Isso reduz erros repetidos e torna a integração mais previsível. ## Como funciona um healthcheck na prática? Um monitor ou o próprio sistema do cliente faz chamadas periódicas ao endpoint de saúde, por exemplo a cada minuto. Se a resposta demorar demais ou vier com erro, o monitor registra o problema e pode disparar um alerta. Existem dois níveis comuns. O mais básico confirma apenas que a aplicação responde. O mais completo verifica também dependências, como banco de dados, filas de processamento e conexão com os órgãos autorizadores, como SEFAZ e prefeituras. ## Qual a diferença entre a API estar no ar e a emissão estar funcionando? A API pode responder normalmente e, mesmo assim, uma SEFAZ ou prefeitura específica estar fora do ar. Nesse caso, a plataforma de emissão recebe o pedido, mas a autorização do documento depende do órgão externo. Por isso, um healthcheck de API não substitui o acompanhamento do status de cada documento. Ele indica a saúde do serviço de integração, enquanto o status do documento mostra se aquela nota específica foi autorizada, rejeitada ou continua em processamento. ## Quais cuidados tomar ao usar healthchecks? Não é preciso consultar o endpoint de saúde a cada segundo, pois chamadas excessivas podem esbarrar no limite de requisições e não trazem ganho real. Um intervalo regular e moderado costuma ser suficiente. Também é importante combinar o healthcheck com outras práticas: timeout bem definido, retry com backoff exponencial, idempotência para evitar notas duplicadas e logs que permitam investigar o que aconteceu durante uma instabilidade. ## Exemplos de Healthcheck de API - Um ERP consulta o endpoint de saúde da API fiscal a cada minuto e, ao receber erro 503 três vezes seguidas, pausa o envio de NF-e e passa a acumular os pedidos em uma fila interna. - Uma equipe de infraestrutura configura um painel de monitoramento que mostra em verde ou vermelho a disponibilidade da API de emissão e envia alerta quando a resposta ultrapassa o tempo esperado. - Antes de iniciar o faturamento em lote do fim do mês, um marketplace verifica o healthcheck da API para confirmar que o serviço está disponível e evitar centenas de falhas seguidas. - Uma empresa de transporte usa o healthcheck para diferenciar uma falha da própria integração de uma instabilidade momentânea no órgão autorizador do CT-e e do MDF-e. ## Perguntas frequentes ### Healthcheck é a mesma coisa que monitoramento? Não exatamente. O healthcheck é uma das ferramentas de monitoramento: uma checagem pontual de disponibilidade. O monitoramento completo também inclui métricas de latência, logs, rastreamento de requisições e alertas, compondo a observabilidade da API. ### Se o healthcheck estiver OK, minha nota será autorizada? Não necessariamente. Ele indica que a API está funcionando, mas a autorização depende dos dados enviados e da disponibilidade do órgão autorizador. Rejeições por erro de validação, por exemplo, podem ocorrer mesmo com a API saudável. ### Com que frequência devo chamar o healthcheck? Depende da criticidade da operação, mas intervalos de alguns segundos a um minuto são comuns. Evite chamadas excessivas, que consomem recursos e podem atingir limites de requisições sem melhorar a detecção de falhas. ### O healthcheck precisa de autenticação? Depende do provedor. Alguns endpoints de saúde são públicos e mostram apenas se o serviço responde; outros exigem token por exibirem detalhes internos. Consulte a documentação da API utilizada. ## Termos relacionados - [Observabilidade da API fiscal](https://conota.dev/glossario/observabilidade-da-api-fiscal.md) - [Endpoint de API](https://conota.dev/glossario/endpoint-de-api.md) - [Latência da API fiscal](https://conota.dev/glossario/latencia-da-api-fiscal.md) - [Janela de manutenção da API](https://conota.dev/glossario/janela-de-manutencao-da-api.md) - [Fallback na integração fiscal](https://conota.dev/glossario/fallback-na-integracao-fiscal.md) - [Retry na integração fiscal](https://conota.dev/glossario/retry-na-integracao-fiscal.md) --- Fonte: [Healthcheck de API](https://conota.dev/glossario/healthcheck-de-api/) · Atualizado em 2026-10-22 --- # Hierarquia de certificados digitais > Hierarquia de certificados digitais é a estrutura em forma de árvore que organiza quem emite e quem garante cada certificado digital. No topo fica uma autoridade raiz, abaixo dela as autoridades certificadoras intermediárias e, na ponta, os certificados de pessoas e empresas. É essa organização que permite verificar se um certificado é confiável. **Também conhecido como:** Hierarquia de certificação, Estrutura hierárquica de certificação, Árvore de certificação, Certificate hierarchy **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** H ## O que é a hierarquia de certificados digitais na prática? Um certificado digital funciona como uma identidade eletrônica. Para que alguém confie nessa identidade, precisa saber quem a emitiu e se esse emissor também é confiável. A hierarquia resolve isso organizando os emissores em níveis: cada nível garante o nível de baixo. Pense em um cartório que reconhece firmas, mas que só pode funcionar porque foi autorizado por um órgão superior. No mundo digital acontece algo parecido: o certificado da sua empresa foi assinado por uma autoridade certificadora, que por sua vez foi autorizada e assinada por uma autoridade acima dela, até chegar à raiz. ## Quais são os níveis da hierarquia da ICP-Brasil? No Brasil, a hierarquia oficial é a ICP-Brasil. No topo está a AC Raiz, que é o ponto máximo de confiança e não emite certificados para usuários finais, apenas credencia e certifica as autoridades abaixo dela. Em seguida vêm as Autoridades Certificadoras de primeiro nível, que podem certificar outras ACs de níveis inferiores. As ACs que emitem certificados para o público contam com Autoridades de Registro, responsáveis por conferir documentos e identificar presencialmente ou por videoconferência quem está solicitando o certificado. Na base da árvore ficam os certificados finais, como o e-CNPJ e o e-CPF, usados por empresas e pessoas para assinar documentos, acessar sistemas do governo e emitir notas fiscais. ## Como a hierarquia garante que um certificado é confiável? Cada certificado carrega a assinatura digital de quem o emitiu. Para validar um certificado, o sistema confere essa assinatura usando o certificado do emissor, depois confere o certificado do emissor usando o do nível acima, e assim por diante até chegar à raiz. Como o certificado da raiz já é previamente conhecido e aceito como confiável, se todas as assinaturas do caminho estiverem corretas, dentro da validade e não revogadas, o certificado final é considerado válido. Se qualquer elo falhar, a confiança se quebra. ## Qual a diferença entre hierarquia e cadeia de certificação? A hierarquia é a estrutura completa, com todas as autoridades e todos os ramos da árvore. A cadeia de certificação é apenas um caminho dentro dessa árvore: a sequência específica que liga um certificado final até a raiz. Em outras palavras, a hierarquia mostra o mapa inteiro, e a cadeia mostra a rota de um certificado específico. Ao validar um documento, o sistema percorre a cadeia daquele certificado, apoiando-se nas regras definidas pela hierarquia. ## Por que a hierarquia importa na emissão de notas fiscais? Documentos como NF-e, NFC-e, CT-e e MDF-e precisam ser assinados digitalmente com um certificado ICP-Brasil, e muitas prefeituras exigem o mesmo para a NFS-e. Ao receber o XML, a SEFAZ ou a prefeitura verifica se o certificado pertence a essa hierarquia e se a cadeia até a AC Raiz é válida. Se o certificado foi emitido fora da ICP-Brasil, está vencido, foi revogado ou a cadeia não pode ser reconstruída, o documento é rejeitado. Por isso, sistemas que emitem notas por API precisam manter atualizados os certificados das autoridades intermediárias e raiz, além de controlar a validade do certificado de cada empresa emissora. ## Exemplos de Hierarquia de certificados digitais - Uma empresa compra um certificado A1 de uma autoridade certificadora credenciada; ao assinar a NF-e, a SEFAZ confere a cadeia desse certificado até a AC Raiz da ICP-Brasil e aceita a assinatura. - Um ERP tenta enviar uma NFS-e assinada com um certificado autoassinado gerado internamente para testes; a prefeitura rejeita o documento porque o certificado não pertence à hierarquia da ICP-Brasil. - Após a autoridade certificadora atualizar seu certificado intermediário, um servidor de integração fiscal desatualizado deixa de reconhecer a cadeia e passa a falhar na conexão com o web service até que os certificados da hierarquia sejam atualizados. - Em um console de gestão fiscal, a equipe identifica que o certificado de um dos CNPJs foi revogado pela AC emissora e providencia um novo antes de retomar as emissões. ## Perguntas frequentes ### Qualquer certificado digital serve para emitir nota fiscal? Não. Para documentos fiscais eletrônicos brasileiros, o certificado precisa ter sido emitido por uma autoridade certificadora credenciada na hierarquia da ICP-Brasil. Certificados de outras hierarquias ou autoassinados são recusados pelos órgãos fiscais. ### Quem fica no topo da hierarquia da ICP-Brasil? A AC Raiz da ICP-Brasil. Ela é o ponto inicial de confiança, credencia as autoridades certificadoras e assina os certificados delas, mas não emite certificados diretamente para empresas ou pessoas. ### O que acontece se um certificado intermediário for revogado? Todos os certificados emitidos abaixo dele perdem a validade na verificação, porque a cadeia até a raiz deixa de ser confiável. Documentos assinados com esses certificados passam a ser rejeitados. ### Preciso instalar os certificados da hierarquia no meu sistema? Depende da integração. Quem assina e valida documentos diretamente precisa manter os certificados raiz e intermediários atualizados. Ao usar uma API fiscal que cuida da assinatura e da comunicação, essa gestão costuma ficar a cargo do provedor. ## Termos relacionados - [Cadeia de certificação digital](https://conota.dev/glossario/cadeia-de-certificacao-digital.md) - [AC Raiz da ICP-Brasil](https://conota.dev/glossario/ac-raiz-da-icp-brasil.md) - [Autoridade Certificadora](https://conota.dev/glossario/autoridade-certificadora.md) - [Autoridade de Registro](https://conota.dev/glossario/autoridade-de-registro.md) - [ICP-Brasil](https://conota.dev/glossario/icp-brasil.md) - [Assinatura digital do XML](https://conota.dev/glossario/assinatura-digital-do-xml.md) --- Fonte: [Hierarquia de certificados digitais](https://conota.dev/glossario/hierarquia-de-certificados-digitais/) · Atualizado em 2026-10-22 --- # Higienização de cadastro tributário > Higienização de cadastro tributário é o processo de revisar, corrigir, padronizar e completar os dados fiscais de clientes, fornecedores, produtos e da própria empresa, como CNPJ, inscrição estadual, endereço, NCM e regime tributário, para que as notas fiscais sejam emitidas sem rejeições e com a tributação correta. **Também conhecido como:** Saneamento de cadastro fiscal, Saneamento cadastral tributário, Limpeza de cadastro fiscal, Revisão de cadastro tributário, Higienização de dados fiscais, Tax data cleansing **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** H ## O que é higienização de cadastro tributário? É uma espécie de faxina nos dados que o sistema usa para emitir documentos fiscais. Com o tempo, cadastros acumulam erros de digitação, informações desatualizadas, campos vazios e registros duplicados. A higienização identifica esses problemas e corrige cada registro, deixando os dados consistentes com as bases oficiais e com as regras exigidas pela SEFAZ e pelas prefeituras. ## Quais dados costumam ser revisados? No cadastro de clientes e fornecedores, são verificados CNPJ ou CPF, razão social, inscrição estadual, inscrição municipal, endereço completo com código do município, CEP e indicação de contribuinte do ICMS. No cadastro de produtos e serviços, entram NCM, CEST, GTIN, unidade de medida, CFOP padrão, CST ou CSOSN, alíquotas e o código de serviço usado na NFS-e. Também são revisados os dados da própria empresa emissora, como regime tributário e certificado digital. ## Para que serve higienizar o cadastro? O principal objetivo é reduzir rejeições na emissão. Muitas notas são recusadas por problemas simples, como inscrição estadual inválida, código de município incorreto ou NCM inexistente. Além disso, cadastros corretos evitam cálculo errado de impostos, notas emitidas com tributação indevida, cartas de correção e cancelamentos desnecessários, além de inconsistências na escrituração fiscal e riscos em uma fiscalização. ## Como funciona a higienização na prática? Normalmente começa com um diagnóstico: o cadastro é exportado e analisado em busca de campos vazios, formatos inválidos, duplicidades e dados divergentes das bases públicas, como a situação cadastral do CNPJ e da inscrição estadual. Depois vêm a correção e a padronização, que podem ser manuais ou automatizadas por consultas e validações. Por fim, criam-se regras no sistema para impedir que novos cadastros entrem com erro, como validação de dígito verificador e campos obrigatórios. ## Qual a relação com a emissão fiscal por API? Quando um ERP, uma plataforma de vendas ou um marketplace emite notas por API, os dados do cadastro são enviados diretamente para montar o documento. Se o cadastro estiver errado, a API repassa o erro e o documento volta rejeitado. Por isso, empresas que automatizam a emissão costumam acompanhar os motivos de rejeição devolvidos pela API para descobrir quais cadastros precisam de correção. Uma rejeição recorrente costuma indicar um problema de cadastro, não da integração. ## Com que frequência deve ser feita? Não há uma regra fixa. O ideal é uma higienização completa ao implantar um novo sistema emissor, migrar de ERP ou mudar de regime tributário, além de revisões periódicas. Mudanças na legislação, como alterações de alíquotas, novos códigos e a reforma tributária com IBS e CBS, também são bons momentos para revisar o cadastro de produtos e serviços. ## Exemplos de Higienização de cadastro tributário - Uma distribuidora percebe que muitas NF-e são rejeitadas por inscrição estadual do destinatário inválida e revisa a base de clientes, atualizando inscrições baixadas e marcando corretamente quem não é contribuinte do ICMS. - Um e-commerce que vai começar a emitir NF-e por API higieniza o cadastro de produtos, corrigindo NCMs desatualizados e preenchendo o CEST nos itens sujeitos à substituição tributária. - Uma empresa de software que emite NFS-e em vários municípios padroniza o código de serviço e a inscrição municipal de cada filial antes de integrar seu sistema a um emissor fiscal. - Após migrar de ERP, uma indústria encontra clientes duplicados com endereços diferentes e unifica os registros, mantendo o código de município correto exigido no XML. ## Perguntas frequentes ### Higienização de cadastro é obrigação legal? Não existe uma obrigação com esse nome, mas a legislação exige que os documentos fiscais tenham dados corretos. Na prática, manter o cadastro limpo é a forma de cumprir essa exigência e evitar rejeições, multas e retrabalho. ### Quem deve fazer a higienização? Geralmente envolve as áreas fiscal, contábil e de tecnologia. O fiscal ou o contador define as regras tributárias corretas, e a equipe de tecnologia ajuda a automatizar validações e corrigir os dados em massa no sistema. ### A API fiscal corrige o cadastro automaticamente? Não. A API envia os dados recebidos e devolve o status e os motivos de rejeição. Essas mensagens ajudam a localizar erros, mas a correção precisa ser feita no cadastro do sistema de origem. ### Higienizar o cadastro elimina todas as rejeições? Reduz bastante, mas não todas. Rejeições também podem vir de certificado vencido, falhas de comunicação, numeração duplicada ou instabilidade nos serviços da SEFAZ e das prefeituras. ## Termos relacionados - [Erro de validação fiscal](https://conota.dev/glossario/erro-de-validacao-fiscal.md) - [Inscrição estadual](https://conota.dev/glossario/inscricao-estadual.md) - [CFOP](https://conota.dev/glossario/cfop.md) - [GTIN](https://conota.dev/glossario/gtin.md) - [Bloqueio de emissão pela SEFAZ](https://conota.dev/glossario/bloqueio-de-emissao-pela-sefaz.md) --- Fonte: [Higienização de cadastro tributário](https://conota.dev/glossario/higienizacao-de-cadastro-tributario/) · Atualizado em 2026-10-23 --- # Hipótese de incidência tributária > Hipótese de incidência tributária é a descrição, feita em lei, de uma situação que, se acontecer na vida real, faz nascer a obrigação de pagar um tributo. Por exemplo, a lei do ICMS descreve a circulação de mercadorias. Quando uma venda ocorre de fato, essa situação concreta é o fato gerador. **Também conhecido como:** Hipótese de incidência, Hipótese tributária, Fato gerador abstrato, Fato gerador em abstrato, Hipótese de incidência do tributo, Taxable event **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** H ## O que significa hipótese de incidência tributária? É a previsão abstrata, escrita na lei, de um acontecimento que deve gerar a cobrança de um tributo. A palavra hipótese indica justamente isso: a lei não diz que algo aconteceu, mas que, se acontecer, haverá tributo a pagar. Pense nela como uma regra do tipo "se… então". Se alguém prestar um serviço listado na lei do município, então deverá recolher ISSQN. Se uma mercadoria circular entre empresas, então incidirá ICMS. Sem essa descrição prévia em lei, o Fisco não pode cobrar o tributo. ## Qual a diferença entre hipótese de incidência e fato gerador? A hipótese de incidência é a descrição genérica que está na lei. O fato gerador é o acontecimento concreto, no mundo real, que se encaixa nessa descrição. Um é o modelo; o outro é o caso que cabe no modelo. Exemplo: a lei prevê que vender mercadoria gera ICMS (hipótese de incidência). Quando uma loja vende uma geladeira para um cliente numa terça-feira, essa venda específica é o fato gerador. Na prática, muita gente e até textos legais usam fato gerador para as duas ideias, o que causa confusão. ## Quais são os elementos de uma hipótese de incidência? Para que a regra funcione, a lei precisa responder a algumas perguntas. O elemento material diz o que precisa acontecer (vender, prestar serviço, transportar carga). O espacial diz onde (em qual estado ou município). O temporal diz quando o fato se considera ocorrido (na saída da mercadoria, na conclusão do serviço). O pessoal diz quem deve pagar e quem pode cobrar. Há ainda o elemento quantitativo, que define quanto será pago, combinando a base de cálculo com a alíquota. Se algum desses pontos estiver faltando ou mal definido, a cobrança pode ser questionada. ## Como a hipótese de incidência aparece na emissão de notas fiscais? Cada documento fiscal registra uma operação que pode se encaixar em uma ou mais hipóteses de incidência. Na NF-e e na NFC-e, a venda de produtos costuma envolver ICMS, IPI, PIS e COFINS. Na NFS-e, a prestação de serviço envolve o ISSQN. No CT-e, o transporte de cargas entre municípios ou estados pode envolver ICMS. Por isso, ao montar o documento, o sistema informa dados como CFOP, CST ou CSOSN, base de cálculo e alíquota. Esses campos indicam, em linguagem fiscal, se a operação está dentro da hipótese de incidência e como o tributo foi calculado. Uma API fiscal recebe essas informações do ERP ou da plataforma de vendas e as transmite ao órgão autorizador, que valida a estrutura do documento. ## O que acontece quando uma operação não se encaixa na hipótese de incidência? Se o acontecimento não corresponde à descrição da lei, ocorre a chamada não incidência: simplesmente não nasce a obrigação de pagar aquele tributo. Por exemplo, a mera transferência de bens sem caráter de venda pode ter tratamento diferente conforme a legislação aplicável. A não incidência é diferente da isenção e da imunidade. Na isenção, o fato se encaixa na hipótese, mas uma lei dispensa o pagamento. Na imunidade, a própria Constituição impede que o tributo seja cobrado em certas situações. Nos documentos fiscais, cada caso costuma ter um código de situação tributária próprio. ## Exemplos de Hipótese de incidência tributária - Uma loja virtual vende um par de tênis para um consumidor de outro estado. A venda se encaixa na hipótese de incidência do ICMS, e a NF-e emitida pela plataforma traz a base de cálculo, a alíquota e o DIFAL correspondentes. - Uma agência de marketing presta serviço de criação de campanha a um cliente. Como a atividade consta na lista de serviços tributáveis, há hipótese de incidência do ISSQN, e o software de gestão emite uma NFS-e com o imposto destacado. - Uma transportadora leva carga de uma cidade para outra em estados diferentes. O transporte interestadual se enquadra na hipótese de incidência do ICMS sobre serviços de transporte, registrado no CT-e. - Um contador analisa se a remessa de um equipamento para conserto gera tributo. Ele verifica se a operação se encaixa na hipótese de incidência do ICMS ou se a legislação a trata como não tributada ou suspensa. ## Perguntas frequentes ### Hipótese de incidência e fato gerador são a mesma coisa? Não exatamente. A hipótese de incidência é a descrição abstrata na lei; o fato gerador é o acontecimento real que se encaixa nessa descrição. Na linguagem do dia a dia, porém, os dois termos costumam ser usados como sinônimos. ### Quem define a hipótese de incidência de um tributo? A lei do ente que tem competência para criar o tributo: União, estados, Distrito Federal ou municípios, sempre dentro dos limites fixados pela Constituição e pelas normas gerais de direito tributário. ### Se houver isenção, existe hipótese de incidência? Sim. Na isenção, a operação se encaixa na hipótese de incidência, mas uma lei dispensa o pagamento. Por isso o documento fiscal ainda precisa indicar a situação tributária correta, com o código que identifica a isenção. ### A API fiscal decide se há incidência de tributo? Em geral, não. O enquadramento tributário é definido pelo sistema do cliente e por sua equipe fiscal ou contábil. A API recebe esses dados, monta e transmite o documento, e o órgão autorizador valida regras de estrutura e consistência. ## Termos relacionados - [Fato gerador](https://conota.dev/glossario/fato-gerador.md) - [Base de cálculo](https://conota.dev/glossario/base-de-calculo.md) - [Alíquota tributária](https://conota.dev/glossario/aliquota-tributaria.md) - [Isenção tributária](https://conota.dev/glossario/isencao-tributaria.md) - [Imunidade tributária](https://conota.dev/glossario/imunidade-tributaria.md) - [Jurisdição tributária](https://conota.dev/glossario/jurisdicao-tributaria.md) --- Fonte: [Hipótese de incidência tributária](https://conota.dev/glossario/hipotese-de-incidencia-tributaria/) · Atualizado em 2026-10-22 --- # Histórico de eventos fiscais > Histórico de eventos fiscais é o registro, em ordem cronológica, de tudo o que aconteceu com um documento fiscal depois da emissão, como autorização, cancelamento, carta de correção, manifestação do destinatário ou encerramento de MDF-e. Ele mostra quando cada evento ocorreu, quem o solicitou e qual foi a resposta do órgão autorizador. **Também conhecido como:** Histórico de eventos do documento fiscal, Linha do tempo do documento fiscal, Registro de eventos fiscais, Fiscal event history **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** H ## O que aparece no histórico de eventos fiscais? Um documento fiscal não termina sua vida no momento em que é autorizado. Depois disso, ele pode passar por várias ocorrências oficiais, chamadas de eventos fiscais. Entre elas estão o cancelamento, a carta de correção eletrônica, a manifestação do destinatário na NF-e, o encerramento e a inclusão de condutor no MDF-e, além de eventos de prestação de serviço em desacordo no CT-e. O histórico reúne essas ocorrências em uma linha do tempo. Para cada uma, costuma mostrar o tipo de evento, a data e a hora, o número de protocolo devolvido pela SEFAZ ou pela prefeitura, o resultado (aceito ou rejeitado) e o motivo, quando houver rejeição. ## Para que serve o histórico de eventos fiscais? Ele responde rapidamente à pergunta: qual é a situação real deste documento hoje? Uma nota pode ter sido autorizada e depois cancelada, ou ter recebido uma correção. Sem o histórico, a empresa corre o risco de tratar como válida uma nota que já não vale mais. Também ajuda na conferência contábil, no atendimento a clientes, na resposta a fiscalizações e na investigação de problemas. Quando alguém pergunta por que um valor ou dado mudou, o histórico mostra o que foi feito e em que momento. ## Como funciona o histórico de eventos em uma API fiscal? Quando o sistema da empresa solicita um evento, como um cancelamento, a API envia o pedido ao órgão autorizador e acompanha a resposta. O resultado é anexado ao documento original, formando o histórico. Cada evento aceito gera seu próprio arquivo XML com protocolo, que deve ser guardado junto com o XML da nota. Em uma infraestrutura como o Conota, o sistema do cliente pode consultar esse histórico pela API, receber atualizações automaticamente e visualizar a linha do tempo no Console. Agentes de inteligência artificial com acesso via MCP também podem consultar os eventos de um documento, dentro das permissões concedidas. ## Qual a diferença entre histórico de eventos fiscais e trilha de auditoria? O histórico de eventos fiscais trata das ocorrências oficiais de um documento, aquelas registradas perante a SEFAZ ou a prefeitura. Já a trilha de auditoria fiscal é mais ampla: registra ações de usuários e sistemas, como quem acessou, quem alterou uma configuração ou quem solicitou uma emissão. O log de integração fiscal, por sua vez, registra a comunicação técnica entre sistemas, como requisições, respostas e erros. Os três se complementam: o histórico mostra o que aconteceu com a nota, a trilha mostra quem fez e o log mostra como a comunicação ocorreu. ## O histórico também existe no órgão autorizador? Sim. Os eventos aceitos ficam vinculados ao documento na base do órgão autorizador, e é por isso que a consulta pela chave de acesso mostra se uma NF-e foi cancelada ou corrigida. O histórico mantido pela empresa ou pela API deve refletir essas informações oficiais. A forma de consulta e os eventos disponíveis variam conforme o tipo de documento. Na NFS-e, por exemplo, o comportamento pode mudar de acordo com o município e com a adoção do Padrão Nacional. ## Exemplos de Histórico de eventos fiscais - Um ERP consulta o histórico de eventos de uma NF-e antes de gerar a cobrança e descobre que a nota foi cancelada no dia anterior, evitando enviar um boleto indevido. - Uma transportadora verifica no histórico de um MDF-e se o evento de encerramento foi aceito antes de emitir um novo manifesto para o mesmo veículo. - A equipe de suporte de um marketplace abre o histórico de uma nota para explicar ao comprador que o endereço foi ajustado por carta de correção eletrônica. - Um agente de IA conectado via MCP lista, a pedido do financeiro, todas as notas do mês que tiveram eventos de cancelamento, com data e protocolo. ## Perguntas frequentes ### É possível apagar um evento do histórico? Não. Eventos aceitos pelo órgão autorizador são definitivos e ficam vinculados ao documento. Se algo foi registrado de forma errada, a correção deve ser feita por um novo evento permitido, quando houver, e não pela exclusão do anterior. ### Preciso guardar o XML dos eventos? Sim. O XML de cada evento aceito, com seu protocolo, faz parte da documentação fiscal e deve ser armazenado junto com o XML do documento original, pelo mesmo prazo de guarda. ### Eventos rejeitados aparecem no histórico? No órgão autorizador, apenas eventos aceitos ficam vinculados ao documento. Muitas plataformas, porém, também mostram tentativas rejeitadas e seus motivos no histórico interno, o que ajuda a entender e corrigir falhas. ### Várias cartas de correção ficam todas no histórico? Sim, todas ficam registradas na linha do tempo. Na NF-e, porém, a carta de correção mais recente substitui as anteriores, então ela deve conter todas as correções desejadas, inclusive as já informadas antes. ## Termos relacionados - [Evento fiscal](https://conota.dev/glossario/evento-fiscal.md) - [Cancelamento de documento fiscal](https://conota.dev/glossario/cancelamento-de-documento-fiscal.md) - [Manifestação do destinatário](https://conota.dev/glossario/manifestacao-do-destinatario.md) - [Encerramento do MDF-e](https://conota.dev/glossario/encerramento-do-mdf-e.md) - [Trilha de auditoria fiscal](https://conota.dev/glossario/trilha-de-auditoria-fiscal.md) - [Status de documento fiscal](https://conota.dev/glossario/status-de-documento-fiscal.md) --- Fonte: [Histórico de eventos fiscais](https://conota.dev/glossario/historico-de-eventos-fiscais/) · Atualizado em 2026-10-22 --- # HMAC em webhooks > HMAC em webhooks é uma técnica de segurança que permite ao sistema que recebe uma notificação automática confirmar que ela foi enviada por quem diz ter enviado e que não foi alterada no caminho. Funciona combinando o conteúdo da mensagem com uma chave secreta compartilhada, gerando uma assinatura que o receptor recalcula e compara. **Também conhecido como:** Assinatura HMAC de webhook, Validação de assinatura de webhook, HMAC-SHA256 em webhooks, Webhook assinado, HMAC, Hash-based Message Authentication Code in webhooks **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** H ## O que significa HMAC? HMAC é a sigla em inglês para código de autenticação de mensagem baseado em hash. É um método que pega duas coisas, o conteúdo de uma mensagem e uma chave secreta, e as passa por uma função de hash, como o SHA-256. O resultado é uma sequência de caracteres de tamanho fixo, que funciona como uma assinatura. Se uma única letra da mensagem mudar, ou se a chave usada for diferente, a assinatura gerada será completamente outra. Por isso, quem conhece a chave consegue verificar se a mensagem é autêntica e está íntegra. ## Para que serve o HMAC em webhooks? Webhook é uma notificação que um sistema envia automaticamente para outro quando algo acontece. Em uma API fiscal, por exemplo, o emissor avisa o ERP do cliente que uma NF-e foi autorizada, que uma NFS-e foi rejeitada ou que um cancelamento foi concluído. O problema é que o endereço que recebe essas notificações fica exposto na internet. Sem proteção, qualquer pessoa poderia enviar uma mensagem falsa dizendo que uma nota foi autorizada. O HMAC resolve isso: o sistema só aceita a notificação se a assinatura que veio junto bater com a que ele mesmo calcula usando a chave secreta. ## Como funciona a validação da assinatura? Antes de tudo, quem envia e quem recebe combinam uma chave secreta, que nunca trafega junto com as notificações. Quando um evento acontece, o remetente calcula o HMAC do corpo da mensagem com essa chave e envia o resultado em um cabeçalho HTTP da requisição. Ao receber, o sistema do cliente pega o corpo exatamente como chegou, calcula o HMAC com a mesma chave e compara com o valor do cabeçalho. Se forem iguais, a mensagem é legítima e pode ser processada. Se forem diferentes, a notificação deve ser descartada e, de preferência, registrada em log para investigação. ## Qual a diferença entre HMAC e assinatura digital? A assinatura digital, como a usada no XML de uma NF-e, utiliza um par de chaves: uma privada, que assina, e uma pública, que qualquer pessoa pode usar para conferir. Ela prova a autoria perante terceiros e tem validade jurídica quando feita com certificado digital. O HMAC usa uma única chave secreta, conhecida pelas duas partes. É mais simples e rápido, ideal para comunicação entre dois sistemas que confiam um no outro, mas não serve para provar a autoria para um terceiro, já que ambos os lados poderiam ter gerado a assinatura. Também é diferente de um hash simples, que não usa chave e, portanto, pode ser recalculado por qualquer um. ## Quais cuidados tomar ao implementar HMAC em webhooks? Calcule a assinatura sobre o corpo bruto da requisição, antes de convertê-lo em objeto JSON, pois reformatar espaços ou a ordem dos campos muda o resultado. Use uma função de comparação em tempo constante, disponível na maioria das linguagens, para evitar ataques que exploram o tempo de resposta. Guarde a chave secreta em um cofre ou gerenciador de segredos, nunca no código-fonte, e troque-a periodicamente. Quando houver um carimbo de data e hora na mensagem, recuse notificações muito antigas para impedir que alguém reenvie uma mensagem verdadeira capturada antes. E mantenha o endpoint em HTTPS, já que o HMAC garante autenticidade, mas não esconde o conteúdo. ## Exemplos de HMAC em webhooks - Um ERP recebe um webhook informando que a NF-e de um pedido foi autorizada, recalcula o HMAC-SHA256 do corpo com a chave secreta configurada e, como o valor confere, atualiza o pedido para faturado e baixa o XML. - Uma plataforma de vendas recebe uma notificação de cancelamento de NFC-e cuja assinatura não confere; o sistema descarta a mensagem, registra o incidente em log e consulta o status diretamente na API para confirmar a situação real. - Um marketplace troca a chave secreta dos webhooks por política de segurança e, durante um período de transição, aceita assinaturas geradas com a chave antiga e com a nova até concluir a migração. - Uma transportadora valida o HMAC das notificações de autorização de CT-e e MDF-e antes de liberar a viagem no seu software de gestão. ## Perguntas frequentes ### O HMAC criptografa o conteúdo do webhook? Não. O HMAC apenas comprova quem enviou e que a mensagem não foi alterada. O conteúdo continua legível; para protegê-lo durante o envio, o endpoint deve usar HTTPS. ### Onde a assinatura HMAC costuma ser enviada? Normalmente em um cabeçalho HTTP da própria requisição do webhook. O nome exato do cabeçalho e o algoritmo usado são definidos na documentação de cada API. ### O que fazer se a chave secreta vazar? Gere uma nova chave imediatamente, atualize-a no sistema receptor e invalide a antiga. Depois, revise os logs para identificar notificações suspeitas recebidas durante o período de exposição. ### Validar o HMAC dispensa consultar o status do documento? Na maioria dos casos, sim, pois a mensagem é confiável. Ainda assim, consultar o status pela API é uma boa prática em operações críticas ou quando a notificação parecer inconsistente. ## Termos relacionados - [Gerenciamento de segredos](https://conota.dev/glossario/gerenciamento-de-segredos.md) - [Key rotation](https://conota.dev/glossario/key-rotation.md) - [Fluxo assíncrono de emissão](https://conota.dev/glossario/fluxo-assincrono-de-emissao.md) - [HTTPS](https://conota.dev/glossario/https.md) - [Assinatura digital do XML](https://conota.dev/glossario/assinatura-digital-do-xml.md) - [Status de documento fiscal](https://conota.dev/glossario/status-de-documento-fiscal.md) --- Fonte: [HMAC em webhooks](https://conota.dev/glossario/hmac-em-webhooks/) · Atualizado em 2026-10-22 --- # Homologação de benefício fiscal > Homologação de benefício fiscal é o reconhecimento formal, feito pela administração tributária, de que uma empresa cumpre os requisitos para usar determinado incentivo, como isenção, redução de base de cálculo ou crédito presumido. Quando essa aprovação é exigida e não existe, aplicar o benefício nas notas fiscais pode gerar cobrança do imposto, multas e juros. **Também conhecido como:** Reconhecimento de benefício fiscal, Credenciamento para benefício fiscal, Habilitação a benefício fiscal, Concessão de benefício fiscal, Tax incentive approval **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** H ## O que é homologação de benefício fiscal? Um benefício fiscal é uma vantagem prevista na legislação que reduz ou elimina o imposto devido em certas situações. Exemplos comuns são a isenção, a redução da base de cálculo, o diferimento e o crédito presumido. Alguns benefícios valem automaticamente para quem se enquadra nas condições da lei. Outros só podem ser usados depois que o fisco analisa o pedido da empresa e confirma que ela atende aos requisitos. Essa confirmação oficial é a homologação do benefício fiscal. Dependendo do estado, do município ou do tributo, o procedimento pode receber outros nomes, como credenciamento, habilitação, regime especial ou termo de acordo. A ideia central é a mesma: a empresa só passa a ter direito ao benefício depois do aval do órgão competente. ## Por que alguns benefícios precisam ser homologados? Benefícios fiscais significam menos arrecadação para o governo. Por isso, muitos deles vêm acompanhados de contrapartidas, como gerar empregos, investir em uma região, manter regularidade fiscal ou operar em determinado segmento. A homologação permite que o fisco verifique essas condições antes de liberar a vantagem e acompanhe se elas continuam sendo cumpridas. Também ajuda a evitar que empresas apliquem benefícios aos quais não têm direito. ## Como funciona o processo de homologação? Em geral, a empresa apresenta um pedido à secretaria de fazenda ou ao órgão responsável, junto com documentos que comprovam o enquadramento. É comum exigir certidões negativas de débitos, inscrição estadual ou municipal ativa e informações sobre as operações que receberão o benefício. Após a análise, o órgão emite um ato de concessão, que pode ter prazo de validade, condições e limites específicos, como produtos, operações ou percentuais autorizados. Se a empresa deixar de cumprir as exigências, o benefício pode ser suspenso ou cancelado. Como as regras variam muito entre estados, municípios e tributos, o enquadramento costuma ser avaliado pelo contador ou pelo setor tributário da empresa. ## Qual a relação com a emissão de notas fiscais? O benefício homologado precisa aparecer corretamente nos documentos fiscais. Na NF-e e na NFC-e, isso envolve preencher o CST ou o CSOSN adequado, ajustar a base de cálculo e a alíquota e, em estados que exigem, informar o código de benefício fiscal do item. Para quem emite notas por um sistema próprio, como um ERP integrado a uma API fiscal, essas informações costumam ficar no cadastro tributário de produtos e operações. Se o benefício for aplicado sem homologação, ou depois de vencido, a nota pode até ser autorizada, mas a empresa fica exposta a autuações e à cobrança da diferença do imposto. Alguns erros de preenchimento, como um código de benefício incompatível com o CST informado, podem causar rejeição da nota já no envio à SEFAZ. ## Qual a diferença entre homologação de benefício fiscal e ambiente de homologação? Apesar da palavra em comum, são coisas diferentes. A homologação de benefício fiscal é uma aprovação jurídica e tributária concedida pelo fisco a uma empresa. Já o ambiente de homologação é um ambiente técnico de testes, oferecido pelas SEFAZ, prefeituras e provedores de API, onde é possível emitir documentos sem validade fiscal para validar uma integração antes de ir para o ambiente de produção. ## Exemplos de Homologação de benefício fiscal - Uma indústria pede à secretaria de fazenda do seu estado o enquadramento em um programa de incentivo e, após a aprovação, passa a emitir NF-e com crédito presumido de ICMS em determinados produtos. - Um atacadista recebe a concessão de um regime especial com redução da base de cálculo do ICMS e atualiza no ERP o CST, a base reduzida e o código de benefício fiscal dos itens contemplados. - Uma empresa percebe que o prazo do benefício homologado venceu e ajusta o cadastro tributário para que as novas notas emitidas via API voltem a destacar o imposto integral. - Um prestador de serviços solicita à prefeitura o reconhecimento de um tratamento tributário diferenciado e só passa a aplicar a regra na NFS-e depois de receber o ato de concessão. ## Perguntas frequentes ### Todo benefício fiscal precisa ser homologado? Não. Alguns se aplicam automaticamente a quem se enquadra nas condições da lei. Outros dependem de pedido e aprovação prévia do fisco. Cabe verificar na legislação do tributo e do ente responsável, geralmente com apoio do contador. ### O que acontece se a empresa usar um benefício sem homologação? Se a homologação era obrigatória, o fisco pode cobrar o imposto que deixou de ser pago, acrescido de multa e juros. Créditos aproveitados indevidamente também podem ser glosados. ### A API fiscal verifica se o benefício está homologado? Em geral, não. A API transmite os dados enviados pelo sistema e a SEFAZ valida regras técnicas do documento. Confirmar o direito ao benefício é responsabilidade da empresa e de sua assessoria tributária. ### A homologação do benefício tem prazo de validade? Muitas vezes, sim. O ato de concessão pode fixar prazo, condições e limites. Vencido o prazo ou descumpridas as condições, o benefício deixa de valer e a emissão das notas deve ser ajustada. ## Termos relacionados - [Benefício fiscal](https://conota.dev/glossario/beneficio-fiscal.md) - [Código de benefício fiscal](https://conota.dev/glossario/codigo-de-beneficio-fiscal.md) - [Crédito presumido](https://conota.dev/glossario/credito-presumido.md) - [Base de cálculo reduzida](https://conota.dev/glossario/base-de-calculo-reduzida.md) - [Isenção tributária](https://conota.dev/glossario/isencao-tributaria.md) - [Ambiente de homologação](https://conota.dev/glossario/ambiente-de-homologacao.md) --- Fonte: [Homologação de benefício fiscal](https://conota.dev/glossario/homologacao-de-beneficio-fiscal/) · Atualizado em 2026-10-22 --- # Homologação fiscal > Homologação fiscal é a etapa de testes e validação em que uma empresa ou sistema emite documentos fiscais, como NF-e, NFS-e e CT-e, em ambiente de testes oficial, sem valor jurídico, para comprovar que a integração gera arquivos corretos e aceitos pelos órgãos autorizadores antes de começar a emitir notas reais em produção. **Também conhecido como:** Homologação da emissão fiscal, Testes de emissão fiscal, Fase de homologação, Tax document sandbox testing **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** H ## O que é homologação fiscal na prática? Homologação fiscal é o período de ensaio da emissão de notas. Antes de emitir documentos que valem de verdade, a empresa envia notas de teste para a SEFAZ, para a prefeitura ou para um emissor intermediário, e confere se elas são autorizadas sem erros. Essas notas de teste não geram imposto, não têm validade jurídica e não podem ser usadas em operações reais. O objetivo é apenas verificar se os dados, o formato do arquivo e o processo de envio estão corretos. O termo também é usado, em alguns contextos, para o processo em que um órgão autorizador valida e libera um contribuinte ou um software para emitir documentos. Por isso, vale confirmar em qual sentido a palavra está sendo usada. ## Para que serve a homologação fiscal? Serve para encontrar problemas antes que eles afetem clientes, faturamento ou obrigações com o fisco. Um erro de cadastro, de tributação ou de formato descoberto em produção pode bloquear vendas ou exigir cancelamentos e correções. Na homologação, a empresa pode errar à vontade: uma rejeição fiscal em teste é apenas um aviso de que algo precisa ser ajustado. Isso dá segurança para a equipe de tecnologia e para o time fiscal validarem juntos as regras de emissão. ## Como funciona a homologação fiscal na emissão por API? Quando a emissão é feita por uma API fiscal, o sistema da empresa, como um ERP ou uma plataforma de vendas, envia os dados da nota para o ambiente de homologação usando credenciais de teste. A API monta o arquivo XML, faz a assinatura digital e encaminha o documento ao órgão autorizador correspondente. O retorno indica se a nota foi autorizada ou rejeitada, junto com o motivo da rejeição quando houver. A equipe ajusta o sistema, repete os testes e, quando os resultados estão consistentes, troca as credenciais e a configuração para o ambiente de produção. Nos documentos estaduais, como NF-e, NFC-e, CT-e e MDF-e, existe um campo no próprio documento que identifica se ele foi emitido em homologação ou produção. Na NFS-e, a disponibilidade de ambiente de testes varia conforme o município ou o padrão adotado. ## Qual a diferença entre homologação fiscal e ambiente de homologação? O ambiente de homologação é o lugar técnico onde os testes acontecem: servidores e endereços separados, que aceitam documentos sem valor fiscal. Já a homologação fiscal é o processo como um todo, que inclui planejar cenários, emitir notas de teste, analisar retornos e decidir quando a integração está pronta. Em resumo, o ambiente é a ferramenta; a homologação é a etapa do projeto que usa essa ferramenta. ## O que costuma ser testado durante a homologação? Os testes mais comuns envolvem a emissão de notas com diferentes produtos ou serviços, regimes tributários, CFOP, CST ou CSOSN, além de operações internas e interestaduais. Também se testam eventos fiscais como cancelamento, carta de correção, inutilização de numeração e, no caso do MDF-e, o encerramento. Do lado técnico, vale testar o recebimento do XML e do PDF, o tratamento de rejeições, timeouts, reenvios sem duplicidade e o recebimento de status por webhook ou consulta. ## Quando a empresa está pronta para ir para produção? Em geral, quando os principais cenários de venda da empresa foram emitidos e autorizados em homologação, as rejeições foram entendidas e tratadas, e o time fiscal validou os valores de impostos calculados. Também é preciso ter em mãos o que a produção exige, como certificado digital válido, inscrição estadual ou municipal ativa e, quando aplicável, a habilitação junto ao órgão autorizador. Notas emitidas em produção têm valor legal, por isso a troca de ambiente deve ser feita de forma controlada. ## Exemplos de Homologação fiscal - Um ERP que vai começar a emitir NF-e para seus clientes envia dezenas de notas de teste para o ambiente de homologação, simulando vendas internas e interestaduais, até que todas sejam autorizadas sem rejeição. - Uma plataforma de serviços integra a emissão de NFS-e por API e testa, em homologação, notas com e sem retenção de ISSQN antes de liberar a funcionalidade aos prestadores. - Uma transportadora valida em homologação o fluxo completo de CT-e e MDF-e, incluindo emissão, cancelamento e encerramento do manifesto, antes de usar o sistema nas viagens reais. - Uma loja virtual que vai emitir NFC-e testa o QR Code e o DANFCE gerados em homologação para conferir se as informações aparecem corretamente para o consumidor. ## Perguntas frequentes ### Nota emitida em homologação tem valor fiscal? Não. Documentos emitidos em homologação servem apenas para teste, não têm validade jurídica, não geram obrigação tributária e não podem ser entregues como comprovante de venda ou prestação de serviço. ### Preciso de certificado digital para fazer homologação? Na maioria dos casos, sim. Documentos como NF-e e CT-e exigem assinatura digital mesmo em teste, então normalmente se usa o certificado digital da empresa emissora. As exigências podem variar conforme o documento e o órgão autorizador. ### Todos os municípios oferecem homologação para NFS-e? Não necessariamente. A existência de ambiente de testes para NFS-e depende do município ou do padrão de emissão adotado. Em alguns casos, a validação precisa ser feita com cuidado redobrado diretamente em produção. ### Quanto tempo dura a homologação fiscal? Não há prazo fixo. Depende da quantidade de cenários de emissão, da complexidade tributária da empresa e de quantos ajustes forem necessários até que as notas de teste sejam autorizadas de forma consistente. ## Termos relacionados - [Ambiente de homologação](https://conota.dev/glossario/ambiente-de-homologacao.md) - [Ambiente de produção](https://conota.dev/glossario/ambiente-de-producao.md) - [Habilitação para emissão fiscal](https://conota.dev/glossario/habilitacao-para-emissao-fiscal.md) - [Rejeição fiscal](https://conota.dev/glossario/rejeicao-fiscal.md) - [Emissão fiscal por API](https://conota.dev/glossario/emissao-fiscal-por-api.md) - [Certificado digital A1](https://conota.dev/glossario/certificado-digital-a1.md) --- Fonte: [Homologação fiscal](https://conota.dev/glossario/homologacao-fiscal/) · Atualizado em 2026-10-22 --- # Honorários de serviços contábeis > Honorários de serviços contábeis são os valores cobrados por contadores e escritórios de contabilidade para prestar serviços como escrituração fiscal, apuração de tributos, folha de pagamento e entrega de obrigações acessórias. Normalmente cobrados em mensalidade fixa, são receita de prestação de serviço e, por isso, exigem a emissão de nota fiscal de serviço, a NFS-e. **Também conhecido como:** Honorários contábeis, Mensalidade contábil, Honorários do contador, Taxa de contabilidade, Accounting fees **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** H ## O que está incluído nos honorários contábeis? Os honorários remuneram o trabalho do contador para manter a empresa em dia com o fisco e com as próprias contas. O pacote mais comum inclui escrituração contábil e fiscal, apuração e emissão de guias de tributos, folha de pagamento, entrega de declarações obrigatórias e orientação ao empresário. O que entra ou não no valor depende do contrato de prestação de serviços. Por isso, é comum que abertura de empresa, alterações contratuais, regularização de pendências ou consultorias específicas sejam cobradas à parte. ## Como os honorários contábeis costumam ser cobrados? O formato mais usado é a mensalidade fixa, calculada a partir do porte da empresa, do regime tributário, do número de funcionários e do volume de notas fiscais movimentadas. Quanto mais complexa a rotina, maior tende a ser o valor. Além da mensalidade, existem cobranças avulsas por serviços pontuais. Alguns escritórios também cobram uma parcela extra no fim do ano, conhecida como décimo terceiro honorário, para cobrir o trabalho adicional de encerramento do exercício e declarações anuais. ## Como emitir nota fiscal de honorários contábeis? Como contabilidade é prestação de serviço, a cobrança dos honorários é documentada com a NFS-e, emitida no município onde o escritório está estabelecido. Para isso, o prestador precisa ter inscrição municipal e estar habilitado para emissão no município ou no padrão nacional, conforme o caso. Na nota, o escritório informa o tomador (o cliente), a descrição do serviço, o código correspondente a serviços de contabilidade na lista de serviços, o valor e os tributos. Dependendo do tipo de cliente e do enquadramento das partes, pode haver retenção de tributos na fonte, que também deve constar no documento. ## Quais tributos incidem sobre os honorários contábeis? O principal imposto é o ISSQN, de competência municipal, cuja alíquota varia conforme a cidade. Em alguns municípios, sociedades formadas por profissionais da mesma área podem recolher o ISS em valor fixo por profissional, em vez de um percentual sobre o faturamento. Também incidem tributos federais sobre a receita e o lucro do escritório, de acordo com o regime escolhido, como Simples Nacional, Lucro Presumido ou Lucro Real. Quando o cliente é pessoa jurídica, a legislação pode exigir a retenção de tributos como IRRF no momento do pagamento. ## Como automatizar a emissão das notas de honorários? Escritórios com muitos clientes emitem dezenas ou centenas de NFS-e todo mês, quase sempre com valores recorrentes. Fazer isso manualmente no portal da prefeitura consome tempo e aumenta o risco de erro de digitação. Com uma API fiscal, o software de gestão do escritório gera as notas automaticamente na data de cobrança, inclusive em lote. A API acompanha cada documento até a autorização e devolve XML, PDF e status, que podem ser enviados ao cliente junto com o boleto ou link de pagamento. ## Exemplos de Honorários de serviços contábeis - Um escritório de contabilidade cobra mensalidade de seus clientes e emite uma NFS-e para cada um no dia 5 de cada mês, informando o serviço de contabilidade e o ISSQN devido. - Uma empresa do Lucro Presumido paga os honorários do contador e, conforme a legislação aplicável, retém IRRF sobre o valor, que aparece destacado na nota fiscal recebida. - Um software de gestão para contadores, integrado a uma API fiscal, emite em lote as notas de honorários de todos os clientes do escritório e anexa o PDF da NFS-e ao e-mail de cobrança. - Em dezembro, um escritório emite uma nota adicional referente ao décimo terceiro honorário, previsto em contrato, para cobrir o fechamento anual do cliente. ## Perguntas frequentes ### O contador é obrigado a emitir nota fiscal dos honorários? Sim. Os honorários são receita de prestação de serviço, e a emissão da NFS-e é obrigatória conforme a legislação do município do prestador. A nota comprova o pagamento para o cliente e serve de base para o recolhimento dos tributos do escritório. ### Quem paga honorários contábeis pode lançar como despesa? Em geral, sim. Os honorários são considerados despesa operacional da empresa e devem estar amparados pela nota fiscal do serviço. O efeito tributário depende do regime da empresa, por isso o próprio contador orienta como fazer o registro. ### Existe tabela oficial de honorários contábeis? Entidades de classe e sindicatos da categoria costumam divulgar tabelas de referência, mas o valor final é livremente negociado entre contador e cliente, considerando a complexidade da rotina e os serviços incluídos no contrato. ## Termos relacionados - [ISSQN](https://conota.dev/glossario/issqn.md) - [IRRF](https://conota.dev/glossario/irrf.md) - [Base de cálculo do ISSQN](https://conota.dev/glossario/base-de-calculo-do-issqn.md) - [Inscrição municipal](https://conota.dev/glossario/inscricao-municipal.md) - [Emissão fiscal por API](https://conota.dev/glossario/emissao-fiscal-por-api.md) - [Batch de documentos fiscais](https://conota.dev/glossario/batch-de-documentos-fiscais.md) --- Fonte: [Honorários de serviços contábeis](https://conota.dev/glossario/honorarios-de-servicos-contabeis/) · Atualizado em 2026-10-22 --- # Hora de emissão da NF-e > Hora de emissão da NF-e é a data e o horário em que a nota fiscal eletrônica foi gerada pelo emitente. Fica registrada no campo dhEmi do XML, com o fuso horário em relação ao UTC. A SEFAZ valida essa informação, que serve de referência para a ordem cronológica, a escrituração e a análise da operação. **Também conhecido como:** Data e hora de emissão da NF-e, dhEmi, Data de emissão da nota fiscal eletrônica, NF-e issue date and time **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** H ## O que é a hora de emissão da NF-e? É o momento oficial em que o emitente declara ter gerado a nota fiscal eletrônica. A informação faz parte do grupo de identificação do documento e aparece no XML na tag dhEmi, que reúne data e hora em um único campo. Ela não deve ser confundida com o horário em que a SEFAZ autoriza a nota. A emissão é informada pelo sistema do emitente. A autorização é registrada pela SEFAZ no protocolo de autorização, depois que o documento é recebido e validado. ## Qual é o formato da hora de emissão no XML? O campo segue o padrão de data e hora com fuso horário: ano, mês, dia, a letra T, horas, minutos, segundos e o deslocamento em relação ao UTC. Um exemplo válido é 2024-05-10T14:30:00-03:00, que indica 14h30 no horário de Brasília. O deslocamento final, como -03:00, -04:00 ou -05:00, precisa corresponder ao fuso da localidade do emitente. Por isso, o sistema não pode simplesmente usar o horário do servidor, que muitas vezes está configurado em UTC ou em outro fuso. ## Por que a SEFAZ pode rejeitar uma nota pela hora de emissão? A SEFAZ compara a hora informada com o momento em que recebe o documento. Se a emissão estiver no futuro em relação ao recebimento, além da pequena tolerância aceita, a nota é rejeitada. Isso costuma acontecer quando o relógio do servidor está adiantado ou quando o fuso foi informado de forma errada. Também há rejeição quando a data de emissão é antiga demais em relação ao envio. Isso pode ocorrer, por exemplo, quando uma nota fica parada em uma fila por muito tempo e é reenviada sem que a data seja atualizada. Os prazos aceitos são definidos no leiaute e nas notas técnicas vigentes. ## Qual a diferença entre hora de emissão e hora de saída ou entrada? A hora de emissão (dhEmi) indica quando o documento foi gerado. A hora de saída ou entrada (dhSaiEnt) indica quando a mercadoria efetivamente saiu do estabelecimento ou entrou nele. Esse segundo campo é opcional em várias situações. Os dois horários podem ser iguais, mas não precisam ser. Uma nota pode ser emitida pela manhã e a mercadoria sair do depósito apenas à tarde, por exemplo. ## Como tratar a hora de emissão em uma integração por API? Em uma emissão fiscal por API, o sistema de origem pode enviar a data e a hora prontas ou deixar que a plataforma de emissão as preencha no momento da geração do XML. O ideal é ter uma única fonte de horário confiável e sincronizada, sempre com o fuso correto da empresa emissora. Em reprocessamentos e novas tentativas, vale verificar se a hora original continua dentro dos limites aceitos. Em contingência, como no EPEC, a nota também registra a data e a hora de entrada em contingência, informação que deve ser coerente com a hora de emissão. ## Exemplos de Hora de emissão da NF-e - Um ERP em Manaus emite uma NF-e com dhEmi 2024-08-15T10:00:00-04:00, refletindo corretamente o fuso local de quatro horas a menos que o UTC. - Um servidor configurado em UTC envia a hora 13:00 com o fuso -03:00, quando o horário real em Brasília era 10:00. A SEFAZ interpreta que a nota foi emitida no futuro e rejeita o documento. - Uma plataforma de vendas deixa notas presas em uma fila durante dias por falha de integração. Ao reenviá-las, ajusta a hora de emissão para evitar a rejeição por data antiga demais. - Uma distribuidora emite a nota às 8h, registrando esse horário em dhEmi, e informa em dhSaiEnt as 14h, quando o caminhão deixou o depósito. ## Perguntas frequentes ### A hora de emissão é a mesma hora da autorização? Não. A hora de emissão é informada pelo emitente no XML. A hora da autorização é registrada pela SEFAZ no protocolo, depois do recebimento e da validação do documento. Normalmente, as duas ficam próximas, mas são informações diferentes. ### Posso emitir uma NF-e com data retroativa? Existe uma tolerância limitada para datas anteriores ao envio, definida no leiaute vigente. Fora desse limite, a SEFAZ rejeita a nota. Usar datas retroativas para simular operações que não ocorreram naquele momento é irregular. ### Por que o fuso horário é obrigatório no campo? O Brasil tem mais de um fuso horário. O deslocamento em relação ao UTC permite que a SEFAZ saiba exatamente o momento da emissão, sem ambiguidade, independentemente de onde a empresa ou o servidor estejam localizados. ### O que fazer se o servidor estiver com o relógio errado? Sincronize o relógio com uma fonte de horário confiável e configure o fuso correto da empresa emissora. Relógios adiantados causam rejeição por emissão no futuro, e relógios atrasados podem gerar inconsistências nos registros. ## Termos relacionados - [Fuso horário na emissão fiscal](https://conota.dev/glossario/fuso-horario-na-emissao-fiscal.md) - [Autorização de uso da NF-e](https://conota.dev/glossario/autorizacao-de-uso-da-nf-e.md) - [Protocolo de autorização](https://conota.dev/glossario/protocolo-de-autorizacao.md) - [Rejeição fiscal](https://conota.dev/glossario/rejeicao-fiscal.md) - [Leiaute fiscal](https://conota.dev/glossario/leiaute-fiscal.md) - [EPEC](https://conota.dev/glossario/epec.md) --- Fonte: [Hora de emissão da NF-e](https://conota.dev/glossario/hora-de-emissao-da-nf-e/) · Atualizado em 2026-10-22 --- # Hora de saída da mercadoria > Hora de saída da mercadoria é a informação da NF-e que registra o momento em que o produto deixa fisicamente o estabelecimento do emitente, ou entra nele, no caso de notas de entrada. Ela fica no campo de data e hora de saída/entrada do XML, aparece no DANFE e pode ser diferente da hora de emissão da nota. **Também conhecido como:** Data e hora de saída/entrada, Hora de saída/entrada da mercadoria, Hora da saída, dhSaiEnt, Goods departure date and time **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** H ## O que é a hora de saída da mercadoria na NF-e? É o registro do momento em que a mercadoria começa a circular, ou seja, quando sai do depósito, da loja ou da fábrica rumo ao destinatário. Em notas de entrada, o mesmo campo indica quando o produto entrou no estabelecimento. No XML da NF-e, essa informação fica no grupo de identificação da nota, em um campo que reúne data e hora, conhecido pela sigla técnica dhSaiEnt. No DANFE, ela aparece nos campos de data e hora de saída/entrada. ## Qual a diferença entre hora de saída e hora de emissão? A hora de emissão indica quando a nota fiscal foi gerada. A hora de saída indica quando a mercadoria efetivamente deixou o estabelecimento. Nem sempre os dois momentos coincidem. Uma empresa pode emitir a nota pela manhã e carregar o caminhão apenas à tarde, por exemplo. Nesse caso, a hora de emissão é a da manhã e a hora de saída é a da tarde. O que não deve acontecer é a mercadoria circular antes de a nota estar autorizada pela SEFAZ. ## A hora de saída é obrigatória? Na NF-e, o campo de data e hora de saída/entrada é opcional no leiaute. Muitas empresas o preenchem quando já sabem o momento do despacho e o deixam em branco quando a saída ainda não está programada. Na NFC-e, usada no varejo com entrega imediata ao consumidor, esse campo não é informado, porque a venda e a saída acontecem no mesmo momento. Regras específicas de cada estado podem existir, por isso vale confirmar com a contabilidade. ## Como a hora de saída deve ser informada no XML? O valor segue o padrão de data e hora com fuso horário, no formato ano-mês-dia, a letra T, horas, minutos, segundos e o deslocamento em relação ao UTC, como 2024-05-10T14:30:00-03:00. O fuso deve corresponder ao local do emitente. A SEFAZ valida se a data e hora informadas são coerentes com a data de emissão. Datas muito distantes, fora do intervalo permitido ou com fuso incorreto podem gerar rejeição da nota. ## Como isso funciona na emissão fiscal por API? Quando um ERP ou plataforma de vendas emite NF-e por uma API fiscal, a hora de saída costuma ser enviada como um campo opcional no JSON da requisição. A API monta o XML com o formato correto, assina e envia para a SEFAZ. Um cuidado comum é garantir que o sistema use o fuso horário certo de cada empresa emissora, principalmente quando um mesmo sistema emite para CNPJs em estados diferentes. Erros de fuso são uma causa frequente de rejeições ligadas a datas. ## Exemplos de Hora de saída da mercadoria - Um ERP de distribuidora emite a NF-e às 9h e informa como hora de saída 15h do mesmo dia, horário previsto para o carregamento do caminhão. - Um marketplace que emite notas por API deixa o campo de hora de saída em branco, porque o horário de coleta pela transportadora ainda não está definido no momento da emissão. - Uma empresa com filial em outro fuso horário passa a enviar a data e hora de saída com o deslocamento correto do local da filial e deixa de receber rejeições por data inválida. - Na nota de entrada de uma devolução, o campo registra a data e a hora em que a mercadoria retornou ao estoque da empresa. ## Perguntas frequentes ### A hora de saída pode ser anterior à hora de emissão? Não deve. A mercadoria só pode circular acompanhada de nota autorizada. Por isso, a hora de saída precisa ser igual ou posterior ao momento de emissão, e a SEFAZ pode rejeitar datas incoerentes. ### Posso corrigir a hora de saída com Carta de Correção Eletrônica? A Carta de Correção não pode alterar dados relacionados à data de emissão ou de saída da mercadoria. Se a informação estiver errada, o caminho geralmente é cancelar a nota dentro do prazo e emitir outra. ### A hora de saída aparece no DANFE? Sim. Quando informada no XML, ela é impressa nos campos de data e hora de saída/entrada do DANFE, junto com a data de emissão. ### O que acontece se eu deixar o campo vazio? Na NF-e o campo é opcional, então a nota pode ser autorizada sem ele. Confirme com a contabilidade se há exigência específica no seu estado ou operação. ## Termos relacionados - [Hora de emissão da NF-e](https://conota.dev/glossario/hora-de-emissao-da-nf-e.md) - [Fuso horário na emissão fiscal](https://conota.dev/glossario/fuso-horario-na-emissao-fiscal.md) - [DANFE](https://conota.dev/glossario/danfe.md) - [Autorização de uso da NF-e](https://conota.dev/glossario/autorizacao-de-uso-da-nf-e.md) - [Erro de validação fiscal](https://conota.dev/glossario/erro-de-validacao-fiscal.md) - [Carta de Correção Eletrônica](https://conota.dev/glossario/carta-de-correcao-eletronica.md) --- Fonte: [Hora de saída da mercadoria](https://conota.dev/glossario/hora-de-saida-da-mercadoria/) · Atualizado em 2026-10-22 --- # HSM > HSM é um equipamento físico especializado em proteger chaves criptográficas e executar operações como assinatura digital sem que a chave privada saia do dispositivo. No contexto fiscal, pode guardar certificados digitais usados para assinar documentos como NF-e e CT-e, reduzindo o risco de cópia, roubo ou uso indevido da chave. **Também conhecido como:** Módulo de Segurança de Hardware, Módulo de segurança criptográfica, Hardware Security Module, HSM **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** H ## O que é um HSM e como ele funciona? HSM é a sigla de Hardware Security Module, ou Módulo de Segurança de Hardware. Trata-se de um aparelho dedicado a gerar, guardar e usar chaves criptográficas em um ambiente isolado e resistente a ataques. Ele costuma ser instalado em data centers ou oferecido como serviço por provedores de nuvem. A ideia central é simples: a chave privada nasce dentro do HSM e nunca sai dele. Quando um sistema precisa assinar algo, envia os dados ao HSM, que faz a assinatura internamente e devolve apenas o resultado. Assim, mesmo que o servidor da aplicação seja invadido, a chave em si não pode ser copiada. Muitos HSMs também têm proteções físicas: se alguém tentar abrir o equipamento ou adulterá-lo, ele pode apagar as chaves armazenadas para impedir o acesso. ## Para que serve um HSM na emissão de documentos fiscais? Todo documento fiscal eletrônico, como NF-e, NFC-e, CT-e e MDF-e, precisa ser assinado digitalmente com um certificado da ICP-Brasil antes de ser enviado ao fisco. Essa assinatura depende de uma chave privada, que é o bem mais sensível de todo o processo. O HSM serve para guardar essa chave com o máximo de segurança e permitir que sistemas automatizados assinem grandes volumes de documentos sem que ninguém tenha acesso direto a ela. Isso é especialmente útil para empresas que emitem notas em escala ou que gerenciam certificados de muitos CNPJs. ## Qual a diferença entre HSM e certificado digital A1? O certificado A1 é um arquivo, normalmente no formato PFX, protegido por senha e instalado em computador ou servidor. É prático para automação, mas, por ser um arquivo, pode ser copiado se cair em mãos erradas. Já os certificados do tipo A3 têm a chave privada gerada e armazenada em hardware, como cartão inteligente, token USB ou HSM. Entre essas opções, o HSM é a que permite uso contínuo em servidores, sem depender de alguém conectar um token físico a uma máquina, o que facilita a emissão automatizada. ## Existe HSM na nuvem? Sim. Além dos equipamentos físicos instalados no próprio data center da empresa, há serviços de HSM em nuvem, nos quais o provedor mantém o hardware e o cliente usa as chaves por meio de interfaces de programação. Nesse modelo, a empresa ganha segurança de hardware sem precisar comprar e manter o aparelho. Também existem soluções de certificado em nuvem oferecidas por autoridades certificadoras, que usam HSMs para guardar a chave do cliente e permitem assinar remotamente, mediante autenticação. ## Toda empresa que emite notas precisa de um HSM? Não. A legislação fiscal exige assinatura com certificado ICP-Brasil, mas não obriga o uso de HSM. Muitas empresas emitem normalmente com certificado A1, desde que adotem boas práticas de armazenamento, como criptografia e gerenciamento de segredos. O HSM costuma fazer mais sentido para operações com alto volume, exigências rígidas de segurança ou auditoria, ou para plataformas que guardam certificados de vários clientes e precisam reduzir ao mínimo o risco de vazamento. ## Exemplos de HSM - Um marketplace que emite NF-e em nome de centenas de lojistas armazena as chaves privadas dos certificados em um HSM, de modo que o servidor de emissão consegue assinar os XMLs sem nunca ter acesso à chave. - Uma transportadora usa um certificado A3 guardado em HSM na nuvem para assinar CT-e e MDF-e automaticamente durante a madrugada, sem depender de um token conectado a um computador. - Uma equipe de segurança define que a chave do e-CNPJ da empresa deve ser gerada diretamente dentro do HSM, garantindo que nenhuma cópia em arquivo jamais exista. - Um ERP integrado ao emissor fiscal envia o hash do documento ao HSM, recebe a assinatura de volta e anexa o resultado ao XML antes de transmiti-lo à SEFAZ. ## Perguntas frequentes ### O que significa a sigla HSM? HSM significa Hardware Security Module, em português Módulo de Segurança de Hardware. É um dispositivo projetado para gerar, armazenar e usar chaves criptográficas com alto nível de proteção física e lógica. ### Dá para exportar a chave privada guardada em um HSM? Em geral, não. O objetivo do HSM é justamente impedir que a chave privada saia do equipamento. Por isso, é importante planejar redundância e backup conforme os recursos oferecidos pelo próprio HSM ou pelo provedor do serviço. ### HSM substitui o certificado digital? Não. O HSM é o local onde a chave do certificado fica protegida. O certificado digital continua sendo emitido por uma Autoridade Certificadora da ICP-Brasil e é ele que identifica a empresa na assinatura. ### Token USB é a mesma coisa que HSM? Não exatamente. Ambos guardam chaves em hardware, mas o token é pequeno, pessoal e precisa estar conectado a um computador. O HSM é um equipamento ou serviço de maior capacidade, feito para uso contínuo em servidores. ## Termos relacionados - [Certificado digital A1](https://conota.dev/glossario/certificado-digital-a1.md) - [Assinatura digital do XML](https://conota.dev/glossario/assinatura-digital-do-xml.md) - [Geração de chave criptográfica](https://conota.dev/glossario/geracao-de-chave-criptografica.md) - [Gerenciamento de segredos](https://conota.dev/glossario/gerenciamento-de-segredos.md) - [ICP-Brasil](https://conota.dev/glossario/icp-brasil.md) - [Arquivo PFX](https://conota.dev/glossario/arquivo-pfx.md) --- Fonte: [HSM](https://conota.dev/glossario/hsm/) · Atualizado em 2026-10-22 --- # HTTP > HTTP é o protocolo de comunicação que define como um cliente, como um navegador ou um sistema de gestão, envia pedidos a um servidor e recebe respostas pela internet. Ele organiza essas mensagens com métodos, endereços, cabeçalhos, corpo e códigos de status, e é a base do funcionamento de sites e APIs, incluindo as APIs fiscais. **Também conhecido como:** Protocolo HTTP, Protocolo de Transferência de Hipertexto, HTTP, Hypertext Transfer Protocol **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** H ## O que é HTTP, em palavras simples? HTTP é um conjunto de regras que dois sistemas seguem para conversar pela internet. Um lado faz um pedido, chamado de requisição, e o outro devolve uma resposta. É como um formulário padronizado: os dois lados sabem onde fica cada informação e como interpretá-la. A sigla vem de Hypertext Transfer Protocol, ou Protocolo de Transferência de Hipertexto. Ele nasceu para transportar páginas da web, mas hoje também é usado para trocar dados entre sistemas, como acontece quando um ERP envia uma nota fiscal para ser emitida por uma API. ## Como funciona uma requisição HTTP? Toda requisição tem algumas partes básicas: um método, que indica a ação desejada; um endereço (URL), que aponta o recurso, como um endpoint de API; cabeçalhos, que levam informações extras, como o token de autenticação e o formato dos dados; e, quando necessário, um corpo com o conteúdo enviado, frequentemente em JSON. O servidor processa o pedido e devolve uma resposta com um código de status, cabeçalhos e um corpo. Em uma API fiscal, esse corpo pode trazer o identificador do documento, seu status, o link para o XML ou o PDF, ou a descrição de um erro. ## Quais são os métodos HTTP mais usados? Os métodos mais comuns são GET, para consultar informações; POST, para criar algo novo, como solicitar a emissão de uma NF-e; PUT e PATCH, para atualizar dados existentes; e DELETE, para remover um recurso. Cada API define quais métodos aceita em cada endpoint. Na emissão fiscal, é comum usar POST para enviar o payload de emissão e GET para consultar o status do documento ou baixar o XML depois da autorização. ## O que significam os códigos de status HTTP? Os códigos de status são números de três dígitos que resumem o resultado da requisição. Os iniciados em 2 indicam sucesso, como 200 (OK), 201 (criado) e 202 (aceito para processamento). Os iniciados em 4 indicam problema no pedido, como 400 (dados inválidos), 401 (não autenticado), 404 (não encontrado) e 429 (excesso de requisições). Os iniciados em 5 indicam falha do lado do servidor. Um ponto importante na área fiscal: um código 2xx significa que a API recebeu o pedido, não necessariamente que a nota foi autorizada pela SEFAZ ou pela prefeitura. A autorização ou rejeição costuma ser informada depois, no status do documento. ## Qual a diferença entre HTTP e HTTPS? HTTP transmite as mensagens sem criptografia, o que permite que alguém no caminho leia ou altere os dados. HTTPS é o mesmo protocolo funcionando sobre uma camada de segurança chamada TLS, que criptografa a comunicação e confirma a identidade do servidor. Como integrações fiscais trafegam dados de empresas, valores, tokens e certificados, elas devem sempre usar HTTPS. Na prática, quando se fala em chamar uma API via HTTP, o tráfego real deve acontecer por HTTPS. ## Por que o HTTP é importante na emissão fiscal por API? É pelo HTTP que o sistema do cliente envia os dados da venda, recebe a confirmação de recebimento e consulta o resultado da emissão. Também é por HTTP que costumam chegar os webhooks, avisos automáticos enviados pela API quando o status de um documento muda. Entender métodos, cabeçalhos e códigos de status ajuda a tratar erros corretamente, configurar retentativas com backoff, respeitar limites de requisições e evitar emissões duplicadas com idempotência. ## Exemplos de HTTP - Um ERP faz uma requisição POST para o endpoint de emissão de NFS-e, enviando os dados do serviço em JSON e o token no cabeçalho Authorization, e recebe o código 202 indicando que o pedido entrou na fila de processamento. - Uma plataforma de vendas faz um GET periódico para consultar o status de uma NFC-e e, quando ele muda para autorizado, baixa o XML e o DANFCE. - Uma integração recebe o código HTTP 401 porque a API Key expirou ou foi digitada errada, e o time técnico identifica rapidamente que o problema está na autenticação, não nos dados da nota. - Um marketplace recebe o código 429 ao enviar muitas notas de uma vez e passa a espaçar as requisições usando backoff exponencial. ## Perguntas frequentes ### Receber código 200 significa que a nota foi autorizada? Não necessariamente. O código HTTP indica que a API recebeu e processou o pedido. A autorização pela SEFAZ ou prefeitura é informada no status do documento, que pode ser consultado depois ou recebido por webhook. ### Posso integrar uma API fiscal usando HTTP sem o S? Não é recomendado. Dados fiscais e credenciais precisam trafegar criptografados, por isso as integrações devem usar HTTPS, que protege a comunicação com TLS. ### HTTP é a mesma coisa que REST? Não. HTTP é o protocolo de comunicação. REST é um estilo de construir APIs que normalmente usa HTTP, aproveitando seus métodos, URLs e códigos de status de forma organizada. ### Preciso saber programar para entender HTTP? Não para entender o conceito. Saber o que são métodos, cabeçalhos e códigos de status já ajuda a interpretar erros e conversar com o time técnico sobre a integração. ## Termos relacionados - [HTTPS](https://conota.dev/glossario/https.md) - [REST](https://conota.dev/glossario/rest.md) - [Endpoint de API](https://conota.dev/glossario/endpoint-de-api.md) - [Header de autenticação](https://conota.dev/glossario/header-de-autenticacao.md) - [JSON](https://conota.dev/glossario/json.md) - [TLS](https://conota.dev/glossario/tls.md) --- Fonte: [HTTP](https://conota.dev/glossario/http/) · Atualizado em 2026-10-22 --- # HTTP 429 na integração fiscal > HTTP 429 na integração fiscal é o código de resposta Too Many Requests, devolvido quando um sistema envia requisições demais em pouco tempo para uma API de emissão de notas. Ele indica que o limite de uso foi atingido e que o cliente deve aguardar antes de tentar novamente, sem que isso signifique erro no documento fiscal. **Também conhecido como:** Erro 429, Too Many Requests, Status 429, Limite de requisições excedido, HTTP 429 Too Many Requests **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** H ## O que significa receber um HTTP 429 ao emitir notas fiscais? Toda resposta de uma API vem acompanhada de um código numérico do protocolo HTTP. O código 429, chamado Too Many Requests (muitas requisições), avisa que o sistema cliente ultrapassou a quantidade de chamadas permitida em determinado intervalo de tempo. Na integração fiscal, isso costuma acontecer quando um ERP, marketplace ou plataforma de vendas dispara muitas emissões, consultas de status ou downloads de XML ao mesmo tempo. A requisição recusada não foi processada: a nota não foi enviada ao fisco, nem rejeitada por ele. O pedido apenas precisa ser repetido mais tarde. ## Por que uma API fiscal limita a quantidade de requisições? O limite, conhecido como rate limit, protege a estabilidade do serviço. Sem ele, um único cliente com um laço de repetição defeituoso ou um pico de vendas poderia sobrecarregar a infraestrutura e atrasar a emissão de todos os outros usuários. Além disso, os próprios sistemas do fisco, como as SEFAZ e as prefeituras, têm capacidade limitada e regras contra consumo excessivo. Controlar o volume na camada da API ajuda a evitar que o emissor seja bloqueado ou penalizado por enviar consultas repetidas sem necessidade. ## Como tratar corretamente um HTTP 429? O primeiro passo é não reenviar imediatamente. Muitas APIs informam no cabeçalho Retry-After quantos segundos o cliente deve esperar. Quando esse cabeçalho existir, ele deve ser respeitado. Se não houver indicação, a prática recomendada é o backoff exponencial: esperar um pouco antes da primeira nova tentativa e aumentar o intervalo a cada falha seguida. Somar um pequeno valor aleatório ao tempo de espera, o chamado jitter, evita que vários processos tentem de novo exatamente no mesmo instante. Como a requisição original pode ser repetida, é importante usar idempotência: enviar uma chave única por documento, para que uma nova tentativa nunca gere uma nota duplicada. ## Qual a diferença entre HTTP 429 e uma rejeição da SEFAZ? O HTTP 429 acontece antes de o documento chegar ao fisco. É um controle de tráfego da API, e a solução é esperar e tentar de novo, sem alterar nada no conteúdo da nota. Uma rejeição da SEFAZ ou da prefeitura ocorre depois que o documento foi analisado e algum dado foi considerado inválido, como um CFOP incorreto ou uma inscrição estadual irregular. Nesse caso, repetir o envio sem corrigir a informação não resolve: é preciso ajustar os dados. ## Como evitar receber HTTP 429 com frequência? Uma boa estratégia é organizar as emissões em uma fila, enviando documentos em ritmo controlado em vez de disparar todos de uma vez. Em fechamentos de mês ou grandes promoções, isso evita picos desnecessários. Outra medida é trocar consultas repetidas de status por notificações automáticas, como webhooks, em um fluxo assíncrono de emissão. Assim, o sistema não precisa perguntar a cada segundo se a nota foi autorizada: ele é avisado quando o resultado estiver pronto. ## Exemplos de HTTP 429 na integração fiscal - Um e-commerce em dia de grande promoção tenta emitir centenas de NFC-e por minuto, recebe HTTP 429 em parte das chamadas e passa a reenviá-las a partir de uma fila, respeitando o tempo indicado no cabeçalho Retry-After. - Um ERP consultava o status de cada NF-e a cada segundo até a autorização; após receber vários HTTP 429, a equipe substituiu as consultas por webhooks e o erro deixou de ocorrer. - Uma plataforma de serviços que emite NFS-e para muitos CNPJs no fechamento do mês aplica backoff exponencial com jitter, evitando que todos os processos tentem novamente ao mesmo tempo. - Um desenvolvedor percebe que um laço de repetição sem pausa estava disparando a mesma requisição de download de XML continuamente, gerando HTTP 429 em sequência. ## Perguntas frequentes ### Receber HTTP 429 significa que a nota fiscal foi rejeitada? Não. A requisição foi recusada pela API antes de qualquer processamento, então o documento não chegou ao fisco. Basta aguardar o tempo indicado e reenviar, de preferência com a mesma chave de idempotência. ### Quanto tempo devo esperar antes de tentar novamente? Se a resposta trouxer o cabeçalho Retry-After, siga o valor informado. Caso contrário, use backoff exponencial, aumentando o intervalo a cada nova falha e adicionando um pequeno atraso aleatório. ### Reenviar após um HTTP 429 pode gerar nota duplicada? Em geral não, pois a requisição recusada não foi processada. Ainda assim, usar idempotência é a forma segura de garantir que nenhuma nova tentativa crie um segundo documento para a mesma venda. ### O HTTP 429 tem relação com a franquia do plano? Não necessariamente. O 429 trata da velocidade das requisições em um curto intervalo, enquanto a franquia se refere à quantidade de documentos no mês. São controles diferentes. ## Termos relacionados - [HTTP](https://conota.dev/glossario/http.md) - [Backoff exponencial](https://conota.dev/glossario/backoff-exponencial.md) - [Jitter nas retentativas de requisição](https://conota.dev/glossario/jitter-nas-retentativas-de-requisicao.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) --- Fonte: [HTTP 429 na integração fiscal](https://conota.dev/glossario/http-429-na-integracao-fiscal/) · Atualizado em 2026-10-22 --- # HTTPS > HTTPS é a versão segura do protocolo HTTP, usada para trocar dados entre sistemas e servidores na internet de forma criptografada. Ele combina o HTTP com o TLS, garantindo que as informações não sejam lidas nem alteradas no caminho e que o servidor acessado seja realmente quem diz ser. É obrigatório em integrações fiscais por API. **Também conhecido como:** HTTP seguro, HTTP sobre TLS, HTTP over TLS, HTTP sobre SSL, HTTPS, Hypertext Transfer Protocol Secure **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** H ## O que é HTTPS, em termos simples? HTTPS significa Hypertext Transfer Protocol Secure, ou protocolo de transferência de hipertexto seguro. É o mesmo HTTP usado para navegar em sites e chamar APIs, mas com uma camada de proteção adicional chamada TLS. Imagine que o HTTP é um cartão-postal: qualquer pessoa no caminho pode ler o que está escrito. O HTTPS coloca esse conteúdo dentro de um envelope lacrado, que só o destinatário consegue abrir. Por isso, endereços que começam com https:// indicam uma conexão protegida. ## Como o HTTPS funciona? Antes de qualquer dado ser enviado, o cliente (por exemplo, um ERP) e o servidor fazem uma negociação inicial, chamada handshake. Nela, o servidor apresenta um certificado digital que comprova sua identidade, e os dois lados combinam chaves de criptografia exclusivas para aquela conexão. A partir daí, tudo o que trafega, incluindo cabeçalhos, tokens de autenticação e o corpo da requisição, segue criptografado. Se alguém interceptar a comunicação, verá apenas dados embaralhados, sem utilidade. ## Por que o HTTPS é essencial na emissão fiscal por API? Uma requisição de emissão fiscal carrega informações sensíveis: dados de clientes, valores de venda, CNPJs, tributos e, em alguns casos, o próprio certificado digital A1 convertido em Base64. Transmitir isso sem criptografia exporia a empresa a vazamentos e fraudes. Além disso, credenciais como API Key ou Bearer token vão no header de autenticação de cada chamada. Sem HTTPS, essas chaves poderiam ser capturadas e usadas por terceiros para emitir ou cancelar notas em nome da empresa. Por isso, APIs fiscais sérias recusam conexões que não sejam HTTPS. ## Qual a diferença entre HTTP, HTTPS e TLS? O HTTP define as regras da conversa entre cliente e servidor: métodos como GET e POST, códigos de status e formato das mensagens. O TLS é o protocolo de segurança responsável pela criptografia e pela verificação de identidade. O HTTPS é justamente a união dos dois: o HTTP funcionando por cima de uma conexão TLS. Já o mTLS é uma variação em que, além do servidor, o cliente também apresenta um certificado para provar quem é. ## O HTTPS também vale para webhooks? Sim. Quando a API fiscal avisa o sistema do cliente que uma nota foi autorizada ou rejeitada, ela envia uma requisição para uma URL de webhook. Essa URL deve usar HTTPS para que o status, o XML e outros dados cheguem protegidos. Para reforçar a segurança, muitos provedores combinam HTTPS com assinatura HMAC nos webhooks, permitindo ao sistema receptor confirmar que a mensagem veio mesmo da API e não foi alterada. ## Exemplos de HTTPS - Um ERP envia o payload de emissão de uma NF-e para o endpoint https://api.exemplo.com/nfe, e todos os dados da venda trafegam criptografados até a API fiscal. - Uma plataforma de serviços cadastra a URL https://minhaplataforma.com/webhooks/nfse para receber automaticamente o status de autorização das NFS-e emitidas. - Um desenvolvedor tenta chamar a API usando http:// por engano e recebe um erro, pois o servidor só aceita conexões HTTPS. - Ao enviar um certificado digital A1 em Base64 para cadastro de uma nova empresa emissora, o arquivo é protegido pela criptografia do HTTPS durante o envio. ## Perguntas frequentes ### Posso integrar uma API fiscal usando apenas HTTP? Não é recomendado e, em geral, não é permitido. APIs fiscais costumam aceitar somente HTTPS, porque as requisições levam credenciais, dados de clientes e informações tributárias que precisam ser protegidas contra interceptação. ### O HTTPS deixa a integração mais lenta? O impacto é pequeno. Existe um custo no handshake inicial, mas recursos como keep-alive reaproveitam a conexão em várias requisições, tornando a diferença de latência praticamente imperceptível no dia a dia. ### O certificado do HTTPS é o mesmo certificado digital A1 da empresa? Não. O certificado do HTTPS identifica o servidor e protege a conexão. O certificado A1 identifica a empresa emissora e é usado para assinar digitalmente o XML dos documentos fiscais. ### Só usar HTTPS já garante a segurança da integração? Não sozinho. O HTTPS protege o transporte dos dados, mas também é preciso guardar bem as chaves de API, controlar permissões de acesso, validar webhooks e fazer rotação periódica de credenciais. ## Termos relacionados - [HTTP](https://conota.dev/glossario/http.md) - [TLS](https://conota.dev/glossario/tls.md) - [mTLS](https://conota.dev/glossario/mtls.md) - [Header de autenticação](https://conota.dev/glossario/header-de-autenticacao.md) - [HMAC em webhooks](https://conota.dev/glossario/hmac-em-webhooks.md) - [Endpoint de API](https://conota.dev/glossario/endpoint-de-api.md) --- Fonte: [HTTPS](https://conota.dev/glossario/https/) · Atualizado em 2026-10-22