Salesforce API Wrapper

Common errors

• statusCode='DUPLICATES_DETECTED', message='You're creating a duplicate record.'

  cause Salesforce org has active duplicate rules or matching rules that prevent the creation or update of records that match existing ones.
  fix Adjust your data to avoid duplicates, or configure Salesforce Duplicate Rules to exclude the integration user or specific scenarios.

• statusCode='INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST'

  cause Attempting to insert or update a picklist field with a value that is not defined in Salesforce's picklist options, or the picklist is restricted.
  fix Ensure that picklist values provided in your code exactly match the values configured in Salesforce. If the picklist is restricted, only defined values are allowed. Consider making picklists non-restricted if appropriate for your integration.

• The access token in the request is missing, invalid, or expired.

  cause The authentication token used for API calls is either not provided, has become invalid (e.g., password change), or has expired.
  fix Verify that your username, password, and security token are correct and up-to-date. If using OAuth, ensure the refresh token mechanism is correctly implemented to obtain new access tokens.

• UNABLE_TO_LOCK_ROW

  cause Multiple processes or API calls are attempting to update the same Salesforce record simultaneously, leading to a database locking conflict.
  fix Implement retry logic with a delay (e.g., exponential backoff) for operations that may encounter this error. Design integrations to minimize concurrent updates to the same records where possible.

Warnings

• gotcha Salesforce API calls are subject to daily and hourly limits. Exceeding these limits can lead to `TOO_MANY_REQUESTS` (429 HTTP status) or other errors, temporarily blocking API access.
  Fix: Implement error handling with exponential backoff for retries. Monitor API usage in Salesforce 'System Overview' to anticipate limits.
• gotcha Authentication with username, password, and security token may require relaxing IP restrictions in Salesforce or whitelisting client IP addresses if operating from a new location.
  Fix: In Salesforce Setup, navigate to 'App Manager' -> 'Connected Apps', then 'Manage' -> 'Edit Policies'. Ensure 'IP Relaxation' is set to 'Relax IP restrictions' or that your application's IP is whitelisted under 'Network Access'.
• gotcha The default login URL is for production. For sandbox environments, you must explicitly specify `domain='test'` or the full sandbox login URL during client initialization.
  Fix: Initialize the `Salesforce` client with `client = Salesforce(..., domain='test')` for sandbox environments.

Install

• pip install salesforce-api Install stable version

Imports

• Salesforce

  from salesforce_api import Salesforce

• Salesforce
  wrong:

  from simple_salesforce import Salesforce

  correct:

  from salesforce_api import Salesforce

  This library (`salesforce-api` by felixlindstrom) is distinct from `simple-salesforce`, a different popular Salesforce Python client. Ensure you import from the correct package.

Quickstart

This quickstart demonstrates how to establish a connection to Salesforce using username, password, and security token authentication. It then performs a simple SOQL query to retrieve account records. Always use environment variables or a secure configuration management system for credentials in production. You may need to create a Connected App in Salesforce and use OAuth for more robust authentication flows.

import os
from salesforce_api import Salesforce

# It's recommended to use environment variables for sensitive credentials.
SF_USERNAME = os.environ.get('SF_USERNAME', 'your_username@example.com')
SF_PASSWORD = os.environ.get('SF_PASSWORD', 'your_password')
SF_SECURITY_TOKEN = os.environ.get('SF_SECURITY_TOKEN', 'your_security_token')

# For sandbox environments, you might need to specify the domain.
# For example, domain='test'

try:
    client = Salesforce(
        username=SF_USERNAME,
        password=SF_PASSWORD,
        security_token=SF_SECURITY_TOKEN
    )
    print("Successfully connected to Salesforce!")

    # Example: Query an SObject
    # Note: Replace 'Account' and field names with actual objects/fields in your org.
    accounts = client.query("SELECT Id, Name FROM Account LIMIT 5")
    print("First 5 Accounts:")
    for record in accounts['records']:
        print(f"  ID: {record['Id']}, Name: {record['Name']}")

    # Example: Create a new contact (adjust fields as per your Salesforce org)
    # new_contact_data = {
    #     'LastName': 'TestContact',
    #     'Email': 'test@example.com'
    # }
    # result = client.Contact.create(new_contact_data)
    # print(f"Created Contact ID: {result['id']}")

except Exception as e:
    print(f"An error occurred: {e}")