Você recebeu um endpoint SOAP. Talvez seja um conversor de moeda legado que sua equipe de cobrança ainda usa, ou um serviço web de gerenciamento de pedidos que um parceiro executa em .NET. Você precisa chamá-lo, confirmar que ele retorna o que o contrato promete e provar que ele permanece correto à medida que o código ao redor muda. As ferramentas REST não se encaixam perfeitamente, porque o SOAP exige um envelope XML completo, um Content-Type específico e um WSDL que descreve cada operação.
O Apidog lida com requisições SOAP e WebService ao lado de REST, GraphQL e gRPC, então você não precisa de um aplicativo separado para aquele único serviço legado em sua pilha. Este guia aborda os dois caminhos documentados: enviar uma requisição SOAP manualmente e importar um WSDL para que o Apidog construa o ambiente e os endpoints para você. Se você quiser primeiro uma visão mais ampla dos protocolos, nossa comparação entre REST, GraphQL, gRPC e SOAP explica onde cada um se encaixa. Para a definição formal da estrutura do envelope, a especificação SOAP do W3C é a fonte autoritária.
O que é SOAP e por que ele precisa de tratamento diferente
O Apidog descreve o SOAP como o Simple Object Access Protocol, um protocolo de comunicação baseado em XML que permite que diversas plataformas e linguagens de programação se comuniquem. Essa única ideia explica por que tantas empresas ainda o utilizam. Um cliente Java e um serviço .NET podem se comunicar através do mesmo contrato sem se importar com os detalhes internos um do outro.
Três propriedades são importantes ao testá-lo. O SOAP usa XML para formatação de mensagens, então cada requisição e resposta é um documento estruturado, não um blob JSON solto. Se o XML em si é um território desconhecido, a referência XML da MDN é um excelente guia sobre a sintaxe que você estará lendo e escrevendo. Geralmente, ele viaja sobre HTTP ou HTTPS, embora o protocolo suporte outros. E segue os padrões do W3C para comunicação estruturada e confiável, razão pela qual a forma da mensagem é rigorosa e as regras de validação são firmes.
Essa rigidez é a razão pela qual os endpoints SOAP permanecem em serviço para integração entre plataformas, pontes de sistemas legados para modernos e transações seguras usando WS-Security para mensagens criptografadas e autenticadas. É também por isso que você não pode simplesmente enviar uma requisição estilo REST para um deles. Você precisa do cabeçalho correto, um corpo XML encapsulado em um envelope SOAP e uma maneira de ler o XML que retorna. Se você quiser uma análise mais aprofundada de como o envelope e seu corpo transportam dados, consulte nossa análise de APIs SOAP e XML.
Antes de começar
Um requisito fundamental antecede tudo abaixo. Para enviar uma requisição SOAP ou WebService, o Apidog precisa ser da versão 2.1.31 ou superior. Versões anteriores não oferecem suporte. Abra o Apidog, verifique sua versão e atualize se estiver desatualizado. Todo o restante deste guia presume que você está na versão 2.1.31 ou posterior.
Se você ainda não tem o Apidog, baixe-o e acompanhe. Experimente gratuitamente, sem necessidade de cartão de crédito.
Você também vai querer ter os detalhes do seu serviço de destino em mãos: a URL do endpoint, o nome da operação que deseja chamar e seus parâmetros. Se você tiver um arquivo WSDL, mantenha-o por perto, pois a segunda parte deste guia o importa diretamente.
Caminho A: enviar uma requisição SOAP manualmente
Este é o caminho quando você tem um endpoint e sabe a operação que deseja chamar. Existem três coisas que você define e que uma requisição REST não precisa, e acertá-las é todo o trabalho.
Passo 1: definir o cabeçalho Content-Type manualmente
As requisições SOAP não inferem seu próprio cabeçalho. Você define o Content-Type manualmente, e existem dois valores válidos:
text/xml; charset=utf-8application/soap+xml
Qual deles está correto depende do serviço. Endpoints SOAP 1.1 geralmente esperam text/xml; charset=utf-8, enquanto endpoints SOAP 1.2 frequentemente desejam application/soap+xml. Se você não tiver certeza, verifique o WSDL ou a documentação do serviço, e se o primeiro valor retornar um erro sobre o tipo de conteúdo, mude para o outro. Adicione o cabeçalho na seção Headers da requisição antes de enviar.
Passo 2: definir o formato do corpo como XML e colar o envelope
Defina o formato do corpo da requisição como xml, e então cole o envelope SOAP. O envelope é um documento com declarações de namespace e um elemento Body que contém a operação que você está chamando, além de quaisquer parâmetros aninhados dentro dele.
Aqui está um exemplo prático contra um serviço público de conversão de números para palavras, o mesmo formato que o Apidog usa em sua documentação. A operação é NumberToWords e recebe um parâmetro, ubiNum:
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:web="http://www.dataaccess.com/webservicesserver/">
<soap:Body>
<web:NumberToWords>
<web:ubiNum>1234</web:ubiNum>
</web:NumberToWords>
</soap:Body>
</soap:Envelope>
O namespace na operação deve corresponder ao que o serviço espera, e é por isso que você o lê do WSDL em vez de adivinhar. O soap:Body envolve a chamada real; web:NumberToWords é a operação; web:ubiNum é a entrada.
Passo 3: enviar e ler a resposta XML
Envie a requisição. A resposta retorna em XML, como um envelope SOAP cujo Body contém a operação de resposta. Para a chamada acima, você recebe um NumberToWordsResponse com o resultado aninhado:
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<m:NumberToWordsResponse xmlns:m="http://www.dataaccess.com/webservicesserver/">
<m:NumberToWordsResult>one thousand two hundred and thirty four</m:NumberToWordsResult>
</m:NumberToWordsResponse>
</soap:Body>
</soap:Envelope>
A resposta espelha a requisição: o nome da operação ganha um sufixo Response, e o valor aparece em um elemento de resultado. Esse espelhamento é o que você verifica. Você confirma que o envelope retornou, que o nó NumberToWordsResponse existe e que o resultado corresponde ao que você esperava. A documentação dedicada do WebService do Apidog em webservice.apidog.io contém a referência completa de configuração e mais exemplos de envelopes, caso você queira um segundo exemplo prático.
Um caso de uso realista segue os mesmos três passos. Troque NumberToWords por uma operação ConvertCurrency em um serviço legado de taxa de câmbio, passe fromCurrency, toCurrency e amount como elementos aninhados, e leia o valor convertido do envelope de resposta. Ou chame uma operação GetOrderStatus em um serviço web de pedidos, passe um orderId, e verifique o nó de status retornado. A mecânica nunca muda: cabeçalho, corpo XML, enviar, ler o envelope.
Caminho B: importar um WSDL para gerar os endpoints
Digitar envelopes manualmente é bom para uma única chamada. Quando um serviço expõe uma dúzia de operações, deixe o WSDL fazer o trabalho. Um arquivo WSDL descreve cada operação, suas entradas e o endereço do serviço, e o Apidog lê tudo isso em uma única importação.
Aqui está o caminho exato de cliques:
- Vá para Configurações, depois Importar Dados.
- Selecione
WSDL. - Faça upload do seu arquivo
.wsdlou.xml. - Revise a pré-visualização dos endpoints da API que o Apidog analisou do arquivo.
- Abra a aba
Environmentse verifique se o endereço do serviço está correto. - Clique em
Confirmar. O ambiente importado é criado automaticamente. - Selecione o ambiente importado no canto superior direito.
- Envie uma requisição. A URL Base é aplicada automaticamente a partir desse ambiente.
Dois passos nessa lista são aqueles que as pessoas pulam e depois se arrependem.
O Passo 5 é importante porque o endereço do serviço no WSDL é o endpoint que cada requisição importada atingirá. Se ele apontar para um host de staging, ou uma URL de placeholder que o autor do WSDL nunca atualizou, suas requisições irão para o lugar errado. Verifique-o na aba Environments antes de clicar em Confirmar, não depois.
O Passo 7 é importante porque a URL Base reside nesse ambiente criado automaticamente. Se você não selecionar o ambiente importado no canto superior direito, suas requisições não terão um endereço base e falharão. Selecione-o primeiro, depois envie.
Uma vez importado, cada operação aparece como um endpoint que você pode chamar sem precisar escrever o envelope, e você verifica a resposta XML exatamente como no Caminho A. Se você estiver migrando um projeto inteiro de outra ferramenta, nosso guia para importar projetos SOAP cobre a migração de ponta a ponta.
Observe uma limitação importante: a importação de WSDL é documentada para upload de arquivos .wsdl e .xml. A importação de um WSDL por URL ou colando seu conteúdo não é documentada, então faça o upload do arquivo em vez de esperar um campo de URL.
Vindo do SoapUI
Se seus testes SOAP atualmente residem no SoapUI, você não precisa reconstruí-los do zero. Exporte ou mantenha seu WSDL, importe-o para o Apidog com o Caminho B, e você terá as mesmas operações como endpoints chamáveis dentro de um workspace que também faz design, mocking e documentação. O ganho é a consolidação: um único projeto contém seu serviço SOAP, seus endpoints REST e seus cenários de teste, em vez de espalhá-los por ferramentas separadas. Nossa comparação lado a lado de Apidog versus SoapUI mostra o que é mantido e onde os fluxos de trabalho diferem.
Asserções e variações
Uma única chamada bem-sucedida prova que o endpoint está ativo. Um teste prova que ele está correto. Uma vez que sua requisição SOAP retorna, adicione asserções no envelope de resposta: confirme que o nó da operação de resposta esperado está presente, extraia o elemento de resultado e verifique seu valor em relação ao que o contrato promete. Para um serviço de moeda, você verifica se o valor convertido é um número dentro do intervalo; para um serviço de pedido, você verifica se o status é um dos valores permitidos.
A partir daí, você constrói um cenário de teste repetível que encadeia chamadas, por exemplo, criar um pedido, depois consultar seu status, passando valores entre as etapas. Nosso guia sobre como escrever um cenário de teste com Apidog mostra como conectar valores extraídos a requisições posteriores. O padrão é agnóstico ao protocolo, então um cenário pode misturar uma chamada SOAP com os endpoints REST ao seu redor.
Para endpoints seguros, o SOAP geralmente usa WS-Security para mensagens criptografadas e autenticadas. Esse cabeçalho de segurança faz parte do envelope SOAP que você envia, então você adiciona o bloco de segurança wsse dentro do cabeçalho do envelope, junto com sua operação. A mecânica de envio permanece a mesma: defina o Content-Type, coloque o envelope completo, incluindo o cabeçalho de segurança, no corpo XML e envie.
Automatize o fluxo de trabalho com a CLI do Apidog
Uma vez que suas requisições SOAP ou importadas via WSDL são salvas como cenários de teste, a CLI do Apidog as executa a partir da linha de comando para que um pipeline possa exercitá-las a cada push. Instale-a com Node.js v16 ou posterior e autentique-se:
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Execute um cenário salvo por ID, contra o ambiente que sua importação WSDL criou:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Aqui -t é o ID do cenário de teste, -e é o ID do ambiente, e -r é o reporter (cli, html ou junit, separados por vírgula para vários). Uma ressalva honesta: a documentação confirma que o runner executa cenários de teste e suítes salvos, mas não afirma se cenários construídos em etapas SOAP são executados sem interface gráfica (headless), então trate a CLI como seu motor para os cenários HTTP do projeto e para manter os endpoints importados do WSDL sincronizados na CI, em vez de assumir a execução específica de SOAP. A integração em um pipeline é abordada em nosso guia CI/CD da CLI do Apidog.
FAQ (Perguntas Frequentes)
Qual Content-Type devo usar para uma requisição SOAP? Ou text/xml; charset=utf-8 ou application/soap+xml. O correto depende do serviço: endpoints SOAP 1.1 geralmente esperam o primeiro, endpoints SOAP 1.2 o segundo. Defina-o manualmente nos cabeçalhos da requisição, e se você receber um erro de tipo de conteúdo, mude para o outro valor.
Preciso de um plano pago para testar SOAP no Apidog? O único requisito documentado é que o Apidog seja da versão 2.1.31 ou superior. Nenhuma restrição de nível de plano ou hospedagem própria é mencionada para o suporte a SOAP ou WSDL, então atualize para uma versão atual e você estará pronto.
Posso importar um WSDL de uma URL? A importação de WSDL documentada aceita uploads de arquivos .wsdl e .xml. A importação por URL ou colando o texto do WSDL não é documentada, então faça o upload do arquivo. Após a importação, o ambiente é criado automaticamente e você o seleciona no canto superior direito antes de enviar.
Como testo APIs SOAP e REST no mesmo projeto? O Apidog as trata como tipos de requisição dentro de um único workspace, então um único projeto pode conter operações SOAP ao lado de endpoints REST e até mesmo chamadas GraphQL. Se GraphQL também está em sua pauta, nosso guia para testar APIs GraphQL no Apidog aborda esse lado, e um cenário de teste pode encadear requisições entre todos eles.
Minhas requisições importadas via WSDL estão atingindo o servidor errado. O que aconteceu? Duas causas comuns. Ou o endereço do serviço na aba Environments estava errado no momento da importação e você clicou em Confirmar sem verificar, ou você não selecionou o ambiente importado no canto superior direito, então nenhuma URL Base foi aplicada. Reimporte e verifique o endereço, depois certifique-se de que o ambiente correto está ativo antes de enviar.
Concluindo
Testar SOAP não precisa significar uma ferramenta legada separada. No Apidog, você pode enviar o envelope manualmente (definir o Content-Type, definir o corpo como xml, colar o envelope, ler a resposta XML) ou importar um WSDL e deixar o Apidog construir os endpoints e o ambiente para você. Ambos os caminhos levam ao mesmo lugar: uma verificação repetível de que seu serviço web ainda cumpre seu contrato. Baixe o Apidog na versão 2.1.31 ou superior, importe seu WSDL e coloque seus serviços legados sob os mesmos testes que o restante da sua superfície de API.