How to...

• Configure authentication in Salesforce
• Retrieve all records of the same type
• Retrieve balances for all Account records
• Create a customer
• Create an invoice
• Create an invoice from an opportunity
• Pay an invoice

Configure authentication in Salesforce

To start working with Financials via the Force.com REST API, you need to configure an authentication flow in your Salesforce organization. The authentication flow we’re going to set up in this section is called the Username-Password OAuth Authentication Flow. It isn’t the most secure one, but it’s fastest to implement for demo purposes. To complete the steps in this section, you need to download and install Postman.

NOTE: In a production environment, you may want to use a more secure authentication flow. For information about all authentication flows you can use with the Force.com REST API, see Understanding Authentication in the Force.com REST API Developer Guide.

Step 1: Create a connected app in Salesforce

1. Log on to your Salesforce org as a system administrator.
2. Go to Setup > App Manager, click New Connected App, and then configure the following:
   • Connected App Name. Type a descriptive name for your app.
   • API Name. Type a descriptive name for the API.
   • Contact Email. Enter your contact email.
3. Under API (Enable OAuth Settings), select the Enable OAuth Settings check box, and then configure the following:
   • Callback URL. Enter any URL starting with https://.
   • Selected OAuth Scopes. Move Full access (full) to the Selected OAuth Scopes column. We set up this scope for demo purposes only. In a production environment, you may want to set up a more strict authentication scope.
4. Click Save.

Step 2: Take note of your app’s key and secret

1. Click Continue.
2. On the page that opens, under API (Enable OAuth Settings), copy the Consumer Key and Consumer Secret values and store them for further use.

Step 3: Get an access token from Salesforce

1. In Postman, create the following POST request:

    POST https://login.salesforce.com/services/oauth2/token
   

2. On the Headers tab, create the following key-value pair:

   Key	Value
   Content-Type	application/x-www-form-urlencoded

3. On the Body tab, create the following key-value pairs:

   Key	Value
   grant_type	password
   client_id	{consumer key you copied in Step 2: Take note of your app’s key and secret }
   client_secret	{consumer secret you copied in Step 2: Take note of your app’s key and secret}
   username	{your Salesforce user name}
   password	{your Salesforce password}

4. Click Send.

5. In the response body, locate and copy the value of the access_token parameter. The parameter value looks similar to the following:

    "access_token": "00D0N000000h6Yq!AR0AQH8Q246.FAmlewZKdJYJ_O3y1ziq62BbR5Gj0yk9yznYqT.YDjz.rZzTZ0d8aLB9WR2EGz6.myY_Z.smrDiERcF7iKP0"
   

   You must append this access token to all subsequent HTTP requests you send to the Force.com REST API. If your token expires, repeat Step 3: Get an access token from Salesforce to get a new access token.

Retrieve all records of the same type

Once you have obtained a valid access token as described in Configure authentication in Salesforce, you can use it to access and manipulate data in Financials. For example, you can retrieve all records of the same type from Financials. In your HTTP request, you can specify the record fields whose values you want to retrieve. You can programmatically parse the retrieved records, filter them if necessary, and work with the records that meet your criteria.

1. In Postman, create the following GET request that uses the Salesforce Object Query Language (SOQL):

    GET https://{your Salesforce domain}/services/data/{vXX.X}/queryAll?q=SELECT {field 1}, {field 2}, {field n} FROM {resource}
   

   where

   • {your Salesforce domain} is your Salesforce sandbox or production domain, for example, mydomain.salesforce.com.
   • {vXX.X} is the Force.com REST API version you want to use, for example, v41.0.
   • {field 1}, {field 2}, {field n} are the resource fields whose values you want to retrieve, for example, Id, Name, and OwnerId. You can specify as many fields as you want; use a comma as a separator. To view a list of all fields for a Financials resource, in Salesforce, go to Setup > Object Manager, in the click the resource in the Label column, click the Fields & Relationships tab, and see the names of fields in the Field Name column.
   • {resource} specifies the record type (object) you want to retrieve from Financials, for example, Company, Bank Account, Dimension, and so on.

   TIP:
   To view what record types you can retrieve, in Financials, go to Setup > Object Manager. Available record types are listed in the API NAME column. Record types related to Financials have the following name format: s2cor__Sage_{name}__c.
   To view the fields whose values you can retrieve for a record type, in Financials, go to Setup > Object Manager. In the LABEL column, click the record type. Click Fields & Relationships. The available fields are listed in the FIELD NAME column.

2. On the Authorization tab, configure the following options:

   Option	Value
   Type	OAuth 2.0
   Add authorization data to	Request URL

3. On the Headers tab, create the following key-value pairs:

   Key	Value
   Authorization	Bearer {access token you obtained in Step 3: Get an access token from Salesforce} Example: Bearer 00D0N000000h6Yq!AR0AQObORnk9lCldrMydk1Y3cuyqpscqcU.T1xvoM1uWkWrr8MLu2ehJLKp7Mz3Qeu.eQGI13qlH_HfGEEMxV_J8FdI1TwdR
   Content-Type	application/json

