Salesforce SOAP Integration Guide: WSDL Types, Apex Web Services & Enterprise Architecture

In plain words: Salesforce SOAP Integration allows enterprise systems to exchange structured data with Salesforce using XML-based messages governed by a strict contract called a WSDL (Web Services Description Language). While REST is great for lightweight, flexible web apps, SOAP provides strict typing, formal contracts, and enterprise-grade reliability for banking, ERP, and legacy systems.

Connecting Salesforce with on-premises infrastructure, financial hubs, and enterprise resource planning (ERP) platforms often requires a contract-first integration approach. SOAP (Simple Object Access Protocol) provides a rigid, XML-based messaging framework that guarantees data structure conformity, strict data typing, and reliable end-to-end communication across enterprise systems.

1. Understanding Salesforce SOAP Architecture

SOAP integrations rely on formal interface definitions called WSDL (Web Services Description Language) documents. Salesforce provides two standard WSDL variants to suit different application designs:

• Enterprise WSDL: Strongly typed and tied directly to a single Salesforce org's schema. It contains all standard and custom objects, fields, and relationships. If you add a custom field to Salesforce, you must regenerate and re-import this WSDL.
• Partner WSDL: Loosely typed and static across all Salesforce orgs. It works with generic sObject structures, making it ideal for third-party software vendors (ISVs) and multi-org integration connectors.
• Custom Apex WSDL: Generated directly from custom Apex classes marked with the webservice keyword, exposing tailored business processes as formal SOAP endpoints.

360 SOAP Integration Architecture Card:

• Protocol Standard: XML envelope containing Header and Body tags over HTTPS.
• Schema Contract: Enforced by WSDL documents downloaded directly from Setup > API.
• Authentication: Session-based authentication via SOAP login() or modern OAuth 2.0 bearer tokens passed in the SOAP header.
• Key Strengths: Strict data contract validation, formal schemas, and legacy ERP interoperability.

2. Inbound Integration: Exposing Custom Apex SOAP Services

When standard Salesforce CRUD SOAP APIs do not fit your custom transactional requirements, you can expose Apex methods as custom SOAP endpoints using the webservice keyword.

Step 1: Write the Global Apex Web Service
Define a global class containing methods marked with the webservice keyword.

global with sharing class InvoiceService {

    webservice static String generateInvoice(Id accountId, Decimal invoiceAmount) {
        if (accountId == null || invoiceAmount == null || invoiceAmount <= 0) {
            return 'ERROR: Invalid account ID or invoice amount.';
        }

        try {
            Account targetAccount = [SELECT Id, Name FROM Account WHERE Id = :accountId WITH USER_MODE LIMIT 1];
            
            // Create a business record
            Task invoiceTask = new Task(
                WhatId = targetAccount.Id,
                Subject = 'Invoice Processed: $' + invoiceAmount,
                Status = 'Completed',
                Priority = 'Normal'
            );
            insert as user invoiceTask;

            return 'SUCCESS: Invoice task created with ID ' + invoiceTask.Id;
        } catch (Exception ex) {
            return 'ERROR: ' + ex.getMessage();
        }
    }
}

Step 2: Generate the Custom WSDL
Navigate to Setup > Apex Classes, find InvoiceService, and click Generate WSDL. Provide this XML document to the external ERP or billing team to import into their middleware (e.g., SAP, MuleSoft, or IBM WebSphere).

3. Outbound Integration: Consuming External SOAP Web Services in Apex

Salesforce allows developers to import external WSDL documents and automatically translate them into callable Apex classes using the WSDL2Apex utility in Setup.

• Importing External WSDLs: Go to Setup > Apex Classes > Generate from WSDL, upload the third-party XML schema, and Salesforce generates synchronous callout stubs.
• Mocking SOAP Callouts for Unit Testing: Because unit tests cannot make live callouts, implement the WebServiceMock interface to simulate XML responses in test classes.

4. Common Traps & Architectural Best Practices

Architecture Trap: Using the Enterprise WSDL in Fast-Changing Sandboxes
Because the Enterprise WSDL is strongly typed, any changes to custom fields or object structures in Salesforce break the external system's schema bindings. If your Salesforce data model changes frequently, use the Partner WSDL or isolate custom logic behind a Custom Apex WSDL with stable data wrapper objects.

Core Rule: Use SOAP APIs when integrating with legacy enterprise middleware that requires strict WSDL contracts and schema validation. For lightweight web apps, mobile clients, and modern microservices, prefer REST APIs.

• Secure Endpoints with HTTPS: Always transmit SOAP payloads over TLS-encrypted HTTPS connections and enforce session timeouts in Connected Apps.
• Monitor Governor & API Limits: SOAP calls consume standard daily 24-hour API request allotments; batch multiple record operations within single SOAP envelopes where possible.
• Handle Faults Cleanly: Intercept and parse <soapenv:Fault> blocks on the client side to surface meaningful error codes rather than cryptic XML parsing exceptions.

Summary

Salesforce SOAP integration provides an enterprise-ready, contract-driven foundation for connecting mission-critical systems. By choosing the right WSDL architecture, exposing custom Apex web services with precision, and adhering to strict security and testing standards, organizations can ensure reliable, synchronous data exchange across complex IT environments.