Guide for B2C Commerce Headless Integration by ISV Partners

Audience: B2C Commerce ISV Partners

Template

The following template and topics should help you when creating your B2C Commerce Headless Integration guide:

Business oriented users should use a guide to get comfortable with the alignment between B2C Commerce and the offering as well as get comfortable that the most common use cases have been considered and outlined.

The technical readers should access the integration guide via documentation on the ISV partner's website and/or developer center and/or in their AppExchange listing. While written documentation is a minimum, taking the extra step of providing a sample app, a React component or a project based on a Salesforce SDK clearly enhances the value of the integration guide itself. ISV Partners can determine how or if they want to distribute the code in their own code repository that supports the use of the integration guide.

1. Summary

<WHAT THE INTEGRATION DOES> 
<3RD PARTY PRODUCTS AND CONTRACTUAL REQUIREMENTS, E.G. WHAT PRODUCT AND PRODUCT VERSION THE COMPONENT INTEGRATES WITH IF CUSTOMER IS REQUIRED TO CONTRACT WITH THE 3RD PARTY OR IF THEIR SERVICES ARE RESOLD BY COMMERCE CLOUD, ANY ADDITIONAL COSTS THE CUSTOMER WILL BE CHARGED BY 3RD PARTY>
<WHAT THE INTEGRATION ENCOMPASSES>
 

2. Integration Overview

Functional Overview 
<BUSINESS/FUNCTIONAL OVERVIEW OF INTEGRATION, INCLUDING FLOW CHARTS, DIAGRAMS WHERE APPLICABLE> <IF THE INTEGRATION ENABLES PAYMENT, MAKE A BULLET POINT LIST FOR ALL SUPPORTED PAYMENT METHODS> <LIST ALL LOCALES THE INTEGRATION AND SERVICE WORKS WITH>

Use Cases
<FUNCTIONALITY COVERED BY THE SERVICE/INTEGRATION>
<LIST OUT ALL SUPPORTED USE CASES CLEARLY>

Limitations/Constraints
<WHICH PARTS OF THE 3RD PARTY OFFERING ARE NOT SUPPORTED>
<WHICH COMMERCE CLOUD APIS, FEATURES OR CONFIGURATIONS ARE NOT SUPPORTED, E.G. MULTIPLE LOCALES, NON-US SHIPPING ADDRESSES, ORDERS WITH MORE THAN ONE SHIPPING ADDRESS, CATALOG SIZE LARGER THAN 500K>

<IF YOUR INTEGRATION REQUIRES A CUSTOM CATALOG FEED, DESCRIBE ANY LIMITATIONS ON PRODUCT ATTRIBUTES, SUCH AS NON-SUPPORTED HTML ATTRIBUTES, 0.00$ PRICES, ONLY ORDERABLE PRODUCTS EXCLUDING BACKORDER>

Compatibility
<SPECIFY WHETHER THE API IN USE IS OCAPI OR COMMERCE APIS>
<INCLUDE WHAT VERSION OF API THE INTEGRATION WAS TESTED AGAINST>
<INCLUDE WHICH VERSION OF THE PWA KIT INTEGRATION WAS TESTED AGAINST IF APPLICABLE>
<IT IS THE RESPONSIBILITY OF THE INTEGRATION DEVELOPER TO MAINTAIN THE INTEGRATION OF THE NECESSARY SALESFORCE APIS.>
<INCLUDE THE VERSION OF ANY NON-SALESFORCE COMPONENT OR API REFERENCED IN THIS DOCUMENT>

Privacy/Payment
<INDICATE IF CUSTOMER PROFILE DATA IS BEING ACCESSED, IF CREDIT CARD DATA IS BEING PROCESSED OR STORED WITHIN B2C COMMERCE>
<SPECIFY LINK TO PRIVACY POLICY FOR YOUR PRODUCT AND/OR COMPANY>

Architectural Considerations
<SPECIFY ASSUMPTIONS AROUND HEADLESS ARCHITECTURAL APPROACH ADDRESSED IN THIS GUIDE. IF POSSIBLE, PLEASE INCLUDE DESCRIPTION THAT INCLUDES BOTH COMMERCE APIS/OCAPI AND PWA KIT. IF NECESSARY, GENERALIZE ANY ORCHESTRATION THAT WOULD TAKE PLACE IN AN INTEGRATION LAYER. DIAGRAMS ARE HELPFUL.>
 

3. Implementation Guide

Configuration
<CONFIGURATION STEPS INCLUDE HOW TO CONFIGURE ANY CUSTOM SITE PREFERENCES, SERVICES, OCAPI SETTINGS, JOBS ETC>

UI Components
<SPECIFY ANY REACT COMPONENTS THAT WILL BE NEEDED TO MAKE THE INTEGRATION FUNCTIONAL. IF POSSIBLE, POINT TO SOLUTIONS FOR OTHER FRAMEWORKS SUCH AS VUE, ANGULAR, ETC. POINT TO REFERENCES OR CODE EXAMPLES WHERE POSSIBLE.>