4. Click Send.

The JSON payload you receive contains the records and fields specified in your request. Below are example request and response:

Request example:

GET https://mydomain.salesforce.com/services/data/v41.0/queryAll?q=SELECT Id, Name FROM s2cor__Sage_COR_Company__c

This request retrieves all Company records (s2cor__Sage_COR_Company__c) together with their Id and Name field values from the mydomain.salesforce.com domain via version 41.0 of the Force.com REST API.

Response example:

{
    "totalSize": 3,
    "done": true,
    "records": [
        {
            "attributes": {
                "type": "s2cor__Sage_COR_Company__c",
                "url": "/services/data/v41.0/sobjects/s2cor__Sage_COR_Company__c/a1E0N000007Q2T3UAK"
            },
            "Id": "a1E0N000007Q2T3UAK",
            "Name": "Canadian Consulting"
        },
        {
            "attributes": {
                "type": "s2cor__Sage_COR_Company__c",
                "url": "/services/data/v41.0/sobjects/s2cor__Sage_COR_Company__c/a1E0N000007Q2T4UAK"
            },
            "Id": "a1E0N000007Q2T4UAK",
            "Name": "Australia Consulting"
        },
        {
            "attributes": {
                "type": "s2cor__Sage_COR_Company__c",
                "url": "/services/data/v41.0/sobjects/s2cor__Sage_COR_Company__c/a1E0N000007Q2T5UAK"
            },
            "Id": "a1E0N000007Q2T5UAK",
            "Name": "United Kingdom Consulting"
        }
    ]
}

Retrieve balances for all Account records

To retrieve balances, you need to get the values of the following fields: Base Balance (s2cor__Base_Balance__c), Base Debit (s2cor__Base_Debit__c), Base Credit (s2cor__Base_Credit__c), Foreign Balance (s2cor__Foreign_Balance__c), Foreign Debit (s2cor__Foreign_Debit__c), and Foreign Credit (s2cor__Foreign_Credit__c).

1. In Postman, create the following GET request that uses the Salesforce Object Query Language (SOQL):

    GET https://{your Salesforce domain}/services/data/{vXX.X}/queryAll?q=SELECT Id,Name,s2cor__Base_Balance__c,s2cor__Base_Debit__c,s2cor__Base_Credit__c,s2cor__Foreign_Balance__c,s2cor__Foreign_Debit__c,s2cor__Foreign_Credit__c FROM s2cor__Sage_ACC_Tag__c WHERE s2cor__Account__c != null
   

   where

   • {your Salesforce domain} is your Salesforce sandbox or production domain, for example, mydomain.salesforce.com.
   • {vXX.X} is the Force.com REST API version you want to use, for example, v41.0.
     
     

2. On the Authorization tab, configure the following options:

   Option	Value
   Type	OAuth 2.0
   Add authorization data to	Request URL

3. On the Headers tab, create the following key-value pairs:

   Key	Value
   Authorization	Bearer {access token you obtained in Step 3: Get an access token from Salesforce} Example: Bearer 00D0N000000h6Yq!AR0AQObORnk9lCldrMydk1Y3cuyqpscqcU.T1xvoM1uWkWrr8MLu2ehJLKp7Mz3Qeu.eQGI13qlH_HfGEEMxV_J8FdI1TwdR
   Content-Type	application/json

4. Click Send.

The JSON payload you receive contains the balances for all Account records in your Salesforce organization.

Response example:

