framework-soap

Fornece padrões de engenharia e integração de serviços web baseados nos padrões W3C SOAP 1.1/1.2 e WSDL 1.1/2.0. Cobre estrutura do XML Envelope, segurança de mensagens com WS-Security (WSS), assinatu

SKILL.md

GitHub

Habilidade de IA: Engenharia e Integração de Serviços SOAP (framework-soap)

Esta skill orienta a inteligência artificial a atuar como especialista nos protocolos de comunicação orientados a mensagens SOAP (Simple Object Access Protocol) e definições de serviço WSDL (Web Services Description Language), alinhada às recomendações do W3C (w3.org/TR/soap/) e especificações WS-*. Cobre integrações corporativas legadas, bancos, governança de esquemas XML e padrões de segurança de mensagens.


🧭 Estrutura da Mensagem SOAP e Contrato WSDL

1. Estrutura do Envelope SOAP (1.1 / 1.2)

Toda mensagem SOAP deve ser um documento XML válido estruturado em um Envelope, um Header opcional (usado para credenciais e WS-Addressing) e um Body contendo os dados do método ou o erro (Fault):

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:web="http://services.empresa.com/banking">
   <soapenv:Header>
      <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
         <wsse:UsernameToken>
            <wsse:Username>usuario_api</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">senha_segura</wsse:Password>
         </wsse:UsernameToken>
      </wsse:Security>
   </soapenv:Header>
   <soapenv:Body>
      <web:ConsultarSaldoRequest>
         <web:NumeroConta>123456-7</web:NumeroConta>
      </web:ConsultarSaldoRequest>
   </soapenv:Body>
</soapenv:Envelope>

2. Desenvolvimento Contract-First (WSDL & XSD)

  • Desenvolva contratos estritos em WSDL definindo types, message, portType (ou interface), binding e service.
  • Defina tipos de dados complexos em schemas XSD (XML Schema Definition) separados para reaproveitamento e validação forte no parser XML antes da execução da lógica de negócios.

🔒 Segurança de Mensagens Corporativas (WS-Security)

Diferente do REST/gRPC que dependem prioritariamente de TLS no transporte, o SOAP suporta criptografia e assinatura de segurança no nível de mensagem (WS-Security):

  • UsernameToken Profile: Autenticação de usuário e hash digest de senha no Header.
  • X.509 Certificate Token Profile: Uso de chaves assimétricas para assinatura digital (XML-Signature) de partes específicas do Body para não-repúdio.
  • XML Encryption: Criptografia de nós específicos da mensagem para tráfego seguro por múltiplos proxies intermediários (ESBs).

🚨 Tratamento de Erros com SOAP Fault

Erros durante o processamento devem retornar a estrutura padronizada <soapenv:Fault> dentro do <soapenv:Body>:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <soapenv:Fault>
         <faultcode>soapenv:Client</faultcode>
         <faultstring>Número de conta inválido ou não encontrado</faultstring>
         <faultactor>http://services.empresa.com/banking</faultactor>
         <detail>
            <err:ErrorDetail xmlns:err="http://services.empresa.com/errors">
               <err:ErrorCode>ACCOUNT_NOT_FOUND</err:ErrorCode>
            </err:ErrorDetail>
         </detail>
      </soapenv:Fault>
   </soapenv:Body>
</soapenv:Envelope>

🔗 Integração com Outras Skills