# Glossário de A a Z — letra W > 19 termos. Glossário compacto: https://conota.dev/glossario/llms-full.txt --- # WAF na proteção de APIs > WAF na proteção de APIs é o uso de um firewall de aplicação web (Web Application Firewall) para inspecionar as requisições HTTP enviadas a uma API e bloquear tráfego malicioso, como injeções de código, abusos de volume e chamadas fora do padrão, antes que cheguem ao sistema. Em APIs fiscais, ajuda a proteger dados de empresas e documentos emitidos. **Também conhecido como:** Firewall de aplicação web, Firewall de aplicações web, WAF para APIs, Web Application Firewall, WAF **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** W ## O que é um WAF, em palavras simples? Um WAF funciona como um porteiro que fica na entrada de uma aplicação na internet. Cada pedido que chega, chamado de requisição, é examinado antes de seguir adiante. Se parece legítimo, passa. Se tem cara de ataque, é barrado ou registrado para análise. A diferença em relação a um firewall comum é o nível de detalhe. O WAF não olha apenas de onde vem o tráfego, mas também o que está dentro dele: o endereço chamado, os cabeçalhos, os parâmetros e o corpo da mensagem. ## Como o WAF funciona na frente de uma API? O WAF é posicionado entre a internet e os servidores da API, muitas vezes junto a um balanceador de carga, a uma rede de distribuição de conteúdo ou a um gateway de API. Toda chamada a um endpoint passa primeiro por ele. A análise é feita com base em regras. Algumas são genéricas e detectam padrões de ataque conhecidos. Outras são criadas sob medida para a API, como aceitar apenas determinados métodos HTTP em cada rota, limitar o tamanho do payload ou bloquear países e endereços IP suspeitos. Quando uma regra é acionada, o WAF pode bloquear a requisição, exigir uma verificação adicional, apenas registrar o evento em log ou aplicar limites de volume. Muitas equipes começam em modo de monitoramento para ajustar as regras antes de bloquear de fato. ## Que tipos de ameaça o WAF ajuda a bloquear? Os casos mais comuns são tentativas de injeção, em que o atacante envia comandos escondidos em campos de texto para manipular o banco de dados ou o servidor. Também entram nessa lista scripts maliciosos, varreduras automáticas em busca de rotas vulneráveis e requisições malformadas feitas para causar erros. O WAF também ajuda contra abusos de volume, como robôs que disparam milhares de chamadas para testar senhas e chaves de API ou para sobrecarregar o serviço. Nesses casos, ele costuma trabalhar em conjunto com o limite de requisições da própria API. ## Qual a diferença entre WAF, firewall de rede e gateway de API? O firewall de rede controla o tráfego por endereços e portas, sem entender o conteúdo das mensagens. O WAF atua na camada da aplicação e entende HTTP, por isso consegue identificar um ataque escondido dentro de uma requisição aparentemente normal. O gateway de API tem outro foco: rotear chamadas, autenticar clientes, aplicar cotas e versionar endpoints. Alguns gateways oferecem recursos de WAF, e alguns WAFs oferecem limites de volume, mas as funções são complementares. Em arquiteturas maduras, os três costumam coexistir. ## Por que o WAF é importante em APIs fiscais? Uma API fiscal recebe dados sensíveis, como CNPJs, valores de vendas, informações de clientes e, em alguns fluxos, certificados digitais. Ela também dispara ações com efeito legal, como emitir ou cancelar uma NF-e, NFC-e ou NFS-e. Uma chamada indevida pode gerar documento fiscal real em nome de uma empresa. Por isso, além de autenticação forte, é útil ter uma camada que filtre tráfego estranho antes que ele chegue à lógica de emissão. O WAF reduz a superfície de ataque, protege a disponibilidade em horários de pico de vendas e gera registros que apoiam a investigação de incidentes. ## O WAF substitui autenticação e outras proteções? Não. O WAF é uma camada extra, não um substituto. A API continua precisando de HTTPS, tokens ou chaves de acesso bem protegidos, permissões por usuário, validação de dados e trilha de auditoria. Um atacante com uma chave de API válida, por exemplo, pode enviar requisições que parecem totalmente normais para o WAF. Também é preciso manutenção: regras muito rígidas podem bloquear integrações legítimas, os chamados falsos positivos. Ajustar o WAF com base nos logs e no comportamento real dos clientes faz parte do trabalho contínuo de segurança. ## Exemplos de WAF na proteção de APIs - Um ERP envia uma requisição de emissão de NF-e com um campo de descrição de produto contendo trechos de comando de banco de dados; o WAF identifica o padrão de injeção e bloqueia a chamada antes que ela chegue à API fiscal. - Durante uma promoção, um robô começa a disparar milhares de tentativas de autenticação com chaves de API aleatórias; o WAF detecta o volume anormal vindo dos mesmos endereços e passa a recusar essas requisições. - Uma plataforma de vendas configura o WAF para aceitar apenas os métodos POST e GET nos endpoints de emissão e consulta, rejeitando automaticamente qualquer outro método enviado a essas rotas. - A equipe de infraestrutura ativa novas regras do WAF em modo de monitoramento por alguns dias, analisa os logs para ver se integrações legítimas de clientes seriam afetadas e só depois passa a bloquear. ## Perguntas frequentes ### WAF é só para sites ou também serve para APIs? Serve para ambos. Como APIs também funcionam sobre HTTP, o WAF consegue inspecionar suas requisições. Para APIs, costuma-se ajustar regras ao formato JSON, aos endpoints existentes e ao volume esperado de chamadas de cada cliente. ### O WAF deixa a API mais lenta? Ele adiciona uma etapa de inspeção, o que pode acrescentar um pequeno tempo à resposta. Em geral, o impacto é baixo quando o WAF está bem dimensionado e próximo da aplicação, e é compensado pela proteção contra abusos que derrubariam o serviço. ### Quem usa uma API fiscal precisa configurar um WAF? Normalmente o WAF fica a cargo de quem opera a API. Quem integra precisa proteger seu próprio sistema e suas credenciais. Se a sua aplicação também expõe APIs na internet, vale considerar um WAF próprio. ### O que é falso positivo em um WAF? É quando o WAF bloqueia uma requisição legítima por confundi-la com um ataque, como um texto de produto que lembra um comando. Isso se resolve ajustando regras com base nos logs. ## Termos relacionados - [Gateway de API fiscal](https://conota.dev/glossario/gateway-de-api-fiscal.md) - [Limite de requisições](https://conota.dev/glossario/limite-de-requisicoes.md) - [HTTPS](https://conota.dev/glossario/https.md) - [mTLS](https://conota.dev/glossario/mtls.md) - [Endpoint de API](https://conota.dev/glossario/endpoint-de-api.md) - [Observabilidade da API fiscal](https://conota.dev/glossario/observabilidade-da-api-fiscal.md) --- Fonte: [WAF na proteção de APIs](https://conota.dev/glossario/waf-na-protecao-de-apis/) · Atualizado em 2026-10-22 --- # Web Crypto API > Web Crypto API é uma interface padrão, presente nos navegadores modernos e em ambientes como Node.js, que permite a programas em JavaScript realizar operações criptográficas, como gerar hashes, criar e verificar assinaturas digitais, cifrar dados e gerar chaves, sem depender de bibliotecas externas. Ela é usada em integrações que exigem segurança, inclusive em sistemas fiscais. **Também conhecido como:** WebCrypto, Web Cryptography API, SubtleCrypto, crypto.subtle, Web Crypto API **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** W ## O que é a Web Crypto API, em palavras simples? A Web Crypto API é um conjunto de funções de criptografia que já vem embutido no navegador e em alguns ambientes de servidor que rodam JavaScript. Em vez de o desenvolvedor instalar uma biblioteca de terceiros para proteger dados, ele usa recursos nativos, padronizados pelo W3C e mantidos pelos próprios navegadores. No código, ela costuma aparecer como crypto.subtle, que reúne as operações mais sensíveis, e crypto.getRandomValues, que gera números aleatórios seguros. Todas as operações principais são assíncronas, ou seja, devolvem o resultado depois de processar, sem travar a aplicação. ## Para que serve a Web Crypto API? Ela serve para tarefas criptográficas comuns: calcular hashes (por exemplo, SHA-256), assinar e verificar dados com algoritmos como RSA e ECDSA, cifrar e decifrar informações com AES, gerar códigos HMAC e criar, importar ou exportar chaves em formatos como JWK, PKCS#8 e SPKI. Em integrações fiscais, esses recursos ajudam a conferir a integridade de um arquivo XML, validar a assinatura HMAC de um webhook recebido, gerar identificadores aleatórios para controle de idempotência ou proteger informações sensíveis antes de armazená-las. ## Como a Web Crypto API se relaciona com a emissão de notas fiscais? Documentos como NF-e, NFC-e, CT-e e MDF-e precisam ser assinados digitalmente com um certificado da ICP-Brasil, seguindo o padrão de assinatura XML. A Web Crypto API consegue executar a parte matemática da assinatura RSA, mas não faz sozinha a preparação do XML exigida pelo padrão, como a canonicalização, nem lê diretamente um arquivo PFX. Por isso, ela costuma ser apenas uma peça do processo, combinada com outras bibliotecas. Em soluções como uma API fiscal, a assinatura e a comunicação com a SEFAZ ou com a prefeitura ficam a cargo do serviço de emissão, e o sistema do cliente usa criptografia principalmente para validar respostas e proteger a integração. ## É seguro usar a Web Crypto API no navegador para assinar documentos fiscais? A API em si é confiável, mas o local onde a chave fica é o ponto crítico. Carregar a chave privada de um certificado digital A1 no navegador de um usuário expõe esse segredo a riscos, como extensões maliciosas ou scripts injetados. Na prática fiscal, o recomendado é manter o certificado no backend, em um cofre de segredos ou em um HSM. A Web Crypto API ajuda com recursos como chaves marcadas como não extraíveis, que podem ser usadas, mas não exportadas pelo código. Além disso, ela só funciona em contextos seguros, isto é, páginas servidas por HTTPS ou em ambiente local de desenvolvimento. ## Qual a diferença entre a Web Crypto API e bibliotecas de criptografia? A Web Crypto API é nativa e padronizada: não precisa ser instalada, tem implementação otimizada e recebe correções junto com o navegador ou o runtime. Em contrapartida, oferece um conjunto limitado de algoritmos e operações de baixo nível. Bibliotecas de criptografia e de emissão fiscal costumam acrescentar recursos que a API não cobre, como leitura de certificados PFX, montagem de assinaturas XML e tratamento de cadeias de certificação. Muitas delas usam a própria Web Crypto API por baixo para as operações matemáticas. ## Exemplos de Web Crypto API - Um ERP em Node.js recebe um webhook de status de NF-e e usa crypto.subtle com HMAC SHA-256 para conferir se a assinatura do cabeçalho confere com o segredo compartilhado antes de atualizar o pedido. - Uma plataforma de vendas calcula o hash SHA-256 do XML autorizado de uma NFS-e e o guarda junto ao registro, para verificar depois que o arquivo armazenado não foi alterado. - Um painel web gera um identificador aleatório com crypto.randomUUID para usar como chave de idempotência ao solicitar a emissão de uma NFC-e, evitando notas duplicadas em caso de reenvio. - Um backend importa uma chave pública no formato JWK pela Web Crypto API para validar a assinatura de um JWT recebido em uma chamada interna da integração fiscal. ## Perguntas frequentes ### A Web Crypto API funciona fora do navegador? Sim. Ambientes como Node.js, Deno e alguns serviços de computação na borda oferecem a mesma interface, o que permite reaproveitar o código criptográfico entre frontend e backend. ### Posso carregar um arquivo PFX direto na Web Crypto API? Não diretamente. A API não interpreta o formato PKCS#12. É preciso extrair a chave privada com outra biblioteca e importá-la, por exemplo, em PKCS#8. Em sistemas fiscais, o mais seguro é deixar o certificado no backend ou no serviço de emissão. ### A Web Crypto API assina sozinha o XML de uma NF-e? Não. Ela executa a assinatura RSA, mas a assinatura de XML fiscal exige etapas adicionais, como canonicalização e montagem da estrutura de assinatura, normalmente feitas por bibliotecas específicas ou pela API fiscal. ### Por que a Web Crypto API exige HTTPS? Porque operações criptográficas só fazem sentido em um canal protegido. Em páginas sem HTTPS, um intermediário poderia alterar o código e comprometer chaves e dados, então os navegadores restringem a API a contextos seguros. ## Termos relacionados - [Assinatura digital do XML](https://conota.dev/glossario/assinatura-digital-do-xml.md) - [Hash de documento fiscal](https://conota.dev/glossario/hash-de-documento-fiscal.md) - [HMAC em webhooks](https://conota.dev/glossario/hmac-em-webhooks.md) - [Geração de chave criptográfica](https://conota.dev/glossario/geracao-de-chave-criptografica.md) - [JavaScript na integração fiscal](https://conota.dev/glossario/javascript-na-integracao-fiscal.md) - [Gerenciamento de segredos](https://conota.dev/glossario/gerenciamento-de-segredos.md) --- Fonte: [Web Crypto API](https://conota.dev/glossario/web-crypto-api/) · Atualizado em 2026-10-22 --- # Web PKI > Web PKI é o conjunto de autoridades certificadoras, regras e certificados digitais que garante conexões seguras na internet, como as feitas por HTTPS. Ela permite que navegadores, sistemas e APIs confirmem que estão falando com o servidor verdadeiro e que os dados trafegam criptografados, sem interceptação ou alteração no caminho. **Também conhecido como:** PKI da Web, Infraestrutura de chaves públicas da Web, PKI pública da internet, Web Public Key Infrastructure **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** W ## O que significa Web PKI? PKI é a sigla em inglês para infraestrutura de chaves públicas. É o sistema que define quem pode emitir certificados digitais, como eles são verificados e em quem se deve confiar. A Web PKI é a versão dessa infraestrutura usada na internet aberta, principalmente para proteger sites e APIs. Na prática, quando aparece o cadeado no navegador ou quando um sistema chama uma API por HTTPS, é a Web PKI que está por trás, confirmando que o endereço acessado pertence de fato a quem diz pertencer. ## Como funciona a Web PKI? Cada servidor seguro possui um certificado digital emitido por uma autoridade certificadora. Esse certificado associa o nome do domínio, como api.exemplo.com.br, a uma chave pública. Ao iniciar a conexão, o servidor apresenta o certificado e prova que tem a chave privada correspondente. O cliente, seja um navegador ou um sistema, verifica a cadeia de certificação: o certificado do servidor foi assinado por uma autoridade intermediária, que por sua vez foi assinada por uma autoridade raiz. Se essa raiz estiver na lista de confiança do sistema operacional, do navegador ou da linguagem de programação, a conexão é aceita. Essa lista de raízes confiáveis, chamada de trust store, é mantida pelos fabricantes de sistemas e navegadores, que exigem das autoridades certificadoras o cumprimento de regras rígidas de segurança e auditoria. ## Para que serve a Web PKI em integrações fiscais? Toda emissão fiscal por API trafega dados sensíveis: CNPJs, valores, itens vendidos, dados de clientes e, em alguns casos, o próprio certificado da empresa. A Web PKI garante que o ERP ou a plataforma de vendas está enviando essas informações ao servidor correto da API fiscal, e não a um intermediário mal-intencionado. Ela também protege o caminho de volta, quando a API devolve XML, PDF e status de autorização, e as notificações por webhook enviadas ao sistema do cliente, que normalmente exigem um endpoint HTTPS com certificado válido. ## Qual a diferença entre Web PKI e ICP-Brasil? A Web PKI é voltada à segurança de conexões na internet e é reconhecida automaticamente pelos navegadores e sistemas do mundo todo. Seus certificados identificam domínios, como o endereço de um site ou de uma API. A ICP-Brasil é a infraestrutura de chaves públicas oficial do Brasil, criada para dar validade jurídica a assinaturas e identificar pessoas e empresas. É dela que vêm o e-CNPJ e o certificado digital A1 usados para assinar o XML de NF-e, NFC-e, CT-e e MDF-e. Em resumo: a Web PKI responde à pergunta estou falando com o servidor certo, enquanto a ICP-Brasil responde à pergunta quem assinou este documento. Uma integração fiscal costuma usar as duas ao mesmo tempo. ## Por que podem surgir erros de certificado ao conectar com a SEFAZ? Alguns serviços governamentais usam certificados de servidor emitidos dentro da ICP-Brasil, e não por autoridades presentes nas listas padrão da Web PKI. Nesses casos, um sistema que confia apenas nas raízes padrão pode recusar a conexão com mensagens como certificado não confiável ou falha na validação da cadeia. A solução usual é adicionar a cadeia da ICP-Brasil à lista de confiança da aplicação, com cuidado para não desativar a verificação de certificados, o que abriria brecha para ataques. Ao usar uma API fiscal intermediária, essa complexidade fica do lado do provedor, e o sistema do cliente conversa apenas com um endpoint protegido pela Web PKI comum. ## Exemplos de Web PKI - Um ERP envia uma requisição de emissão de NF-e para a API fiscal por HTTPS; antes de transmitir os dados, a biblioteca HTTP valida o certificado do servidor pela Web PKI. - Uma plataforma de e-commerce cadastra a URL do seu webhook para receber o status das NFC-e, e a API só aceita endereços HTTPS com certificado válido emitido por autoridade reconhecida. - Um desenvolvedor recebe erro de cadeia de certificação ao chamar diretamente um web service estadual e percebe que o certificado do servidor pertence à ICP-Brasil, não às raízes padrão da Web PKI. - A equipe de infraestrutura monitora a data de expiração do certificado TLS do endpoint que recebe notificações fiscais, para evitar que a renovação atrasada interrompa o recebimento de XMLs. ## Perguntas frequentes ### Web PKI e HTTPS são a mesma coisa? Não. HTTPS é o protocolo que criptografa a comunicação. A Web PKI é a estrutura de confiança que fornece e valida os certificados usados pelo HTTPS para provar a identidade do servidor. ### O certificado A1 da empresa faz parte da Web PKI? Não. O certificado A1 é emitido no âmbito da ICP-Brasil e serve para assinar documentos fiscais e identificar a empresa. Os certificados da Web PKI identificam domínios e protegem conexões. ### Posso desativar a verificação de certificado para resolver um erro de conexão? Não é recomendado. Desativar a verificação permite que um invasor se passe pelo servidor e capture dados fiscais. O correto é ajustar a lista de raízes confiáveis ou corrigir o certificado do servidor. ### O que acontece se o certificado TLS de um servidor expirar? Clientes que seguem as regras da Web PKI passam a recusar a conexão. Em integrações fiscais, isso pode interromper emissões, consultas ou o recebimento de webhooks até a renovação. ## Termos relacionados - [HTTPS](https://conota.dev/glossario/https.md) - [Autoridade Certificadora](https://conota.dev/glossario/autoridade-certificadora.md) - [Cadeia de certificação digital](https://conota.dev/glossario/cadeia-de-certificacao-digital.md) - [Hierarquia de certificados digitais](https://conota.dev/glossario/hierarquia-de-certificados-digitais.md) - [ICP-Brasil](https://conota.dev/glossario/icp-brasil.md) - [AC Raiz da ICP-Brasil](https://conota.dev/glossario/ac-raiz-da-icp-brasil.md) --- Fonte: [Web PKI](https://conota.dev/glossario/web-pki/) · Atualizado em 2026-10-22 --- # Web service fiscal > Web service fiscal é o serviço eletrônico disponibilizado por órgãos do governo, como as SEFAZ e as prefeituras, para receber, validar e autorizar documentos fiscais pela internet. Sistemas de empresas se comunicam com ele enviando arquivos XML assinados digitalmente, geralmente pelo protocolo SOAP, e recebem respostas como autorização, rejeição ou consulta de status. **Também conhecido como:** Webservice fiscal, Web service da SEFAZ, Serviço web fiscal, Web service do autorizador, Web service **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** W ## O que é um web service fiscal, em termos simples? Pense no web service fiscal como um balcão de atendimento do Fisco que funciona pela internet, sem pessoas do outro lado. Em vez de levar um papel até uma repartição, o sistema da empresa envia um arquivo eletrônico. O serviço do governo analisa esse arquivo e devolve uma resposta automática. É por meio desses serviços que documentos como NF-e, NFC-e, CT-e, MDF-e e NFS-e ganham validade jurídica. Uma nota só passa a valer depois que o web service do órgão responsável a recebe, confere as regras e registra a autorização. ## Como funciona a comunicação com um web service fiscal? O sistema emissor monta o documento em XML, seguindo o leiaute oficial, e o assina com o certificado digital da empresa. Em seguida, envia esse conteúdo para um endereço específico do órgão autorizador, normalmente usando o protocolo SOAP sobre HTTPS. A conexão costuma exigir autenticação mútua: o servidor do governo verifica o certificado da empresa e a empresa verifica o certificado do servidor, mecanismo conhecido como mTLS. Depois do processamento, o web service responde com um código de status e uma mensagem, indicando se o documento foi autorizado, rejeitado ou se ainda está em processamento. Em alguns casos o retorno é imediato. Em outros, o serviço entrega apenas um recibo, e o sistema precisa consultar depois para saber o resultado final, num fluxo assíncrono. ## Quais serviços um web service fiscal oferece? Cada operação tem o seu próprio serviço. No caso da NF-e, por exemplo, há serviços para autorizar notas, consultar o resultado de um lote, consultar a situação de uma nota pela chave de acesso, verificar se o próprio serviço está no ar, registrar eventos como cancelamento e carta de correção, inutilizar faixas de numeração e distribuir documentos emitidos contra um CNPJ. Os outros documentos seguem lógica parecida, com serviços adaptados às suas particularidades, como o encerramento do MDF-e ou os eventos específicos do CT-e. ## Quem disponibiliza os web services fiscais? Para documentos estaduais, como NF-e, NFC-e, CT-e e MDF-e, os serviços são mantidos pelas Secretarias da Fazenda. Alguns estados operam estrutura própria, enquanto outros usam autorizadores compartilhados. Também existem serviços de contingência, como a SVC, usados quando o autorizador principal fica indisponível. Para a NFS-e, a situação é mais variada: cada prefeitura pode ter seu próprio serviço, com regras e formatos diferentes, além do ambiente do Padrão Nacional da NFS-e. Em quase todos os casos há dois ambientes separados: homologação, para testes sem valor fiscal, e produção, para documentos reais. ## Qual a diferença entre web service fiscal e API fiscal? O web service fiscal é o serviço oficial do governo, com as regras, formatos e protocolos definidos pelo Fisco. Já uma API fiscal é uma camada intermediária, oferecida por um fornecedor, que conversa com esses web services em nome da empresa. Na prática, a API fiscal costuma receber dados em JSON por uma interface REST, mais simples para desenvolvedores, e se encarrega de gerar o XML, assinar, escolher o endereço correto, tratar contingências e devolver XML, PDF e status. Assim, o sistema da empresa não precisa lidar diretamente com dezenas de serviços diferentes. ## Por que integrar diretamente com web services fiscais é trabalhoso? Os leiautes mudam com frequência por meio de notas técnicas, os endereços variam por estado e município, e os serviços podem ficar instáveis ou lentos em horários de pico. Isso exige tratamento de timeouts, novas tentativas, contingência e monitoramento constante. Além disso, é preciso gerenciar certificados digitais com segurança, interpretar códigos de rejeição e manter compatibilidade com padrões municipais distintos de NFS-e. Por isso, muitas empresas preferem usar uma API fiscal que concentra esse trabalho em uma única integração. ## Exemplos de Web service fiscal - Um ERP envia o XML assinado de uma NF-e ao web service de autorização da SEFAZ do estado do emitente e recebe de volta o protocolo de autorização. - Antes de emitir notas em lote, um sistema consulta o serviço de status da SEFAZ para confirmar que o autorizador está operando normalmente. - Uma plataforma de serviços precisa emitir NFS-e em vários municípios e descobre que cada prefeitura tem um web service com formato e regras próprias. - Quando o web service da SEFAZ fica fora do ar, o emissor passa a enviar as notas para o serviço de contingência SVC, conforme as regras previstas. ## Perguntas frequentes ### Preciso de certificado digital para usar um web service fiscal? Sim, na grande maioria dos casos. O certificado é usado para assinar o XML e para autenticar a conexão com o servidor do órgão autorizador. O tipo mais comum em integrações automatizadas é o certificado A1. ### Todo web service fiscal usa SOAP? Não. Os serviços estaduais de NF-e, NFC-e, CT-e e MDF-e tradicionalmente usam SOAP com XML, mas há serviços de NFS-e com outros formatos, incluindo interfaces mais modernas no Padrão Nacional da NFS-e. ### O que acontece se o web service fiscal ficar fora do ar? O documento não pode ser autorizado naquele momento. O emissor pode aguardar e tentar de novo ou, quando permitido, usar modalidades de contingência, como a SVC ou o EPEC, conforme o tipo de documento. ### Posso testar a integração sem emitir notas reais? Sim. Os órgãos mantêm um ambiente de homologação, em que os documentos são processados normalmente, mas não têm valor fiscal. Depois dos testes, a empresa passa a usar o ambiente de produção. ## Termos relacionados - [SOAP](https://conota.dev/glossario/soap.md) - [SEFAZ](https://conota.dev/glossario/sefaz.md) - [API fiscal](https://conota.dev/glossario/api-fiscal.md) - [Leiaute fiscal](https://conota.dev/glossario/leiaute-fiscal.md) - [mTLS](https://conota.dev/glossario/mtls.md) - [Prefeitura autorizadora de NFS-e](https://conota.dev/glossario/prefeitura-autorizadora-de-nfs-e.md) --- Fonte: [Web service fiscal](https://conota.dev/glossario/web-service-fiscal/) · Atualizado em 2026-10-22 --- # Webhook fiscal > Webhook fiscal é um aviso automático que a plataforma de emissão envia ao sistema da empresa sempre que um documento fiscal muda de situação, como autorização, rejeição ou cancelamento. Em vez de perguntar repetidamente se a nota ficou pronta, o sistema recebe a informação assim que ela acontece, por meio de uma requisição HTTP. **Também conhecido como:** Webhook de documento fiscal, Notificação de status fiscal, Callback fiscal, Webhook de emissão fiscal, Fiscal webhook **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** W ## O que é um webhook fiscal, em palavras simples? Pense no webhook como uma campainha. Em vez de você ir até a porta a cada minuto para ver se chegou alguém, a campainha toca quando há visita. No mundo fiscal, a visita é uma novidade sobre uma nota: ela foi autorizada, rejeitada ou cancelada. Tecnicamente, o webhook é uma chamada HTTP que a API fiscal faz para um endereço informado pela empresa, chamado de URL de destino. Essa chamada leva um conteúdo, geralmente em JSON, com os dados do evento, como o identificador do documento, o novo status e links para baixar o XML e o PDF. ## Para que serve um webhook fiscal? A emissão de documentos como NF-e, NFS-e, NFC-e, CT-e e MDF-e costuma depender de órgãos externos, como a SEFAZ ou a prefeitura. A resposta nem sempre é imediata, por isso muitas plataformas trabalham com fluxo assíncrono: o pedido é aceito na hora, mas o resultado chega depois. O webhook serve para avisar o sistema da empresa sobre esse resultado no momento certo. Assim, o ERP, a loja virtual ou o marketplace pode liberar o pedido, enviar a nota ao cliente, registrar a rejeição para correção ou atualizar a contabilidade sem intervenção manual. ## Como funciona um webhook fiscal na prática? Primeiro, a empresa cadastra na plataforma fiscal uma URL do seu sistema que ficará esperando os avisos e, em muitos casos, escolhe quais eventos quer receber. Depois, ao enviar um documento para emissão, o sistema segue com suas tarefas normalmente. Quando o documento muda de status, a plataforma envia uma requisição para a URL cadastrada. O sistema da empresa lê o conteúdo, confere se o aviso é legítimo, atualiza seus registros e responde com um código de sucesso, como 200. Se não houver resposta ou ocorrer erro, a plataforma normalmente tenta reenviar mais tarde. ## Qual a diferença entre webhook fiscal e polling de status? No polling, o sistema da empresa pergunta à API, de tempos em tempos, qual é a situação de cada documento. Isso gera muitas consultas desnecessárias e pode atrasar a percepção de mudanças, dependendo do intervalo escolhido. No webhook, a lógica se inverte: a plataforma fiscal avisa quando algo acontece. Na prática, muitas integrações usam os dois juntos, com o webhook como canal principal e o polling como verificação de segurança caso algum aviso não seja recebido. ## Como garantir que um webhook fiscal é seguro e confiável? Como a URL de destino fica acessível pela internet, é importante confirmar que o aviso veio mesmo da plataforma fiscal. Uma prática comum é a assinatura com HMAC, em que a plataforma calcula um código a partir do conteúdo e de uma chave secreta, e o sistema da empresa refaz o cálculo para comparar. O uso de HTTPS também é essencial para proteger os dados no caminho. Para confiabilidade, o sistema receptor deve responder rápido e processar o aviso em segundo plano, tratar avisos repetidos sem duplicar ações, aplicando o conceito de idempotência, e registrar tudo em log. Do lado da plataforma, mecanismos de retry com backoff exponencial ajudam a entregar avisos que falharam por instabilidade momentânea. ## Exemplos de Webhook fiscal - Uma loja virtual envia uma NFC-e para emissão e só libera a etiqueta de envio quando recebe o webhook informando que o documento foi autorizado. - Um ERP recebe um webhook de rejeição de NF-e com o motivo informado pela SEFAZ e cria automaticamente uma tarefa para a equipe fiscal corrigir o cadastro do produto. - Uma plataforma de serviços recebe o webhook de NFS-e autorizada contendo o link do PDF e envia a nota por e-mail ao tomador do serviço. - Uma transportadora recebe um webhook confirmando o encerramento de um MDF-e e atualiza o status da viagem em seu sistema de gestão. ## Perguntas frequentes ### Preciso de um servidor próprio para receber webhooks fiscais? Sim, é necessário ter um endereço acessível pela internet, com HTTPS, capaz de receber requisições HTTP. Pode ser parte do backend do seu sistema ou um serviço dedicado apenas a receber e processar esses avisos. ### O que acontece se meu sistema estiver fora do ar quando o webhook for enviado? Em geral, a plataforma tenta reenviar o aviso algumas vezes, com intervalos crescentes. Ainda assim, é recomendável manter uma consulta periódica de status para recuperar eventos que eventualmente não tenham sido entregues. ### Posso receber o mesmo webhook mais de uma vez? Sim. Por causa dos reenvios automáticos, um mesmo evento pode chegar repetido. Por isso, o sistema deve verificar se aquele evento já foi processado antes de executar ações como enviar e-mails ou baixar estoque. ## Termos relacionados - [Polling de status fiscal](https://conota.dev/glossario/polling-de-status-fiscal.md) - [HMAC em webhooks](https://conota.dev/glossario/hmac-em-webhooks.md) - [Fluxo assíncrono de emissão](https://conota.dev/glossario/fluxo-assincrono-de-emissao.md) - [Status de documento fiscal](https://conota.dev/glossario/status-de-documento-fiscal.md) - [Retry na integração fiscal](https://conota.dev/glossario/retry-na-integracao-fiscal.md) - [Idempotência na emissão fiscal](https://conota.dev/glossario/idempotencia-na-emissao-fiscal.md) --- Fonte: [Webhook fiscal](https://conota.dev/glossario/webhook-fiscal/) · Atualizado em 2026-10-22 --- # WebSocket na comunicação entre sistemas > WebSocket é um protocolo de comunicação que mantém uma conexão aberta e permanente entre dois sistemas, permitindo que ambos enviem mensagens a qualquer momento, sem precisar fazer uma nova requisição a cada troca. É usado quando informações precisam chegar em tempo real, como atualizações de status, notificações e painéis que se atualizam sozinhos. **Também conhecido como:** Web Socket, Websockets, Conexão WebSocket, Protocolo WebSocket, WS, WebSocket **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** W ## O que é WebSocket, em palavras simples? Pense na diferença entre mandar cartas e fazer uma ligação telefônica. No modelo tradicional da web, baseado em HTTP, o sistema cliente envia um pedido, o servidor responde e a conversa termina. Para saber algo novo, é preciso enviar outro pedido. O WebSocket funciona como uma ligação que fica aberta: depois de conectados, os dois lados podem falar a qualquer momento. Essa característica é chamada de comunicação bidirecional (ou full-duplex): tanto o cliente quanto o servidor podem iniciar o envio de uma mensagem, sem esperar que o outro pergunte primeiro. ## Como funciona uma conexão WebSocket? A conexão começa como uma requisição HTTP comum, em que o cliente pede ao servidor para trocar de protocolo. Se o servidor aceitar, a conexão é promovida a WebSocket e passa a ficar aberta. Esse primeiro passo é chamado de handshake (aperto de mãos). A partir daí, as mensagens trafegam em pequenos blocos, chamados frames, que podem conter texto, como JSON, ou dados binários. Os endereços usam o prefixo ws:// para conexões sem criptografia e wss:// para conexões protegidas, equivalentes ao HTTPS. Em ambientes que lidam com dados fiscais, o uso de wss:// é o recomendado. A conexão permanece ativa até que um dos lados a encerre ou ocorra uma falha de rede. Por isso, aplicações bem feitas costumam implementar reconexão automática e mensagens periódicas de verificação para saber se o outro lado ainda está respondendo. ## Qual a diferença entre WebSocket, webhook e polling? No polling, o sistema pergunta repetidamente ao servidor se algo mudou, por exemplo, a cada poucos segundos. É simples, mas gera muitas requisições inúteis quando não há novidades. No webhook, o servidor envia uma requisição HTTP para um endereço do cliente quando um evento acontece, como a autorização de uma nota fiscal. Não há conexão aberta permanentemente: cada aviso é uma chamada independente. É o modelo mais comum para integrações entre servidores, inclusive em APIs fiscais. No WebSocket, existe uma conexão contínua por onde as mensagens circulam nos dois sentidos. Ele brilha quando há muitas atualizações frequentes e uma tela ou aplicação precisa reagir imediatamente, mas exige manter a conexão viva e tratar quedas. ## Onde o WebSocket aparece no contexto de emissão fiscal? A emissão de documentos como NF-e, NFS-e e CT-e costuma seguir um fluxo assíncrono: o sistema envia o documento, o processamento acontece em etapas e o resultado (autorizado, rejeitado, em contingência) chega depois. O WebSocket pode ser usado para levar essas mudanças de status em tempo real até a interface do usuário. Um uso típico é dentro do próprio sistema do cliente: o backend recebe a notificação do emissor fiscal, geralmente por webhook ou consulta, e repassa a atualização via WebSocket para o navegador do operador, que vê a nota mudar de status na tela sem recarregar a página. A comunicação entre servidores, por sua vez, costuma ficar com HTTP, webhooks e consultas à API. ## Quais cuidados tomar ao usar WebSocket? Segurança: use sempre conexões criptografadas (wss://) e autentique o cliente no início da conexão, por exemplo com um token. Como a conexão fica aberta por muito tempo, é importante prever a expiração e a renovação das credenciais. Confiabilidade: conexões caem por instabilidade de rede, reinícios de servidor ou proxies que encerram conexões ociosas. O sistema deve reconectar com intervalos crescentes entre tentativas e conseguir recuperar o que perdeu durante a queda, consultando o estado atual dos documentos na API. Escala: cada conexão aberta consome recursos do servidor. Em aplicações com muitos usuários simultâneos, é preciso planejar a infraestrutura, inclusive balanceadores de carga compatíveis com conexões persistentes. ## Exemplos de WebSocket na comunicação entre sistemas - Um ERP exibe um painel de faturamento em que cada NF-e enviada aparece como 'processando' e muda para 'autorizada' ou 'rejeitada' assim que o backend recebe o retorno, com a atualização chegando ao navegador via WebSocket. - Um sistema de PDV com NFC-e mantém uma conexão WebSocket com o servidor da loja para avisar o operador de caixa, em tempo real, quando a emissão entra em contingência. - Uma plataforma de marketplace usa webhooks para receber do emissor fiscal o status das notas e, em seguida, distribui essas atualizações por WebSocket para os painéis dos vendedores conectados. - Uma transportadora acompanha em uma tela de operação o encerramento de MDF-e e a autorização de CT-e, com os dados atualizados continuamente sem que o usuário precise recarregar a página. ## Perguntas frequentes ### WebSocket substitui uma API REST? Não. A API REST continua sendo usada para ações pontuais, como emitir, cancelar ou consultar um documento. O WebSocket complementa esse modelo quando é preciso receber atualizações contínuas em tempo real, principalmente em interfaces com usuários. ### Preciso de WebSocket para saber se minha nota foi autorizada? Normalmente não. Webhooks ou consultas periódicas à API resolvem bem a comunicação entre servidores. O WebSocket é útil quando você quer mostrar essa mudança instantaneamente na tela do usuário. ### WebSocket é seguro para trafegar dados fiscais? Pode ser, desde que use conexão criptografada (wss://), autenticação adequada no início da conexão e controle de permissões sobre quais informações cada cliente pode receber. ### O que acontece se a conexão WebSocket cair? As mensagens enviadas durante a queda podem ser perdidas. Por isso, o sistema deve reconectar automaticamente e consultar a API para sincronizar o status atual dos documentos. ## Termos relacionados - [HTTP](https://conota.dev/glossario/http.md) - [HTTPS](https://conota.dev/glossario/https.md) - [Fluxo assíncrono de emissão](https://conota.dev/glossario/fluxo-assincrono-de-emissao.md) - [HMAC em webhooks](https://conota.dev/glossario/hmac-em-webhooks.md) - [Endpoint de API](https://conota.dev/glossario/endpoint-de-api.md) - [Backoff exponencial](https://conota.dev/glossario/backoff-exponencial.md) --- Fonte: [WebSocket na comunicação entre sistemas](https://conota.dev/glossario/websocket-na-comunicacao-entre-sistemas/) · Atualizado em 2026-10-22 --- # Whitelist de IP > Whitelist de IP é uma lista de endereços IP autorizados a acessar um sistema, API ou servidor. Qualquer conexão vinda de um endereço fora da lista é bloqueada automaticamente. Em integrações fiscais, funciona como camada extra de segurança, garantindo que apenas servidores conhecidos, como os do ERP da empresa, consigam emitir ou consultar documentos fiscais. **Também conhecido como:** Allowlist de IP, Lista de IPs permitidos, Lista branca de IPs, IP whitelisting, Restrição de acesso por IP, IP whitelist (IP allowlist) **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** W ## O que é um endereço IP e por que filtrar por ele? Todo computador ou servidor conectado à internet tem um endereço IP, que funciona como um endereço de rua: ele identifica de onde vem cada requisição. Quando o seu ERP envia uma nota fiscal para uma API, o servidor que recebe o pedido sabe de qual IP ele partiu. Filtrar por IP significa usar essa informação para decidir quem pode entrar. Em vez de aceitar conexões de qualquer lugar do mundo, o sistema aceita apenas as que vêm de endereços previamente cadastrados, como um condomínio que só libera a entrada de moradores registrados na portaria. ## Como funciona uma whitelist de IP? O administrador cadastra os endereços permitidos, um a um ou em faixas (por exemplo, usando a notação CIDR, como 203.0.113.0/24, que representa um bloco de endereços). A cada requisição recebida, o servidor, firewall ou gateway compara o IP de origem com a lista. Se o endereço estiver na lista, a requisição segue para as próximas verificações, como a validação da API Key ou do token de autenticação. Se não estiver, a conexão é recusada antes mesmo de chegar à aplicação, geralmente com um erro de acesso negado. ## Para que serve a whitelist de IP na emissão fiscal? Emitir documentos fiscais é uma operação sensível: uma NF-e, NFC-e ou NFS-e emitida indevidamente gera obrigação tributária e pode exigir cancelamento ou outros eventos fiscais. Restringir quem pode chamar a API fiscal reduz o risco de uso indevido caso uma credencial vaze. Na prática, mesmo que alguém obtenha a chave de acesso da integração, não conseguirá emitir notas a partir de um computador qualquer, pois o IP dele não estará autorizado. A whitelist também pode ser aplicada no sentido inverso, quando o sistema da empresa só aceita receber webhooks vindos de IPs conhecidos do provedor de emissão. ## A whitelist de IP substitui a API Key ou o token? Não. A whitelist responde à pergunta de onde vem a requisição, enquanto a API Key, o Bearer token ou o OAuth 2.0 respondem quem está fazendo a requisição. São camadas complementares e o ideal é usá-las juntas. Confiar apenas no IP é arriscado, porque um servidor autorizado pode ser comprometido ou o endereço pode passar a pertencer a outro cliente de um provedor de nuvem. Da mesma forma, confiar apenas na chave deixa a API exposta caso ela seja copiada. Combinar as duas, junto com HTTPS e boas práticas de gerenciamento de segredos, torna a integração bem mais segura. ## Quais cuidados tomar ao usar whitelist de IP? O principal cuidado é garantir que o servidor tenha IP fixo. Muitas conexões domésticas, ambientes de nuvem com escalonamento automático e funções serverless trocam de IP com frequência, o que faz requisições legítimas serem bloqueadas de repente. Nesses casos, costuma-se usar um IP de saída fixo, configurado por meio de NAT ou proxy. Também é importante manter a lista atualizada: remover IPs de servidores desativados, cadastrar os novos antes de uma migração e documentar quem pode alterar a lista. Esquecer de liberar o IP do ambiente de produção após testes no ambiente de homologação é uma causa comum de falhas na virada da integração. ## Qual a diferença entre whitelist, allowlist e blacklist? Whitelist e allowlist são a mesma coisa: uma lista do que é permitido, em que tudo o que não está nela é bloqueado. O termo allowlist tem sido cada vez mais usado por ser mais descritivo. A blacklist, ou blocklist, faz o oposto: lista apenas o que é proibido e libera todo o resto. Para APIs fiscais, a whitelist é mais restritiva e, por isso, mais adequada quando se sabe exatamente quais servidores precisam de acesso. ## Exemplos de Whitelist de IP - Uma empresa de software de gestão cadastra os dois IPs fixos dos seus servidores de produção na whitelist, de modo que apenas eles conseguem enviar requisições de emissão de NF-e para a API fiscal. - Um marketplace configura seu firewall para aceitar webhooks de status de documentos fiscais somente a partir dos endereços IP informados pelo provedor de emissão, descartando qualquer chamada de outra origem. - Após migrar o ERP para um novo provedor de nuvem, a equipe de TI percebe que as notas pararam de ser emitidas com erro de acesso negado, pois o novo IP de saída ainda não havia sido incluído na whitelist. - Uma equipe libera uma faixa de IPs em notação CIDR para todo o cluster que processa a fila de emissão fiscal, em vez de cadastrar cada máquina separadamente. ## Perguntas frequentes ### Whitelist de IP é obrigatória para usar uma API fiscal? Depende do provedor e da política de segurança da empresa. Em muitos casos é um recurso opcional, recomendado como camada extra de proteção junto com a API Key ou o token de autenticação. ### Posso usar whitelist de IP se meu sistema roda em nuvem? Sim, desde que as requisições saiam por um IP fixo. Em ambientes com IPs que mudam, é comum configurar um gateway NAT ou proxy com endereço estático para concentrar o tráfego de saída. ### O que acontece se meu IP não estiver na whitelist? A requisição é recusada, normalmente com um erro de acesso negado, como HTTP 403. O documento fiscal não chega a ser processado, então é preciso cadastrar o IP e reenviar a solicitação. ### Whitelist de IP protege contra vazamento de API Key? Ajuda bastante, pois quem obtiver a chave não conseguirá usá-la de um IP não autorizado. Mesmo assim, a chave vazada deve ser revogada e substituída imediatamente. ## Termos relacionados - [API Key](https://conota.dev/glossario/api-key.md) - [Permissão de acesso à API](https://conota.dev/glossario/permissao-de-acesso-a-api.md) - [Gateway de API fiscal](https://conota.dev/glossario/gateway-de-api-fiscal.md) - [Gerenciamento de segredos](https://conota.dev/glossario/gerenciamento-de-segredos.md) - [mTLS](https://conota.dev/glossario/mtls.md) - [HMAC em webhooks](https://conota.dev/glossario/hmac-em-webhooks.md) --- Fonte: [Whitelist de IP](https://conota.dev/glossario/whitelist-de-ip/) · Atualizado em 2026-10-22 --- # Worker de emissão fiscal > Worker de emissão fiscal é um processo que roda em segundo plano, separado do sistema de vendas, responsável por retirar documentos de uma fila, montar e assinar o XML, enviar à SEFAZ ou prefeitura, aguardar a resposta e registrar o resultado, como autorização ou rejeição, sem travar o atendimento ao cliente. **Também conhecido como:** Worker fiscal, Processador de emissão fiscal, Consumidor da fila de emissão, Job de emissão fiscal, Tax document issuance worker **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** W ## O que é um worker de emissão fiscal? Worker, em inglês, significa trabalhador. Em tecnologia, é um programa que fica rodando nos bastidores executando tarefas que chegam por uma fila. No contexto fiscal, o worker é quem efetivamente faz o trabalho pesado de emitir notas: pega o pedido de emissão, transforma em documento fiscal válido e conversa com o órgão autorizador. Ele não interage com o usuário final. Enquanto o ERP, a loja virtual ou o marketplace registram a venda e seguem atendendo, o worker processa a nota em paralelo e avisa quando ela estiver pronta. ## Para que serve um worker de emissão fiscal? Serve para separar a emissão da venda. A comunicação com SEFAZ e prefeituras pode demorar, oscilar ou ficar indisponível. Se o sistema de vendas esperasse cada resposta, o cliente ficaria travado na tela. Com o worker, a venda é concluída e a nota segue seu caminho de forma assíncrona. Ele também permite lidar com volume. Em dias de pico, os pedidos se acumulam na fila e vários workers podem trabalhar ao mesmo tempo, processando os documentos de forma organizada, sem perder nenhum. ## Como funciona um worker de emissão fiscal? O ciclo típico é: o sistema envia o payload de emissão, que entra na fila; o worker retira o item, valida os dados, monta o XML no leiaute exigido, assina com o certificado digital e transmite ao autorizador. Depois, consulta ou recebe o retorno e grava o status: autorizada, rejeitada ou pendente. Quando há falha temporária, como timeout ou instabilidade do servidor público, o worker faz novas tentativas com intervalos crescentes (backoff exponencial). Para não emitir a mesma nota duas vezes, usa controles de idempotência. Ao final, notifica o sistema de origem, por webhook ou deixando o resultado disponível para consulta. ## Qual a diferença entre worker e fila de emissão fiscal? A fila é o lugar onde os pedidos esperam sua vez; o worker é quem os processa. Uma analogia simples: a fila é a pilha de pedidos na cozinha de um restaurante, e o worker é o cozinheiro que pega cada pedido e prepara o prato. Os dois trabalham juntos. Sem fila, o worker não teria como receber tarefas de forma ordenada; sem worker, a fila apenas acumularia pedidos sem que nenhuma nota fosse emitida. ## Preciso construir meus próprios workers de emissão? Depende da estratégia. Construir internamente exige lidar com certificados, leiautes que mudam por notas técnicas, regras de cada prefeitura, contingência, retentativas, monitoramento e escala. É um esforço contínuo de manutenção. Ao usar uma API fiscal como o Conota, essa camada de workers fica do lado do provedor. O sistema do cliente apenas envia a requisição e recebe XML, PDF e status automaticamente, concentrando-se na regra de negócio da venda. ## Exemplos de Worker de emissão fiscal - Um e-commerce registra 3 mil pedidos durante uma promoção; cada pedido gera uma tarefa na fila e os workers emitem as NFC-e ou NF-e em paralelo, enquanto o checkout continua rápido. - Uma plataforma de serviços envia uma NFS-e e a prefeitura está fora do ar; o worker reprograma novas tentativas automaticamente até conseguir a resposta ou registrar a falha. - Uma transportadora emite CT-e e, em seguida, o worker gera o MDF-e da viagem, atualizando o status de cada documento no sistema de gestão. - Um ERP recebe por webhook o aviso de que o worker obteve a autorização da NF-e, junto com o XML e o DANFE, e libera o faturamento do pedido. ## Perguntas frequentes ### O worker de emissão fiscal é um software separado? Geralmente sim. É um processo independente do sistema principal, que pode rodar em servidores ou contêineres próprios e ser multiplicado conforme a demanda, sem afetar a aplicação que atende os usuários. ### O que acontece se o worker falhar no meio da emissão? Em uma arquitetura bem feita, a tarefa volta para a fila e outro worker a retoma. Controles de idempotência e consulta de status evitam que a mesma nota seja emitida em duplicidade. ### Worker e processamento assíncrono são a mesma coisa? Não exatamente. Processamento assíncrono é o modelo em que a resposta não é imediata; o worker é o componente que executa esse processamento nos bastidores. ### Quem usa uma API fiscal precisa gerenciar workers? Normalmente não. O provedor da API mantém os workers, filas e retentativas. O sistema do cliente apenas envia os dados e acompanha o status ou recebe notificações. ## Termos relacionados - [Fila de emissão fiscal](https://conota.dev/glossario/fila-de-emissao-fiscal.md) - [Processamento assíncrono](https://conota.dev/glossario/processamento-assincrono.md) - [Fluxo assíncrono de emissão](https://conota.dev/glossario/fluxo-assincrono-de-emissao.md) - [Orquestração de emissão fiscal](https://conota.dev/glossario/orquestracao-de-emissao-fiscal.md) - [Retry na integração fiscal](https://conota.dev/glossario/retry-na-integracao-fiscal.md) - [Idempotência na emissão fiscal](https://conota.dev/glossario/idempotencia-na-emissao-fiscal.md) --- Fonte: [Worker de emissão fiscal](https://conota.dev/glossario/worker-de-emissao-fiscal/) · Atualizado em 2026-10-22 --- # Workflow de emissão fiscal > Workflow de emissão fiscal é a sequência organizada de etapas que leva um documento fiscal, como NF-e, NFS-e ou NFC-e, desde a coleta dos dados da venda até sua autorização pelo órgão competente, incluindo validação, assinatura, envio, acompanhamento de status, tratamento de rejeições e entrega do XML e do PDF finais. **Também conhecido como:** Fluxo de emissão fiscal, Fluxo de emissão de notas fiscais, Processo de emissão fiscal, Workflow fiscal, Tax invoice issuance workflow **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** W ## O que é um workflow de emissão fiscal? Workflow significa fluxo de trabalho. Na emissão fiscal, é o caminho padronizado que todo documento percorre para se tornar válido: os dados saem do sistema que fez a venda, são conferidos, transformados no formato exigido, assinados digitalmente, enviados à SEFAZ ou à prefeitura e, por fim, autorizados ou rejeitados. Pensar a emissão como um workflow ajuda a enxergar que emitir uma nota não é um único clique, mas uma série de passos que podem dar certo ou errado de forma independente. Cada passo tem entradas, saídas e possíveis falhas que precisam ser tratadas. ## Quais são as etapas de um workflow de emissão fiscal? De forma simplificada, as etapas costumam ser: coleta dos dados da operação (emitente, destinatário, itens, impostos); validação das regras fiscais e do esquema XML; montagem do documento; assinatura digital com o certificado da empresa; transmissão ao órgão autorizador; recebimento do protocolo de autorização ou do motivo de rejeição; e geração dos arquivos finais, como o XML e o DANFE. Depois da autorização, o workflow pode continuar com eventos posteriores, como cancelamento, carta de correção ou, no caso do MDF-e, o encerramento. Também entram aqui a guarda dos documentos e o registro de cada etapa para auditoria. ## Por que o workflow costuma ser assíncrono? Os órgãos autorizadores nem sempre respondem na hora. Algumas prefeituras e serviços processam documentos em lote e devolvem o resultado depois, e instabilidades podem atrasar a resposta. Por isso, muitos workflows usam processamento assíncrono: o sistema envia o pedido, recebe uma confirmação de que ele entrou na fila e é avisado depois sobre o resultado. Esse aviso pode chegar por webhook, quando o emissor notifica o sistema automaticamente, ou por polling, quando o próprio sistema consulta o status de tempos em tempos. Assim, a venda não fica travada esperando a resposta do governo. ## Como o workflow lida com erros e rejeições? Um bom workflow distingue dois tipos de problema. Erros temporários, como timeout ou indisponibilidade do órgão, podem ser resolvidos com novas tentativas automáticas, muitas vezes usando backoff exponencial. Já rejeições fiscais, como CFOP incompatível ou dados do destinatário inválidos, exigem correção dos dados antes de reenviar. Para evitar notas duplicadas durante essas novas tentativas, usa-se idempotência: cada pedido recebe um identificador único, e o emissor reconhece quando a mesma solicitação chega mais de uma vez. ## Quem executa o workflow: o sistema da empresa ou uma API fiscal? Uma empresa pode construir todo o workflow dentro do próprio ERP ou plataforma, mas isso exige lidar com leiautes diferentes por documento e por município, certificados, filas, reprocessamento e mudanças trazidas por notas técnicas. A alternativa é delegar parte do fluxo a uma API fiscal. No Conota, por exemplo, o sistema do cliente continua cuidando da venda e envia os dados por API; a infraestrutura assume a assinatura, a transmissão, o acompanhamento até a autorização e devolve XML, PDF e status automaticamente. Rejeições e certificados ficam visíveis em um Console, e agentes de IA podem consultar documentos via MCP com permissões controladas. ## Qual a diferença entre workflow e orquestração de emissão fiscal? O workflow é o desenho das etapas: o que acontece e em que ordem. A orquestração é o mecanismo que coordena essas etapas na prática, decidindo quando enviar, quando tentar novamente, para qual fila mandar cada documento e como registrar o resultado. Em resumo, o workflow é o roteiro e a orquestração é quem garante que ele seja seguido. ## Exemplos de Workflow de emissão fiscal - Um e-commerce conclui uma venda, envia os dados do pedido por API e recebe um webhook minutos depois com a NF-e autorizada, o XML e o DANFE para anexar ao e-mail do cliente. - Uma software house de gestão para clínicas monta um workflow em que cada consulta paga gera automaticamente uma NFS-e; quando a prefeitura rejeita por código de serviço incorreto, o sistema alerta o usuário para corrigir e reenviar. - Uma transportadora integra ao seu sistema um workflow que emite o CT-e de cada frete, depois o MDF-e da viagem e, ao final da entrega, registra o evento de encerramento do manifesto. - Um PDV de varejo emite NFC-e em fluxo rápido e, quando a SEFAZ está instável, aciona tentativas automáticas sem duplicar a nota graças à chave de idempotência. ## Perguntas frequentes ### Workflow de emissão fiscal é a mesma coisa que emissor de nota? Não. O emissor é a ferramenta que gera e transmite o documento. O workflow é o conjunto completo de etapas, que inclui coleta de dados, validação, envio, acompanhamento, tratamento de erros, eventos posteriores e guarda dos arquivos. ### O workflow muda conforme o tipo de documento? Sim. A estrutura geral é parecida, mas NF-e, NFC-e, NFS-e, CT-e e MDF-e têm leiautes, órgãos autorizadores e eventos próprios. A NFS-e, por exemplo, pode variar conforme o município ou seguir o Padrão Nacional. ### É possível testar o workflow antes de emitir notas reais? Sim. O ideal é validar todo o fluxo no ambiente de homologação, que não gera documentos com valor fiscal, e só depois passar para o ambiente de produção. ### O que acontece se o órgão autorizador estiver fora do ar? Um workflow bem projetado mantém o documento em fila, faz novas tentativas automáticas e, quando permitido, usa contingências como SVC ou EPEC, informando o status ao sistema de origem. ## Termos relacionados - [Orquestração de emissão fiscal](https://conota.dev/glossario/orquestracao-de-emissao-fiscal.md) - [Fluxo assíncrono de emissão](https://conota.dev/glossario/fluxo-assincrono-de-emissao.md) - [Fila de emissão fiscal](https://conota.dev/glossario/fila-de-emissao-fiscal.md) - [Status de documento fiscal](https://conota.dev/glossario/status-de-documento-fiscal.md) - [Reprocessamento de emissão fiscal](https://conota.dev/glossario/reprocessamento-de-emissao-fiscal.md) - [Emissão fiscal por API](https://conota.dev/glossario/emissao-fiscal-por-api.md) --- Fonte: [Workflow de emissão fiscal](https://conota.dev/glossario/workflow-de-emissao-fiscal/) · Atualizado em 2026-10-22 --- # WORM no armazenamento de documentos > WORM no armazenamento de documentos é o modelo em que um arquivo, depois de gravado, não pode ser alterado nem apagado durante um período definido, apenas lido quantas vezes for necessário. O nome vem do inglês Write Once, Read Many. É usado para preservar a integridade de registros importantes, como XMLs de notas fiscais. **Também conhecido como:** Write Once, Read Many, Armazenamento imutável, Bloqueio de objetos, Retenção imutável, WORM **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** W ## O que significa WORM? WORM é a sigla de Write Once, Read Many, que em português quer dizer escrever uma vez, ler muitas. A ideia é simples: o arquivo é gravado uma única vez e, a partir daí, fica protegido contra qualquer modificação ou exclusão, mas continua disponível para consulta. O conceito surgiu com mídias físicas que só aceitavam uma gravação, como alguns discos ópticos. Hoje ele é aplicado principalmente por software, em servidores e serviços de armazenamento em nuvem que oferecem bloqueio de objetos com prazo de retenção. ## Como funciona o armazenamento WORM? Quando um documento é salvo em um repositório com WORM ativado, o sistema associa a ele uma regra de retenção, geralmente um prazo em dias ou anos. Enquanto esse prazo não termina, tentativas de sobrescrever, editar ou apagar o arquivo são recusadas, inclusive para usuários com permissões elevadas, dependendo da configuração. Muitas soluções oferecem dois níveis de proteção: um mais flexível, em que administradores autorizados podem remover o bloqueio em situações excepcionais, e outro rígido, em que ninguém consegue alterar ou excluir o arquivo antes do fim do prazo. Também é comum existir a retenção por tempo indeterminado, usada quando há uma disputa judicial ou auditoria em andamento. ## Para que serve WORM na guarda de documentos fiscais? Documentos fiscais eletrônicos, como NF-e, NFC-e, NFS-e, CT-e e MDF-e, têm validade jurídica baseada no arquivo XML assinado digitalmente. Se esse XML for alterado, mesmo que por engano, a assinatura deixa de ser válida e o documento perde sua prova de autenticidade. Com WORM, a empresa garante que o XML autorizado permanece exatamente como foi recebido do Fisco durante todo o prazo exigido pela legislação tributária. Isso protege contra erros operacionais, exclusões acidentais, ataques de ransomware que tentam criptografar ou apagar arquivos e até tentativas internas de adulteração. ## Qual a diferença entre WORM e backup comum? Um backup comum é uma cópia de segurança que, em geral, pode ser substituída, editada ou apagada por quem tem acesso ao sistema. Se um invasor ou um processo com defeito alcançar o backup, ele também pode ser comprometido. No WORM, a proteção é contra mudança, e não apenas contra perda. Por isso, as duas práticas se complementam: o backup garante cópias em lugares diferentes, e o WORM garante que pelo menos uma dessas cópias não possa ser modificada. ## Quais cuidados tomar ao adotar WORM? O principal cuidado é definir corretamente o prazo de retenção. Um prazo curto demais deixa os documentos desprotegidos antes do fim da obrigação legal, e um prazo longo demais pode gerar custo de armazenamento desnecessário, já que os arquivos não poderão ser removidos antes da data configurada. Também vale organizar bem o que entra no repositório protegido. Como nada pode ser corrigido depois, o ideal é gravar apenas a versão final dos arquivos, como o XML já autorizado e os XMLs de eventos, como cancelamento e carta de correção, cada um como um registro separado. ## Exemplos de WORM no armazenamento de documentos - Um ERP que emite NF-e via API salva automaticamente cada XML autorizado em um repositório na nuvem com bloqueio WORM configurado para o prazo de guarda exigido pela legislação. - Uma transportadora mantém os XMLs de CT-e e MDF-e em armazenamento WORM para conseguir apresentar os arquivos originais e íntegros em uma fiscalização, mesmo anos depois da emissão. - Após um ataque de ransomware que criptografou os servidores internos, um marketplace recupera os XMLs de NFS-e intactos a partir de uma cópia WORM que o invasor não conseguiu alterar. - Durante um processo administrativo tributário, uma empresa aplica retenção por tempo indeterminado aos documentos envolvidos, impedindo sua exclusão até o encerramento do caso. ## Perguntas frequentes ### WORM é obrigatório para guardar notas fiscais? Não há, em regra, exigência de uma tecnologia específica. A obrigação é manter o XML íntegro e disponível pelo prazo legal. O WORM é uma forma eficiente de cumprir essa exigência com segurança. ### É possível corrigir um arquivo gravado em WORM? Não. O arquivo original permanece inalterado até o fim do prazo de retenção. Correções fiscais devem ser feitas por eventos próprios, como carta de correção ou cancelamento, que geram novos arquivos a serem guardados separadamente. ### WORM protege contra perda do arquivo? Protege contra exclusão e alteração no repositório onde está ativado. Contra falhas físicas ou indisponibilidade do provedor, o recomendado é manter também cópias em outros locais. ### Só posso usar WORM em mídias físicas? Não. Hoje o mais comum é o WORM por software, oferecido por serviços de armazenamento em nuvem e sistemas corporativos por meio de bloqueio de objetos com prazo de retenção. ## Termos relacionados - [Guarda de documentos fiscais](https://conota.dev/glossario/guarda-de-documentos-fiscais.md) - [Arquivo XML fiscal](https://conota.dev/glossario/arquivo-xml-fiscal.md) - [Hash de documento fiscal](https://conota.dev/glossario/hash-de-documento-fiscal.md) - [Autenticidade de documento eletrônico](https://conota.dev/glossario/autenticidade-de-documento-eletronico.md) - [Assinatura digital do XML](https://conota.dev/glossario/assinatura-digital-do-xml.md) - [Carimbo do tempo](https://conota.dev/glossario/carimbo-do-tempo.md) --- Fonte: [WORM no armazenamento de documentos](https://conota.dev/glossario/worm-no-armazenamento-de-documentos/) · Atualizado em 2026-10-22 --- # Wrapper de API fiscal > Wrapper de API fiscal é uma camada de software que envolve uma API fiscal ou os webservices das autoridades tributárias e oferece uma interface mais simples ao sistema que emite notas. Ele esconde detalhes técnicos, como formatos XML, assinatura digital, autenticação e tratamento de erros, permitindo emitir NF-e, NFS-e e outros documentos com menos código. **Também conhecido como:** Wrapper fiscal, Camada de abstração fiscal, Cliente de API fiscal, SDK fiscal, Fiscal API wrapper **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** W ## O que é um wrapper de API fiscal, em termos simples? A palavra wrapper vem do inglês e significa embrulho ou invólucro. Na programação, é um trecho de código que fica em volta de outro sistema e traduz a forma de conversar com ele para algo mais fácil de usar. No mundo fiscal, o wrapper fica entre o sistema da empresa, como um ERP ou uma plataforma de vendas, e a API que realmente emite os documentos. Em vez de montar manualmente cada requisição, o desenvolvedor chama funções simples, como emitir nota, consultar status ou cancelar documento, e o wrapper cuida do resto. ## Para que serve um wrapper de API fiscal? O principal objetivo é reduzir complexidade. A emissão fiscal envolve regras de leiaute, certificados digitais, códigos de rejeição, ambientes de homologação e produção e diferenças entre documentos como NF-e, NFC-e, NFS-e, CT-e e MDF-e. O wrapper concentra esse conhecimento em um único ponto. Ele também padroniza o código. Se várias partes do sistema emitem notas, todas usam a mesma camada, o que facilita manutenção, testes e mudanças futuras. Quando a API por trás muda de versão, basta ajustar o wrapper, sem mexer em todo o restante do sistema. ## Como funciona um wrapper de API fiscal na prática? O sistema da empresa envia ao wrapper os dados da venda em um formato que já usa internamente, por exemplo um objeto com cliente, itens e valores. O wrapper converte esses dados para o payload exigido pela API, geralmente em JSON, adiciona o header de autenticação e faz a chamada ao endpoint correto. Depois, ele interpreta a resposta. Pode transformar códigos de erro em mensagens compreensíveis, repetir a tentativa em caso de falha temporária, acompanhar o processamento assíncrono até a autorização e devolver ao sistema o status, a chave de acesso, o XML e o PDF do documento. Há wrappers em dois níveis: os que envolvem diretamente os webservices das SEFAZ e prefeituras, que costumam usar SOAP e XML, e os que envolvem uma API fiscal moderna, oferecendo funções prontas em linguagens como Java ou JavaScript. ## Qual a diferença entre wrapper, biblioteca de emissão fiscal e gateway de API fiscal? O wrapper é um conceito de arquitetura: qualquer camada que simplifica o acesso a outra API. Uma biblioteca de emissão fiscal é um pacote de código instalado no projeto que costuma funcionar como wrapper, mas pode incluir também geração de XML, assinatura e validação localmente. Já o gateway de API fiscal é um serviço que roda fora do sistema do cliente, recebendo requisições e encaminhando aos órgãos autorizadores. Em resumo, o wrapper normalmente vive dentro do código da empresa, enquanto o gateway é uma infraestrutura externa. É comum usar um wrapper próprio para conversar com um gateway ou uma API fiscal como o Conota. ## Quais cuidados ter ao criar ou usar um wrapper de API fiscal? Um wrapper não deve esconder informações importantes. Motivos de rejeição, protocolos de autorização e identificadores de requisição precisam continuar acessíveis para que a equipe consiga investigar problemas e manter a trilha de auditoria. Também vale garantir idempotência, para que uma nova tentativa não gere nota duplicada, definir timeouts adequados, guardar credenciais com segurança e manter o wrapper atualizado quando a API ou as notas técnicas fiscais mudarem. ## Exemplos de Wrapper de API fiscal - Um ERP cria uma classe EmissorFiscal com o método emitirNFe(pedido), que monta o JSON, chama a API fiscal, aguarda a autorização e grava a chave de acesso no pedido. - Uma plataforma de agendamento de serviços usa um wrapper em JavaScript que traduz os dados do atendimento para a NFS-e, tratando as diferenças entre municípios em um único lugar. - Uma equipe que antes acessava os webservices SOAP da SEFAZ substitui esse código por um wrapper que chama uma API REST para emissão fiscal, sem alterar as telas do sistema. - Um marketplace usa um wrapper que converte códigos de rejeição em mensagens claras para os vendedores, como informar que o NCM do produto está inválido. ## Perguntas frequentes ### Preciso de um wrapper para usar uma API fiscal? Não é obrigatório. É possível chamar a API diretamente por HTTP. O wrapper é recomendado quando o sistema emite documentos em vários pontos ou quando se quer isolar a integração para facilitar manutenção e testes. ### Wrapper e SDK são a mesma coisa? São próximos. Um SDK geralmente é um wrapper oficial distribuído pelo fornecedor da API, às vezes com ferramentas extras. Um wrapper pode ser criado pela própria empresa, sob medida para seu sistema. ### O wrapper emite a nota sozinho? Não. Ele apenas organiza e envia os dados. Quem processa a emissão é a API fiscal ou o órgão autorizador, como a SEFAZ ou a prefeitura, que valida e autoriza o documento. ## Termos relacionados - [API fiscal](https://conota.dev/glossario/api-fiscal.md) - [Biblioteca de emissão fiscal](https://conota.dev/glossario/biblioteca-de-emissao-fiscal.md) - [Gateway de API fiscal](https://conota.dev/glossario/gateway-de-api-fiscal.md) - [API REST para emissão fiscal](https://conota.dev/glossario/api-rest-para-emissao-fiscal.md) - [Backend de integração fiscal](https://conota.dev/glossario/backend-de-integracao-fiscal.md) - [SOAP](https://conota.dev/glossario/soap.md) --- Fonte: [Wrapper de API fiscal](https://conota.dev/glossario/wrapper-de-api-fiscal/) · Atualizado em 2026-10-22 --- # Write-ahead log na persistência fiscal > Write-ahead log na persistência fiscal é a técnica de registrar, em um arquivo de diário durável, cada operação sobre um documento fiscal antes de executá-la ou gravá-la definitivamente. Assim, se o sistema cair no meio da emissão de uma NF-e ou NFS-e, é possível recuperar o estado correto, evitando perda de dados, duplicidade e inconsistências. **Também conhecido como:** WAL, Write-ahead logging, Log de escrita antecipada, Registro antecipado de escrita, Journaling, Write-ahead log **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** W ## O que é write-ahead log, em termos simples? Write-ahead log, ou WAL, significa algo como registro antecipado de escrita. A ideia é anotar a intenção antes de agir: primeiro o sistema escreve em um diário seguro o que pretende fazer e só depois altera os dados principais. Uma comparação útil é a de um caixa de loja que anota cada venda num caderno antes de mexer no estoque. Se faltar luz no meio do processo, basta consultar o caderno para saber o que já foi feito e o que ficou pendente. Na persistência fiscal, ou seja, na forma como um sistema guarda informações sobre notas, eventos e protocolos, essa técnica ajuda a garantir que nada se perca entre o pedido de emissão e a resposta do fisco. ## Por que o write-ahead log é importante na emissão fiscal? Emitir um documento fiscal envolve várias etapas: montar o XML, assinar, enviar à SEFAZ ou à prefeitura, receber o protocolo e guardar o resultado. Uma falha no meio desse caminho pode deixar o sistema sem saber se a nota foi autorizada ou não. Sem um registro confiável, o sistema pode reenviar a mesma nota e gerar duplicidade, pular uma numeração ou perder o XML autorizado, que precisa ser guardado. Com o WAL, o sistema sabe exatamente em que ponto parou e pode retomar dali com segurança. ## Como funciona o write-ahead log na prática? Antes de cada mudança importante, o sistema grava uma entrada no log, por exemplo: nota 1520 reservada, XML assinado, lote enviado, protocolo recebido. Essa gravação é feita de forma durável, isto é, confirmada em disco, e não apenas na memória. Só depois dessa confirmação os dados principais são atualizados. Se houver uma queda, o processo de recuperação lê o log, refaz as etapas confirmadas que não chegaram aos dados principais e identifica as que ficaram incompletas, como um envio sem resposta, para consultar o status no fisco antes de agir. Muitos bancos de dados já usam WAL internamente. Em integrações fiscais, a mesma lógica costuma aparecer também na aplicação, em tabelas de eventos ou filas que registram cada passo da emissão. ## Qual a diferença entre write-ahead log, backup e log de auditoria? O backup é uma cópia dos dados feita periodicamente para recuperar informações em caso de perda grave. O WAL atua continuamente, operação por operação, para manter os dados consistentes mesmo após uma falha repentina. O log de auditoria, ou histórico de eventos fiscais, serve para mostrar quem fez o quê e quando, com foco em rastreabilidade. O WAL tem foco técnico: garantir que as operações sejam concluídas ou desfeitas corretamente. Os dois podem coexistir e até compartilhar informações, mas têm objetivos diferentes. ## Como o write-ahead log se relaciona com idempotência e filas de emissão? Idempotência é a capacidade de repetir uma requisição sem gerar um efeito duplicado. O WAL ajuda nisso porque registra que uma emissão já foi iniciada com determinada chave, permitindo que uma nova tentativa reconheça o trabalho já feito em vez de criar outra nota. Em fluxos assíncronos, em que a nota entra numa fila e é processada depois, o log registra o estado de cada item. Assim, se o processador reiniciar, ele sabe quais documentos estão pendentes, quais aguardam retorno e quais já foram concluídos. ## Quem precisa se preocupar com write-ahead log? Equipes que desenvolvem ERPs, plataformas de venda ou marketplaces com emissão própria precisam pensar em como garantir a consistência dos dados em caso de falha. Quando a emissão é delegada a uma API fiscal, boa parte dessa responsabilidade fica com o emissor, mas o sistema do cliente ainda deve registrar seus pedidos de forma segura e usar chaves de idempotência para não perder nem duplicar solicitações. ## Exemplos de Write-ahead log na persistência fiscal - Um ERP grava no log que a NF-e de número 3050 foi enviada; o servidor reinicia antes de receber o protocolo e, ao voltar, o sistema consulta o status na SEFAZ em vez de reenviar a nota. - Uma plataforma de serviços registra cada DPS da NFS-e no write-ahead log antes de chamar a API fiscal, conseguindo reprocessar apenas os pedidos que ficaram sem resposta após uma queda de rede. - Um marketplace usa uma tabela de eventos no estilo WAL para acompanhar cada NFC-e do pedido até a autorização e o armazenamento do XML, evitando notas órfãs no banco. - Uma transportadora registra no log a emissão de cada CT-e vinculado a um MDF-e, garantindo que o manifesto só seja encerrado quando todos os documentos estiverem confirmados. ## Perguntas frequentes ### O write-ahead log substitui o backup? Não. O WAL garante consistência após falhas repentinas, operação por operação. O backup protege contra perdas maiores, como corrupção de disco ou exclusão acidental. Os dois são complementares. ### O write-ahead log evita notas duplicadas? Ajuda bastante. Ao registrar que uma emissão já começou, o sistema consegue verificar o status antes de reenviar. Para proteção completa, deve ser combinado com chaves de idempotência e consulta ao fisco. ### Preciso implementar WAL se uso um banco de dados moderno? Muitos bancos já usam WAL internamente para suas próprias transações. Porém, etapas externas, como o envio à SEFAZ, não são cobertas por ele, por isso a aplicação também deve registrar o estado de cada emissão. ## Termos relacionados - [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) - [Duplicidade de NF-e](https://conota.dev/glossario/duplicidade-de-nf-e.md) - [Histórico de eventos fiscais](https://conota.dev/glossario/historico-de-eventos-fiscais.md) - [Guarda de documentos fiscais](https://conota.dev/glossario/guarda-de-documentos-fiscais.md) --- Fonte: [Write-ahead log na persistência fiscal](https://conota.dev/glossario/write-ahead-log-na-persistencia-fiscal/) · Atualizado em 2026-10-22 --- # WS-Addressing > WS-Addressing é uma especificação técnica que define como incluir, no cabeçalho de mensagens SOAP, informações de endereçamento, como destino, ação solicitada, identificador da mensagem e para onde enviar a resposta. Em integrações fiscais, aparece em alguns webservices de prefeituras e órgãos públicos que exigem esses dados para aceitar requisições de emissão ou consulta. **Também conhecido como:** Web Services Addressing, WS-A, Endereçamento de Web Services **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** W ## O que é WS-Addressing, em termos simples? WS-Addressing, abreviação de Web Services Addressing, é um padrão que acrescenta dados de endereçamento dentro de uma mensagem SOAP, o formato baseado em XML usado por muitos webservices governamentais. Esses dados ficam no cabeçalho da mensagem, separados do conteúdo principal, como uma nota fiscal ou um pedido de consulta. Uma boa comparação é uma carta: o conteúdo é o que vai dentro do envelope, e o WS-Addressing é o que vai escrito por fora, como destinatário, assunto, número de protocolo e endereço para resposta. Com isso, a mensagem carrega consigo as informações de entrega, sem depender apenas do canal por onde viaja. ## Como funciona o WS-Addressing numa mensagem SOAP? O sistema que envia a requisição inclui no cabeçalho SOAP alguns elementos padronizados. Os mais comuns são: To, que indica o endereço do serviço de destino; Action, que informa qual operação está sendo pedida, como enviar um lote de RPS ou consultar uma nota; MessageID, um identificador único da mensagem; ReplyTo, que diz para onde a resposta deve ir; e RelatesTo, usado na resposta para apontar a qual mensagem ela se refere. O servidor lê esses elementos antes de processar o conteúdo. Se algum item obrigatório estiver ausente ou incorreto, a requisição costuma ser recusada logo na entrada, mesmo que o XML da nota esteja perfeito. ## Onde o WS-Addressing aparece na emissão de notas fiscais? Grande parte dos webservices fiscais brasileiros usa SOAP, mas nem todos exigem WS-Addressing. A exigência é mais comum em alguns sistemas de NFS-e de prefeituras, especialmente os construídos sobre plataformas que adotam esse padrão por configuração. Nesses casos, o manual de integração do município costuma indicar quais cabeçalhos devem ser enviados e com quais valores. Como cada município pode adotar um provedor e uma tecnologia diferentes, uma mesma empresa emissora pode precisar enviar WS-Addressing para uma cidade e não para outra. Essa variação é uma das razões pelas quais integrar NFS-e diretamente com várias prefeituras dá bastante trabalho. ## Qual a diferença entre WS-Addressing e o endereço HTTP do endpoint? O endpoint é a URL para onde a requisição é enviada pela rede, usando HTTP ou HTTPS. O WS-Addressing repete e complementa essa informação dentro da própria mensagem XML, junto com dados que o HTTP não carrega naturalmente, como o identificador da mensagem e a operação desejada. Na prática, mesmo acertando a URL, a chamada pode falhar se o elemento To ou o Action dentro do cabeçalho SOAP não corresponderem ao que o serviço espera. São duas camadas diferentes que precisam estar coerentes. ## Quais erros são comuns ao usar WS-Addressing? Os problemas mais frequentes são: esquecer de enviar os cabeçalhos quando o serviço os exige; usar um valor de Action diferente do previsto no contrato do webservice (o WSDL); declarar o namespace errado do WS-Addressing; e reaproveitar o mesmo MessageID em mensagens diferentes. Esses erros geralmente retornam como falhas SOAP genéricas, com mensagens pouco claras, o que dificulta o diagnóstico. Comparar a requisição enviada com um exemplo oficial do manual do provedor costuma ser o caminho mais rápido para encontrar a diferença. ## Quem usa uma API fiscal precisa lidar com WS-Addressing? Normalmente não. Uma API fiscal que recebe dados em JSON e se encarrega da comunicação com os órgãos públicos monta internamente as mensagens SOAP, incluindo os cabeçalhos de WS-Addressing quando o webservice de destino exige. O sistema do cliente, como um ERP ou uma plataforma de vendas, envia a mesma estrutura de dados independentemente da tecnologia usada por cada prefeitura. Entender o conceito ainda é útil para equipes técnicas que precisam interpretar logs, investigar rejeições ou avaliar o esforço de uma integração direta com webservices municipais. ## Exemplos de WS-Addressing - Um ERP que integra diretamente com o webservice de NFS-e de uma prefeitura recebe uma falha SOAP ao enviar um lote de RPS; ao investigar, a equipe descobre que o serviço exigia o cabeçalho Action do WS-Addressing, que não estava sendo enviado. - Um desenvolvedor configura o cliente SOAP para gerar automaticamente um MessageID único a cada requisição, atendendo à exigência do webservice municipal de que cada mensagem tenha identificador próprio. - Uma plataforma de marketplace que emite NFS-e para vendedores em várias cidades usa uma API fiscal e não precisa saber quais municípios exigem WS-Addressing, pois a API monta os cabeçalhos corretos para cada destino. - Ao analisar um log de integração, o time de suporte compara o elemento To do cabeçalho SOAP com a URL do endpoint e identifica que a mensagem apontava para o ambiente de homologação enquanto era enviada ao de produção. ## Perguntas frequentes ### WS-Addressing é obrigatório para emitir NF-e? Não como regra geral. A exigência depende do webservice de destino. Ela aparece com mais frequência em alguns sistemas municipais de NFS-e. Sempre consulte o manual de integração do órgão ou provedor específico. ### WS-Addressing tem relação com a assinatura digital do XML? São coisas diferentes. A assinatura digital garante a autoria e a integridade do documento fiscal. O WS-Addressing apenas informa destino, operação e identificação da mensagem SOAP. Uma requisição pode precisar dos dois ao mesmo tempo. ### WS-Addressing funciona em APIs REST com JSON? Não. O WS-Addressing foi criado para mensagens SOAP em XML. APIs REST usam outros mecanismos, como a URL, o método HTTP e cabeçalhos HTTP, para indicar destino e operação. ### Como saber se um webservice exige WS-Addressing? Verifique o WSDL do serviço, que pode declarar o uso do padrão, e o manual de integração do provedor. Mensagens de erro mencionando Action, To ou addressing também são um bom indício. ## Termos relacionados - [Endpoint de API](https://conota.dev/glossario/endpoint-de-api.md) - [Esquema XML](https://conota.dev/glossario/esquema-xml.md) - [Arquivo XML fiscal](https://conota.dev/glossario/arquivo-xml-fiscal.md) - [HTTPS](https://conota.dev/glossario/https.md) - [Assinatura digital do XML](https://conota.dev/glossario/assinatura-digital-do-xml.md) - [Header Content-Type](https://conota.dev/glossario/header-content-type.md) --- Fonte: [WS-Addressing](https://conota.dev/glossario/ws-addressing/) · Atualizado em 2026-10-22 --- # WS-I Basic Profile > WS-I Basic Profile é um conjunto de regras técnicas que orienta como web services baseados em SOAP, WSDL e XML devem ser construídos para que sistemas diferentes consigam se comunicar sem incompatibilidades. Ele serve de referência para serviços governamentais, como os web services das SEFAZ usados na emissão e consulta de documentos fiscais eletrônicos. **Também conhecido como:** Basic Profile, Perfil Básico WS-I, WS-I BP, WS-I Basic Profile **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** W ## O que é o WS-I Basic Profile? O WS-I Basic Profile é uma especificação publicada pela WS-I, sigla de Web Services Interoperability Organization, um consórcio da indústria de tecnologia criado para melhorar a compatibilidade entre web services. A palavra profile, ou perfil, indica que ele não cria uma tecnologia nova: ele escolhe como usar tecnologias que já existem. Padrões como SOAP, WSDL e XML Schema são amplos e permitem várias interpretações. Na prática, isso fazia com que um serviço feito em uma linguagem de programação não funcionasse bem com um cliente feito em outra. O Basic Profile reduz essas ambiguidades, dizendo o que é obrigatório, o que é recomendado e o que deve ser evitado. ## Para que serve o WS-I Basic Profile? Ele serve para garantir interoperabilidade, ou seja, a capacidade de sistemas diferentes trocarem mensagens de forma previsível. Um ERP escrito em Java, um software de gestão em C# e uma plataforma em PHP podem consumir o mesmo web service se todos seguirem as mesmas regras. Para quem integra com órgãos públicos, isso significa menos surpresas: o formato das mensagens, a forma de descrever o serviço e o jeito de transmitir os dados seguem um padrão conhecido, documentado e suportado pelas principais ferramentas de desenvolvimento. ## Como funciona o WS-I Basic Profile na prática? O perfil estabelece regras sobre como montar o envelope SOAP, como escrever o arquivo WSDL que descreve o serviço, como usar XML Schema para definir os dados e como transportar as mensagens via HTTP ou HTTPS. Um exemplo comum é a preferência pelo estilo document/literal, em que o corpo da mensagem é um documento XML validado por um esquema, em vez de formatos de codificação mais antigos e menos padronizados. Também há regras sobre cabeçalhos, códigos de resposta HTTP e tratamento de erros por meio de mensagens SOAP Fault. ## Qual a relação do WS-I Basic Profile com a NF-e e outros documentos fiscais? Os web services das Secretarias da Fazenda usados para autorizar, cancelar e consultar documentos como NF-e, NFC-e, CT-e e MDF-e são baseados em SOAP e XML. Os manuais técnicos desses documentos citam o WS-I Basic Profile como referência de padronização da comunicação. Por isso, quem desenvolve uma integração direta com a SEFAZ precisa lidar com envelopes SOAP, arquivos WSDL, esquemas XML, certificado digital na conexão HTTPS e assinatura digital do XML. Pequenos desvios nessas regras costumam gerar falhas de comunicação ou rejeições difíceis de diagnosticar. ## Qual a diferença entre seguir o WS-I Basic Profile e usar uma API REST fiscal? O Basic Profile trata de web services SOAP, em que tudo é XML e a descrição do serviço fica em um WSDL. APIs REST costumam usar JSON, métodos HTTP simples e endpoints mais diretos, o que tende a ser mais fácil para desenvolvedores atuais. Uma API fiscal como a do Conota recebe os dados em JSON pelo sistema do cliente e cuida da comunicação SOAP com os órgãos autorizadores. Assim, a empresa não precisa implementar diretamente as exigências do Basic Profile, embora elas continuem existindo na comunicação com o fisco. ## Exemplos de WS-I Basic Profile - Um desenvolvedor que integra o ERP da empresa diretamente com a SEFAZ gera as classes de cliente a partir do WSDL do serviço de autorização da NF-e, confiando que ele segue o WS-I Basic Profile. - Uma equipe recebe erros de comunicação ao chamar o web service de consulta de status e descobre que o envelope SOAP montado manualmente não respeitava o estilo document/literal esperado. - Uma plataforma de vendas troca a integração SOAP própria por uma API REST de emissão fiscal, deixando para o provedor a conformidade com o WS-I Basic Profile e os esquemas XML oficiais. - Um software de gestão valida suas mensagens com ferramentas de teste de interoperabilidade antes de levá-las do ambiente de homologação para o ambiente de produção. ## Perguntas frequentes ### O WS-I Basic Profile é uma lei ou norma fiscal? Não. É uma especificação técnica de tecnologia, criada para padronizar web services. Ela aparece no contexto fiscal porque os serviços da SEFAZ adotam esse padrão como referência para a comunicação com os sistemas das empresas. ### Preciso conhecer o WS-I Basic Profile para emitir notas fiscais? Só se for integrar diretamente com os web services SOAP do fisco. Ao usar uma API fiscal que recebe JSON, como a do Conota, essa camada é tratada pelo provedor e o sistema da empresa não lida com SOAP. ### O WS-I Basic Profile vale para APIs REST? Não. Ele foi pensado para web services baseados em SOAP, WSDL e XML. APIs REST seguem outras convenções, normalmente usando JSON, métodos HTTP e documentação própria, sem depender desse perfil. ## Termos relacionados - [Esquema XML](https://conota.dev/glossario/esquema-xml.md) - [Arquivo XML fiscal](https://conota.dev/glossario/arquivo-xml-fiscal.md) - [Assinatura digital do XML](https://conota.dev/glossario/assinatura-digital-do-xml.md) - [HTTPS](https://conota.dev/glossario/https.md) - [API REST para emissão fiscal](https://conota.dev/glossario/api-rest-para-emissao-fiscal.md) - [Integração fiscal](https://conota.dev/glossario/integracao-fiscal.md) --- Fonte: [WS-I Basic Profile](https://conota.dev/glossario/ws-i-basic-profile/) · Atualizado em 2026-10-22 --- # WS-Policy > WS-Policy é uma especificação técnica que define como um web service baseado em SOAP descreve, em XML, suas regras e exigências de comunicação, como tipo de segurança, assinatura, criptografia e protocolos aceitos. Assim, o sistema que vai se conectar sabe de antemão quais condições precisa cumprir para que a troca de mensagens funcione corretamente. **Também conhecido como:** Web Services Policy, WS Policy, Web Services Policy Framework **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** W ## O que é WS-Policy, em palavras simples? Pense no WS-Policy como o regulamento de entrada de um prédio, escrito em linguagem que computadores entendem. Ele não executa a segurança, apenas informa as regras: se é preciso apresentar certificado, se a mensagem deve ser assinada, se o conteúdo precisa estar criptografado e assim por diante. Ele faz parte da família de especificações conhecidas como WS-* (WS-Security, WS-Addressing, WS-SecurityPolicy, entre outras), criadas para padronizar a comunicação entre web services do tipo SOAP. O nome completo em inglês é Web Services Policy Framework. ## Como funciona o WS-Policy? Uma política é um documento XML formado por asserções, que são requisitos ou capacidades individuais, por exemplo, exigir transporte via HTTPS ou exigir assinatura no corpo da mensagem. Essas asserções podem ser combinadas com operadores como All (todas devem ser atendidas) e ExactlyOne (apenas uma das alternativas deve ser escolhida). A política costuma ser anexada ao WSDL, o arquivo que descreve o web service, por meio de um mecanismo chamado Policy Attachment. Ferramentas de desenvolvimento leem esse WSDL, interpretam a política e configuram automaticamente o cliente para respeitar as regras exigidas pelo servidor. ## Para que serve o WS-Policy na integração fiscal? Muitos serviços de emissão de documentos fiscais no Brasil, como os web services das SEFAZ e de diversas prefeituras para NFS-e, foram construídos sobre SOAP e descritos por WSDL. Quando um desses serviços declara políticas, elas indicam ao desenvolvedor como a conexão e as mensagens devem ser montadas. Na prática, entender a política ajuda a evitar erros de comunicação difíceis de diagnosticar, como mensagens recusadas por falta de um cabeçalho de segurança ou por uso de um protocolo diferente do esperado. Como cada órgão pode ter suas próprias exigências, ler a documentação e a política de cada serviço é parte do trabalho de integração. ## Qual a diferença entre WS-Policy e WS-Security? O WS-Security define como aplicar segurança dentro da mensagem SOAP, por exemplo, como incluir assinaturas, tokens e criptografia no cabeçalho. Já o WS-Policy apenas descreve quais requisitos o serviço exige. Existe ainda o WS-SecurityPolicy, que fornece as asserções específicas de segurança usadas dentro de uma política WS-Policy. Em resumo: o WS-Policy é a estrutura geral, o WS-SecurityPolicy é o vocabulário de segurança e o WS-Security é a forma de aplicar essas regras na mensagem. ## Quem usa uma API fiscal REST precisa se preocupar com WS-Policy? Em geral, não diretamente. Quando o sistema emite documentos por meio de uma API REST para emissão fiscal, é o provedor da API que lida com os web services SOAP dos órgãos, incluindo políticas, certificados, assinaturas e formatos XML específicos de cada SEFAZ ou município. Isso permite que o desenvolvedor trabalhe com JSON e endpoints padronizados, sem precisar interpretar WSDL ou políticas de dezenas de serviços diferentes. O conceito continua útil, porém, para quem mantém integrações próprias ou precisa entender por que certos serviços exigem configurações tão específicas. ## Exemplos de WS-Policy - Um desenvolvedor importa o WSDL do web service de NFS-e de uma prefeitura e a ferramenta gera automaticamente um cliente configurado para enviar mensagens assinadas, porque a política anexada exige essa assinatura. - Uma política WS-Policy declara, com o operador ExactlyOne, que o serviço aceita autenticação por certificado digital ou por token de usuário, cabendo ao cliente escolher apenas uma das opções. - Uma equipe de ERP investiga por que suas requisições SOAP são recusadas e descobre, lendo a política do serviço, que faltava incluir um carimbo de tempo no cabeçalho de segurança. - Uma plataforma de vendas troca a integração direta com vários web services SOAP por uma API fiscal REST e deixa de precisar tratar as políticas de cada órgão separadamente. ## Perguntas frequentes ### WS-Policy é obrigatório em todo web service SOAP? Não. É opcional. Muitos serviços SOAP descrevem suas exigências apenas na documentação escrita, sem anexar políticas formais ao WSDL. Quando a política existe, ela facilita a configuração automática do cliente. ### WS-Policy é usado em APIs REST? Não. WS-Policy foi criado para o ecossistema SOAP e WSDL. APIs REST costumam descrever requisitos de autenticação e formato em sua documentação ou em especificações próprias, usando mecanismos como Bearer token, API Key e headers HTTP. ### O WS-Policy garante a segurança da comunicação? Não sozinho. Ele apenas declara as regras exigidas. A proteção real vem da aplicação dessas regras, como uso de HTTPS, certificados digitais, assinatura e criptografia das mensagens. ## Termos relacionados - [Esquema XML](https://conota.dev/glossario/esquema-xml.md) - [Assinatura digital do XML](https://conota.dev/glossario/assinatura-digital-do-xml.md) - [HTTPS](https://conota.dev/glossario/https.md) - [API REST para emissão fiscal](https://conota.dev/glossario/api-rest-para-emissao-fiscal.md) - [Endpoint de API](https://conota.dev/glossario/endpoint-de-api.md) - [Integração fiscal](https://conota.dev/glossario/integracao-fiscal.md) --- Fonte: [WS-Policy](https://conota.dev/glossario/ws-policy/) · Atualizado em 2026-10-22 --- # WS-ReliableMessaging > WS-ReliableMessaging é uma especificação técnica para web services baseados em SOAP que garante a entrega confiável de mensagens entre sistemas, mesmo diante de falhas de rede. Ela define sequências numeradas, confirmações de recebimento e reenvios automáticos, evitando mensagens perdidas, duplicadas ou fora de ordem na comunicação entre aplicações. **Também conhecido como:** WS-RM, Web Services Reliable Messaging, Mensageria confiável em web services **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** W ## O que é WS-ReliableMessaging? WS-ReliableMessaging, conhecido pela sigla WS-RM, é um padrão aberto mantido pelo consórcio OASIS. Ele faz parte da família de especificações WS-*, criada para complementar o protocolo SOAP, muito usado na troca de mensagens em XML entre sistemas corporativos. Seu objetivo é resolver um problema simples de entender: quando um sistema envia uma mensagem pela rede, nada garante que ela chegou. A conexão pode cair, o servidor pode reiniciar ou a resposta pode se perder no caminho. O WS-RM cria regras para que remetente e destinatário saibam exatamente o que foi entregue e o que precisa ser reenviado. ## Como funciona o WS-ReliableMessaging? O padrão define dois papéis: a origem (RM Source), que envia as mensagens, e o destino (RM Destination), que as recebe. Antes de começar, os dois abrem uma sequência, que funciona como uma conversa identificada por um código único. Cada mensagem enviada recebe um número dentro dessa sequência. O destino devolve confirmações (acknowledgements) informando quais números já recebeu. Se algum número não for confirmado, a origem reenvia apenas aquela mensagem. Ao final, a sequência é encerrada formalmente. Toda essa informação de controle viaja no cabeçalho da mensagem SOAP, separada do conteúdo de negócio. Assim, a aplicação continua tratando apenas os dados que importam, enquanto a camada de infraestrutura cuida da confiabilidade. ## Quais garantias de entrega o WS-ReliableMessaging oferece? A especificação descreve níveis de garantia que podem ser combinados: no máximo uma vez (a mensagem nunca é entregue em duplicidade, mas pode se perder), pelo menos uma vez (a mensagem sempre chega, mas pode chegar repetida) e exatamente uma vez (chega uma única vez, sem perdas nem duplicatas). Há ainda a garantia de ordem, que assegura que as mensagens sejam entregues à aplicação na mesma sequência em que foram enviadas. Isso é importante quando a ordem muda o resultado, como em um cancelamento que só faz sentido depois da emissão correspondente. ## O WS-ReliableMessaging é usado na emissão de notas fiscais? Os web services das autoridades fiscais brasileiras, como os usados para NF-e, CT-e e MDF-e, são baseados em SOAP, mas em geral não exigem WS-ReliableMessaging. A confiabilidade nesses ambientes é obtida por outros mecanismos, como consulta de recibo de lote, consulta pela chave de acesso e controle de numeração. Por isso, quem integra sistemas fiscais costuma aplicar os mesmos princípios do WS-RM por conta própria: identificar cada requisição de forma única, reenviar com cuidado em caso de falha e verificar o status antes de repetir uma emissão, evitando notas duplicadas. ## Qual a diferença entre WS-ReliableMessaging e idempotência em APIs REST? O WS-RM resolve a confiabilidade na camada do protocolo, com sequências e confirmações padronizadas entre os dois lados. Já em APIs REST, que normalmente usam JSON sobre HTTP, não existe um padrão equivalente tão difundido, e a confiabilidade é construída na aplicação. Nesse modelo, usa-se idempotência (uma chave que impede que a mesma operação seja processada duas vezes), retentativas com backoff exponencial, filas e webhooks para avisar o resultado. O efeito prático é parecido: evitar perdas e duplicidades, mas com ferramentas mais simples e flexíveis. ## Exemplos de WS-ReliableMessaging - Um ERP legado integrado a um parceiro logístico via SOAP usa WS-ReliableMessaging para garantir que cada pedido de coleta chegue exatamente uma vez, mesmo com instabilidade na rede. - Um banco configura WS-RM em seus serviços SOAP internos para que ordens de transferência sejam entregues na ordem correta e sem duplicidade entre sistemas de diferentes áreas. - Uma equipe que migra uma integração SOAP para uma API REST de emissão fiscal substitui o WS-RM por chaves de idempotência e consulta de status, mantendo a garantia de não emitir a mesma nota duas vezes. - Um desenvolvedor configura o WS-RM em um framework de web services Java para que mensagens não confirmadas sejam reenviadas automaticamente após uma queda do servidor de destino. ## Perguntas frequentes ### WS-ReliableMessaging funciona com APIs REST? Não diretamente. O WS-RM foi projetado para mensagens SOAP e usa cabeçalhos específicos desse protocolo. Em APIs REST, a confiabilidade é obtida com idempotência, retentativas controladas, filas e webhooks. ### Preciso implementar WS-ReliableMessaging para emitir NF-e? Em geral, não. Os web services fiscais brasileiros não costumam exigi-lo. A segurança contra perdas e duplicidades vem da consulta de recibo, da chave de acesso e de boas práticas de reenvio no sistema emissor. ### WS-ReliableMessaging garante segurança dos dados? Não. Ele trata apenas da entrega confiável. Criptografia, autenticação e integridade são responsabilidade de outros mecanismos, como HTTPS, assinatura digital e especificações como WS-Security. ### Qual a diferença entre WS-RM e uma fila de mensagens? O WS-RM é um protocolo de entrega confiável entre dois pontos de um web service. Uma fila armazena mensagens para processamento posterior. Ambos buscam evitar perdas, mas atuam em camadas diferentes e podem ser usados juntos. ## Termos relacionados - [Idempotência na emissão fiscal](https://conota.dev/glossario/idempotencia-na-emissao-fiscal.md) - [Backoff exponencial](https://conota.dev/glossario/backoff-exponencial.md) - [Fluxo assíncrono de emissão](https://conota.dev/glossario/fluxo-assincrono-de-emissao.md) - [Fila de emissão fiscal](https://conota.dev/glossario/fila-de-emissao-fiscal.md) - [API REST para emissão fiscal](https://conota.dev/glossario/api-rest-para-emissao-fiscal.md) - [HTTP](https://conota.dev/glossario/http.md) --- Fonte: [WS-ReliableMessaging](https://conota.dev/glossario/ws-reliablemessaging/) · Atualizado em 2026-10-22 --- # WS-Security > WS-Security é um padrão de segurança para webservices baseados em SOAP que define como incluir, no cabeçalho da mensagem XML, informações de autenticação, assinatura digital e criptografia. Ele garante que a mensagem venha de quem diz ter enviado, não tenha sido alterada no caminho e, se necessário, só possa ser lida pelo destinatário. **Também conhecido como:** Web Services Security, WSS, WS Security, Segurança de webservices SOAP **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** W ## O que é WS-Security, em palavras simples? WS-Security é um conjunto de regras que diz como proteger mensagens trocadas entre sistemas que usam o protocolo SOAP. Em vez de confiar apenas no canal de comunicação, ele coloca a segurança dentro da própria mensagem, em uma área do cabeçalho chamada Security. Uma boa comparação é um envelope lacrado e assinado: mesmo que ele passe por vários intermediários, quem recebe consegue verificar quem enviou e se alguém mexeu no conteúdo. O nome vem de Web Services Security, e a sigla WSS também é usada. ## Como funciona o WS-Security? O padrão combina três mecanismos que podem ser usados juntos ou separados. O primeiro são os tokens de segurança, que identificam o remetente, como um usuário e senha (UsernameToken) ou um certificado digital X.509. O segundo é a assinatura digital de partes da mensagem, baseada no padrão XML Signature. O terceiro é a criptografia de trechos do XML, baseada no padrão XML Encryption. Também é comum incluir um carimbo de tempo (Timestamp) no cabeçalho, indicando quando a mensagem foi criada e até quando é válida. Isso ajuda a impedir que alguém capture uma mensagem legítima e a reenvie depois. ## Onde o WS-Security aparece na emissão fiscal? Muitos serviços fiscais no Brasil, como os da SEFAZ e de diversas prefeituras, ainda funcionam com webservices SOAP. Alguns webservices municipais de NFS-e exigem WS-Security no cabeçalho, seja com usuário e senha, seja com assinatura usando o certificado digital do emissor. Como cada autorizador pode adotar uma variação diferente do padrão, integrar diretamente com vários municípios exige montar cabeçalhos específicos, tratar namespaces XML corretamente e acompanhar mudanças de leiaute. Esse é um dos motivos pelos quais empresas preferem usar uma API fiscal, que esconde essa complexidade atrás de uma única integração REST. ## Qual a diferença entre WS-Security e mTLS ou HTTPS? HTTPS e mTLS protegem o canal de comunicação: os dados ficam criptografados durante o trajeto entre dois pontos, e no mTLS os dois lados se autenticam com certificados. Quando a conexão termina, essa proteção não acompanha a mensagem. O WS-Security protege a mensagem em si. A assinatura e a criptografia continuam válidas mesmo que o XML seja armazenado ou repassado por intermediários. Na prática, muitos serviços usam as duas camadas ao mesmo tempo: o canal seguro por TLS e a mensagem protegida por WS-Security. ## WS-Security é a mesma coisa que assinar o XML da nota? Não. A assinatura digital do XML de uma NF-e ou NFS-e faz parte do próprio documento fiscal e comprova a autoria e a integridade da nota, mesmo anos depois. Ela é exigida pelo leiaute do documento. O WS-Security atua no envelope SOAP usado para transportar o pedido até o webservice. Ele protege a requisição naquele momento, não o documento fiscal como registro permanente. Um mesmo envio pode ter as duas assinaturas: a da nota, dentro do corpo, e a do WS-Security, no cabeçalho. ## Exemplos de WS-Security - Uma prefeitura exige que cada requisição ao seu webservice de NFS-e traga, no cabeçalho SOAP, um UsernameToken com o login e a senha cadastrados pelo prestador de serviço. - Um ERP envia um lote de RPS para um webservice municipal que exige o cabeçalho WS-Security assinado com o certificado digital A1 da empresa, além do Timestamp de validade da mensagem. - Um desenvolvedor recebe a falha 'Security header is missing' ao testar no ambiente de homologação e descobre que esqueceu de incluir o bloco Security no envelope SOAP. - Uma plataforma de vendas integra a API REST do Conota em JSON, e a montagem dos cabeçalhos WS-Security exigidos por determinados municípios fica a cargo da infraestrutura de emissão. ## Perguntas frequentes ### WS-Security funciona com APIs REST? Não diretamente. O padrão foi criado para mensagens SOAP em XML. APIs REST costumam usar outros mecanismos, como Bearer token, OAuth 2.0, JWT, JWS e HMAC, além de HTTPS para proteger o canal. ### Preciso de certificado digital para usar WS-Security? Depende do serviço. Alguns aceitam apenas usuário e senha no UsernameToken. Outros exigem assinatura com certificado X.509, como o certificado digital A1 da empresa emissora. ### Toda prefeitura usa WS-Security na NFS-e? Não. Cada município ou provedor define sua forma de autenticação. Alguns usam WS-Security, outros apenas mTLS, assinatura do XML ou credenciais no corpo da mensagem. O Padrão Nacional da NFS-e também tem regras próprias. ### O que acontece se o cabeçalho WS-Security estiver errado? O webservice normalmente recusa a requisição antes mesmo de analisar a nota, devolvendo uma falha SOAP de autenticação ou de segurança. O documento não chega a ser processado nem autorizado. ## Termos relacionados - [SOAP](https://conota.dev/glossario/soap.md) - [Assinatura digital do XML](https://conota.dev/glossario/assinatura-digital-do-xml.md) - [mTLS](https://conota.dev/glossario/mtls.md) - [Certificado digital A1](https://conota.dev/glossario/certificado-digital-a1.md) - [Header de autenticação](https://conota.dev/glossario/header-de-autenticacao.md) - [Namespace XML](https://conota.dev/glossario/namespace-xml.md) --- Fonte: [WS-Security](https://conota.dev/glossario/ws-security/) · Atualizado em 2026-10-22 --- # WS-Trust > WS-Trust é uma especificação de segurança para serviços web baseados em SOAP que define como solicitar, emitir, renovar e validar tokens de segurança. Ela cria a figura de um serviço emissor de tokens, que confirma a identidade de quem pede acesso e entrega uma credencial confiável para ser usada em outros sistemas. **Também conhecido como:** Web Services Trust, WS-Trust Language, WS-Trust **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** W ## O que é WS-Trust, em termos simples? WS-Trust é um conjunto de regras técnicas que diz como dois sistemas podem estabelecer confiança entre si antes de trocar informações por serviços web do tipo SOAP. Em vez de cada sistema verificar diretamente a identidade de todos os outros, existe um intermediário confiável que emite uma espécie de crachá digital, chamado token de segurança. A especificação é mantida pela OASIS, organização que publica padrões abertos, e funciona como uma extensão do WS-Security, que trata de proteger as mensagens SOAP com assinatura e criptografia. ## Como funciona o WS-Trust? O ponto central é o Security Token Service, ou STS, um serviço especializado em emitir tokens. O sistema que quer acessar um recurso envia ao STS uma mensagem chamada RequestSecurityToken, apresentando alguma prova de identidade, como usuário e senha, um certificado digital ou outro token já existente. Se a prova for aceita, o STS responde com uma RequestSecurityTokenResponse contendo o token, que pode estar em formatos como SAML. O sistema então anexa esse token às mensagens enviadas ao serviço de destino, que confia no STS e, por isso, aceita o token sem precisar conferir as credenciais originais. Além da emissão, a especificação prevê operações para renovar um token prestes a expirar, validar se um token ainda é legítimo e cancelá-lo quando não for mais necessário. ## Para que serve o WS-Trust? Ele serve principalmente para federação de identidade: permitir que uma organização reconheça usuários ou sistemas autenticados por outra, sem compartilhar senhas. Também ajuda a centralizar a autenticação, já que vários serviços passam a confiar em um único emissor de tokens. Outro uso comum é a troca de credenciais, quando um sistema possui um tipo de token e precisa de outro formato para falar com um serviço diferente. O STS faz essa conversão de forma controlada. ## O WS-Trust é usado na emissão de documentos fiscais? Na integração com os serviços oficiais de NF-e, NFC-e, CT-e e MDF-e, a autenticação costuma se apoiar em conexão HTTPS com certificado digital do emitente e na assinatura digital do XML, e não em um fluxo WS-Trust. Os requisitos exatos dependem de cada serviço e, no caso da NFS-e, podem variar conforme o município ou o padrão adotado. O WS-Trust aparece com mais frequência em ambientes corporativos baseados em SOAP, como integrações entre ERPs legados, serviços internos de grandes empresas ou plataformas de identidade federada. Uma equipe pode encontrá-lo ao integrar o sistema fiscal com outras partes da infraestrutura da empresa. ## Qual a diferença entre WS-Trust e autenticação com JWT ou Bearer token? O WS-Trust pertence ao mundo SOAP e XML, com mensagens mais longas e estruturadas. Já o uso de JWT e Bearer token é típico de APIs REST, que trocam dados em JSON e enviam o token em um cabeçalho HTTP de forma mais leve. A ideia de fundo é parecida: um emissor confiável entrega um token que comprova identidade e permissões. A diferença está no formato, no protocolo e na complexidade. Por isso, APIs fiscais modernas tendem a usar API Key, Bearer token ou JWT, enquanto o WS-Trust permanece comum em integrações SOAP mais antigas ou muito formais. ## Exemplos de WS-Trust - Uma empresa com ERP legado baseado em SOAP usa um STS interno compatível com WS-Trust para emitir tokens que liberam o acesso do módulo financeiro ao serviço de cadastro de clientes. - Um grupo empresarial com várias filiais adota WS-Trust para que usuários autenticados no diretório da matriz acessem serviços web das filiais sem precisar de novas senhas. - Um integrador recebe um token SAML do STS de um parceiro via WS-Trust e o anexa às mensagens SOAP enviadas ao sistema desse parceiro para consultar pedidos antes de solicitar a emissão das notas fiscais por uma API REST. - Uma equipe de TI configura a renovação automática de tokens WS-Trust para evitar que integrações noturnas entre sistemas internos falhem por expiração de credencial. ## Perguntas frequentes ### O que significa STS no WS-Trust? STS significa Security Token Service, o serviço responsável por emitir, renovar, validar e cancelar tokens de segurança. Ele é o intermediário confiável que verifica a identidade de quem pede acesso e entrega a credencial usada nas chamadas seguintes. ### Preciso conhecer WS-Trust para emitir notas fiscais por API? Em geral, não. APIs fiscais no padrão REST costumam usar API Key, Bearer token ou JWT. O WS-Trust só se torna relevante se sua empresa precisar integrar sistemas SOAP que exijam esse tipo de autenticação. ### Qual a relação entre WS-Trust e WS-Security? O WS-Security define como proteger mensagens SOAP com assinatura, criptografia e tokens. O WS-Trust se apoia nele e acrescenta as regras para obter, renovar e validar esses tokens por meio de um serviço emissor. ## Termos relacionados - [Bearer token](https://conota.dev/glossario/bearer-token.md) - [JWT](https://conota.dev/glossario/jwt.md) - [Assinatura digital do XML](https://conota.dev/glossario/assinatura-digital-do-xml.md) - [Header de autenticação](https://conota.dev/glossario/header-de-autenticacao.md) - [HTTPS](https://conota.dev/glossario/https.md) - [Certificado digital A1](https://conota.dev/glossario/certificado-digital-a1.md) --- Fonte: [WS-Trust](https://conota.dev/glossario/ws-trust/) · Atualizado em 2026-10-22 --- # WSDL > WSDL é um documento em formato XML que descreve um serviço web baseado em SOAP: quais operações ele oferece, que dados cada operação recebe e devolve, como as mensagens devem ser montadas e em qual endereço o serviço está disponível. Funciona como um manual técnico que os sistemas leem para saber como conversar com o serviço. **Também conhecido como:** Arquivo WSDL, Descritor de serviço web, Contrato WSDL, WSDL, Web Services Description Language **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** W ## O que significa WSDL? WSDL é a sigla de Web Services Description Language, ou Linguagem de Descrição de Serviços Web. Trata-se de um padrão para escrever, em XML, a descrição completa de um serviço que pode ser acessado pela internet. Na prática, o WSDL é um arquivo que fica publicado junto ao serviço. Quem quer usar o serviço consulta esse arquivo para entender o que pode pedir, em que formato deve enviar os dados e o que vai receber de volta. ## Para que serve o WSDL? O WSDL funciona como um contrato entre quem oferece o serviço e quem o consome. Ele define com precisão as regras da conversa, evitando que cada desenvolvedor precise adivinhar nomes de campos, tipos de dados ou endereços. Outra vantagem é a automação: muitas linguagens de programação têm ferramentas que leem o WSDL e geram automaticamente o código necessário para chamar o serviço. Assim, o programador trabalha com funções prontas em vez de montar cada mensagem XML manualmente. ## Como é a estrutura de um WSDL? Um WSDL costuma ser dividido em blocos. Os tipos (types) descrevem os dados, geralmente usando um esquema XML. As mensagens (messages) indicam o que é enviado e recebido. As operações (agrupadas em portType ou interface) listam as ações disponíveis, como autorizar ou consultar. Há ainda o binding, que informa o protocolo e o formato usados, normalmente SOAP sobre HTTP, e o service, que aponta o endereço real (endpoint) onde o serviço responde. Juntos, esses blocos dizem o que o serviço faz, como falar com ele e onde encontrá-lo. ## Onde o WSDL aparece na emissão de documentos fiscais? Os web services das SEFAZ usados para NF-e, NFC-e, CT-e e MDF-e são baseados em SOAP e descritos por WSDLs. Cada serviço, como autorização, consulta de protocolo, status do serviço e recepção de eventos, tem seu próprio endereço e sua descrição. Muitas prefeituras também oferecem a emissão de NFS-e por web services SOAP com WSDL, e cada uma pode ter estrutura, operações e regras diferentes. Por isso, quem integra diretamente com vários municípios precisa lidar com diversos WSDLs, além de certificado digital e conexão segura exigidos pelos órgãos. ## Qual a diferença entre WSDL e OpenAPI? Os dois descrevem serviços, mas para estilos diferentes. O WSDL descreve serviços SOAP, que trocam mensagens em XML. O OpenAPI descreve APIs REST, que geralmente trocam dados em JSON e usam os métodos do HTTP, como GET e POST. Em termos de uso, o OpenAPI é mais comum em APIs modernas e costuma ser exibido em documentações interativas, como o Swagger UI. O WSDL segue presente em sistemas governamentais e corporativos mais antigos, onde o SOAP ainda é o padrão. ## Preciso lidar com WSDL ao usar uma API fiscal? Depende de como a integração é feita. Quem conecta seu sistema diretamente à SEFAZ ou às prefeituras precisa ler os WSDLs, gerar clientes SOAP e acompanhar mudanças de endereços e leiautes. Ao usar uma API fiscal REST, como a do Conota, essa camada fica com o provedor. O sistema do cliente envia dados em JSON para um único endpoint, e a comunicação SOAP com os órgãos autorizadores acontece nos bastidores. ## Exemplos de WSDL - Um desenvolvedor de ERP importa o WSDL do serviço de NFS-e de uma prefeitura em sua ferramenta de programação, que gera automaticamente as classes para enviar o lote de RPS e consultar o resultado. - Durante testes no ambiente de homologação, a equipe acessa o endereço do serviço de autorização da NF-e com o sufixo ?wsdl para verificar quais operações estão disponíveis e qual é o formato esperado da mensagem. - Após uma nota técnica, um órgão autorizador altera a versão de um web service, e a equipe de integração precisa atualizar o cliente gerado a partir do novo WSDL para continuar emitindo. - Uma plataforma de vendas que emite NFS-e em vários municípios troca as integrações SOAP individuais por uma API REST de emissão fiscal, deixando de manter dezenas de WSDLs diferentes. ## Perguntas frequentes ### WSDL é a mesma coisa que SOAP? Não. SOAP é o protocolo que define o formato das mensagens trocadas entre os sistemas. O WSDL é o documento que descreve um serviço SOAP: suas operações, mensagens e endereço. Um descreve, o outro é usado na comunicação. ### Onde encontro o WSDL de um serviço? Normalmente, ele é publicado pelo próprio provedor do serviço. Em muitos casos, basta acrescentar ?wsdl ao endereço do web service. Órgãos fiscais costumam divulgar os endereços em seus portais e manuais de integração. ### O WSDL substitui o esquema XML (XSD)? Não. O WSDL descreve o serviço como um todo e geralmente referencia esquemas XML para definir os dados. Na emissão fiscal, os XSDs do leiaute validam o conteúdo do documento, enquanto o WSDL define como enviá-lo. ### Preciso conhecer WSDL para usar o Conota? Não. O Conota funciona por API REST com dados em JSON. A comunicação SOAP com SEFAZ e prefeituras, incluindo o uso dos WSDLs, é tratada pela própria infraestrutura de emissão. ## Termos relacionados - [SOAP](https://conota.dev/glossario/soap.md) - [Esquema XML](https://conota.dev/glossario/esquema-xml.md) - [Endpoint de API](https://conota.dev/glossario/endpoint-de-api.md) - [OpenAPI](https://conota.dev/glossario/openapi.md) - [Namespace XML](https://conota.dev/glossario/namespace-xml.md) - [REST](https://conota.dev/glossario/rest.md) --- Fonte: [WSDL](https://conota.dev/glossario/wsdl/) · Atualizado em 2026-10-22