{
    "totalSize": 4,
    "done": true,
    "records": [
        {
            "attributes": {
                "type": "s2cor__Sage_ACC_Tag__c",
                "url": "/services/data/v41.0/sobjects/s2cor__Sage_ACC_Tag__c/a130N00000IuXiBQAV"
            },
            "Id": "a130N00000IuXiBQAV",
            "Name": "Australian AI Inc",
            "s2cor__Base_Balance__c": 27000,
            "s2cor__Base_Debit__c": 200000,
            "s2cor__Base_Credit__c": 173000,
            "s2cor__Foreign_Balance__c": 0,
            "s2cor__Foreign_Debit__c": 0,
            "s2cor__Foreign_Credit__c": 0
        },
        {
            "attributes": {
                "type": "s2cor__Sage_ACC_Tag__c",
                "url": "/services/data/v41.0/sobjects/s2cor__Sage_ACC_Tag__c/a130N00000IuXvxQAF"
            },
            "Id": "a130N00000IuXvxQAF",
            "Name": "Blue Cloud Blockchain",
            "s2cor__Base_Balance__c": 54000,
            "s2cor__Base_Debit__c": 106750,
            "s2cor__Base_Credit__c": 52750,
            "s2cor__Foreign_Balance__c": 0,
            "s2cor__Foreign_Debit__c": 0,
            "s2cor__Foreign_Credit__c": 0
        },
        {
            "attributes": {
                "type": "s2cor__Sage_ACC_Tag__c",
                "url": "/services/data/v41.0/sobjects/s2cor__Sage_ACC_Tag__c/a130N00000IuXi5QAF"
            },
            "Id": "a130N00000IuXi5QAF",
            "Name": "BlueRail Consulting",
            "s2cor__Base_Balance__c": 8000,
            "s2cor__Base_Debit__c": 75000,
            "s2cor__Base_Credit__c": 67000,
            "s2cor__Foreign_Balance__c": 0,
            "s2cor__Foreign_Debit__c": 0,
            "s2cor__Foreign_Credit__c": 0
        },
        {
            "attributes": {
                "type": "s2cor__Sage_ACC_Tag__c",
                "url": "/services/data/v41.0/sobjects/s2cor__Sage_ACC_Tag__c/a130N00000IuXhtQAF"
            },
            "Id": "a130N00000IuXhtQAF",
            "Name": "CodeSecure Inc",
            "s2cor__Base_Balance__c": 7500,
            "s2cor__Base_Debit__c": 77500,
            "s2cor__Base_Credit__c": 70000,
            "s2cor__Foreign_Balance__c": 0,
            "s2cor__Foreign_Debit__c": 0,
            "s2cor__Foreign_Credit__c": 0
        }
    ]
}

Create a customer

In this scenario we assume that the Company record we want to assign to the new customer already exists in Financials and we know the Company record ID.

To create a customer, we need to run several dependent requests in a single API call:

• Retrieve the Customer dimension ID. We’ll use it to classify the new record we are going to create as customer.
• Retrieve the existing Company record ID.
• Create a new Account record and retrieve its ID.
• Assign the Customer dimension ID, Company record ID, and Account record ID to the new customer.

To do so, we’ll be using a composite request. For more information, see Using Composite Resources.

1. In Postman, create the following composite request:

    POST https://{your Salesforce domain}/services/data/{vXX.X}/composite
   

   where

   • {your Salesforce domain} is your Salesforce sandbox or production domain, for example, mydomain.salesforce.com.
   • {vXX.X} is the Force.com REST API version you want to use, for example, v41.0.
     
     

2. On the Authorization tab, configure the following options:

   Option	Value
   Type	OAuth 2.0
   Add authorization data to	Request URL

3. On the Headers tab, create the following key-value pairs:

   Key	Value
   Authorization	Bearer {access token you obtained in Step 3: Get an access token from Salesforce} Example: Bearer 00D0N000000h6Yq!AR0AQObORnk9lCldrMydk1Y3cuyqpscqcU.T1xvoM1uWkWrr8MLu2ehJLKp7Mz3Qeu.eQGI13qlH_HfGEEMxV_J8FdI1TwdR
   Content-Type	application/json

4. On the Body tab, add the following JSON payload:

    {
    "allOrNone" : true,
    "compositeRequest" :
        [
            {
            "method" : "GET",
            "url" : "/services/data/v41.0/sobjects/s2cor__Sage_ACC_Dimension__c/s2cor__UID__c/Customer/?fields=Id",
            "referenceId" : "CustomerDimension"
            },
            {
            "method" : "GET",
            "url" : "/services/data/v41.0/sobjects/s2cor__Sage_COR_Company__c/a1E0N000007Q2T5UAK?fields=Id",
            "referenceId" : "Company"
            },
            {
            "method" : "POST",          
            "url" : "/services/data/v41.0/sobjects/Account",
            "referenceId" : "NewAccount",
            "body" : { 
                "Name" : "Example new customer - account name"
                }
            },
            {
            "method" : "POST",          
            "url" : "/services/data/v41.0/sobjects/s2cor__Sage_ACC_Tag__c",
            "referenceId" : "NewCustomerTag",
            "body" : { 
                "Name" : "Example new customer - name",
                "s2cor__Account__c": "@{NewAccount.id}",
                "s2cor__Dimension__c": "@{CustomerDimension.Id}",
                "s2cor__Company__c" : "@{Company.Id}"
                }
            }
        ]
    }
   

   In this JSON payload:

   • The first request (GET) retrieves the ID of the Customer dimension and stores it in the CustomerDimension variable.
   • The second request (GET) retrieves the ID of the Company record we want to assign to the new customer and stores the ID in the Company variable.
   • The third request (POST) creates a new Account record, names it Example new customer, and stores its details in the NewAccount variable.

   • The fourth request (POST) creates a new Dimension Tag record that combines the Customer dimension ID, Company record ID, and Account record ID and name. The Dimension Tag record basically defines our new customer.

     NOTE: We use the referenceId parameter in the fourth request just because it must be present in each request that’s part of a composite request.

5. Click Send to create the customer.

Create an invoice

Coming soon…

Create an invoice from an opportunity

Coming soon…

Pay an invoice

Coming soon…

Provide feedback