External Interfaces
<INTERFACES TO EXTERNAL SERVICES, E.G HTTP CLIENT, WEB SERVICE CALLS, DESCRIPTION OF REQUESTS AND RESPONSES>
<INCLUDE LIST OF API ENDPOINTS AND USAGE HERE>
<INCLUDE VALIDATION CODES, ETC. HERE, SPECIFY ANY SPECIFIC ERROR HANDLING DETAILS, IF NECESSARY> Functional Steps
<IF POSSIBLE, PROVIDE A STEP BY STEP SET OF INSTRUCTIONS BASED ON THE ASSUMED ARCHITECTURE REFERENCED ABOVE. PROVIDE CODE EXAMPLES WHERE POSSIBLE.>
 

4. Testing

<LIST ALL BASIC TEST CASES TO ENSURE THAT EVERYTHING INSTALLED WORKS. INCLUDE SCREENSHOTS AND STEPS ON HOW TO PERFORM ALL TEST CASES. IN CASES WHERE THE CODE PROVIDED IS FOR EXAMPLE PURPOSES, PLEASE REINFORCE THAT HERE.>
 

5. Operations & Maintenance

Data Storage
<DESCRIBE ANY DATA THAT WILL BE STORED WITHIN COMMERCE CLOUD, E.G. CUSTOM OBJECTS, INCLUDING DURATION AND CLEANUP JOBS IF APPLICABLE>

<IS THERE A SEPARATE DATA STORAGE OUTSIDE OF COMMERCE CLOUD, SPECIFY LOCATION AND DURATION IF APPLICABLE>

Availability
<EXPECTED AVAILABILITY /UPTIME OF ANY EXTERNAL SERVICE, INTERFACES>
<FALLBACK SOLUTION, BEHAVIOR IF EXTERNAL SERVICES ARE NOT AVAILABLE, IMPACT ON CUSTOMER STOREFRONT>
<ANY EXISTING UTILITIES THAT HELP TO DETECT AVAILABILITY/UPTIME OF EXTERNAL SERVICE, E.G. WEBSERVICE CALL, GOMEZ PING>
<ESTIMATED PERFORMANCE METRICS FOR PEAK BUSINESS HOURS IF AVAILABLE>
<NOTIFICATION PROCESS IF EXTERNAL SERVICES, INTERFACES ARE NOT RESPONDING, E.G. HOTLINE /SUPPORT PHONE NUMBER>

Failover/Recovery Process
<WHAT MERCHANTS SHOULD EXPECT WHEN SERVICE IS DOWN AND WHAT TO DO>

Support
<CONTACT EMAIL IN CASE DEFECT FIXES OR IMPROVEMENTS FOR COMPONENT ARE REQUIRED>
 

6. User Guide

Roles & Responsibilities
<LIST RECURRING TASKS THAT NEED TO BE FULFILLED BY CUSTOMER, MERCHANT TO RUN THE INTEGRATION, E.G. MANUAL FEED OF CATALOG DATA INTO 3RD PARTY SERVICE, IF APPLICABLE>

Business Manager
<FROM TIME TO TIME, STEPS MAY BE TAKEN IN BUSINESS MANAGER TO COMPLETE AND/OR MAINTAIN THE INTEGRATION SUCH AS JOBS, ETC. PLEASE DOCUMENT HERE IF KNOWN AND/OR NECESSARY >

7. Known Issues

<LIST KNOWN ISSUES AND WORKAROUNDS>

8. Security Best Practices

PLEASE PROVIDE A LINK OR INCLUDE WITHIN THIS DOCUMENTATION YOUR API SECURITY BEST PRACTICES AVAILABLE TO DEVELOPERS.>
<PLEASE INCLUDE THE FOLLOWING TOPICS IN YOUR SECURITY BEST PRACTICES: SECURE BY DEFAULT, LEAST PRIVILEGE, SECURE COMMUNICATIONS, CREDENTIALS, PAYLOAD, LOGGING AND DEPRECATION STRATEGY.
<FOR PWA KIT INTEGRATIONS, PROVIDE A SNYK ADVISOR LINK AND HEALTH SCORE FOR AHY UNDERLYING SDK OR API CLIENT. SEE AN EXAMPLE HERE>
<EXAMPLES OF SECURITY BEST PRACTICES CAN BE FOUND HERE:
● Security Requirements for AppExchange Partners and Solutions
● B2C Commerce Security Guide
● B2C Commerce/Commerce Cloud Security, Privacy, and Architecture
<OTHER EXAMPLES OF API SECURITY BEST PRACTICES PUBLISHED BY THIRD PARTIES>:
● Paypal Security Guidelines and Best Practice