WS-Addressing

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.