Build a B2C Commerce Web Service Integration

Learning Objectives

After completing this unit, you'll be able to:

• List the steps to create a web service.
  
• Describe B2C Commerce web services framework actions for timeout, circuit breaker, and rate limiting.
  
• List the Business Manager configurations required for each web service.
  
• Explain why web service names are important.
  
• Explain the purpose of the service type.
  

Introduction

When you integrate an external service—whether a payment gateway, tax engine, or shipping provider—you need to do more than make an HTTP call. The B2C Commerce web services framework organizes integration through Business Manager configurations, coding conventions, and automated protection tools. These mechanisms ensure storefront stability even when external providers face performance issues or outages.

This unit walks you through how to build an integration from start to finish.

Steps to Create a New Web Service

To create a web service integration in B2C Commerce, follow these four steps.

• Configure the web service in Business Manager. Create a service profile, a service credential, and a service configuration under Administration | Operations | Services. If the service becomes slow or unavailable, these configurations tell B2C Commerce how to connect to the service, what credentials to use, and how to protect the storefront.
  
• Code the web service script. Use LocalServiceRegistry.createService() to create a Service instance. Pass the service configuration name and a callback object that implements createRequest, parseResponse, and (for testing) mockCall. Call Service.call() to invoke the service. The framework checks the rate limiter and circuit breaker before calling the service, then runs your callbacks.
  
• Set up logging and troubleshoot. Configure a log prefix in the service configuration. Access log files at Administration | Site Development | Log Files. Use the Service Status dashboard at Administration | Operations | Service Status to review near-real-time performance trends. Adjust log levels under Administration | Operations | Custom Log Settings.
  
• Get the service ready to go live. Configure credentials on both development and production instances—these credentials can't be imported or exported; create them manually on each. Use code replication to push your cartridge, then use Administration | Operations | Import & Export | Service to export your service, profile, and credential configurations and import them into each target instance.
  

Business Manager Configurations for Each Web Service

Every web service requires three configurations in Business Manager.

Service Profile

This profile controls how B2C Commerce detects and manages high call volumes and service failures. Multiple services with similar requirements can share one profile.

Navigate to Administration | Operations | Services and click the Profiles tab to create a profile. Key settings include:

• Timeout (ms): How long B2C Commerce waits for a response before throwing an error. B2C Commerce uses this process for each individual connection and read operation.
  
• Enable Circuit Breaker: Checked by default. Detects when a service is unavailable and stops making calls. Configure Max Circuit Breaker Calls and Circuit Breaker Interval (ms) together for threshold-based tripping beyond the default behavior.
  
• Enable Rate Limit: Caps the number of outgoing calls within an interval. Set Max Rate Limit Calls and Rate Limit Interval (ms) together.
  

Service Credential

This credential stores the endpoint URL and basic authentication credentials. Navigate to Administration | Operations | Services and click the Credentials tab to create a credential. Key settings include:

• Name: A descriptive name without spaces, such as http.mysite.payment.cred. Don't embed usernames or passwords in the name.
  
• URL: The base URL including the protocol, such as https://api.payment.example.com.
  
• User and password: The username and password for basic authentication. Business Manager masks passwords after entry and doesn't expose them again, so store them securely elsewhere.
  

Service Configuration

The configuration ties together the profile and credential and provides the additional settings that control runtime behavior. Navigate to Administration | Operations | Services and click New. Key settings include:

• Name: Follow the pattern {cartridge}.{protocol}.{service}.{operation}.
  
• Service Type: Determines the underlying client class used for the call.
  
• Enabled: Check this setting to accept calls. The setting is off by default.
  
• Service Mode: Set to Live to call the real endpoint or Mocked to return a simulated response from your script.
  
• Log Prefix: Sets the prefix for the service log file. Defaults to main if left blank.
  
• Communication Log Enabled: Logs request and response data. Turn it off in production unless you configure log filtering to remove sensitive data.
  
• Profile and Credential: Select the profile and credential that you created.
  

Why Web Service Names Are Important

The name you assign to a service configuration is more than a label—it becomes the logging hierarchy for that integration.

Salesforce recommends the naming pattern {cartridge}.{protocol}.{service}.{operation}. For example: mycartridge.http.payment.authorize or mycartridge.ftp.partner.getPriceList.

Each period-delimited segment becomes a node in the logging hierarchy. For the preceding examples, B2C Commerce creates log categories such as:

service.mycartridge.http.payment.authorize.head
service.mycartridge.http.payment.authorize.comm
service.mycartridge.http.payment.authorize.log

This hierarchy has two practical benefits.

Grouped log management. Turn logging on or off for an entire integration at once. Setting mycartridge.http.payment to debug in Custom Log Settings turns on debug logging for every service under that path—without configuring each service individually.

Unique names across integrations. Including the cartridge name prevents service name collisions when your site integrates with multiple external providers. Collisions mix log output and make troubleshooting much harder.

Tip

Use a consistent naming pattern from the start. Renaming a service later requires updating both Business Manager and every script that references the service name.

The Purpose of the Service Type

When you create a service configuration in Business Manager, it’s a good idea to select a service type. The type determines the underlying client class that B2C Commerce uses to make the call. Each type adds protocol-specific methods on top of the types inherited from the base Service class.

Selecting the correct type matters because the framework casts the service instance your callbacks receive to the corresponding subclass. An HTTP service passes an HTTPService object to createRequest, which exposes methods like setRequestMethod, addHeader, and addParam. An FTP service passes an FTPService object, which exposes setOperation to specify the FTP command to run. If you select the wrong type, those methods aren't on the service instance.

Demo: HTTP Service Callback Pattern

An HTTP service typically implements three callbacks. Match the service name in createService exactly to a service configuration name in Business Manager, the framework uses that name to look up the profile and credential at call time.

var paymentService = LocalServiceRegistry.createService("mycartridge.http.payment.authorize", {
    createRequest: function(svc, args) {
        svc.setRequestMethod("POST");
        svc.addHeader("Content-Type", "application/json");
        return JSON.stringify(args);
    },
    parseResponse: function(svc, client) {
        return JSON.parse(client.text);
    },
    mockCall: function(svc, client) {
        return { statusCode: 200, statusMessage: "Success", text: '{"authorized": true}' };
    }
});
var result = paymentService.call(requestData);
if (result.ok) {
    // handle success
} else {
    // inspect result.status and result.errorMessage
}

Best Practices: Timeout

As a best practice, never rely on platform defaults (2 minutes for storefront requests, 15 minutes for jobs). Set an explicit, low timeout in every service profile. Match the value to the latency that your storefront can tolerate for that operation: a payment authorization warrants 2,000 ms; a background data sync can tolerate more. The timeout applies to each individual connection and read operation, not the total call duration.

Next Up

In this unit you learned about the four essential steps for building an B2C Commerce web service integration, detailing the required Business Manager configurations for the service profile, credentials, and service configuration. You learned the critical protection best practices, which include setting an explicit timeout, keeping the circuit breaker active, and configuring the rate limiter for any quota-restricted service. Next, you will move to the coding phase, covering how to implement the web service script, integrate SOAP and WS-Security, and connect the service via a controller.

Resources

• Salesforce Help: Creating a New Web Services