How to Integrate with Salesforce (REST and SOAP API)

How to integrate with Salesforce

There are two main ways a partner or 3^rd party vendor can integrate into Salesforce.

REST API

To access Salesforce via REST API(https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/intro_rest.htm), an integration vendor typically needs to follow these steps:

1. Set Up a Connected App (https://help.salesforce.com/s/articleView?id=sf.connected_app_overview.htm&type=5)
   • Create a Connected App in the Salesforce org that will be integration. This app provides the integration with credentials, authentication options, and permissions required to access data.
   • In Setup, go to App Manager, click New Connected App, and complete the necessary fields:
     • App Name: Choose a name that identified the integration
     • API Name: Used internally in Salesforce
     • Callback URL: Required for OAuth, often set to the URL where the vendor’s application listens for a response.
     • OAuth Scopes: Chose permissions such as Full Access, API, or Refresh Token (if persistent access is needed).
     • Enable OAuth settings: Ensure this is checked to allow the app to use OAuth.
2. Authenticate with OAuth 2.0 (https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_flows.htm&type=5)
   • Salesforce REST API required OAuth2.0 for secure, token-based authentication.
   • The vendor needs to authenticate to Salesforce by one of the following OAuth flows:
     • Authorization Code Flow (Web Server Flow): (https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_web_server_flow.htm&type=5) For server-to-server communication, where the user logs in and consents to allows access. Common for integrations with secure backend access.
     • JWT Bearer Flow: (https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_jwt_flow.htm&type=5)Used for server-to-server communication without user interaction, allowing the vendors to authenticate on behalf of a specific Salesforce User.
     • Username-Password Flow: (https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_username_password_flow.htm&type=5)  Direct login using a username and password. However, it’s generally not recommended for third-party integrations due to security risks and lack of refresh tokens.
     • Refresh Token Flow: (https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_refresh_token_flow.htm&type=5) Used to refresh the access token if the original token expires, preventing disruptions in service.
   • For example, in the Authorization Code Flow:
     • Redirect the user to Salesforce’s authorization endpoint with Connected App’s client ID and scopes.
     • The user logs in and authorizes the app.
     • Salesforce redirects back to the specified callback URL with an authorization code.
     • The vendor exchanges the authorization code for an access token by making a request to Salesforce’s token endpoint.
3. Access Salesforce Data Using the REST API
   • With the access token received, the vendor can make API requests to Salesforce. The token must be included in each HTTP request’s authorization header: 
     • API Requests:
       • The vendor can perform various operations, such as:
         1. Querying data: Using SOQL via the /services/data/{version}/query/  endpoint.
         2. CRUD Operations: For creating, updating and deleting records using /service/data/{version}/sobjects/.
         3. Batch Operations: For bulk actions, they can use composite requests at  /services/data/{version}/composite/.
     • Example request to retrieve a record:
4. Handle Rate Limits and Governor Limits
   • Salesforce enforces rate limits on API calls based on the organization’s licenses and user permissions. The vendor must:
     • Monitor API Usage and avoid exceeding limits.
     • Implement retry logic to handle limits gracefully
     • Use Composite API requests to bundle multiple requests and reduce API call volumes.
5. Manage Token Refreshing
   • If the access token expires, the vendor should he Refresh Token Flow to obtain a new access token without needing user interaction.
   • The refresh token is sent to the endpoint: 
6. Data security and Compliance
   • Ensure data security by following Salesforce’s best practices, such as:
     • Using secure storage for client secrets and tokens.
     • Encrypting sensitive data.
     • Respecting data access controls based on OAuth scopres and permissions.

SOAP API

To access Salesforce via SOAP API(https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_quickstart_intro.htm), an integration vendor typically needs to follow these steps:

1. Set Up a Connected App (Optional) https://help.salesforce.com/s/articleView?id=sf.connected_app_overview.htm&type=5
   • For integration that need API access without using user credentials, you can set up a Connected App in Salesforce to manage authentication, although it’s option for SOAP if you’re using username-password-based login.
   • Setup: Go to App Manager in Salesforce and create a New Connected App. Set up OAuth scopes as needed, though for SOAP, a Connected App is less common unless enhanced security or user tracking is required.
2. Authenticate Using the SOAP Login Service (https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_calls_login.htm)
   • Authentication via the SOAP API often uses the Username-Password Authentication Flow: https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_username_password_flow.htm&type=5
     • WSDL File: Download the Enterprise or Partner WSDL from Salesforce Setup, depending on the integration needs:
       1. Enterprise WSDL: Strongly types for a specific Salesforce Org (ideal of the data structure is likely to change.)
       2. Partner WSDL: Loosely typed and more flexible, suitable for integrations across multiple Salesforce Orgs.
     • SOAP Login Request: Send SOAP request to Salesforce’s login endpoint (https://login.salesforce.com/services/Soap/c/{version} ) with the username, password, and security token (if required).
       1. For example:
       2. Response: Salesforce returns a session ID (equivalent of an access token in REST) and the instance URL for future requests.
3. Use the session ID to Access Salesforce Data
   • Session ID: Use the session ID form the login response as an authorization token in the SOAP headers for all subsequent API calls. This token is passed in the SOAP header, as shown in this example: 
   • API Requests:
     • The vendor can perform various operations, such as:
       1. CRUD Operations: To create, read, update, or delete records.
       2. Query Operations: Use SOQL to retrieve data.
       3. Metadata Operations: Some metadata manipulation is possible, depending on the WSDL,
4. Handle SOAP Requests and Responses
   • Structured Data: SOAP requests and responses are XML-based, with structured elements fir each field and object. This requires parsing and handling XML properly in the integration.
   • Error Handling: Salesforce returns errors as SOAP fault messages, which should be handled by the integration to identify issues such as missing fields, incorrect data types, or permissions issues.
5. Session Management
   • Session Timeout: The session ID has a limited lifespan. If it expires, the integration needs to reauthenticate by re-running the login request.
   • Session Reuse: For efficiency, the vendor can reuse a session ID across multiple requests for a single user until it expires.
6. Download and Use the WSDL for Operations
   • Partner WSDL (recommended for Flexibility): Ideal for multi-org integration as it dynamically adjusts to org structure, allowing the integration to retrieve and interact with various objects and fields without org-specific dependencies.
   • Enterprise WSDL (Org-Specific): Strictly defined for a specific Salesforce Org and used when the integration is specific to that org’s structure and objects, making it suitable for strongly types languages.
7. Respect Salesforce SOAP API Limits
   • API Limits: Monitor API usage to avoid exceeding daily limits.
   • Optimize Queries: Use efficient SOQL queries and batch processing where possible.
8. Security Best Practices
   • Protect Credentials: Store login credentials and session IDs securely.
   • Use Security Token: Append the security token to the password for enhanced security if accessing from untrusted IPs.
   • Mange IP whitelisting: Optionally whitelist the IPs for the integration to add an additional layer of security.