API Overview

JustOn Billing & Invoice Management operates on Salesforce Platform, leveraging the platform's connectivity. You can, consequently, manipulate JustOn-relevant data – creating accounts, inserting invoices, etc. – using one of Salesforce Platform APIs, namely REST API and Bulk API.

In addition, JustOn exposes a number of specific APIs that allow to invoke certain JustOn functionality remotely from external systems. This page summarizes the available interfaces.

Subscription Build Web Service
Invoice Run
Invoice Import and Fix
Balance Import and Fix
Apex Refund Interface

Subscription Build Web Service

Some business use cases may require to invoke the subscription builder remotely from external systems. To this end, you can call the subscription builder using a REST web service. The web service accepts one ore more records and creates subscriptions in the same way as the local batch job.

API URL

The web service is available via

https://INSTANCE.salesforce.com/services/apexrest/ONB2/subscription_builder/1/

Replace INSTANCE with the actual Salesforce instance or custom domain where JustOn is installed and running.

Authentication

The web service supports two authentication mechanisms:

OAuth 2.0
Session ID

For details, see Step Two: Set Up Authorization in the Salesforce Platform REST API Developer's Guide.

JSON Structure for Web Service Call

The web service accepts HTTP POST requests. The body of the request must contain a valid JSON data structure. Basically, the JSON structure represents a deserialized sObject and lists a number of records. The keys are mapped to field names of the subscription or the item.

Info

The JSON code can also include child records.

The key ON_Account__c is mandatory at the parent record. It can refer to a Salesforce ID or an external ID. When referring to an external ID, you must also refer to an existing mapping that holds the externalIdFields variable for Account__c (see externalIdFields). The keys ON_MasterSubscription__c, ON_MappingName__c and ON_UseCase__c on the parent record are used in the same way as for accordingly configured objects (see ON Fields on Objects).

Keys that start with ON_ are directly mapped to subscription or item fields. Fields without the ON_ prefix can only be referenced and used by a corresponding mapping (see Using Data Mapping).

[
    {
        "parent":{
            "ON_Name__c":"Sample Name 1",
            "ON_Account__c":"Sample External Id 1",
            "ON_MasterSubscription__c":"Master Subscription Name",
            "ON_MappingId__c":"Salesforce Id",
            "ON_UseCase__c":"NEW",
            "ON_StartDate__c":"2015-12-01",
            "ON_Template__c":"Salesforce Template Id"
        },
        "children":{
            "SUBSCRIPTION_FEE":{
                "ON_Name__c":"SUBSCRIPTION_FEE",
                "ON_Price__c":47.11,
                "ON_Quantity__c":1,
                "ON_BillingType__c":"Recurring"
            },
            "SUPPORT_HOURS":{
                "ON_Name__c":"SUPPORT_HOURS",
                "ON_Price__c":100.0,
                "ON_BillingType__c":"Transactional"
            }
        }
    },
    {
        "parent":{
            "ON_Name__c":"Sample Name 2",
            "ON_Account__c":"Salesforce Account Id",
            "ON_MasterSubscription__c":"Other Master Subscription Name",
            "ON_MappingId__c":"Salesforce Id",
            "ON_Status__c":"Active",
            "ON_Template__c":"External Template Id",
            "ON_Contact__c":"External Contact Id"
        }
    }
]

Web Service Response

The response of the web service holds a result record for each record from the request:

[
    {
        "success":true,
        "subscriptionId":"Salesforce Id",
        "buildError":null,
        "index":0
    },
    {
        "success":true,
        "subscriptionId":"Salesforce Id",
        "buildError":null,
        "index":1
    }
]

The response always returns the HTTP status code 200 once the body of the request can be successfully parsed. Otherwise, the system will return an HTTP status code 500 with the error in the body of the response. For details about possible HTTP status codes, see RestResponse Class in the Apex Developer Guide.

Error Handling

If the subscription build fails before the database insert (like, for example, with a missing account, a missing mapping, or a missing master subscription), it is marked as failed. Other subscriptions passed with the same request may still succeed, however.

If the error occurs during the database insert, all subscriptions of the request will fail:

[
    {
        "success":false,
        "subscriptionId":null,
        "index":0,
        "buildError":"Batch persisting of Subscriptions failed."
    },
    {
        "success":false,
        "subscriptionId":null,
        "index":1,
        "buildError":"Item upsert: Name=SUBSCRIPTION_FEE : REQUIRED_FIELD_MISSING: Required fields are missing: [ONB2__Title__c]; fields  [ONB2__Title__c]"
    },
    {
        "success":false,
        "subscriptionId":null,
        "index":2,
        "buildError":"Batch persisting of Subscriptions failed."
    }
]

Invoice Run

In certain cases, you may need to invoke the invoice run from outside Salesforce. To do so, you must make use of Salesforce's REST API, which allows for executing Apex code via REST calls.

Setting up support for this "remote control" in JustOn/Salesforce involves the following major tasks:

(1) Create a piece of Apex code to invoke the invoice run batch chain, like

// 1. Create a new Invoice Run record OR use an existing Invoice Run
ONB2__InvoiceRun__c invoiceRun = new ONB2__InvoiceRun__c(
    ONB2__PeriodEndDate__c = Date.newInstance(2018, 3, 1),
    ONB2__PeriodStartDate__c = Date.newInstance(2018, 3, 31)

    // === optional parameters: ===
    // ONB2__Filter__c
    // ONB2__TransactionFilter__c
    // ONB2__OpportunityFilter__c
    // ONB2__GenericFilters__c
    // ONB2__InvoiceDate__c
);
insert invoiceRun;

// 2. Start the Invoice Run batch chain
new ONB2.ChainRunner()
.execute(
    new ONB2.ChainFactory().getByName('InvoiceRunChain')
    .setParameters(
        new Map<String, Object>{'invoiceRunId' => invoiceRun.Id} // Here you pass the Invoice Run Id
    )
);

(2) You can now

Call this code via the Tooling API using the executeAnonymous resource, as described in REST Resources in the Salesforce Developer Documentation, or
Implement this code in an Apex class and expose this class as a REST web service, as described in Exposing Apex Classes as REST Web Services in the Salesforce Developer Documentation.

(3) You can then create an external application that accesses your Apex code through the REST architecture.

Invoice Import and Fix

If you create invoices via REST, JustOn Billing & Invoice Management allows you to fix these invoices via REST as well. Please note that the number of invoices that can be fixed in one call should not exceed 10. You should also not call the API in parallel.

JustOn Billing & Invoice Management accepts an HTTP POST request at the following endpoint:

https://INSTANCE.salesforce.com/services/apexrest/ONB2/FixInvoicesApi

The body of the request must be in JSON format and contain a list of invoice IDs to be fixed:

{"invoiceIds":["id1","id2"]}

For more information, see Invoice Import and Fix.

Balance Import and Fix

JustOn allows you to fix balances via REST. Please note that the number of balances that can be fixed in one call is limited.

JustOn accepts an HTTP POST request at the following endpoint:

https://INSTANCE.salesforce.com/services/apexrest/ONB2/FixBalancesApi

The body of the request must be in JSON format and contain a list of balance IDs to be fixed:

{ "balanceIds": [ /* ids */ ] }

JustOn allows you to delete balances via REST as well. Please note that the number of balances that can be fixed in one call is limited.

JustOn accepts an HTTP POST request at the following endpoint:

https://INSTANCE.salesforce.com/services/apexrest/ONB2/DelBalancesApi

The body of the request must be in JSON format and contain a list of balance IDs to be fixed:

{
    "balanceIds": [ /* ids */ ],
    "unregisterOnly": false
}

For more information, see Balance Import and Fix.

Apex Refund Interface

JustOn provides an API that allows for creating refunds for a set of related payment balances, like, for example, the payment balances that originate from a specific payment transaction made via a payment service provider.

The API ONB2.RefundPaymentApi takes a list of related payment balances and creates refund balances for a specified refund amount.

Method	Description	Required
`global ONB2.RefundPaymentApi setPaymentBalances(List<ONB2__Balance__c> paymentBalances)`	Sets the related payment balances. The payments are refunded in the order as specified by the passed list. Only balances of the type `Payment` or `Prepayment` that are not locked can be refunded.
`global ONB2.RefundPaymentApi setReason(String reason)`	Specifies the lock reason of the created refund balances and the related payment balances.
`global ONB2.RefundPaymentApi compensateOverRefund()`	Enables the creation of additional payment balances to settle a refund if the refund amount is larger than the sum of the amount of the passed payment balances.
`global ONB2.RefundPaymentApi refund(Decimal amount)`	Creates refund balances for the passed payment balances.

Data	Description
`global static String REASON_REFUND_BY_PAYMENT_PROVIDER`	Default reason string for refunds initiated via a payment provider

The refund methods throw an ONB2.Exceptions.ValidationException in the following cases:

Message	Description
`Cannot refund without an existing payment balance`	There have not been set any payment balances.
`Only payment or prepayment balances can be refunded`	The specified list of payment balances contains balances that are not of the type `Payment` or `Prepayment`.
`All payments balances to be refunded must be associated to the same account.`	The payment balances are related to multiple accounts.
`The refund amount of {0} exceeds the available payment amount of {1}.`	The specified refund amount is larger than the sum of the available payment balances, and `compensateOverRefund` has not been enabled.

For more information, see Apex Refund Interface.